MediaStream.removeTrack() — Methode · JavaScript-Referenz

Signatur

MediaStream.prototype.removeTrack(track)

Beschreibung

Die Methode removeTrack() nimmt einen MediaStreamTrack aus der Track-Menge eines MediaStream heraus. Danach liefern getTracks(), getAudioTracks() und getVideoTracks() diesen Track nicht mehr zurück. Ist der Track gar nicht im Stream enthalten, passiert nichts. Es wird also keine Ausnahme geworfen.

Wichtig: removeTrack() stoppt den Track nicht. Kamera oder Mikrofon bleiben aktiv, solange der Track noch läuft. Wenn du die Hardware freigeben willst, musst du zusätzlich track.stop() aufrufen. Das Entfernen ändert nur, wie der Stream zusammengesetzt ist. So kannst du zum Beispiel einem Vorschau-Stream die Tonspur wegnehmen, während sie an anderer Stelle weiterläuft.

Typische Einsatzfälle sind: Streams für die Aufnahme mit MediaRecorder zusammenstellen, Kamera oder Bildschirmfreigabe in einem Vorschau-Stream austauschen oder die Audiospur aus einer lokalen Videovorschau entfernen. Bei WebRTC-Verbindungen reicht MediaStream.removeTrack() nicht aus, damit der Track auch beim Gegenüber verschwindet. Dafür nutzt du RTCPeerConnection.removeTrack(sender) oder RTCRtpSender.replaceTrack().

Parameter

Name	Typ	Default	Beschreibung
$track Pflicht	MediaStreamTrack		Der Track, der aus dem Stream entfernt werden soll. Übergibst du keinen `MediaStreamTrack`, wirft die Methode einen `TypeError`.

Beispiele

Audiospur aus der lokalen Vorschau entfernen

const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });

// Tonspur aus dem Stream nehmen und das Mikrofon freigeben
const [audioTrack] = stream.getAudioTracks();
stream.removeTrack(audioTrack);
audioTrack.stop();

document.querySelector('video').srcObject = stream;
console.log(stream.getTracks().map(t => t.kind));

["video"]

Kamera gegen Bildschirmfreigabe austauschen

const preview = await navigator.mediaDevices.getUserMedia({ video: true });
const videoEl = document.querySelector('#preview');
videoEl.srcObject = preview;

const switchToScreen = async () => {
  const screen = await navigator.mediaDevices.getDisplayMedia({ video: true });
  const [screenTrack] = screen.getVideoTracks();

  // Alte Kameraspuren entfernen und stoppen
  for (const camTrack of preview.getVideoTracks()) {
    preview.removeTrack(camTrack);
    camTrack.stop();
  }
  preview.addTrack(screenTrack);
};

document.querySelector('#share').addEventListener('click', switchToScreen);

Auf das removetrack-Ereignis reagieren

const stream = await navigator.mediaDevices.getUserMedia({ audio: true, video: true });

// removetrack wird nur ausgelöst, wenn der Browser den Track selbst entfernt
// (z. B. bei WebRTC-Remote-Streams), nicht bei eigenem removeTrack()-Aufruf
stream.addEventListener('removetrack', (e) => {
  console.log('Track entfernt:', e.track.kind);
});

const [video] = stream.getVideoTracks();
stream.removeTrack(video);
console.log(stream.getVideoTracks().length);

// Wichtig · Fallstricke

Der Track wird nicht gestoppt: Wenn du nur removeTrack() aufrufst, bleiben Kamera oder Mikrofon aktiv, und die Aufnahme-Anzeige im Browser bleibt an. Für die Freigabe musst du zusätzlich track.stop() aufrufen.
Kein removetrack-Ereignis bei eigenem Aufruf: Das Ereignis removetrack wird nur ausgelöst, wenn der Browser selbst einen Track entfernt, etwa bei Remote-Streams in WebRTC. Ruft dein Skript removeTrack() auf, wird es nicht ausgelöst.
Sind alle Tracks entfernt oder beendet, kann stream.active den Wert false annehmen, und der Stream löst dann inactive aus. Das Verhalten ist nicht in allen Browsern gleich.
Ein laufender MediaRecorder reagiert auf geänderte Tracks je nach Browser mit einem Fehler oder beendet die Aufnahme. Stelle die Tracks deshalb möglichst vor dem Start zusammen.
Bei WebRTC wirkt sich MediaStream.removeTrack() nicht auf die Übertragung aus. Nutze dafür RTCPeerConnection.removeTrack() oder RTCRtpSender.replaceTrack().
Unterstützt von allen modernen Browsern (Chrome, Edge, Firefox, Safari). Der Zugriff auf Kamera und Mikrofon setzt einen sicheren Kontext (HTTPS) voraus.

Siehe auch

MediaKeyStatusMap.entries() MediaStream.addTrack() MediaStream.getTracks() MediaStream.getVideoTracks() MediaStream.getAudioTracks()