MediaStreamEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface MediaStreamEvent extends Event

Beschreibung

Das Interface MediaStreamEvent beschreibt Ereignisse, die sich auf einen ganzen MediaStream beziehen. Es erbt von Event und hat eine zusätzliche Eigenschaft: stream. Sie verweist auf den MediaStream, um den es beim Ereignis geht.

Verwendet wurde es in frühen WebRTC-Versionen für die Ereignisse addstream und removestream an einer RTCPeerConnection. Diese Ereignisse wurden ausgelöst, wenn die Gegenstelle einen Stream hinzufügte oder entfernte. Die Handler registrierte man über pc.onaddstream bzw. pc.addEventListener("addstream", …).

Die aktuelle WebRTC-Spezifikation arbeitet nicht mehr mit ganzen Streams, sondern mit einzelnen Spuren (Tracks). An die Stelle von addstream ist das Ereignis track vom Typ RTCTrackEvent getreten. Das Array event.streams dieses Ereignisses enthält die zugehörigen Streams. Verwende MediaStreamEvent in neuem Code nicht mehr. Nützlich ist es nur noch, um alten Code zu verstehen oder schrittweise zu migrieren.

Eigenschaften:

MediaStreamEvent.stream (nur lesbar): der betroffene MediaStream.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Konstruktor-Parameter: Name des Ereignisses, z. B. `"addstream"` oder `"removestream"`.
$eventInitDict Pflicht	{ stream: MediaStream, bubbles?: boolean, cancelable?: boolean, composed?: boolean }		Konstruktor-Parameter: Optionen-Objekt. `stream` ist der zugehörige `MediaStream`. Die übrigen Felder entsprechen denen von `EventInit`.

Rückgabewert

Typ

MediaStreamEvent

Beschreibung

Der Konstruktor new MediaStreamEvent(type, eventInitDict) gibt ein neues Ereignisobjekt zurück. Dessen Eigenschaft stream vom Typ MediaStream ist nur lesbar.

Beispiele

Instanz erzeugen und selbst auslösen (nur wo unterstützt)

// Prüfen, ob der Browser das veraltete Interface noch kennt
if (typeof MediaStreamEvent === 'function') {
  const stream = new MediaStream();
  const target = new EventTarget();

  target.addEventListener('addstream', (event) => {
    console.log('Stream-ID:', event.stream.id);
  });

  const evt = new MediaStreamEvent('addstream', { stream });
  target.dispatchEvent(evt);
} else {
  console.log('MediaStreamEvent wird nicht unterstützt');
}

Stream-ID: 3f1c… (oder: MediaStreamEvent wird nicht unterstützt)

Alter Code: Remote-Stream über onaddstream anzeigen

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

// VERALTET: nur zur Veranschaulichung von Legacy-Code
pc.onaddstream = (event) => {
  // event ist ein MediaStreamEvent
  video.srcObject = event.stream;
};

pc.addEventListener('removestream', (event) => {
  console.log('Stream entfernt:', event.stream.id);
  video.srcObject = null;
});

Migration: modernes track-Ereignis statt addstream

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

pc.addEventListener('track', (event) => {
  // event ist ein RTCTrackEvent
  const [remoteStream] = event.streams;
  if (remoteStream && video.srcObject !== remoteStream) {
    video.srcObject = remoteStream;
  }

  // Entfernte Spuren über den Stream beobachten
  remoteStream?.addEventListener('removetrack', (e) => {
    console.log('Spur entfernt:', e.track.kind);
  });
});

// Wichtig · Fallstricke

Veraltet: MediaStreamEvent sowie die Ereignisse addstream und removestream stehen nicht mehr in der WebRTC-Spezifikation. Auch die Methoden addStream() und removeStream() wurden entfernt. Die Browser unterstützen das nur uneinheitlich, und die Unterstützung kann ganz wegfallen. Deshalb vor der Nutzung immer mit typeof MediaStreamEvent === 'function' bzw. 'onaddstream' in RTCPeerConnection.prototype prüfen.
Ersatz: Verwende pc.addTrack() und das Ereignis track (RTCTrackEvent). Um entfernte Spuren zu erkennen, beobachte removetrack am MediaStream oder das Ereignis ended am MediaStreamTrack.
Das Ereignis track wird pro Spur ausgelöst. Bei Audio und Video also meist zweimal für denselben Stream. Daher vor dem Setzen von srcObject prüfen, ob der Stream schon zugewiesen ist, sonst wird die Wiedergabe neu gestartet.
Nicht verwechseln mit MediaStreamTrackEvent: Das ist das noch gültige Ereignis-Interface für addtrack/removetrack an einem MediaStream.

Siehe auch

RTCTrackEvent MediaStream MediaStreamTrackEvent RTCPeerConnection RTCPeerConnection.prototype.addTrack() Event