RTCRtpSender: setParameters() 方法

语法

setParameters(parameters)

参数

parameters

一个参数对象，该对象之前是通过调用同一发送方的 getParameters() 方法获得的，并包含对发送方配置参数所需的更改。这些参数包括可用于编码发送方 track 的潜在编解码器。可用参数包括：

encodings

一个对象数组，每个对象指定一个可用于编码 track 媒体的编解码器的参数。对象的属性包括：

激活

将此值设置为 true（默认值）会使此编码被发送，而 false 会停止发送和使用它（但不会导致 SSRC 被移除）。

codec 可选

选择用于此编码的 RTP 流的 媒体编解码器。如果未设置，用户代理可以选择任何已协商用于发送的编解码器。

channels 可选

一个正整数，指示编解码器支持的通道数。例如，对于音频编解码器，值为 1 表示单声道，值为 2 表示立体声。

clockRate

一个正整数，指定编解码器的时钟频率（以赫兹 (Hz) 为单位）。时钟频率是编解码器的 RTP 时间戳前进的速率。大多数编解码器都有特定的允许值或允许值范围。IANA 维护着一个编解码器及其参数列表，包括其时钟频率。

mimeType

一个字符串，指示编解码器的 MIME 媒体类型和子类型，格式为 "type/subtype"。RTP 使用的 MIME 类型字符串与别处使用的不同。IANA 维护着一个有效 MIME 类型注册表。另请参阅 WebRTC 使用的编解码器，了解可能在此引用的潜在编解码器的详细信息。

sdpFmtpLine 可选

一个字符串，提供本地描述提供的格式特定参数。

dtx 已弃用 非标准

仅用于 RTCRtpSender 且其 kind 为 audio 的情况。此属性指示是否使用不间断传输（一种通过在没有语音活动时自动关闭电话或静音麦克风的功能）。值可以是 enabled 或 disabled。

maxBitrate

一个正整数，指示用户代理允许分配给使用此编码编码的轨道的每秒最大比特数。其他参数可能会进一步限制比特率，例如 maxFramerate 的值，或者可用于传输或物理网络的带宽。

该值使用标准“传输独立应用程序特定最大值 (TIAS)”带宽计算，如 RFC 3890，第 6.2.2 节所定义；这是在不考虑 IP、TCP 或 UDP 等协议开销的情况下所需的最大带宽。

请注意，比特率可以通过多种方式实现，具体取决于媒体和编码。例如，对于视频，低比特率可以通过丢帧来实现（零比特率可能只允许发送一帧），而对于音频，如果比特率过低无法发送，则轨道可能不得不停止播放。

maxFramerate

一个值，指定允许此编码的最大每秒帧数。

优先级

一个字符串，指示 RTCRtpSender 的优先级，这可能会决定用户代理如何在发送方之间分配带宽。允许的值为 very-low、low（默认）、medium、high。

rid

一个字符串，如果设置，指定要使用 RID 头部扩展发送的RTP 流 ID（RID）。此参数不能通过 setParameters() 修改。其值只能在收发信器首次创建时设置。

scaleResolutionDownBy

仅用于 track 的 kind 为 video 的发送方，这是一个浮点值，指定编码过程中视频缩小的系数。默认值 1.0 表示视频将以原始大小进行编码。值为 2.0 表示将视频帧的每个维度缩小 2 倍，resulting in a video 1/4 the size of the original。该值不得小于 1.0（尝试将视频放大到更大的尺寸将引发 RangeError）。

transactionId

一个包含唯一 ID 的字符串。此 ID 在之前的 getParameters() 调用中设置，并确保参数源自之前对 getParameters() 的调用。

codecs

一个对象数组，描述发送方将从中选择的 媒体编解码器。此参数在初始设置后无法更改。

数组中的每个编解码器对象可能具有以下属性：

channels 可选

一个正整数，指示编解码器支持的通道数。例如，对于音频编解码器，值为 1 表示单声道，值为 2 表示立体声。

clockRate

一个正整数，指定编解码器的时钟频率（以赫兹 (Hz) 为单位）。时钟频率是编解码器的 RTP 时间戳前进的速率。大多数编解码器都有特定的允许值或允许值范围。IANA 维护着一个编解码器及其参数列表，包括其时钟频率。

mimeType

一个字符串，指示编解码器的 MIME 媒体类型和子类型，格式为 "type/subtype"。RTP 使用的 MIME 类型字符串与别处使用的不同。IANA 维护着一个有效 MIME 类型注册表。另请参阅 WebRTC 使用的编解码器，了解可能在此引用的潜在编解码器的详细信息。

payloadType

用于标识此编解码器的 RTP 有效载荷类型。

sdpFmtpLine 可选

一个字符串，提供本地描述提供的格式特定参数。

headerExtensions

零个或多个 RTP 头部扩展的数组，每个扩展标识发送方支持的扩展。头部扩展在 RFC 3550，第 5.3.1 节中有描述。此参数无法更改。

rtcp

一个对象，提供用于发送方上 RTCP 的配置参数。此参数无法更改。

该对象可能具有以下属性：

cname

一个只读字符串，提供 RTCP 使用的规范名称 (CNAME)（例如，在 SDES 消息中）。

reducedSize

一个只读布尔值，如果配置了精简型 RTCP（RFC 5506），则为 true；如果指定了复合型 RTCP（RFC 3550），则为 false。

degradationPreference 已弃用

指定 WebRTC 层在带宽受限情况下优化带宽与质量的首选方式。可能的值为 maintain-framerate（保持帧率）、maintain-resolution（保持分辨率）或 balanced（平衡）。默认值为 balanced。

返回值

一个 Promise，当 RTCRtpSender.track 属性使用给定参数更新时，该 Promise 会解决。

异常

如果发生错误，返回的 Promise 将以以下列表中的相应异常被拒绝。

InvalidModificationError DOMException

当检测到以下问题之一时返回：

• parameters 对象中的 encodings 属性指定的编码数量与 RTCRtpSender 当前列出的编码数量不匹配。发送方创建后，您无法更改编码选项的数量。
• 指定的 encodings 的顺序与当前列表的顺序不同。
• 尝试修改发送方首次创建后无法更改的属性。

InvalidStateError DOMException

当发送方所在的收发信器未运行或没有要设置的参数时返回。

OperationError DOMException

当发生此处未指定的错误时返回。

RangeError

当 scaleResolutionDownBy 选项的值小于 1.0（这将导致放大而不是缩小，这是不允许的）时返回；或者当指定的一个或多个 encodings maxFramerate 值小于 0.0 时返回。

此外，如果在配置或访问媒体时发生 WebRTC 错误，将抛出 RTCError，其 errorDetail 设置为 hardware-encoder-error。

描述

重要的是要记住，您无法自己创建 parameters 对象并期望它能正常工作。相反，您必须先调用 getParameters()，修改接收到的参数对象，然后将该对象传递给 setParameters()。WebRTC 使用参数对象的 transactionId 属性来确保当您设置参数时，您的更改是基于最新的参数而不是过时的配置。

示例

setParameters() 的一个用例是在带宽受限的环境中，通过更改 RTCRtpSender 传输的媒体的分辨率和/或比特率来尝试减少网络带宽使用。

目前，一些浏览器对其实现存在限制，可能导致问题。因此，这里给出了两个示例。第一个示例展示了当所有浏览器完全支持所使用的参数时如何使用 setParameters()，而第二个示例演示了如何使用解决方法来帮助解决对 maxBitrate 和 scaleResolutionDownBy 参数支持不完整的浏览器中的问题。

根据规范

一旦所有浏览器都完全实现规范，setVideoParams() 的此实现将完成工作。这演示了所有应该如何工作。目前，您可能应该使用下面的第二个示例。但这更清晰地展示了首先获取参数，然后修改它们，然后设置它们的という基本概念。

async function setVideoParams(sender, height, bitrate) {
  const scaleRatio = sender.track.getSettings().height / height;
  const params = sender.getParameters();

  params.encodings[0].scaleResolutionDownBy = Math.max(scaleRatio, 1);
  params.encodings[0].maxBitrate = bitrate;
  await sender.setParameters(params);
}

通过调用此函数，您可以指定一个发送方，以及您希望将发送方的视频缩放到哪个高度，以及允许发送方传输的最大比特率。将计算出视频尺寸的缩放因子 scaleRatio。然后使用 getParameters() 获取发送方的当前参数。

然后通过更改第一个 encodings 对象的 scaleResolutionDownBy 和 maxBitrate 分别设置为计算出的缩放因子和指定的最高 bitrate 来修改参数。

然后通过调用发送方的 setParameters() 方法来保存已更改的参数。

当前兼容的实现

如上所述，前面的示例展示了事情的本应如何工作。不幸的是，目前许多浏览器中存在实现问题。因此，如果您想兼容 iPhone 和运行 Safari 的其他设备以及 Firefox，请使用更像这样的代码：

async function setVideoParams(sender, height, bitrate) {
  const scaleRatio = sender.track.getSettings().height / height;
  const params = sender.getParameters();

  // If encodings is null, create it
  params.encodings ??= [{}];
  params.encodings[0].scaleResolutionDownBy = Math.max(scaleRatio, 1);
  params.encodings[0].maxBitrate = bitrate;
  await sender.setParameters(params);

  // If the newly changed value of scaleResolutionDownBy is 1,
  // use applyConstraints() to be sure the height is constrained,
  // since scaleResolutionDownBy may not be implemented

  if (sender.getParameters().encodings[0].scaleResolutionDownBy === 1) {
    await sender.track.applyConstraints({ height });
  }
}

这里的主要区别

• 如果 encodings 为 null，我们将创建它，以确保随后可以成功设置参数而不崩溃。
• 如果在设置参数后，scaleResolutionDownBy 的值仍然为 1，我们将调用发送方 track 的 applyConstraints() 方法来将 track 的高度限制为 height。这可以弥补 scaleResolutionDownBy 的未实现（正如目前 Safari 的情况）。

如果浏览器完全实现了所使用的功能，此代码将干净地回退并正常工作。

规范

浏览器兼容性

另见

• WebRTC API
• WebRTC 使用的编解码器
• Web 媒体技术