MediaStreamTrackEvent.track — Eigenschaft · JavaScript-Referenz

Signatur

MediaStreamTrackEvent.track

Beschreibung

Die Eigenschaft track eines MediaStreamTrackEvent verweist auf die Audio- oder Videospur, um die es bei dem Ereignis geht. Solche Ereignisse löst ein MediaStream aus, und zwar als addtrack, wenn eine Spur hinzukommt, und als removetrack, wenn eine entfernt wird.

Nützlich ist das vor allem bei WebRTC: Ein entfernter Teilnehmer kann während einer laufenden Verbindung Spuren hinzufügen oder entfernen, zum Beispiel die Kamera ein- und ausschalten oder eine Bildschirmfreigabe starten. Über event.track erfahren Sie, welche Spur betroffen ist (kind, id, label), und können die Oberfläche darauf abstimmen.

Wichtig: Die Ereignisse werden laut Spezifikation nur ausgelöst, wenn der Browser den Stream verändert, etwa durch eine WebRTC-Neuaushandlung. Rufen Sie selbst stream.addTrack() oder stream.removeTrack() auf, wird kein Ereignis ausgelöst.

Rückgabewert

Typ

MediaStreamTrack

Beschreibung

Die Spur (MediaStreamTrack), die dem Stream hinzugefügt oder aus ihm entfernt wurde. Der Wert ist schreibgeschützt und wird beim Erzeugen des Ereignisses festgelegt.

Beispiele

Neue Spuren eines entfernten WebRTC-Streams erkennen

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

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

  // Später hinzukommende Spuren (z. B. eine Bildschirmfreigabe)
  remoteStream.addEventListener('addtrack', (event) => {
    const { kind, id, label } = event.track;
    console.log(`Neue ${kind}-Spur: ${label || id}`);
  });
});

Neue video-Spur: 3f1c9a2e-…

Entfernte Spur per onremovetrack behandeln

const handleStream = (stream) => {
  stream.onremovetrack = (event) => {
    const track = event.track;
    console.log(`Spur entfernt: ${track.kind} (${track.id})`);

    if (track.kind === 'video') {
      document.querySelector('#camera-off').hidden = false;
    }
  };
};

Spur entfernt: video (3f1c9a2e-…)

Ereignis selbst erzeugen und track auslesen

const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const [audioTrack] = stream.getAudioTracks();

stream.addEventListener('addtrack', (e) => {
  console.log(e.track === audioTrack, e.track.kind);
});

// Konstruktor verlangt das track-Feld
const event = new MediaStreamTrackEvent('addtrack', { track: audioTrack });
stream.dispatchEvent(event);

true audio

// Wichtig · Fallstricke

addTrack() und removeTrack() auf einem MediaStream lösen keine addtrack- bzw. removetrack-Ereignisse aus. Die Ereignisse gibt es nur bei Änderungen durch den Browser, etwa bei WebRTC.
Verwechseln Sie das nicht mit dem track-Ereignis von RTCPeerConnection. Dort ist das Ereignisobjekt ein RTCTrackEvent, das zusätzlich streams, receiver und transceiver enthält.
Nach einem removetrack hat die Spur nicht unbedingt readyState === "ended". Rufen Sie bei Bedarf selbst track.stop() auf, um Ressourcen freizugeben.
Der Konstruktor new MediaStreamTrackEvent(type, { track }) wirft einen TypeError, wenn track fehlt.
Browser-Unterstützung: Chrome, Edge, Firefox und Safari unterstützen die Eigenschaft in aktuellen Versionen. Die Medien-APIs setzen einen sicheren Kontext (HTTPS) voraus.

Siehe auch

MediaStreamTrackEvent MediaStreamTrack MediaStream RTCTrackEvent MediaQueryListEvent.media