クイックスタート - 通話アプリでビデオ制約を設定する - An Azure Communication Services quickstart

重要

この記事で説明されている機能は、現在パブリックプレビュー段階にあります。このプレビューバージョンはサービスレベルアグリーメントなしで提供されており、運用環境のワークロードに使用することは推奨されません。特定の機能はサポート対象ではなく、機能が制限されることがあります。詳しくは、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 constriant
     */
    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 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);
});

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

概要

前提条件

クラス

ビデオ制約の使用

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

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

制限事項

メディア統計

概要

前提条件

クラス

ビデオ制約の使用

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

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

制限事項

メディア統計

概要

前提条件

クラス

ビデオ制約の使用

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

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

制限事項

メディア統計

ビデオの制約を送信する

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

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

ビデオの制約を受け取る

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

次のステップ

その他のリソース

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

概要

前提条件

クラス

ビデオ制約の使用

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

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

制限事項

メディア統計

概要

前提条件

クラス

ビデオ制約の使用

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

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

制限事項

メディア統計

概要

前提条件

クラス

ビデオ制約の使用

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

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

制限事項

メディア統計

ビデオの制約を送信する

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

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

ビデオの制約を受け取る

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

次のステップ

その他のリソース

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