RTCPeerConnection: addstream — Ereignis · JavaScript-Referenz

Signatur

peerConnection.addEventListener("addstream", handler)

Beschreibung

Das addstream-Ereignis wird an eine RTCPeerConnection ausgelöst, sobald bei der Verarbeitung einer entfernten Sitzungsbeschreibung (setRemoteDescription()) ein neuer entfernter MediaStream erkannt wird. Das Ereignisobjekt ist ein MediaStreamEvent, dessen Eigenschaft stream den hinzugefügten Stream enthält.

Registrieren lässt sich ein Handler entweder mit pc.addEventListener("addstream", handler) oder über die Eigenschaft pc.onaddstream = handler. Das Ereignis stammt aus der frühen, stream-basierten WebRTC-API, zusammen mit addStream(), removeStream() und dem Ereignis removestream.

In neuem Code sollte das Ereignis nicht mehr verwendet werden. Die aktuelle Spezifikation arbeitet track-basiert: Stattdessen fügt man Medien mit addTrack() hinzu und reagiert auf das track-Ereignis. Dessen RTCTrackEvent liefert über event.streams ebenfalls die zugehörigen MediaStream-Objekte.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"addstream"`.
$handler Pflicht	(event: MediaStreamEvent) => void		Callback, der ein `MediaStreamEvent` erhält; `event.stream` ist der neu hinzugefügte entfernte `MediaStream`.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal`.

Rückgabewert

Typ

void

Beschreibung

addEventListener() gibt nichts zurück. Der Handler erhält ein MediaStreamEvent mit der Eigenschaft stream.

Beispiele

Legacy-Code: entfernten Stream mit addEventListener anzeigen

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

const onAddStream = (event) => {
  // event ist ein MediaStreamEvent
  console.log('Neuer entfernter Stream:', event.stream.id);
  remoteVideo.srcObject = event.stream;
};

pc.addEventListener('addstream', onAddStream);

// Später, z. B. beim Aufräumen:
// pc.removeEventListener('addstream', onAddStream);

Neuer entfernter Stream: 3f2a9c1e-…

Äquivalent über die onaddstream-Eigenschaft

const pc = new RTCPeerConnection();

pc.onaddstream = ({ stream }) => {
  const video = document.createElement('video');
  video.autoplay = true;
  video.playsInline = true;
  video.srcObject = stream;
  document.body.append(video);
};

// Handler wieder entfernen
// pc.onaddstream = null;

Moderne Alternative mit Fallback: track-Ereignis bevorzugen

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

const attach = (stream) => {
  if (remoteVideo.srcObject !== stream) {
    remoteVideo.srcObject = stream;
  }
};

if ('ontrack' in pc) {
  // Standardweg: track-Ereignis
  pc.addEventListener('track', (event) => {
    const [stream] = event.streams;
    if (stream) attach(stream);
  });
} else {
  // Nur für sehr alte Browser
  pc.addEventListener('addstream', (event) => attach(event.stream));
}

// Wichtig · Fallstricke

Veraltet: addstream ist nicht Teil der aktuellen WebRTC-Spezifikation. Firefox hat die Unterstützung entfernt; in Chromium und Safari existiert es nur noch aus Kompatibilitätsgründen. Verwende stattdessen das track-Ereignis.
Das Ereignis wird pro Stream ausgelöst, nicht pro Track. Kommen Tracks später in einen bestehenden Stream hinzu, feuert addstream nicht erneut; dafür bräuchte man addtrack am MediaStream.
Den Handler vor setRemoteDescription() registrieren, sonst kann das Ereignis verloren gehen.
Nicht mit track zusammen ohne Prüfung kombinieren: In Browsern, die beides unterstützen, würde derselbe Stream doppelt verarbeitet.
Polyfills wie webrtc-adapter vereinheitlichen das Verhalten, fördern aber ebenfalls die Umstellung auf ontrack.

Siehe auch

RTCPeerConnection RTCPeerConnection.prototype.addTrack() RTCPeerConnection.prototype.addStream() MediaStream RTCTrackEvent RTCPeerConnection: removestream