在通话应用中设置视频约束

概述

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

先决条件

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

类

使用视频约束

下文介绍了如何在通话的不同时间为传入和/或传出视频流设置视频约束。

在开始通话之前设置视频约束

对于传入视频流，需要将 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);

在通话期间设置视频约束

也可以在通话期间动态调整视频约束，而不是在开始通话之前设置视频约束。 需要对 SetVideoConstraints 类型的类调用 Call 并提供约束。

    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 存在一些已知限制。

• 约束是最大约束，这意味着实际约束值可以小于等于规定值。 无法保证实际值与用户规定值保持相同。

• 当用户设置太小的约束值时，SDK 将使用受支持的最小可用值。

• 如果在通话期间设置 OutgoingVideoConstraints，当前正在进行的视频流不会自动应用指定的限制条件。 若要使约束生效，需要停止并重新开始正在发送的视频。

• IncomingVideoConstraints 当前是用户首选约束，而不是硬约束，这意味着根据网络和硬件，收到的实际值可能仍超过约束集。

媒体统计信息

若要在应用视频约束后评估和比较视频质量，可以访问 MediaStats API 以获取流的视频分辨率和比特率信息。 媒体统计信息还包括与流相关的其他粒度统计信息，例如抖动、数据包丢失、往返时间等。

概述

视频约束 API 使开发人员能够在视频通话中控制视频质量。 本文介绍如何使用 API 设置约束。

先决条件

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

类

使用视频约束

下文介绍了如何在通话的不同时间为传入和/或传出视频流设置视频约束。

在开始通话之前设置视频约束

对于传入的视频流，您需要在IncomingVideoOptions中添加一个 IncomingVideoConstraints 。

    IncomingVideoConstraints incomingVideoConstraints = new IncomingVideoConstraints();
    incomingVideoConstraints.setMaxWidth(/*value*/);
    incomingVideoConstraints.setMaxHeight(/*value*/);

    // ...

    IncomingVideoOptions incomingVideoOptions = new IncomingVideoOptions();
    incomingVideoOptions.setConstraints(incomingVideoConstraints);

对于传出视频流，请将 OutgoingVideoOptions 添加 OutgoingVideoConstraints。

    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);

在通话期间设置视频约束

也可以在通话期间动态调整视频约束，而不是在开始通话之前设置视频约束。 需要对 setVideoConstraints 类型的类调用 Call 并提供约束。

    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 存在一些已知限制。

• 约束是最大约束，这意味着实际约束值可以小于等于规定值。 无法保证实际值与用户规定值保持相同。

• 当用户设置太小的约束值时，SDK 将使用受支持的最小可用值。

• 如果在通话期间设置 OutgoingVideoConstraints，当前正在进行的视频流不会自动应用指定的限制条件。 若要使约束生效，需要停止并重新开始正在发送的视频。

• IncomingVideoConstraints 当前是用户首选约束，而不是硬约束，这意味着根据网络和硬件，收到的实际值可能仍超过约束集。

媒体统计信息

若要在应用视频约束后评估和比较视频质量，可以访问 MediaStats API 以获取流的视频分辨率和比特率信息。 媒体统计信息还包括与流相关的其他粒度统计信息，例如抖动、数据包丢失、往返时间等。

概述

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

先决条件

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

类

使用视频约束

下文介绍了如何在通话的不同时间为传入和/或传出视频流设置视频约束。

在开始通话之前设置视频约束

对于传入的视频流，需要在IncomingVideoOptions中添加一个IncomingVideoConstraints。

    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);

在通话期间设置视频约束

可以在通话期间动态调整视频约束，而不是在开始通话之前设置视频约束。 需要对 set(videoConstraints) 类型的类调用 Call 并提供约束。

    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 存在一些已知限制。

• 约束是最大约束，这意味着实际约束值可以小于等于规定值。 无法保证实际值与用户规定值保持相同。

• 当用户设置太小的约束值时，SDK 将使用受支持的最小可用值。

• 如果在通话期间设置 OutgoingVideoConstraints，当前正在进行的视频流不会自动应用指定的限制条件。 若要使约束生效，需要停止并重新开始正在发送的视频。

• IncomingVideoConstraints 当前是用户首选约束，而不是硬约束，这意味着根据网络和硬件，收到的实际值可能仍超过约束集。

媒体统计信息

若要在应用视频约束后评估和比较视频质量，可以访问 MediaStats API 以获取流的视频分辨率和比特率信息。 媒体统计信息还包括与流相关的其他粒度统计信息，例如抖动、数据包丢失、往返时间等。

可以在通话中设置视频约束，以根据视频通话中的分辨率、帧速率或比特率来控制视频质量。 在本快速入门指南中，我们将介绍如何在通话开始时设置视频约束，以及如何在通话对象上使用 setConstraints 方法在通话期间动态设置视频约束。

发送视频约束

Azure 通信服务 Web 通话 SDK 支持设置客户端发送的最大视频分辨率、帧速率或比特率。 不论是在桌面浏览器（Chrome、Microsoft Edge、Firefox）上，还是在使用 iOS Safari 移动浏览器或 Android Chrome 移动浏览器时，都支持发送方视频约束。

在呼叫开始时设置视频约束 - 传出（发送）视频

视频约束设置在 Call 接口上实现。 若要使用视频约束，可以在呼叫、接受呼叫或加入通话时在 CallOptions 中指定约束。 必须在 localVideoStreams 中指定 videoOptions。

如果加入仅包含音频选项的通话并在以后打开相机，则约束不起作用。 在这种情况下，可以在 setConstraints 界面上使用 Call 方法动态设置视频约束。

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 会选择最小的可用分辨率。 在这种情况下，所选分辨率的高度可以大于约束值。

当移动设备处于竖屏模式时，frameHeight 中的 VideoSendConstraints 具有不同的含义。 在竖屏模式下，此值代表设备的较短侧。 例如，竖屏模式下，在 1080（宽）x 1920（高）的设备上将 frameHeight.max 值设为 240，则约束的高度应用于 1080（宽）侧。 当同一设备处于横屏模式（1920[宽] x 1080[高]）时，约束应用于 1080（高）侧。

如果使用 MediaStats API 跟踪发送的视频分辨率，你可能会发现发送的分辨率在调用期间可能会更改。 它可能变高或变低，但应小于等于提供的约束值。 这种分辨率的变化是预料之中的。 浏览器也有一些退化规则，用于根据 CPU 或网络状态调整发送的分辨率。

在通话中调整视频限制 - 传出（发送）视频

通过在 setConstraints 对象上使用 Call 方法，可以在通话期间设置视频约束。

// 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
            }
        }
    }
});

接收视频约束

管理传入流的视频质量需要了解 Azure 通信服务分辨率阶梯，它是一份预定义的视频分辨率列表，其中包含预估的比特率边界上限和下限。 当客户端请求特定分辨率时，WebJS 和后端服务器会查阅分辨率阶梯来分配适当的视频比特率，同时考虑网络条件和设备功能。

对于以控制传入视频流的比特率和帧速率的为目标的开发人员，定义视呈现大小是一个关键步骤。 视频流的初始质量和分辨率取决于创建并放置在网页上的呈现器的大小。 例如，如果呈现器较小，则 WebJS SDK 会请求较小的分辨率。 相反，如果呈现器很大，ACS SDK 的目标则是从服务器获取可能的最佳分辨率。 此过程可确保根据客户端的要求和功能优化视频质量。 当客户端请求特定分辨率时，服务器会查阅分辨率阶梯来分配适当的视频比特率，同时考虑网络条件和设备功能。

分辨率阶梯表提供了 WebJS 通话 SDK 分辨率阶梯的内容，以及适用于不同分辨率的预估传入视频比特率。 这些详细信息可帮助开发人员了解分辨率、比特率和帧速率之间的关系，以及特定传入视频流使用的近似带宽量。 例如，当客户端使用近似最低比特率 1 MBPS 和近似最高比特率 2.5 MBPS 时，视频流的分辨率为 1280x720，帧速率为 30 FPS。

Azure 通信服务 WebJS 通话 SDK 可根据可用带宽调整视频大小，以确保一致的通信体验。 WebJS 通话 SDK 可根据监视网络条件的算法调整视频大小。 当网络带宽充足时，SDK 会根据网页上定义的呈现大小将视频分辨率提高到其最高级别。 相反，当带宽有限时，它会降低视频分辨率，以防止缓冲并保持连接稳定。

下表提供了每个分辨率的分辨率等级、估计比特率以及在该分辨率下传输的相关 FPS。

使用媒体静力学来了解视频约束影响

若要在应用视频约束后评估和比较视频质量，可以访问 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);
});