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

重要

この記事で説明されている機能は、現在パブリック プレビュー段階にあります。 このプレビュー バージョンはサービス レベル アグリーメントなしで提供されており、運用環境のワークロードに使用することは推奨されません。 特定の機能はサポート対象ではなく、機能が制限されることがあります。 詳しくは、Microsoft Azure プレビューの追加使用条件に関するページをご覧ください。

概要

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

前提条件

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

クラス

名前	説明
VideoConstraints	受信ビデオの制約と送信ビデオの制約の両方を保持するために使用します。
OutgoingVideoConstraints	送信ビデオ ストリームの制約 (MaxWidth | MaxHeight | MaxFrameRate) を指定するために使用します。
IncomingVideoConstraints	受信ビデオ ストリームの制約 (MaxWidth | MaxHeight) を指定するために使用します。

ビデオ制約の使用

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

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

受信ビデオ ストリームの場合、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 値を持つ制約は無視されます。

制限事項

Note

ビデオ制約 API を使用する場合、これらの制限事項にご注意ください。 制限事項の一部は、今後のリリースで削除される予定です。

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

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

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

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

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

メディア統計

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

重要

この記事で説明されている機能は、現在パブリック プレビュー段階にあります。 このプレビュー バージョンはサービス レベル アグリーメントなしで提供されており、運用環境のワークロードに使用することは推奨されません。 特定の機能はサポート対象ではなく、機能が制限されることがあります。 詳しくは、Microsoft Azure プレビューの追加使用条件に関するページをご覧ください。

概要

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

前提条件

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

クラス

名前	説明
VideoConstraints	受信ビデオの制約と送信ビデオの制約の両方を保持するために使用します。
OutgoingVideoConstraints	送信ビデオ ストリームの制約 (maxWidth | maxHeight | maxFrameRate) を指定するために使用します。
IncomingVideoConstraints	受信ビデオ ストリームの制約 (maxWidth | maxHeight) を指定するために使用します。

ビデオ制約の使用

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

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

受信ビデオ ストリームの場合、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 値を持つ制約は無視されます。

制限事項

Note

ビデオ制約 API を使用する場合、これらの制限事項にご注意ください。 制限事項の一部は、今後のリリースで削除される予定です。

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

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

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

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

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

メディア統計

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

重要

この記事で説明されている機能は、現在パブリック プレビュー段階にあります。 このプレビュー バージョンはサービス レベル アグリーメントなしで提供されており、運用環境のワークロードに使用することは推奨されません。 特定の機能はサポート対象ではなく、機能が制限されることがあります。 詳しくは、Microsoft Azure プレビューの追加使用条件に関するページをご覧ください。

概要

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

前提条件

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

クラス

名前	説明
VideoConstraints	受信ビデオの制約と送信ビデオの制約の両方を保持するために使用します。
OutgoingVideoConstraints	送信ビデオ ストリームの制約 (maxWidth | maxHeight | maxFrameRate) を指定するために使用します。
IncomingVideoConstraints	受信ビデオ ストリームの制約 (maxWidth | maxHeight) を指定するために使用します。

ビデオ制約の使用

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

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

受信ビデオ ストリームの場合、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 値を持つ制約は無視されます。

制限事項

Note

ビデオ制約 API を使用する場合、これらの制限事項にご注意ください。 制限事項の一部は、今後のリリースで削除される予定です。

現在のビデオ制約 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 constraint
     */
    bitrate?: MediaConstraintRange;
};

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

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

Note

すべての bitrate、frameHeight、frameRate の制約値は max 制約です。つまり、通話内の実際の値を、指定した値以下にすることができます。 送信されたビデオ解像度が指定した解像度のままであるという保証はありません。

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
            }
        }
    }
});

Note

制約値を 0 に設定すると、以前に設定した制約が設定解除されます。 この方法を使うと、制約をリセットまたは削除できます。

ビデオの制約を受け取る

受信ストリームのビデオ品質を管理するには、Azure Communication Services の解像度ラダーを理解する必要があります。これは、ビット レートの上限と下限境界が見積もられたビデオ解像度の定義済みの一覧です。 クライアントが特定の解像度を要求すると、WebJS とバックエンド サーバーは解像度ラダーを調べ、ネットワーク条件とデバイス機能の両方を考慮して、適切なビデオ ビット レートを割り当てます。

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

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

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

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

[高さ]	幅	FPS	最小ビット レート (MBps)	最大ビット レート (MBps)
1080	1920	30	1.75	10
720	1280	30	1	2.5
540	960	30	0.5	1.125
360	640	30	0.4	0.57
240	426	15	0.125	0.5
240	320	15	0.2	0.175

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

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

次のステップ

詳細については、次の記事を参照してください。

• ビデオ制約の概念の詳細情報
• Calling SDK の機能の詳細情報