你当前正在访问 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 constriant
     */
    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);
});

后续步骤

有关详细信息，请参阅以下文章：

• 阅读视频约束概念文档
• 详细了解通话 SDK 的功能