你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：在通话应用中设置视频约束

重要

本文中所述的功能目前以公共预览版提供。 此预览版在提供时没有附带服务级别协议，我们不建议将其用于生产工作负荷。 某些功能可能不受支持或者受限。 有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。

概述

视频约束 API 使开发人员能够在视频通话中控制视频质量。 在本快速入门指南中，我们将演示如何使用 API 设置约束。

先决条件

若要使用语音呼叫设置示例应用，请参阅语音呼叫快速入门。

类

“属性”	描述
视频约束	用于保存传入视频约束和传出视频约束。
传出视频约束	用于规定传出视频流的约束 (MaxWidth | MaxHeight | MaxFrameRate)。
传入视频约束	用于规定传入视频流的约束 (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 设置约束。

先决条件

若要使用语音呼叫设置示例应用，请参阅语音呼叫快速入门。

类

“属性”	描述
视频约束	用于保存传入视频约束和传出视频约束。
传出视频约束	用于规定传出视频流的约束 (maxWidth | maxHeight | maxFrameRate)。
传入视频约束	用于规定传入视频流的约束 (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 设置约束。

先决条件

若要使用语音呼叫设置示例应用，请参阅语音呼叫快速入门。

类

“属性”	描述
视频约束	用于保存传入视频约束和传出视频约束。
传出视频约束	用于规定传出视频流的约束 (maxWidth | maxHeight | maxFrameRate)。
传入视频约束	用于规定传入视频流的约束 (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 分辨率阶梯的内容，以及适用于不同分辨率的预估传入视频比特率。 这些详细信息可帮助开发人员了解分辨率、比特率和帧速率之间的关系，以及特定传入视频流使用的近似带宽量。 例如，当客户端使用近似最低比特率 1 MBPS 和近似最高比特率 2.5 MBPS 时，视频流的分辨率为 1280x720，帧速率为 30 FPS。

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 的功能