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

重要

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

限制

注意

使用視訊條件約束 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 值的條件約束。

限制

注意

使用視訊條件約束 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 值的條件約束。

限制

注意

使用視訊條件約束 API 時，請確定您了解這些限制。 未來版本將會移除其中某些限制。

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

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

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

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

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

媒體統計資料

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

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

傳送視訊條件約束

Azure 通訊服務 Web 通話 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 會選擇最小的可用解析度。 在此情況下，所選解析度的高度可以大於條件約束值。

注意

對於所有 bitrate、frameHeight 和 frameRate，條件約束值是 max 條件約束，這表示通話中的實際值可以是指定值或更小的值。 不保證傳送的視訊解析度會維持在指定的解析度。

當行動裝置處於直向模式時，VideoSendConstraints 中的 frameHeight 會有不同的意義。 在直向模式中，此值表示裝置較短的一邊。 例如，使用直向模式在 1080 (寬) x 1920 (高) 裝置上指定 frameHeight.max 值為 240 時，條件約束的高是在 1080 (寬) 這一邊。 當相同的裝置處於橫向模式 (1920(寬) x 1080(高)) 時，條件約束是在 1080(高) 這一邊。

如果您使用 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 通訊服務 解析度階梯，這是預先定義的視訊解析度清單，其中包含估計的比特率上限和較低界限。 當用戶端要求特定解析度時，WebJS 和後端伺服器會參考解析度階梯來配置適當的視訊比特率，同時考慮網路條件和裝置功能。

定義視訊轉譯大小對於旨在控制傳入視訊串流比特率和幀速率的開發人員而言，是關鍵步驟。 視訊數據流的初始品質和解析度取決於建立並放置在網頁上的轉譯器大小。 例如，如果轉譯器很小，WebJS SDK 會要求較小的解析度。 相反地，如果轉譯器很大，ACS SDK 會以伺服器的最佳解析度為目標。 此程式可確保視訊品質根據用戶端的需求和功能進行優化。 當用戶端要求特定解析度時，伺服器會參考解析度階梯來配置適當的視訊比特率，考慮網路狀況和裝置功能。

解析度階梯表格提供 WebJS 呼叫 SDK 解析階梯所包含的內容，以及各種解析度的預估傳入視訊比特率。 這些詳細數據可協助開發人員瞭解解析度、比特率和幀速率之間的關聯性，以及特定傳入視訊串流所使用的大約頻寬量。 例如，1280x720 數據流的解析度為 30 FPS，用戶端使用大約 1 MBPS 的最小比特率和大約 2.5 MBPS 的最大比特率。

Azure 通訊服務 WebJS 通話 SDK 會根據可用的頻寬調整視訊大小，以確保一致的通訊體驗。 WebJS 呼叫 SDK 會根據監視網路狀況的演演算法調整視訊大小。 當網路頻寬足夠時，SDK 會根據網頁上定義的轉譯大小，將視訊解析度提高到其最大層級。 相反地，當頻寬有限時，它會減少視訊解析度，以防止緩衝並維持穩定的連線。

下表提供每個解析度的解析度階梯和預估比特率，以及將在該解析度上傳遞的相關 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);
});

下一步

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

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