new RTCTrackEvent() — Methode · JavaScript-Referenz

Signatur

new RTCTrackEvent(type, options)

Beschreibung

Der Konstruktor RTCTrackEvent() erstellt ein Ereignisobjekt vom Typ RTCTrackEvent. Solche Ereignisse löst der Browser normalerweise selbst als track-Ereignis auf einer RTCPeerConnection aus, sobald bei der Verhandlung (SDP-Austausch) ein neuer eingehender Medien-Track auftaucht. Das Objekt enthält dann den MediaStreamTrack, den zugehörigen RTCRtpReceiver, den RTCRtpTransceiver und die Liste der MediaStreams, zu denen der Track gehört.

Selbst aufrufen muss man den Konstruktor nur selten. Nützlich ist er vor allem in Unit-Tests, beim Mocken von WebRTC-Verbindungen oder wenn eine eigene Abstraktionsschicht ein bereits vorhandenes Track-Ereignis an andere Listener weiterreichen soll, z. B. über ein eigenes EventTarget.

Wichtig: Die Felder receiver, track und transceiver im Optionsobjekt sind Pflicht. Echte Instanzen von RTCRtpReceiver und RTCRtpTransceiver lassen sich nicht direkt erzeugen, man bekommt sie nur über eine RTCPeerConnection (etwa mit addTransceiver()). Ein selbst erzeugtes Ereignis ist außerdem nicht isTrusted und löst auf der Verbindung keine interne Medienverarbeitung aus.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses. Für Track-Ereignisse normalerweise `"track"`.
$options Pflicht	object		Wörterbuch (Dictionary) mit den Eigenschaften des Ereignisses. Erlaubt sind außerdem die Felder von `EventInit` (`bubbles`, `cancelable`, `composed`).
$options.receiver Pflicht	RTCRtpReceiver		Der Receiver, über den die Mediendaten des Tracks empfangen werden.
$options.track Pflicht	MediaStreamTrack		Der Medien-Track, auf den sich das Ereignis bezieht.
$options.transceiver Pflicht	RTCRtpTransceiver		Der Transceiver, zu dem Receiver und Track gehören.
$options.streams	MediaStream[]	[]	Die Streams, zu denen der Track gehört. Ist das Feld nicht gesetzt, entsteht ein leeres Array.

Rückgabewert

Typ

RTCTrackEvent

Beschreibung

Ein neues RTCTrackEvent mit den schreibgeschützten Eigenschaften receiver, track, transceiver und streams.

Beispiele

Ereignis aus einem echten Transceiver erzeugen

const pc = new RTCPeerConnection();
// Transceiver liefert gültige Receiver- und Track-Objekte
const transceiver = pc.addTransceiver('video', { direction: 'recvonly' });

const event = new RTCTrackEvent('track', {
  receiver: transceiver.receiver,
  track: transceiver.receiver.track,
  transceiver,
  streams: [new MediaStream([transceiver.receiver.track])]
});

console.log(event.type, event.track.kind, event.streams.length);

track video 1

Eigenes Track-Ereignis in einem Test auslösen

const pc = new RTCPeerConnection();
const transceiver = pc.addTransceiver('audio');

// Handler, der in der Anwendung eingehende Tracks verarbeitet
pc.addEventListener('track', (e) => {
  console.log(`Neuer ${e.track.kind}-Track, trusted: ${e.isTrusted}`);
});

// Ereignis manuell auslösen, um den Handler zu testen
pc.dispatchEvent(new RTCTrackEvent('track', {
  receiver: transceiver.receiver,
  track: transceiver.receiver.track,
  transceiver
}));

pc.close();

Neuer audio-Track, trusted: false

Typische Praxis: vom Browser erzeugte Ereignisse abfangen

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

pc.ontrack = ({ track, streams }) => {
  // Stream des Gegenübers im Video-Element anzeigen
  if (streams[0]) {
    remoteVideo.srcObject = streams[0];
  } else {
    remoteVideo.srcObject = new MediaStream([track]);
  }
};

// Wichtig · Fallstricke

Fehlt eines der Pflichtfelder receiver, track oder transceiver, wirft der Konstruktor einen TypeError. Das passiert auch, wenn der Konstruktor ohne options aufgerufen wird.
RTCRtpReceiver und RTCRtpTransceiver haben keinen öffentlichen Konstruktor. Echte Objekte bekommt man nur über RTCPeerConnection.addTransceiver() oder getTransceivers(). Einfache Mock-Objekte werden vom Browser abgelehnt.
Selbst erzeugte Ereignisse haben isTrusted === false und ändern den Zustand der Verbindung nicht. Sie erreichen nur die Listener.
streams kann leer sein, zum Beispiel wenn der Sender Tracks ohne Stream-Zuordnung hinzufügt. Beim Verarbeiten sollte man deshalb immer auf track zurückgreifen können.
Unterstützung: In allen aktuellen Browsern (Chrome, Edge, Firefox, Safari) vorhanden. In Node.js gibt es die API nicht, dort braucht man Bibliotheken wie wrtc/node-datachannel.

Siehe auch

RTCTrackEvent RTCPeerConnection.prototype.addTransceiver() RTCPeerConnection.prototype.addTrack() RTCRtpReceiver MediaStreamTrack new CSSMatrixComponent()