共用方式為

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

  • 發行項

重要

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

下一步

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