RTCPeerConnection.getTransceivers() — Methode · JavaScript-Referenz

Signatur

RTCPeerConnection.prototype.getTransceivers()

Beschreibung

getTransceivers() liefert eine Momentaufnahme aller Transceiver, die zu einer RTCPeerConnection gehören. Ein Transceiver steht für genau einen Medienabschnitt (m-line) im SDP. Er fasst immer einen RTCRtpSender und einen RTCRtpReceiver zusammen, die sich dieselbe mid teilen.

Transceiver entstehen auf drei Wegen: explizit mit addTransceiver(), implizit durch addTrack() oder beim Anwenden einer entfernten Beschreibung mit setRemoteDescription(), wenn diese neue Medienabschnitte enthält. Die Reihenfolge im Array entspricht der Reihenfolge, in der die Transceiver hinzugefügt wurden.

Typische Anwendungsfälle:

Die Übertragungsrichtung ändern (direction), etwa um Video stummzuschalten, ohne neu zu verhandeln.
Codec-Präferenzen mit setCodecPreferences() festlegen.
Einzelne Medienabschnitte mit stop() dauerhaft beenden.
Den Verbindungszustand pro Medium auswerten, z. B. mid und currentDirection.

Die Liste wird bei jedem Aufruf neu erzeugt. Transceiver, die später hinzukommen, erscheinen nicht in einem Array, das du vorher abgerufen hast.

Rückgabewert

Typ

RTCRtpTransceiver[]

Beschreibung

Ein neues Array mit allen RTCRtpTransceiver-Objekten der Verbindung, in der Reihenfolge ihres Hinzufügens. Gestoppte Transceiver sind darin weiterhin enthalten. Wie lange noch, hängt vom Browser ab (siehe Hinweise). Gibt es keine Transceiver, ist das Array leer.

Beispiele

Alle Transceiver auflisten

const pc = new RTCPeerConnection();
pc.addTransceiver('audio', { direction: 'sendrecv' });
pc.addTransceiver('video', { direction: 'recvonly' });

for (const t of pc.getTransceivers()) {
  console.log(t.receiver.track.kind, t.direction, t.mid);
}

audio sendrecv null video recvonly null

Eigenes Video pausieren, ohne den Track zu entfernen

const pauseVideo = (pc, paused) => {
  const videoTransceivers = pc.getTransceivers()
    .filter(t => !t.stopped && t.receiver.track.kind === 'video');

  for (const t of videoTransceivers) {
    // Nur noch empfangen bzw. wieder senden und empfangen
    t.direction = paused ? 'recvonly' : 'sendrecv';
  }
  // Die Richtungsänderung löst negotiationneeded aus
};

// Aufruf nach dem Verbindungsaufbau
pauseVideo(pc, true);

Codec-Präferenz für Video setzen (z. B. VP9 bevorzugen)

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const pc = new RTCPeerConnection();
stream.getTracks().forEach(track => pc.addTrack(track, stream));

const { codecs } = RTCRtpReceiver.getCapabilities('video');
const sorted = [
  ...codecs.filter(c => c.mimeType === 'video/VP9'),
  ...codecs.filter(c => c.mimeType !== 'video/VP9')
];

pc.getTransceivers()
  .filter(t => t.receiver.track.kind === 'video')
  .forEach(t => t.setCodecPreferences(sorted));

const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

Alle Medienabschnitte beim Auflegen stoppen

const hangUp = (pc) => {
  pc.getTransceivers().forEach(t => {
    t.sender.track?.stop(); // lokale Kamera/Mikrofon freigeben
    t.stop();
  });
  pc.close();
};

// Wichtig · Fallstricke

Momentaufnahme: Das zurückgegebene Array aktualisiert sich nicht. Rufe die Methode nach addTrack(), addTransceiver() oder setRemoteDescription() erneut auf.
Gestoppte Transceiver: Nach stop() bleiben Transceiver bis zur nächsten abgeschlossenen Aushandlung in der Liste. Ältere Browser behalten sie auch danach. Prüfe deshalb currentDirection === 'stopped' (oder die veraltete Eigenschaft stopped), bevor du einen Transceiver weiterverwendest.
mid ist anfangs null: Die mid wird erst gesetzt, wenn eine lokale oder entfernte Beschreibung angewendet wurde.
Art des Mediums bestimmen: sender.track kann null sein, z. B. bei recvonly. receiver.track ist dagegen immer vorhanden. Die Art (kind) liest du deshalb zuverlässig über receiver.track.kind aus.
Kompatibilität: Die Methode setzt die Unified-Plan-SDP-Semantik voraus. Chrome unterstützt sie seit Version 69 (Standard seit 72), Firefox seit 59 und Safari seit 12.1. Das alte Plan-B-Verfahren in Chrome kannte keine Transceiver.
Nach close() liefert die Methode weiterhin die Transceiver. Diese sind dann aber gestoppt.

Siehe auch

RTCPeerConnection RTCRtpTransceiver RTCPeerConnection.addTransceiver() RTCPeerConnection.addTrack() RTCPeerConnection.getSenders() RTCPeerConnection.getReceivers() RTCRtpTransceiver.setCodecPreferences()