RTCRtpSender: метод replaceTrack()

Базовая Широко доступная

Эта функция хорошо отработана и работает на многих устройствах и версиях браузеров. Она доступна в браузерах с января 2020 года.

Метод RTCRtpSender replaceTrack() заменяет текущий трек, используемый в качестве источника отправителя, на новый MediaStreamTrack.

Новый трек должен быть того же типа медиа (аудио, видео и т.д.), и переключение треков не должно требовать переговор.

Среди вариантов использования replaceTrack() — распространенная необходимость переключения между задней и передней камерами на телефоне. С помощью replaceTrack(), вы можете иметь объект трека для каждой камеры и переключаться между ними по мере необходимости. См. пример переключения видеокамер ниже.

Синтаксис

replaceTrack(newTrack)

Параметры

newTrack Необязательно: MediaStreamTrack, определяющий трек, которым необходимо заменить текущий источник RTCRtpSender. Тип нового трека kind должен совпадать с текущим, иначе запрос на замену трека завершится ошибкой.

Возвращаемое значение

Promise , который выполняется, когда трек успешно заменен. Обещание отклоняется, если трек нельзя заменить по какой-либо причине; это обычно происходит, потому что изменение требует повторного согласования кодека, что не разрешено (см. Требующие переговор аспекты).

Если newTrack был опущен или был null, replaceTrack() останавливает отправитель. В этом случае переговор не требуется.

При выполнении обещания обработчик выполнения получает значение undefined.

Исключения

Если возвращаемое обещание отклонено, обработчик отклонения получает одно из следующих исключений:

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://developer.mozilla.org/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

Совместимость с браузерами

	Рабочий стол					Мобильный
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox для Android	Opera Android	Safari на iOS	Samsung Internet	WebView Android
`replaceTrack`	65	79	34	52	11	65	34	47	11	9.0	65

См. также

API WebRTC

© 2005–2024 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/RTCRtpSender/replaceTrack