クイックスタート: 通話アプリでビデオ制約を設定する

概要

ビデオ制約 API を使用すると、開発者がビデオ通話でビデオの品質を制御できます。 このクイックスタート ガイドでは、API を使用して制約を設定する方法について説明します。

前提条件

音声通話を使用してサンプル アプリを設定するには、音声通話のクイック スタートを参照してください。

クラス

ビデオ制約の使用

次のセクションでは、受信および送信ビデオ ストリームに対して、通話のさまざまなタイミングでビデオ制約を設定する方法について説明します。

通話を開始する前にビデオ制約を設定する

受信ビデオ ストリームの場合、IncomingVideoConstraints を IncomingVideoOptions に追加する必要があります。

    var IncomingVideoOptions = new IncomingVideoOptions()
    {
        Constraints = new IncomingVideoConstraints() 
        { 
            MaxWidth = /*value*/, 
            MaxHeight = /*value*/ 
        },
        // other options
        // ...
    }

送信ビデオ ストリームの場合、OutgoingVideoConstraints を OutgoingVideoOptions に追加する必要があります。

    var OutgoingVideoOptions = new OutgoingVideoOptions()
    {
        Constraints = new OutgoingVideoConstraints() 
        { 
            MaxWidth = /*value*/, 
            MaxHeight = /*value*/, 
            MaxFrameRate = /*value*/ 
        },
        // other options
        // ...
    }

オプションは通話の開始/参加に使用されるため、制約はその後にストリームに自動的に適用できます。 次に例を示します。

    var joinCallOptions = new JoinCallOptions()
    {
        IncomingVideoOptions = new IncomingVideoOptions()
        {
            Constraints = new IncomingVideoConstraints() 
            { 
                MaxWidth = /*value*/, 
                MaxHeight = /*value*/ 
            },
            // other options
            // ...
        },

        OutgoingVideoOptions = new OutgoingVideoOptions()
        {
            Constraints = new OutgoingVideoConstraints() 
            { 
                MaxWidth = /*value*/, 
                MaxHeight = /*value*/, 
                MaxFrameRate = /*value*/ 
            },
            // other options
            // ...
        }
    };
    await callAgent.JoinAsync(locator, joinCallOptions);

通話中にビデオ制約を設定する

通話を開始する前にビデオ制約を設定する代わりに、通話中にビデオ制約を動的に調整することもできます。 Call 型クラスで SetVideoConstraints を呼び出し、制約を指定する必要があります。

    OutgoingVideoConstraints outgoingVideoConstraints = new OutgoingVideoConstraints()
    {
        outgoingVideoConstraints.MaxWidth = /*value*/ ;
        outgoingVideoConstraints.MaxHeight = /*value*/ ;
        outgoingVideoConstraints.MaxFrameRate = /*value*/ ;
    };
    
    IncomingVideoConstraints incomingVideoConstraints = new IncomingVideoConstraints()
    {
        incomingVideoConstraints.MaxWidth = /*value*/ ;
        incomingVideoConstraints.MaxHeight = /*value*/ ;
    };
  
    VideoConstraints constraints = new VideoConstraints();
    constraints.OutgoingVideoConstraints = outgoingVideoConstraints;
    constraints.IncomingVideoConstraints = incomingVideoConstraints;
    
    call.SetVideoConstraints(constraints);

前に設定したビデオ制約をリセットまたは削除するには、上記のパターンに従い、制約値として 0 を指定する必要があります。 IncomingVideoConstraints または OutgoingVideoConstraints に null 値を指定しても、制約はリセットまたは削除されず、null 値を持つ制約は無視されます。

制限事項

現在のビデオ制約 API には、いくつかの既知の制限があります。

• 制約は最大制約です。つまり、制約値として使用できるのは、指定した値以下です。 実際の値がユーザー指定と同じであるという保証はありません。

• ユーザーが小さすぎる制約値を設定すると、SDK はサポートされている使用可能な最小値を使用します。

• 通話中に OutgoingVideoConstraints を設定する場合、現在進行中のビデオ ストリームでは、指定された制約が自動的には取得されません。 制約を有効にするには、送信ビデオを停止して再起動する必要があります。

• 現在、IncomingVideoConstraints はハード制約ではなくユーザー優先制約です。つまり、ネットワークとハードウェアによっては、受け取った実際の値が制約セットを超える可能性があります。

メディア統計

ビデオ制約を適用した後のビデオ品質を評価および比較するには、MediaStats API にアクセスして、ストリームのビデオ解像度とビットレート情報を取得できます。 メディア統計には、ジッター、パケット損失、ラウンド トリップ時間など、ストリームに関連するその他の詳細な統計も含まれます。

概要

ビデオ制約 API を使用すると、開発者がビデオ通話でビデオの品質を制御できます。 このクイックスタート ガイドでは、API を使用して制約を設定する方法について説明します。

前提条件

音声通話を使用してサンプル アプリを設定するには、音声通話のクイック スタートを参照してください。

クラス

ビデオ制約の使用

次のセクションでは、受信および送信ビデオ ストリームに対して、通話のさまざまなタイミングでビデオ制約を設定する方法について説明します。

通話を開始する前にビデオ制約を設定する

受信ビデオ ストリームの場合、IncomingVideoConstraints を IncomingVideoOptions に追加する必要があります。

    IncomingVideoConstraints incomingVideoConstraints = new IncomingVideoConstraints();
    incomingVideoConstraints.setMaxWidth(/*value*/);
    incomingVideoConstraints.setMaxHeight(/*value*/);

    // ...

    IncomingVideoOptions incomingVideoOptions = new IncomingVideoOptions();
    incomingVideoOptions.setConstraints(incomingVideoConstraints);

送信ビデオ ストリームの場合、OutgoingVideoConstraints を OutgoingVideoOptions に追加する必要があります。

    OutgoingVideoConstraints outgoingVideoConstraints = new OutgoingVideoConstraints() 
    outgoingVideoConstraints.setMaxWidth(/*value*/); 
    outgoingVideoConstraints.setMaxHeight(/*value*/); 
    outgoingVideoConstraints.setMaxFrameRate(/*value*/); 
   
    // ...
    
    OutgoingVideoOptions outgoingVideoOptions = new OutgoingVideoOptions();
    outgoingVideoOptions.setConstraints(outgoingVideoConstraints);

オプションは通話の開始/参加に使用されるため、制約はその後にストリームに自動的に適用できます。 次に例を示します。

    JoinCallOptions joinCallOptions = new JoinCallOptions();
    joinCallOptions.setIncomingVideoOptions(incomingVideoOptions);
    joinCallOptions.setOutgoingVideoOptions(outgoingVideoOptions);
    callAgent.Join(context, locator, joinCallOptions);

通話中にビデオ制約を設定する

通話を開始する前にビデオ制約を設定する代わりに、通話中にビデオ制約を動的に調整することもできます。 Call 型クラスで setVideoConstraints を呼び出し、制約を指定する必要があります。

    OutgoingVideoConstraints outgoingVideoConstraints = new OutgoingVideoConstraints();
    outgoingVideoConstraints.setMaxWidth(/*value*/); 
    outgoingVideoConstraints.setMaxHeight(/*value*/); 
    outgoingVideoConstraints.setMaxFrameRate(/*value*/); 
    
    IncomingVideoConstraints incomingVideoConstraints = new IncomingVideoConstraints();
    incomingVideoConstraints.setMaxWidth(/*value*/);
    incomingVideoConstraints.setMaxHeight(/*value*/);
  
    VideoConstraints constraints = new VideoConstraints();
    constraints.setOutgoingVideoConstraints(outgoingVideoConstraints);
    constraints.setIncomingVideoConstraints(incomingVideoConstraints);
    
    call.setVideoConstraints(constraints);

前に設定したビデオ制約をリセットまたは削除するには、上記のパターンに従い、制約値として 0 を指定する必要があります。 IncomingVideoConstraints または OutgoingVideoConstraints に null 値を指定しても、制約はリセットまたは削除されず、null 値を持つ制約は無視されます。

制限事項

現在のビデオ制約 API には、いくつかの既知の制限があります。

• 制約は最大制約です。つまり、制約値として使用できるのは、指定した値以下です。 実際の値がユーザー指定と同じであるという保証はありません。

• ユーザーが小さすぎる制約値を設定すると、SDK はサポートされている使用可能な最小値を使用します。

• 通話中に OutgoingVideoConstraints を設定する場合、現在進行中のビデオ ストリームでは、指定された制約が自動的には取得されません。 制約を有効にするには、送信ビデオを停止して再起動する必要があります。

• 現在、IncomingVideoConstraints はハード制約ではなくユーザー優先制約です。つまり、ネットワークとハードウェアによっては、受け取った実際の値が制約セットを超える可能性があります。

メディア統計

ビデオ制約を適用した後のビデオ品質を評価および比較するには、MediaStats API にアクセスして、ストリームのビデオ解像度とビットレート情報を取得できます。 メディア統計には、ジッター、パケット損失、ラウンド トリップ時間など、ストリームに関連するその他の詳細な統計も含まれます。

概要

ビデオ制約 API を使用すると、開発者がビデオ通話でビデオの品質を制御できます。 このクイックスタート ガイドでは、API を使用して制約を設定する方法について説明します。

前提条件

音声通話を使用してサンプル アプリを設定するには、音声通話のクイック スタートを参照してください。

クラス

ビデオ制約の使用

次のセクションでは、受信および送信ビデオ ストリームに対して、通話のさまざまなタイミングでビデオ制約を設定する方法について説明します。

通話を開始する前にビデオ制約を設定する

受信ビデオ ストリームの場合、IncomingVideoConstraints を IncomingVideoOptions に追加する必要があります。

    let incomingVideoConstraints = IncomingVideoConstraints()
    incomingVideoConstraints.maxWidth = /*value*/ 
    incomingVideoConstraints.maxHeight = /*value*/ 
    
    // ...
    
    let incomingVideoOptions = IncomingVideoOptions()
    incomingVideoOptions.constraints = incomingVideoConstraints

送信ビデオ ストリームの場合、OutgoingVideoConstraints を OutgoingVideoOptions に追加する必要があります。

    let outgoingVideoConstraints = OutgoingVideoConstraints()
    outgoingVideoConstraints.maxWidth = /*value*/ 
    outgoingVideoConstraints.maxHeight = /*value*/
    outgoingVideoConstraint.maxFrameRate = /*value*/ 
    
    // ...

    let outgoingVideoOptions = OutgoingVideoOptions()
    outgoingVideoOptions.constraints = outgoingVideoConstraints

オプションは通話の開始/参加に使用されるため、制約はその後にストリームに自動的に適用できます。 次に例を示します。

    let incomingVideoConstraints = IncomingVideoConstraints()
    incomingVideoConstraints.maxWidth = /*value*/ 
    incomingVideoConstraints.maxHeight = /*value*/ 
    let incomingVideoOptions = IncomingVideoOptions()
    incomingVideoOptions.constraints = incomingVideoConstraints
    
    let outgoingVideoConstraints = OutgoingVideoConstraints()
    outgoingVideoConstraints.maxWidth = /*value*/ 
    outgoingVideoConstraints.maxHeight = /*value*/
    outgoingVideoConstraint.maxFrameRate = /*value*/ 
    let outgoingVideoOptions = OutgoingVideoOptions()
    outgoingVideoOptions.constraints = outgoingVideoConstraints
    
    let joinCallOptions = new JoinCallOptions()
    joinCallOptions.incomingVideoOptions = incomingVideoOptions
    joinCallOptions.outgoingVideoOptions = outgoingVideoOptions

    callAgent.join(with: locator, joinCallOptions: joinCallOptions);

通話中にビデオ制約を設定する

通話を開始する前にビデオ制約を設定する代わりに、通話中にビデオ制約を動的に調整することもできます。 Call 型クラスで set(videoConstraints) を呼び出し、制約を指定する必要があります。

    let outgoingVideoConstraints = OutgoingVideoConstraints()
    outgoingVideoConstraints.maxWidth = /*value*/ 
    outgoingVideoConstraints.maxHeight = /*value*/
    outgoingVideoConstraint.maxFrameRate = /*value*/ 
    
    let incomingVideoConstraints = IncomingVideoConstraints()
    incomingVideoConstraints.maxWidth = /*value*/ 
    incomingVideoConstraints.maxHeight = /*value*/ 
  
    let videoConstraints = VideoConstraints()
    videoConstraints.outgoingVideoConstraints = outgoingVideoConstraints
    videoConstraints.incomingVideoConstraints = incomingVideoConstraints
    
    call?.set(videoConstraints: videoConstraints)

前に設定したビデオ制約をリセットまたは削除するには、上記のパターンに従い、制約値として 0 を指定する必要があります。 IncomingVideoConstraints または OutgoingVideoConstraints に null 値を指定しても、制約はリセットまたは削除されず、null 値を持つ制約は無視されます。

制限事項

現在のビデオ制約 API には、いくつかの既知の制限があります。

• 制約は最大制約です。つまり、制約値として使用できるのは、指定した値以下です。 実際の値がユーザー指定と同じであるという保証はありません。

• ユーザーが小さすぎる制約値を設定すると、SDK はサポートされている使用可能な最小値を使用します。

• 通話中に OutgoingVideoConstraints を設定する場合、現在進行中のビデオ ストリームでは、指定された制約が自動的には取得されません。 制約を有効にするには、送信ビデオを停止して再起動する必要があります。

• 現在、IncomingVideoConstraints はハード制約ではなくユーザー優先制約です。つまり、ネットワークとハードウェアによっては、受け取った実際の値が制約セットを超える可能性があります。

メディア統計

ビデオ制約を適用した後のビデオ品質を評価および比較するには、MediaStats API にアクセスして、ストリームのビデオ解像度とビットレート情報を取得できます。 メディア統計には、ジッター、パケット損失、ラウンド トリップ時間など、ストリームに関連するその他の詳細な統計も含まれます。

通話内にビデオの制約を設定して、ビデオ通話の解像度またはフレームレートやビットレートに基づいてビデオ品質を制御できます。 このクイックスタート ガイドでは、通話の開始時にビデオの制約を設定する方法と、通話オブジェクトで setConstraints メソッドを使って通話中にビデオの制約を動的に設定する方法について説明します。

ビデオの制約を送信する

Azure Communication Services Web Calling SDK は、クライアントが送信する最大ビデオ解像度、フレームレート、またはビットレートの設定をサポートしています。 送信者のビデオの制約は、デスクトップ ブラウザー (Chrome、Edge、Firefox) でサポートされているだけではなく、iOS Safari モバイル ブラウザーまたは Android Chrome モバイル ブラウザーを使う場合もサポートされています。

通話の開始時のビデオの制約の設定 - 発信 (送信) ビデオ

ビデオ制約の設定は、Call インターフェイスに実装されます。 ビデオの制約を使うには、通話を発信するとき、通話を受けるとき、または通話に参加するときに、CallOptions 内から制約を指定します。 videoOptions で localVideoStreams を指定する必要があります。
音声のみのオプションで通話に参加し、後でカメラをオンにした場合、制約は機能しません。 この場合は、Call インターフェイスで setConstraints メソッドを使ってビデオの制約を動的に設定できます。

const callOptions = {
    videoOptions: {
        localVideoStreams: [...],
        constraints: {
            send: {
                bitrate: {
                    max: 575000
                },
                frameHeight: {
                    max: 240
                },
                frameRate: {
                    max: 20
                }
            }
        }
    },
    audioOptions: {
        muted: false
    }
};
// make a call
this.callAgent.startCall(identitiesToCall, callOptions);
// join a group call
this.callAgent.join({ groupId }, callOptions);
// accept an incoming call
this.incomingCall.accept(callOptions)

ビデオ制約の種類を次に示します。

export declare interface VideoOptions {
    localVideoStreams?: LocalVideoStream[];
    //video constraint when call starts
    constraints?: VideoConstraints;
};

export declare type VideoConstraints = {
    send?: VideoSendConstraints;
};

export type VideoSendConstraints = {
    /**
     * Resolution constraint
     */
    frameHeight?: MediaConstraintRange;

    /**
     * FrameRate constraint
     */
    frameRate?: MediaConstraintRange;

    /**
     * Bitrate constriant
     */
    bitrate?: MediaConstraintRange;
};

export declare type MediaConstraintRange = {
    max?: number;
};

ビデオの制約を設定すると、SDK によって、解像度、フレームレート、ビットレートの値が設定されている最大制約値を超えないように、制約セットに収まる最も近い値が選ばれれます。 また、解像度の制約値が小さすぎるときは、SDK は使用できる最小の解像度を選びます。 この場合、選択した解像度の高さは制約値よりも大きくなる可能性があります。

VideoSendConstraints の frameHeight は、モバイル デバイスが縦長モードの場合は意味が異なります。 縦長モードでは、この値はデバイスの短い側を示します。 たとえば、縦長モードの 1080(W) x 1920(H) のデバイスで frameHeight.max 値に 240 を指定すると、制約の高さは 1080 (W) の側になります。 同じデバイスが横向きモード (1920(W) x 1080(H)) の場合、制約は 1080(H) の側になります。

MediaStats API を使用して、送信されたビデオの解像度を追跡すると、送信された解像度が通話中に変更される場合があることに気付くかもしれません。 上下に変動する場合がありますが、指定した制約値と等しいか小さくなります。 この解像度の変更は予期される動作です。 また、ブラウザーには、CPU またはネットワークの状態に基づいて、送信された解像度を調整する低下ルールもいくつかあります。

通話中のビデオの制約の設定 - 発信 (送信) ビデオ

通話中にビデオの制約を設定するには、Call オブジェクトに対して setConstraints メソッドを使います。

// For eg, when you've started a call,
const currentCall = this.callAgent.startCall(identitiesToCall, callOptions);

// To set constraints during the call,
await currentCall.setConstraints({
    video: {
        send: {
            frameHeight: {
                max: 360
            },
            frameRate: {
                max: 15
            }
        }
    }
});

// To set only a particular constraint (the others will stay as what they were set before, if they were set)
await currentCall.setConstraints({
    video: {
        send: {
            bitrate: {
                max: 400000
            }
        }
    }
});

// To unset any constraint,
await currentCall.setConstraints({
    video: {
        send: {
            frameHeight: {
                max: 0
            }
        }
    }
});

ビデオの制約を受け取る

Azure Communication Services Web Calling SDK を使って受信側で解像度を制御するには、そのビデオのレンダラーのサイズを調整できます。 Calling SDK は、レンダラーのサイズに基づいて受信した解像度を自動的に調整します。 SDK では、レンダラーのビデオ ウィンドウに収まる受信ビデオ ストリーム (幅と高さ) は要求されません。

ビデオの制約の影響を理解するためのメディア スタティックの使用

ビデオ制約を適用した後のビデオ品質を評価および比較するには、「MediaStats API」にアクセスして、送信ストリームのビデオ解像度とビットレート情報を取得できます。 メディア統計には、ジッター、パケット損失、ラウンド トリップ時間など、ストリームに関連するその他の詳細な統計も含まれます。

const mediaStatsFeature = call.feature(Features.MediaStats);
const mediaStatsCollector = mediaStatsFeature.createCollector();

mediaStatsCollector.on('sampleReported', (sample: SDK.MediaStatsReportSample) => {
    // process the stats for the call.
    console.log(sample);
});