通話アプリでビデオ制約を設定する

概要

Video Constraints 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値を持つ制約は無視されます。

制限事項

現在の Video Constraints API には、いくつかの既知の制限があります。

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

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

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

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

メディア統計

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

概要

Video Constraints API を使用すると、開発者はビデオ呼び出し内からビデオ品質を制御できます。 この記事では、API を使用して制約を設定する方法について説明します。

前提条件

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

クラス

ビデオ制約の使用

次のセクションでは、通話の異なる時間に、ビデオの制約を着信ビデオ ストリームまたは送信ビデオ ストリームに設定する方法について説明します。

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

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

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

    // ...

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

送信ビデオ ストリームの場合は、OutgoingVideoOptionsにOutgoingVideoConstraintsを追加します。

    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値を持つ制約は無視されます。

制限事項

現在の Video Constraints API には、いくつかの既知の制限があります。

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

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

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

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

メディア統計

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

概要

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

前提条件

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

クラス

ビデオ制約の使用

次のセクションでは、通話の異なる時間に、ビデオの制約を着信ビデオ ストリームまたは送信ビデオ ストリームに設定する方法について説明します。

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

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

    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値を持つ制約は無視されます。

制限事項

現在の Video Constraints API には、いくつかの既知の制限があります。

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

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

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

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

メディア統計

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

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

ビデオの制約を送信する

Azure Communication Services Web Calling SDK は、クライアントが送信する最大ビデオ解像度、フレームレート、またはビットレートの設定をサポートしています。 送信者のビデオの制約は、デスクトップ ブラウザー (Chrome、Microsoft 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 constraint
     */
    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 の解像度ラダーを理解する必要があります。これは、ビット レートの上限と下限境界が見積もられたビデオ解像度の定義済みの一覧です。 クライアントが特定の解像度を要求すると、WebJS とバックエンド サーバーは解像度ラダーを調べ、ネットワーク条件とデバイス機能の両方を考慮して、適切なビデオ ビット レートを割り当てます。

ビデオ レンダリング サイズの定義は、着信ビデオ ストリームのビット レートとフレーム レートの制御を目指す開発者にとって重要な手順です。 ビデオ ストリームの初期品質と解像度は、Web ページに作成および配置されたレンダラーのサイズによって決まります。 たとえば、レンダラーが小さい場合、WebJS SDK はより小さな解像度を要求します。 逆に、レンダラーが大きい場合、ACS SDK はサーバーから可能な限り最高の解像度を目標にします。 このプロセスにより、クライアントの要件と機能に基づいてビデオ品質が確実に最適化されます。 クライアントが特定の解像度を要求すると、サーバーは解像度ラダーを調べ、ネットワーク条件とデバイス機能の両方を考慮して、適切なビデオ ビット レートを割り当てます。

解決ラダーの表は、WebJS Calling SDK 解像度ラダーの構成内容と、さまざまな解像度の推定着信ビデオ ビット レートを示しています。 これらの詳細は、解像度、ビット レート、フレーム レート、特定の着信ビデオ ストリームで使用される帯域幅のおおよその量の関係を理解するのに役立ちます。 たとえば、1280 x 720 ストリームの解像度は 30 FPS で、クライアントでは約最小ビットレートが 1 MBPS、最大ビットレートが約 2.5 MBPS です。

Azure Communication Services WebJS Calling SDK は、一貫した通信エクスペリエンスを確保するために、使用可能な帯域幅に基づいてビデオ サイズを調整します。 WebJS Calling SDK は、ネットワークの状態を監視するアルゴリズムに基づいてビデオ サイズを調整します。 ネットワーク帯域幅が十分な場合、SDK は、Web ページで定義されているレンダリング サイズに基づいて、ビデオ解像度を最大レベルに引き上げます。 逆に、帯域幅が制限されている場合は、バッファリングを防ぎ、安定した接続を維持するためにビデオ解像度を引き下げます。

次の表は、各解像度の解像度ラダーと推定ビットレートと、その解像度で提供される関連する FPS を示しています。

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

ビデオ制約を適用した後のビデオ品質を評価および比較するには、「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);
});