MediaStream: addtrack — Ereignis · JavaScript-Referenz

Signatur

mediaStream.addEventListener("addtrack", handler)

Beschreibung

Der Browser löst das Ereignis addtrack an einem MediaStream aus, sobald dem Stream eine neue Spur (MediaStreamTrack) hinzugefügt wurde. Übergeben wird ein MediaStreamTrackEvent. Dessen Eigenschaft track enthält die neu hinzugekommene Audio- oder Videospur.

Wichtig: Das Ereignis wird nur ausgelöst, wenn der Browser selbst die Spur hinzufügt. Das passiert typischerweise bei einem entfernten Stream aus einer RTCPeerConnection: Fügt die Gegenseite während einer Neuverhandlung eine Spur hinzu, erscheint sie im zugehörigen Remote-Stream. Rufst du dagegen selbst stream.addTrack(track) auf, wird kein addtrack-Ereignis ausgelöst.

Du kannst den Handler auf zwei Arten registrieren:

mit stream.addEventListener("addtrack", handler). Diese Variante empfiehlt sich, weil sie mehrere Handler zulässt.
über die Eigenschaft stream.onaddtrack = handler.

Gut geeignet ist das Ereignis, um die Oberfläche anzupassen, wenn eine Spur neu dazukommt. Zum Beispiel kannst du bei einer Videokonferenz den Stummschalt-Hinweis ausblenden, sobald die Gegenseite ihr Mikrofon zuschaltet, oder ein Video-Element einblenden. Das Gegenstück ist das Ereignis removetrack.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"addtrack"`.
$handler Pflicht	(event: MediaStreamTrackEvent) => void		Callback-Funktion. Sie erhält ein `MediaStreamTrackEvent`, dessen Eigenschaft `event.track` die hinzugefügte `MediaStreamTrack` enthält.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal` (`AbortSignal` zum Entfernen des Listeners).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein MediaStreamTrackEvent (erbt von Event, nicht abbrechbar, blubbert nicht).

Beispiele

Neue Spuren eines entfernten WebRTC-Streams erkennen

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

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

  // Spätere Spuren (z. B. nach einer Neuverhandlung) melden
  remoteStream.addEventListener('addtrack', (event) => {
    const { kind, label, id } = event.track;
    console.log(`Neue ${kind}-Spur: ${label || id}`);
    if (kind === 'audio') {
      document.querySelector('#muted-badge').hidden = true;
    }
  });
});

Neue audio-Spur: 3f2a9c1e-...

Handler über onaddtrack setzen und wieder entfernen

const stream = new MediaStream();

// Variante 1: on-Property (nur ein Handler möglich)
stream.onaddtrack = (event) => {
  console.log('Spur hinzugefügt:', event.track.kind);
};

// Variante 2: addEventListener und removeEventListener
const onAddTrack = (event) => console.log('Listener:', event.track.id);
stream.addEventListener('addtrack', onAddTrack);

// Später aufräumen
stream.removeEventListener('addtrack', onAddTrack);
stream.onaddtrack = null;

Achtung: stream.addTrack() löst kein Ereignis aus

const run = async () => {
  const media = await navigator.mediaDevices.getUserMedia({ audio: true });
  const stream = new MediaStream();

  stream.addEventListener('addtrack', () => {
    console.log('addtrack ausgelöst');
  });

  stream.addTrack(media.getAudioTracks()[0]);
  console.log('Spuren im Stream:', stream.getTracks().length);
};

run();

Spuren im Stream: 1 (kein "addtrack ausgelöst", weil die Spur vom Skript hinzugefügt wurde)

// Wichtig · Fallstricke

Häufigster Fallstrick: MediaStream.prototype.addTrack() und clone() lösen kein addtrack aus. Das Ereignis kommt nur, wenn der Browser die Spur hinzufügt, praktisch vor allem bei entfernten Streams einer RTCPeerConnection. Wenn du selbst Spuren hinzufügst, musst du deine Oberfläche direkt im eigenen Code aktualisieren.
Verwechsle das Ereignis nicht mit RTCPeerConnection: track. Dieses wird für jede eingehende Spur ausgelöst, oft bevor du überhaupt einen Listener am Stream registrieren konntest. Für den ersten Aufbau ist pc.ontrack deshalb meist der zuverlässigere Weg.
Es gibt auch addtrack-Ereignisse an AudioTrackList, VideoTrackList und TextTrackList von Media-Elementen. Das sind andere Ereignisse mit anderem Ereignistyp (TrackEvent).
Browser-Kompatibilität: Chrome, Edge, Firefox und Safari unterstützen das Ereignis. In älteren Safari-Versionen gibt es Unterschiede bei WebRTC-Neuverhandlungen. Teste deshalb dort gezielt.
Das Ereignis ist nicht abbrechbar (cancelable: false) und blubbert nicht.

Siehe auch

MediaStream MediaStream.prototype.addTrack() MediaStreamTrackEvent MediaStreamTrack EventTarget.prototype.addEventListener()