RTCRtpTransceiver: setCodecPreferences() 方法

setCodecPreferences() 方法是 RTCRtpTransceiver 接口的方法，用于设置转发器允许用于解码接收数据的编解码器，按优先级递减排序。

使用此方法设置的偏好会影响与远程对等端协商用于编码其发送数据的编解码器，包括用于重传、冗余和前向纠错的编解码器。不在偏好列表中的编解码器将不会作为协商的一部分。请注意，此转发器用于发送内容的偏好取决于远程对等端的偏好。

设置编解码器偏好的推荐方法是，首先获取实际支持解码接收数据的编解码器数组，然后按优先级递减排序。这确保了数组按要求排序，不包含任何不支持的编解码器，并且还包含用于重传、冗余和前向纠错所需的编解码器。

指定的编解码器集将用于所有包含此转发器的未来连接，直到再次调用此方法。

准备打开 RTCPeerConnection 时，应在调用 RTCPeerConnection.createOffer() 或 createAnswer()（它们会启动协商）之前使用 setCodecParameters() 设置编解码器，因为默认情况下，它们会使用 用户代理 的默认配置中的编解码器参数。

您可以在进行通信时更改编解码器，但需要先调用 setCodecParameters()，然后启动新的协商。WebRTC 应用程序已经在 negotiationneeded 事件处理程序 中包含了用于执行此操作的代码。但请注意，在撰写本文时，当您调用 setCodecParameters() 时不会自动触发此事件，因此您需要自己调用 onnegotiationneeded。

有关 WebRTC 支持的编解码器（以及每个编解码器的优缺点）的指南，请参阅 WebRTC 使用的编解码器。

语法

js
setCodecPreferences(codecs)

参数

codecs

一个对象数组，每个对象都提供转发器支持的 媒体编解码器 的参数，按优先级排序。如果 codecs 为空，则所有编解码器配置都将恢复为用户代理的默认值。

注意： codecs 中未包含的任何编解码器在协商连接的过程中都不会被考虑。这使您可以阻止使用您不想使用的编解码器。

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

channels 可选

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

clockRate

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

mimeType

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

sdpFmtpLine 可选

一个字符串，提供与编解码器相对应的 SDP 中 a=fmtp 行的格式特定参数字段（如果存在）。如果没有参数字段，则省略此属性。

返回值

无 (undefined).

异常

InvalidAccessError DOMException

codecs 列表中包含一个或多个与转发器关联的 RTCRtpReceiver 不支持的编解码器。

InvalidModificationError DOMException

codecs 列表仅包含 RTX、RED、FEC 或舒适噪声的条目，或者为空集。编解码器必须始终包含媒体的编解码器。

示例

创建首选编解码器数组

设置编解码器偏好的推荐方法是，首先获取实际支持解码接收数据的编解码器数组，然后按优先级递减排序。

从支持的编解码器列表（而不是硬编码的首选编解码器列表）开始非常重要，因为如果您包含与关联的 RTCRtpReceiver 不支持的任何编解码器，浏览器将在您调用 setCodecPreferences() 方法时抛出 InvalidAccessError 异常。此外，数组必须包含用于重传、冗余和前向纠错的适当编解码器，从支持的编解码器列表开始可确保这些编解码器存在。

您可以使用 RTCRtpReceiver.getCapabilities() 静态方法获取支持解码数据的编解码器，如下所示

js
const availReceiveCodecs = transceiver.receiver.getCapabilities("video").codecs;

为了按我们的首选顺序重新排序编解码器数组，我们可以使用下面的排序函数来按 MIME 类型排序（这来自 setCodecPreferences is now in all browsers! 博客文章，发布在 blog.mozilla.org 上 (2024)）。

js
function sortByMimeTypes(codecs, preferredOrder) {
  return codecs.sort((a, b) => {
    const indexA = preferredOrder.indexOf(a.mimeType);
    const indexB = preferredOrder.indexOf(b.mimeType);
    const orderA = indexA >= 0 ? indexA : Number.MAX_VALUE;
    const orderB = indexB >= 0 ? indexB : Number.MAX_VALUE;
    return orderA - orderB;
  });
}

该方法接受支持的编解码器列表和一个包含首选 MIME 类型（按优先级递减排序）的数组，并返回按位置排序的数组。下面的代码展示了如何在假设您已经设置了对等连接 (peerConnection) 的情况下使用该方法。

js
// Get supported codecs the sort using preferred codecs
const supportedCodecs = RTCRtpReceiver.getCapabilities("video").codecs;
const preferredCodecs = ["video/H264", "video/VP8", "video/VP9"];
const sortedCodecs = sortByMimeTypes(supportedCodecs, preferredCodecs);

// Get transceiver for connection and set the preferences
const [transceiver] = peerConnection.getTransceivers();
transceiver.setCodecPreferences(sortedCodecs); // <---

规范

规范
WebRTC：浏览器中的实时通信
# dom-rtcrtptransceiver-setcodecpreferences

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。

另请参阅