MediaStreamTrackEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface MediaStreamTrackEvent extends Event

Beschreibung

Die Schnittstelle MediaStreamTrackEvent gehört zur Media Capture and Streams API. Sie beschreibt die Ereignisse addtrack und removetrack, die ein MediaStream auslöst, wenn sich die Menge seiner Audio- oder Videospuren ändert. Sie erbt von Event und hat zusätzlich genau eine Eigenschaft: track. Diese schreibgeschützte Eigenschaft verweist auf den betroffenen MediaStreamTrack.

Wichtig: Beide Ereignisse lösen nur aus, wenn der Browser (User Agent) den Stream verändert. Eigene Aufrufe von stream.addTrack() oder stream.removeTrack() lösen kein Ereignis aus. Typisch ist das bei WebRTC: Ein MediaStream aus RTCPeerConnection bekommt Spuren hinzu oder verliert welche, wenn die Gegenstelle neu verhandelt, zum Beispiel beim Zu- oder Abschalten der Kamera.

Sie können die Ereignisse mit addEventListener("addtrack", …) bzw. addEventListener("removetrack", …) abonnieren. Alternativ gibt es die Eigenschaften onaddtrack und onremovetrack. Mit dem Konstruktor new MediaStreamTrackEvent(type, { track }) können Sie solche Ereignisse auch selbst erzeugen, etwa für Tests oder eigene Ereignis-Pipelines.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, der Groß- und Kleinschreibung beachtet. In der Praxis `"addtrack"` oder `"removetrack"`.
$eventInitDict Pflicht	{ track: MediaStreamTrack, bubbles?: boolean, cancelable?: boolean, composed?: boolean }		Einstellungs-Objekt für den Konstruktor. `track` ist Pflicht und gibt den betroffenen `MediaStreamTrack` an. Die übrigen Felder stammen aus `EventInit` und sind standardmäßig `false`.

Rückgabewert

Typ

MediaStreamTrackEvent

Beschreibung

Ein neues Ereignis-Objekt. Die schreibgeschützte Eigenschaft track (MediaStreamTrack) enthält die Spur, die hinzugefügt oder entfernt wurde.

Beispiele

Neue Spuren eines WebRTC-Streams erkennen

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

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

  // Wird ausgelöst, wenn die Gegenstelle später weitere Spuren sendet
  stream.addEventListener('addtrack', (event) => {
    console.log(`Neue ${event.track.kind}-Spur:`, event.track.label);
  });

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

Neue video-Spur: … video-Spur entfernt (id: 3f2a…)

onremovetrack-Eigenschaft und Listener wieder entfernen

const handleAdd = (event) => {
  console.log('Hinzugefügt:', event.track.kind);
};

const attach = (stream) => {
  stream.addEventListener('addtrack', handleAdd);
  // Alternative Schreibweise über die on-Eigenschaft
  stream.onremovetrack = ({ track }) => {
    console.log('Entfernt:', track.kind);
    if (stream.getTracks().length === 0) {
      console.log('Stream ist leer');
    }
  };
};

const detach = (stream) => {
  stream.removeEventListener('addtrack', handleAdd);
  stream.onremovetrack = null;
};

Ereignis selbst erzeugen und auslösen (z. B. für Tests)

const main = async () => {
  const media = await navigator.mediaDevices.getUserMedia({ audio: true });
  const [audioTrack] = media.getAudioTracks();

  const stream = new MediaStream();
  stream.addEventListener('addtrack', (e) => {
    console.log(e instanceof MediaStreamTrackEvent, e.track.kind);
  });

  // addTrack() selbst löst KEIN Ereignis aus – daher manuell:
  stream.addTrack(audioTrack);
  stream.dispatchEvent(new MediaStreamTrackEvent('addtrack', { track: audioTrack }));
};

main();

true audio

// Wichtig · Fallstricke

Häufiger Fallstrick: stream.addTrack() und stream.removeTrack() lösen kein addtrack- bzw. removetrack-Ereignis aus. Die Ereignisse kommen nur, wenn der Browser den Stream verändert, typischerweise bei WebRTC-Streams der Gegenstelle.
Ein beendeter Track (track.stop() oder das Ereignis ended) wird dadurch nicht aus dem Stream entfernt, und es gibt auch kein removetrack. Wenn Sie das Ende einer Spur erkennen wollen, reagieren Sie zusätzlich auf ended am MediaStreamTrack.
Bei WebRTC ist das track-Ereignis von RTCPeerConnection (Typ RTCTrackEvent) meist der bessere Weg, um eingehende Spuren zu erkennen. MediaStreamTrackEvent ist eine andere Schnittstelle.
Der Konstruktor wirft einen TypeError, wenn im Einstellungs-Objekt track fehlt.
Kompatibilität: Alle aktuellen Browser unterstützen die Schnittstelle. getUserMedia funktioniert nur in sicheren Kontexten (HTTPS oder localhost).

Siehe auch

Event MediaStreamEvent MediaStreamTrack MediaStreamTrackGenerator MediaStreamTrackProcessor