new MediaStreamEvent() — Methode · JavaScript-Referenz

Signatur

new MediaStreamEvent(type, options)

Beschreibung

Der Konstruktor MediaStreamEvent() erzeugt ein Ereignisobjekt vom Typ MediaStreamEvent. Dieses erbt von Event und hat zusätzlich die schreibgeschützte Eigenschaft stream, die auf einen MediaStream zeigt – oder auf null, wenn keiner angegeben wurde.

Früher wurde dieser Ereignistyp von RTCPeerConnection für die inzwischen entfernten Ereignisse addstream und removestream ausgelöst. In der aktuellen WebRTC-Spezifikation arbeitet man mit einzelnen Spuren: An ihre Stelle ist das Ereignis track mit dem Objekt RTCTrackEvent getreten.

Selbst erzeugen musst du ein MediaStreamEvent praktisch nur, wenn du älteren Code testest, ältere Schnittstellen nachbildest oder eigene EventTarget-Objekte mit Stream-bezogenen Ereignissen versorgen willst. Für neuen Code solltest du stattdessen RTCTrackEvent oder ein CustomEvent mit detail verwenden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, z. B. `"addstream"` oder `"removestream"`. Groß- und Kleinschreibung wird beachtet.
$options	{ stream?: MediaStream \| null, bubbles?: boolean, cancelable?: boolean, composed?: boolean }	{}	Optionales Wörterbuch mit Einstellungen. `stream` legt den `MediaStream` fest (Standardwert `null`). Außerdem gelten die üblichen Optionen von `EventInit`: `bubbles`, `cancelable` und `composed`, jeweils mit dem Standardwert `false`.

Rückgabewert

Typ

MediaStreamEvent

Beschreibung

Ein neues MediaStreamEvent-Objekt. Seine Eigenschaft stream enthält den übergebenen MediaStream oder null.

Beispiele

Unterstützung prüfen und ein Ereignis erzeugen

if (typeof MediaStreamEvent === 'function') {
  const stream = new MediaStream(); // leerer Stream ohne Spuren
  const event = new MediaStreamEvent('addstream', { stream });
  console.log(event.type);
  console.log(event.stream === stream);
} else {
  console.log('MediaStreamEvent wird nicht unterstützt');
}

addstream true (oder: MediaStreamEvent wird nicht unterstützt)

Eigenes EventTarget, das Streams meldet

class StreamHub extends EventTarget {
  add(stream) {
    // Rückfall auf CustomEvent, falls MediaStreamEvent fehlt
    const event = typeof MediaStreamEvent === 'function'
      ? new MediaStreamEvent('addstream', { stream })
      : new CustomEvent('addstream', { detail: { stream } });
    this.dispatchEvent(event);
  }
}

const hub = new StreamHub();
hub.addEventListener('addstream', (e) => {
  const stream = e.stream ?? e.detail?.stream;
  console.log('Neuer Stream:', stream.id.length > 0);
});

hub.add(new MediaStream());

Neuer Stream: true

Moderner Ersatz: das track-Ereignis von RTCPeerConnection

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

// Statt des veralteten 'addstream' mit MediaStreamEvent:
pc.addEventListener('track', (event) => {
  // event ist ein RTCTrackEvent
  const [remoteStream] = event.streams;
  if (video && video.srcObject !== remoteStream) {
    video.srcObject = remoteStream;
  }
  console.log('Spur empfangen:', event.track.kind);
});

Spur empfangen: video (sobald eine entfernte Spur eintrifft)

// Wichtig · Fallstricke

Veraltet: MediaStreamEvent gehört nicht mehr zur WebRTC-Spezifikation. Chromium-basierte Browser und Safari stellen den Konstruktor nicht (mehr) bereit, nur in Firefox ist er noch vorhanden. Prüfe deshalb vor der Nutzung, ob er existiert: typeof MediaStreamEvent === 'function'.
Die Ereignisse addstream/removestream und die Eigenschaft onaddstream an RTCPeerConnection sind ebenfalls veraltet. Nutze stattdessen track (RTCTrackEvent) sowie addTrack()/removeTrack().
Den Konstruktor musst du mit new aufrufen. Ohne new wird ein TypeError geworfen. Fehlt das Argument type, gibt es ebenfalls einen TypeError.
Selbst erzeugte Ereignisse haben isTrusted === false. Code, der das prüft, reagiert nicht darauf.
Für eigene Ereignisse, die in allen Browsern funktionieren sollen, ist CustomEvent mit dem Stream in detail die robustere Wahl.

Siehe auch

new MediaStream() new MediaStreamTrackEvent() new MessageEvent() new VRDisplayEvent() new CustomEvent()