RTCTrackEvent.track — Eigenschaft · JavaScript-Referenz

Signatur

RTCTrackEvent.track

Beschreibung

Die Eigenschaft track gehört zum RTCTrackEvent, das eine RTCPeerConnection beim Ereignis track auslöst. Sie verweist auf den MediaStreamTrack (Audio oder Video), den die Gegenseite neu übertragen hat und der jetzt lokal empfangen wird.

Gebraucht wird sie vor allem, um entfernte Medien darzustellen: Man hängt den Track an ein <video>- oder <audio>-Element an, meist über einen MediaStream, der als srcObject gesetzt wird. Über track.kind ("audio" oder "video") lässt sich unterscheiden, um welche Art Medium es geht.

Der Track ist identisch mit event.receiver.track und event.transceiver.receiver.track. Gehört er zu einem oder mehreren Streams der Gegenseite, stehen diese in event.streams. Kommt der Track ohne Stream-Zuordnung an (z. B. bei addTrack(track) ohne Stream-Argument), ist event.streams leer. Dann muss man selbst einen MediaStream anlegen.

Rückgabewert

Typ

MediaStreamTrack

Beschreibung

Der empfangene MediaStreamTrack, der mit dem RTCRtpReceiver des Ereignisses verknüpft ist. Die Eigenschaft ist schreibgeschützt.

Beispiele

Entfernten Track in einem Video-Element anzeigen

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

pc.addEventListener('track', (event) => {
  const { track, streams } = event;
  console.log(`Neuer ${track.kind}-Track: ${track.id}`);

  // Stream der Gegenseite nutzen, falls vorhanden
  if (streams.length > 0) {
    remoteVideo.srcObject = streams[0];
  } else {
    // Kein Stream mitgeliefert: selbst einen anlegen
    remoteVideo.srcObject ??= new MediaStream();
    remoteVideo.srcObject.addTrack(track);
  }
});

Neuer video-Track: 3f2a…

Audio und Video getrennt verarbeiten (on-Property)

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

pc.ontrack = ({ track }) => {
  remoteStream.addTrack(track);

  if (track.kind === 'audio') {
    console.log('Audio empfangen, Status:', track.readyState);
  }

  // Aufräumen, wenn die Gegenseite den Track beendet
  track.addEventListener('ended', () => {
    remoteStream.removeTrack(track);
    console.log(`${track.kind}-Track beendet`);
  });
};

Audio empfangen, Status: live

Stummschalten der Gegenseite erkennen

const pc = new RTCPeerConnection();

pc.addEventListener('track', ({ track }) => {
  // mute/unmute zeigen an, ob gerade RTP-Daten ankommen
  track.onmute = () => console.log(`${track.kind} pausiert`);
  track.onunmute = () => console.log(`${track.kind} läuft wieder`);

  console.log('Identisch mit receiver.track:', track === pc.getReceivers().find(r => r.track === track)?.track);
});

Identisch mit receiver.track: true

// Wichtig · Fallstricke

Schreibgeschützt: Zuweisungen an event.track werden ignoriert (im Strict Mode gibt es einen TypeError).
Leeres streams-Array: Nicht blind event.streams[0] verwenden. Ohne Stream-Zuordnung durch den Sender ist das Array leer, dann den Track per MediaStream.addTrack() selbst einbinden.
Mehrfaches Auslösen: Das track-Ereignis kommt einmal pro Track. Bei Audio und Video also zweimal, meist mit demselben Stream. Beim Setzen von srcObject auf doppelte Zuweisungen achten.
Mute-Status: Ein neu empfangener Track kann anfangs muted sein, bis RTP-Pakete eintreffen. ended tritt ein, wenn die Gegenseite den Transceiver stoppt oder die Verbindung schließt. removeTrack() auf der Gegenseite beendet den Track dagegen nicht, sondern schaltet ihn nur stumm.
Kompatibilität: Alle modernen Browser unterstützen die Eigenschaft. Das veraltete Ereignis addstream mit event.stream sollte man nicht mehr verwenden.

Siehe auch

RTCTrackEvent RTCTrackEvent.streams RTCTrackEvent.receiver RTCTrackEvent.transceiver RTCPeerConnection.prototype.addTrack() MediaStreamTrack MediaStream