RTCRtpSender: replaceTrack() 方法

RTCRtpSender 方法replaceTrack()使用新的MediaStreamTrack替换当前用作发送方源的轨道。

新轨道必须与相同的媒体类型（音频、视频等）相同，并且切换轨道不应该需要协商。

replaceTrack() 的用例之一是常见的在手机上切换后置和前置摄像头的需求。使用 replaceTrack()，您可以为每个摄像头创建一个轨道对象，并在需要时在这两个摄像头之间切换。请参阅下面的示例切换视频摄像头。

语法

replaceTrack(newTrack)

参数

newTrack 可选: 一个MediaStreamTrack，指定用于替换 RTCRtpSender 当前源轨道的轨道。新轨道的 kind 必须与当前轨道的相同，否则替换轨道请求将失败。

返回值

一个Promise，在轨道成功替换后完成。如果由于任何原因无法替换轨道，则该 Promise 将被拒绝；这通常是因为更改需要重新协商编解码器，这是不允许的（请参阅需要协商的事项）。

如果 newTrack 被省略或为 null，则 replaceTrack() 将停止发送方。在这种情况下，不需要协商。

当 Promise 完成时，完成处理程序将接收 undefined 的值。

异常

如果返回的 Promise 被拒绝，则以下异常之一将提供给拒绝处理程序

InvalidModificationError DOMException: 如果用新的轨道替换 RTCRtpSender 的当前轨道需要协商，则返回。
InvalidStateError DOMException: 如果调用此方法的轨道已停止而不是正在运行，则返回。
TypeError: 如果新轨道的 kind 与原始轨道不匹配，则返回。

使用说明

需要协商的事项

大多数轨道替换可以在不重新协商的情况下完成。事实上，即使看起来很大的更改也可以在不需要协商的情况下完成。但是，某些更改可能需要协商，因此 replaceTrack() 将失败。

新轨道具有超出与对等方协商的尺寸范围的分辨率；但是，大多数浏览器端点允许更改分辨率。
新轨道的帧率足够高，以至于导致编解码器的块速率超出。
新轨道是视频轨道，其原始或预编码状态与原始轨道不同。
新轨道是音频轨道，其通道数与原始轨道不同。
具有内置编码器（例如硬件编码器）的媒体源可能无法提供协商的编解码器。软件源可能未实现协商的编解码器。

示例

切换视频摄像头

const localConnection = new RTCPeerConnection();
const remoteConnection = new RTCPeerConnection();
// Configuring these to use the WebRTC API can be explored at
// https://mdn.org.cn/en-US/docs/Web/API/WebRTC_API/Simple_RTCDataChannel_sample
const connections = [localConnection, remoteConnection];
function setCamera(selectedCamera) {
  navigator.mediaDevices
    .getUserMedia({
      video: {
        deviceId: {
          exact: selectedCamera,
        },
      },
    })
    .then((stream) => {
      const [videoTrack] = stream.getVideoTracks();
      connections.forEach((pc) => {
        const sender = pc
          .getSenders()
          .find((s) => s.track.kind === videoTrack.kind);
        console.log("Found sender:", sender);
        sender.replaceTrack(videoTrack);
      });
    })
    .catch((err) => {
      console.error(`Error happened: ${err}`);
    });
}

规范

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

浏览器兼容性

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

另请参阅

WebRTC API