RTCRtpSender: Methode replaceTrack()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

Die Methode replaceTrack() des RTCRtpSender ersetzt die momentan als Quelle des Senders verwendete Spur mit einer neuen MediaStreamTrack.

Die neue Spur muss vom gleichen Medientyp sein (Audio, Video usw.) und der Wechsel der Spur sollte keine Neuverhandlung erfordern.

Zu den Anwendungsfällen für replaceTrack() gehört der häufige Bedarf, zwischen den rückseitigen und den frontseitigen Kameras eines Telefons zu wechseln. Mit replaceTrack() können Sie ein Spur-Objekt für jede Kamera haben und bei Bedarf zwischen den beiden wechseln. Siehe das Beispiel Wechseln zwischen Videokameras unten.

Syntax

replaceTrack(newTrack)

Parameter

newTrack Optional: Ein MediaStreamTrack, der die Spur spezifiziert, mit der die aktuelle Quellspur des RTCRtpSender ersetzt werden soll. Die kind der neuen Spur muss mit der der aktuellen Spur übereinstimmen, sonst schlägt die Anforderung zum Ersetzen der Spur fehl.

Rückgabewert

Ein Promise, das erfüllt wird, sobald die Spur erfolgreich ersetzt wurde. Das Versprechen wird abgelehnt, wenn die Spur aus irgendeinem Grund nicht ersetzt werden kann; dies liegt häufig daran, dass die Änderung eine Neuverhandlung des Codecs erfordern würde, was nicht erlaubt ist (siehe Dinge, die eine Neuverhandlung erfordern).

Wenn newTrack weggelassen wurde oder null war, stoppt replaceTrack() den Sender. In diesem Fall ist keine Neuverhandlung erforderlich.

Wenn das Versprechen erfüllt ist, erhält der Erfüllungshandler einen Wert von undefined.

Ausnahmen

Wenn das zurückgegebene Versprechen abgelehnt wird, wird dem Ablehnungshandler einer der folgenden Ausnahmen bereitgestellt:

InvalidModificationError DOMException: Wird zurückgegeben, wenn das Ersetzen der aktuellen Spur des RTCRtpSender durch die neue eine Neuverhandlung erfordern würde.
InvalidStateError DOMException: Wird zurückgegeben, wenn die Spur, auf der diese Methode aufgerufen wurde, gestoppt statt ausgeführt wird.
TypeError: Wird zurückgegeben, wenn die kind der neuen Spur nicht mit der ursprünglichen Spur übereinstimmt.

Nutzungshinweise

Dinge, die eine Neuverhandlung erfordern

Die meisten Spurwechsel können ohne Neuverhandlung durchgeführt werden. Tatsächlich können sogar Änderungen, die groß erscheinen, ohne Neuverhandlung durchgeführt werden. Einige Änderungen können jedoch eine Neuverhandlung erfordern und damit dazu führen, dass replaceTrack() fehlschlägt:

Die neue Spur hat eine Auflösung, die außerhalb der mit dem Gegenüber verhandelten Dimensionen liegt; jedoch erlauben die meisten Browser-Endpunkte Änderungen der Auflösung.
Die Bildrate der neuen Spur ist hoch genug, um die Blockrate des Codecs zu überschreiten.
Die neue Spur ist eine Videospur und ihr Roh- oder Vorab-codierter Zustand unterscheidet sich von dem der ursprünglichen Spur.
Die neue Spur ist eine Audiospur mit einer anderen Anzahl von Kanälen als die ursprüngliche.
Medienquellen, die über integrierte Encoder verfügen — wie Hardware-Encoder — können möglicherweise den verhandelten Codec nicht bereitstellen. Softwarequellen implementieren möglicherweise den verhandelten Codec nicht.

Beispiele

Wechseln zwischen Videokameras

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

Spezifikationen

Specification
WebRTC: Real-Time Communication in Browsers # dom-rtcrtpsender-replacetrack

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch

WebRTC API