RTCRtpSender.setStreams() — Methode · JavaScript-Referenz

Signatur

RTCRtpSender.prototype.setStreams(...mediaStreams)

Beschreibung

setStreams() ändert, zu welchen Streams der gesendete Track gehört. Das ist Signalisierungs-Metadaten, keine Medienänderung: Die Stream-IDs landen als a=msid-Zeilen im SDP. Auf der Gegenseite enthält dann das Array event.streams im track-Event von RTCPeerConnection passende entfernte MediaStream-Objekte, zu denen der Track gehört.

Gebraucht wird das vor allem in drei Fällen: wenn ein Track per addTrack(track) ohne Stream hinzugefügt wurde, wenn ein Transceiver über addTransceiver() angelegt wurde (dort gibt es keinen Stream-Parameter am Sender, außer über init.streams), oder wenn ein Track während der Sitzung einer anderen Stream-Gruppe zugeordnet werden soll, z. B. weil Audio und Video auf der Empfängerseite zusammen in einem <video>-Element laufen sollen.

Jeder Aufruf ersetzt die bisherige Zuordnung komplett. Ein Aufruf ganz ohne Argumente entfernt alle Zuordnungen. Doppelt übergebene Streams werden nur einmal gezählt. Weil sich dadurch die lokale Beschreibung ändert, löst der Aufruf ein negotiationneeded-Event aus. Erst nach einer neuen Offer/Answer-Runde wirkt sich die Änderung auf der Gegenseite aus.

Parameter

Name	Typ	Default	Beschreibung
$...mediaStreams	MediaStream		Beliebig viele `MediaStream`-Objekte, denen der Track des Senders zugeordnet wird. Maßgeblich ist nur ihre `id`. Ohne Argumente werden alle Zuordnungen entfernt.

Rückgabewert

Typ

undefined

Beschreibung

Gibt keinen Wert zurück. Die Änderung wirkt erst nach der nächsten SDP-Aushandlung auf der Gegenseite.

Beispiele

Track nachträglich einem Stream zuordnen

const pc = new RTCPeerConnection();
const localStream = await navigator.mediaDevices.getUserMedia({ audio: true, video: true });

// Tracks zunächst ohne Stream hinzufügen
const senders = localStream.getTracks().map((track) => pc.addTrack(track));

// Jetzt alle Sender demselben Stream zuordnen,
// damit Audio und Video auf der Gegenseite zusammengehören
for (const sender of senders) {
  sender.setStreams(localStream);
}

pc.addEventListener('negotiationneeded', async () => {
  await pc.setLocalDescription();
  console.log(pc.localDescription.sdp.includes(`msid:${localStream.id}`));
});

true

Transceiver mit Stream-Zuordnung verwenden

const pc = new RTCPeerConnection();
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [videoTrack] = stream.getVideoTracks();

const transceiver = pc.addTransceiver('video', { direction: 'sendonly' });
await transceiver.sender.replaceTrack(videoTrack);

// Zuordnung ergänzen, sonst ist event.streams auf der Gegenseite leer
transceiver.sender.setStreams(stream);

Empfängerseite: Stream aus dem track-Event nutzen

const remotePc = new RTCPeerConnection();
const videoEl = document.querySelector('#remote');

remotePc.addEventListener('track', ({ track, streams }) => {
  console.log(`Track ${track.kind} gehört zu ${streams.length} Stream(s)`);
  if (streams[0] && videoEl.srcObject !== streams[0]) {
    videoEl.srcObject = streams[0];
  }
});

Track video gehört zu 1 Stream(s)

Alle Zuordnungen entfernen

const sender = pc.getSenders().find((s) => s.track?.kind === 'audio');

// Ohne Argumente: Track gehört keinem Stream mehr an
sender.setStreams();
// Danach neu aushandeln (negotiationneeded wird ausgelöst)

// Wichtig · Fallstricke

Kein Medienwechsel: setStreams() ändert nur Metadaten. Den eigentlichen Track tauschst du mit replaceTrack() aus.
Neuverhandlung nötig: Der Aufruf löst negotiationneeded aus. Ohne neue Offer/Answer-Runde bemerkt die Gegenseite nichts.
Ersetzen statt Ergänzen: Jeder Aufruf überschreibt die komplette bisherige Liste. Wenn du einen Stream hinzufügen willst, musst du alle gewünschten Streams erneut übergeben.
Fehler: Ist die RTCPeerConnection bereits geschlossen (signalingState === 'closed'), wird eine InvalidStateError-DOMException geworfen.
Kompatibilität: Die Methode wird von aktuellen Chromium-Browsern, Firefox und Safari unterstützt, fehlt aber in älteren Versionen. Prüfe sie bei Bedarf mit 'setStreams' in RTCRtpSender.prototype und weiche sonst auf addTrack(track, stream) aus.
Die Gegenseite sieht nur die Stream-id. Die lokalen MediaStream-Objekte selbst werden nicht übertragen, und Tracks, die du später zum lokalen Stream hinzufügst, werden nicht automatisch mitgesendet.

Siehe auch

RTCRtpSender RTCRtpSender.replaceTrack() RTCPeerConnection.addTrack() RTCPeerConnection.addTransceiver() MediaStream