RTCPeerConnection: track — Ereignis · JavaScript-Referenz

Signatur

peerConnection.addEventListener("track", handler)

Beschreibung

Das track-Ereignis tritt ein, wenn beim Verhandeln einer WebRTC-Verbindung (nach setRemoteDescription()) ein neuer eingehender Medien-Track zu einem RTCRtpReceiver der Verbindung hinzukommt. Der Handler bekommt ein RTCTrackEvent mit den Eigenschaften track (der MediaStreamTrack), streams (Array der zugehörigen MediaStream-Objekte), receiver und transceiver.

Das ist der Einstiegspunkt, um Audio und Video der Gegenstelle anzuzeigen: Normalerweise weist man event.streams[0] der Eigenschaft srcObject eines <video>- oder <audio>-Elements zu. Das Ereignis wird für jeden Track einzeln ausgelöst – bei Audio und Video also in der Regel zweimal.

Man kann das Ereignis mit pc.addEventListener("track", handler) abonnieren oder die Eigenschaft pc.ontrack = handler setzen. Es ersetzt das veraltete addstream-Ereignis (onaddstream).

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"track"`.
$handler Pflicht	(event: RTCTrackEvent) => void		Callback, der ein `RTCTrackEvent` mit `track`, `streams`, `receiver` und `transceiver` erhält.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal` (zum Entfernen über einen `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener() gibt nichts zurück; der Handler erhält ein RTCTrackEvent.

Beispiele

Entfernten Stream im Video-Element anzeigen (addEventListener)

const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
});
const remoteVideo = document.querySelector('#remote');

pc.addEventListener('track', (event) => {
  console.log('Neuer Track:', event.track.kind);
  const [stream] = event.streams;
  // Nur einmal zuweisen, da das Ereignis pro Track feuert
  if (stream && remoteVideo.srcObject !== stream) {
    remoteVideo.srcObject = stream;
  }
});

Neuer Track: audio Neuer Track: video

ontrack-Eigenschaft mit Fallback für Tracks ohne Stream

const pc = new RTCPeerConnection();
const remoteStream = new MediaStream();
document.querySelector('#remote').srcObject = remoteStream;

pc.ontrack = ({ track, streams, transceiver }) => {
  // Gegenstelle hat addTrack() ohne Stream aufgerufen → streams ist leer
  if (streams.length === 0) {
    remoteStream.addTrack(track);
  }
  console.log(`Track ${track.id} über mid=${transceiver.mid}`);

  track.addEventListener('ended', () => {
    remoteStream.removeTrack(track);
  });
};

Track 3f2a... über mid=0

Listener per AbortController wieder entfernen

const pc = new RTCPeerConnection();
const controller = new AbortController();

const onTrack = (event) => {
  console.log('Empfangen:', event.track.kind, event.track.label);
};

pc.addEventListener('track', onTrack, { signal: controller.signal });

// Beim Auflegen: Listener entfernen und Verbindung schließen
const hangUp = () => {
  controller.abort(); // entspricht pc.removeEventListener('track', onTrack)
  pc.close();
};

// Wichtig · Fallstricke

Das Ereignis wird pro Track ausgelöst. Wer bei jedem Aufruf srcObject neu setzt, riskiert Flackern oder abgebrochene play()-Promises – vorher prüfen, ob der Stream bereits gesetzt ist.
event.streams kann leer sein, wenn die Gegenstelle addTrack(track) ohne Stream-Argument aufruft. Dann den Track manuell in einen eigenen MediaStream einfügen.
Das Ereignis feuert während setRemoteDescription() – den Handler also vor dem Verbindungsaufbau registrieren, sonst verpasst man Tracks.
Ein entfernter Track wird nicht durch ein eigenes Ereignis auf der Verbindung gemeldet; stattdessen feuert removetrack auf dem MediaStream bzw. mute/ended auf dem Track.
Autoplay-Richtlinien: Videos mit Ton starten ggf. nur nach Nutzerinteraktion; muted/playsinline (iOS Safari) setzen.
Das veraltete onaddstream nicht mehr verwenden; ontrack wird von allen aktuellen Browsern unterstützt.

Siehe auch

RTCPeerConnection RTCTrackEvent RTCPeerConnection.addTrack() RTCPeerConnection.setRemoteDescription() RTCRtpReceiver MediaStreamTrack HTMLMediaElement.srcObject