快速入門：在您的通話應用程式中設定影片條件約束

重要

本文所述的功能目前為公開預覽狀態。 此預覽版本沒有服務等級協定，不建議用於處理生產工作負載。 可能不支援特定功能，或可能已經限制功能。 如需詳細資訊，請參閱 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 作為條件約束值。 提供 null 或 OutgoingVideoConstraints 的值不會重設/移除條件約束，且會忽略具有null值的條件約束。IncomingVideoConstraints

限制

注意

使用影片條件約束 API 時，請確定您知道這些限制。 未來版本將會移除某些限制。

目前影片條件約束 API 有一些已知的限制。

• 條件約束是 max 條件約束，這表示可能的條件約束值可以是指定的值或更小的值。 不保證實際值維持與使用者指定的相同。

• 當使用者設定條件約束值太小時，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 作為條件約束值。 提供 null 或 OutgoingVideoConstraints 的值不會重設/移除條件約束，且會忽略具有null值的條件約束。IncomingVideoConstraints

限制

注意

使用影片條件約束 API 時，請確定您知道這些限制。 未來版本將會移除某些限制。

目前影片條件約束 API 有一些已知的限制。

• 條件約束是 max 條件約束，這表示可能的條件約束值可以是指定的值或更小的值。 不保證實際值維持與使用者指定的相同。

• 當使用者設定條件約束值太小時，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 作為條件約束值。 提供 null 或 OutgoingVideoConstraints 的值不會重設/移除條件約束，且會忽略具有null值的條件約束。IncomingVideoConstraints

限制

注意

使用影片條件約束 API 時，請確定您知道這些限制。 未來版本將會移除某些限制。

目前影片條件約束 API 有一些已知的限制。

• 條件約束是 max 條件約束，這表示可能的條件約束值可以是指定的值或更小的值。 不保證實際值維持與使用者指定的相同。

• 當使用者設定條件約束值太小時，SDK 會使用支援的最小可用值。

• 若要在呼叫期間設定 OutgoingVideoConstraints ，目前進行中的視訊串流不會自動挑選指定的條件約束。 若要讓條件約束生效，您必須停止並重新啟動傳出影片。

• IncomingVideoConstraints 目前是使用者慣用的條件約束，而不是硬式條件約束，這表示視您的網路和硬體而定，收到的實際值可能仍超過條件約束集。

媒體統計數據

若要在套用視訊條件約束之後評估及比較視訊品質，您可以存取 MediaStats API 以取得串流的視訊解析度和比特率資訊。 媒體統計數據也包含與數據流相關的其他細微統計數據，例如抖動、封包遺失、來回時間等。

您可以在通話中設定視訊條件約束，以根據視訊通話中的解析度或幀速率或比特率來控制視訊品質。 在本快速入門指南中，我們會說明如何在呼叫開始時設定視訊條件約束，以及如何在呼叫物件上使用我們的 setConstraints 方法，在呼叫期間動態設定視訊條件約束。

傳送視訊條件約束

Azure 通訊服務 Web 通話 SDK 支援設定用戶端傳送的最大視訊解析度、幀速率或比特率。 使用 iOS Safari 行動瀏覽器或 Android Chrome 行動瀏覽器時，桌面瀏覽器（Chrome、Edge、Firefox）支援發件者視訊條件約束。

支持的條件約束
傳入視訊：解析度 傳出視訊：解析度、幀速率、比特率

在通話開始時設定視訊條件約束 - 撥出 （傳送） 視訊

影片條件約束設定會在介面上實作 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 會選擇限制集內最接近的值，以防止解析度、frameRate 和比特率的值超過設定的最大條件約束值。 此外，當解析條件約束值太小時，SDK 會選擇最小的可用解析度。 在此情況下，所選解析度的高度可以大於條件約束值。

注意

對於所有 bitrate、 frameHeight 和 frameRate，條件約束值是 max 條件約束，這表示呼叫中的實際值可以是指定的值或更小的值。 沒有關口，傳送的視頻解析度將保留在指定的解析度。

當行動裝置處於直向模式時，中的 frameHeightVideoSendConstraints 具有不同的意義。 在直向模式中，此值表示裝置的較短一面。 例如，以直向模式在 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
            }
        }
    }
});

注意

將條件約束值設定為 0 會取消設定任何先前設定的條件約束。 您可以使用這種方式來重設或移除條件約束。

接收視訊條件約束

若要使用 Azure 通訊服務 Web 通話 SDK 控制接收端的解析度，您可以調整該視訊轉譯器的大小。 呼叫的 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);
});

下一步

如需詳細資訊，請參閱下列文章：

• 瞭解 影片條件約束概念檔
• 深入了解 通話 SDK 功能