MediaStream: removetrack — Ereignis · JavaScript-Referenz

Signatur

mediaStream.addEventListener("removetrack", handler)

Beschreibung

Das Ereignis removetrack wird an einem MediaStream ausgelöst, sobald eine Audio- oder Videospur (MediaStreamTrack) aus dem Stream entfernt wurde. Das Ereignisobjekt ist ein MediaStreamTrackEvent. Seine Eigenschaft track enthält die entfernte Spur.

Du kannst das Ereignis auf zwei Arten abonnieren: mit stream.addEventListener("removetrack", handler) oder über die Eigenschaft stream.onremovetrack = handler. addEventListener ist vorzuziehen, weil sich damit mehrere Handler registrieren und gezielt mit removeEventListener wieder entfernen lassen.

Am häufigsten braucht man das Ereignis bei WebRTC. Entfernt die Gegenstelle mit RTCPeerConnection.removeTrack() eine Spur und wird danach neu verhandelt, nimmt der Browser die Spur aus dem entfernten MediaStream heraus und löst removetrack aus. So kannst du die Oberfläche anpassen, etwa ein Kamera-aus-Symbol zeigen oder ein Videoelement ausblenden.

Wichtig: Das Ereignis wird nicht ausgelöst, wenn du selbst stream.removeTrack() aufrufst. Es meldet nur Änderungen, die der Browser vornimmt.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Name des Ereignisses: `"removetrack"`.
$handler Pflicht	(event: MediaStreamTrackEvent) => void		Callback-Funktion, die ein `MediaStreamTrackEvent` erhält. `event.track` ist die entfernte Spur, `event.target` ist der betroffene `MediaStream`.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once` oder `signal`, mit denen der Handler automatisch wieder abgemeldet wird.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Die Informationen stehen im übergebenen MediaStreamTrackEvent.

Beispiele

Entfernte WebRTC-Spur erkennen (addEventListener)

const pc = new RTCPeerConnection();
const remoteVideo = document.querySelector('#remote');

pc.addEventListener('track', ({ streams: [stream] }) => {
  if (remoteVideo.srcObject === stream) return;
  remoteVideo.srcObject = stream;

  stream.addEventListener('removetrack', (event) => {
    console.log(`Spur entfernt: ${event.track.kind} (${event.track.id})`);

    // Keine Videospur mehr? Dann Platzhalter anzeigen
    if (stream.getVideoTracks().length === 0) {
      remoteVideo.classList.add('kamera-aus');
    }
  });
});

Spur entfernt: video (3f2a…)

Über die on-Property und removeEventListener

const stream = new MediaStream();

const onRemove = (event) => {
  console.log('Entfernt:', event.track.kind);
};

// Variante 1: Eigenschaft (erlaubt nur einen Handler)
stream.onremovetrack = onRemove;

// Variante 2: addEventListener und später wieder abmelden
stream.addEventListener('removetrack', onRemove);
stream.removeEventListener('removetrack', onRemove);
stream.onremovetrack = null;

Handler mit AbortController aufräumen

const controller = new AbortController();

const watchStream = (stream) => {
  stream.addEventListener('removetrack', ({ track }) => {
    console.log(`${track.kind}-Spur weg, verbleibend: ${stream.getTracks().length}`);
  }, { signal: controller.signal });
};

// Beim Verlassen des Anrufs alle Handler auf einmal entfernen
const leaveCall = () => controller.abort();

audio-Spur weg, verbleibend: 1

Fallstrick: removeTrack() löst kein Ereignis aus

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

media.addEventListener('removetrack', () => console.log('Ereignis!'));

const [videoTrack] = media.getVideoTracks();
media.removeTrack(videoTrack); // eigener Aufruf, daher kein removetrack
console.log(media.getVideoTracks().length);

// Wichtig · Fallstricke

Kein Ereignis bei eigenen Aufrufen: stream.removeTrack() löst removetrack nicht aus. Wenn du selbst Spuren entfernst, aktualisiere die Oberfläche direkt im Code.
Nicht mit ended verwechseln: Beendet sich eine Spur, z. B. durch track.stop() oder wenn die Kamera getrennt wird, feuert ended am MediaStreamTrack. Die Spur bleibt dabei im Stream. removetrack meldet nur, dass die Spur aus dem Stream herausgenommen wurde.
Bei WebRTC kommt das Ereignis erst nach der Neuverhandlung (SDP-Austausch), also nicht sofort nach removeTrack() auf der Gegenseite.
onremovetrack nimmt nur einen Handler auf. Eine neue Zuweisung überschreibt den alten Handler.
Kompatibilität: wird in allen aktuellen Browsern unterstützt. Ältere Safari-Versionen haben entfernte Spuren teils unzuverlässig gemeldet, daher im Zweifel zusätzlich stream.getTracks() prüfen.

Siehe auch

MediaStream.prototype.removeTrack() MediaStreamTrackEvent MediaStream HTMLMediaElement: pause MediaStream: addtrack