RTCRtpTransceiver — Schnittstelle · JavaScript-Referenz

Signatur

interface RTCRtpTransceiver

Beschreibung

Ein RTCRtpTransceiver entspricht genau einer m-Zeile (Media Section) in der SDP-Aushandlung einer RTCPeerConnection. Er bündelt einen RTCRtpSender (ausgehender Medienstrom) und einen RTCRtpReceiver (eingehender Medienstrom). Beide teilen sich die mid (Media-ID) und die Übertragungsrichtung.

Transceiver entstehen automatisch durch addTrack(), wenn eine Remote-Beschreibung neue Medien anbietet, oder ausdrücklich über RTCPeerConnection.addTransceiver(). Mit dem ausdrücklichen Weg legt man genau fest, ob eine Verbindung nur senden ("sendonly"), nur empfangen ("recvonly"), beides ("sendrecv") oder nichts ("inactive") tun soll. Das ist z. B. für reine Empfänger (Zuschauer eines Streams) oder für Simulcast mit mehreren Kodierungen nötig.

Wichtige Eigenschaften und Methoden:

mid – schreibgeschützt; die ausgehandelte Media-ID oder null, solange noch nicht ausgehandelt.
sender / receiver – das zugehörige RTCRtpSender- bzw. RTCRtpReceiver-Objekt.
direction – gewünschte Richtung; Änderungen lösen negotiationneeded aus.
currentDirection – schreibgeschützt; die tatsächlich ausgehandelte Richtung (oder null).
setCodecPreferences(codecs) – legt die bevorzugte Codec-Reihenfolge für die Aushandlung fest.
stop() – beendet den Transceiver dauerhaft; die m-Zeile wird im nächsten Angebot mit Port 0 abgelehnt.

Die Schnittstelle hat keinen öffentlichen Konstruktor. Instanzen erhält man über addTransceiver(), getTransceivers() oder das track-Event (event.transceiver).

Parameter

Name	Typ	Default	Beschreibung
$trackOrKind Pflicht	MediaStreamTrack \| "audio" \| "video"		Erstes Argument von `RTCPeerConnection.addTransceiver()`: ein vorhandener Track oder die Medienart als Zeichenkette.
$init.direction	"sendrecv" \| "sendonly" \| "recvonly" \| "inactive"	"sendrecv"	Anfangsrichtung des Transceivers.
$init.streams	MediaStream[]	[]	Streams, denen der gesendete Track auf der Gegenseite zugeordnet wird.
$init.sendEncodings	RTCRtpEncodingParameters[]		Kodierungen für den Sender, z. B. mehrere Ebenen mit `rid` und `scaleResolutionDownBy` für Simulcast.

Rückgabewert

Typ

RTCRtpTransceiver

Beschreibung

addTransceiver() gibt den neu angelegten Transceiver zurück; getTransceivers() liefert ein RTCRtpTransceiver[].

Beispiele

Reinen Empfangs-Transceiver anlegen (Zuschauer)

const pc = new RTCPeerConnection();

// Nur Video und Audio empfangen, nichts senden
const videoTx = pc.addTransceiver('video', { direction: 'recvonly' });
const audioTx = pc.addTransceiver('audio', { direction: 'recvonly' });

pc.addEventListener('track', ({ track, streams }) => {
  document.querySelector('video').srcObject = streams[0] ?? new MediaStream([track]);
});

const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
console.log(videoTx.direction, videoTx.mid);

recvonly 0

Kamera stummschalten über die Richtung

const pc = new RTCPeerConnection();
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const transceiver = pc.addTransceiver(stream.getVideoTracks()[0], {
  direction: 'sendrecv',
  streams: [stream]
});

// Später: Senden pausieren, Empfang beibehalten
const pauseVideo = () => {
  transceiver.direction = 'recvonly'; // löst negotiationneeded aus
};

pc.addEventListener('negotiationneeded', async () => {
  await pc.setLocalDescription();
  // Beschreibung per Signalisierung an Gegenseite senden …
  console.log('Neu verhandeln, gewünscht:', transceiver.direction);
});

pauseVideo();

Neu verhandeln, gewünscht: recvonly

Codec-Präferenz setzen (VP9 bevorzugen)

const pc = new RTCPeerConnection();
const transceiver = pc.addTransceiver('video');

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

const offer = await pc.createOffer();
console.log(offer.sdp.includes('VP9'));

true

Alle Transceiver auflisten und einen stoppen

const pc = new RTCPeerConnection();
pc.addTransceiver('audio');
pc.addTransceiver('video');

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

// Video-Transceiver dauerhaft beenden
const videoTx = pc.getTransceivers().find(t => t.receiver.track.kind === 'video');
videoTx.stop();
console.log(videoTx.direction);

audio sendrecv null video sendrecv null stopped

// Wichtig · Fallstricke

direction vs. currentDirection: direction ist nur der Wunsch. Erst nach abgeschlossener Offer/Answer-Runde zeigt currentDirection das Ergebnis. Bis dahin ist der Wert null.
stop() ist endgültig: Ein gestoppter Transceiver lässt sich nicht wieder aktivieren. direction steht dann auf "stopped", eine Zuweisung wirft InvalidStateError. Zum vorübergehenden Pausieren nimmt man "inactive"/"recvonly" oder sender.replaceTrack(null) (ohne neue Aushandlung).
Veraltet: Die Eigenschaft stopped wurde aus der Spezifikation entfernt. Prüfe stattdessen direction === "stopped".
setCodecPreferences() akzeptiert nur Codecs aus RTCRtpReceiver.getCapabilities(), sonst kommt ein InvalidModificationError. Firefox unterstützt die Methode erst ab Version 128.
Kompatibilität: In Chrome ist die Schnittstelle seit Version 69 verfügbar (Unified Plan, Standard ab 72), in Firefox seit 59 und in Safari seit 12.1. Alte „Plan B“-Implementierungen von Chrome kannten keine Transceiver.
mid ist erst nach setLocalDescription()/setRemoteDescription() belegt. Nutze sie nicht als Schlüssel, solange sie noch null ist.

Siehe auch

RTCPeerConnection RTCPeerConnection.addTransceiver() RTCPeerConnection.getTransceivers() RTCRtpSender RTCRtpReceiver RTCTrackEvent RTCRtpTransceiver.setCodecPreferences()