RTCRtpTransceiver.direction — Eigenschaft · JavaScript-Referenz

Signatur

RTCRtpTransceiver.direction

Beschreibung

Die Eigenschaft direction eines RTCRtpTransceiver legt fest, in welche Richtung dieser Transceiver Medien übertragen soll. Gemeint ist, ob er senden, empfangen, beides oder nichts soll. Der Wert fließt beim nächsten Aufruf von createOffer() bzw. createAnswer() als Richtungsattribut (a=sendrecv, a=sendonly …) in die SDP-Beschreibung ein.

Wichtig ist der Unterschied zu currentDirection. direction ist nur ein Wunsch der lokalen Seite. Die tatsächlich ausgehandelte Richtung steht erst nach Abschluss der Offer/Answer-Aushandlung in currentDirection. Wenn die Gegenseite z. B. nur recvonly anbietet, bleibt eine lokal gewünschte Richtung sendrecv zwar in direction stehen, ausgehandelt wird aber sendonly.

Wenn du den Wert auf eine andere Richtung setzt, wird der Transceiver als „aushandlungsbedürftig“ markiert, und die RTCPeerConnection löst das Ereignis negotiationneeded aus. Typische Anwendungsfälle:

Kamera „stummschalten“, ohne den Track zu entfernen ("recvonly")
Halten eines Anrufs (Hold, "inactive")
reine Zuschauer- oder Sender-Rollen bei Broadcasts

Die möglichen Werte sind "sendrecv", "sendonly", "recvonly" und "inactive". Nachdem stop() aufgerufen wurde, liefert die Eigenschaft "stopped".

Parameter

Name	Typ	Default	Beschreibung
$value	"sendrecv" \| "sendonly" \| "recvonly" \| "inactive"	"sendrecv" (bei addTrack/addTransceiver ohne Option)	Neue bevorzugte Richtung beim Schreiben. `"stopped"` darf nicht gesetzt werden. Dafür gibt es `stop()`.

Rückgabewert

Typ

string

Beschreibung

Die aktuell bevorzugte Richtung: einer der Werte "sendrecv", "sendonly", "recvonly", "inactive" oder "stopped".

Beispiele

Richtung beim Anlegen festlegen und auslesen

const pc = new RTCPeerConnection();

// Nur Video empfangen, z. B. als Zuschauer eines Streams
const transceiver = pc.addTransceiver('video', { direction: 'recvonly' });

console.log(transceiver.direction);        // gewünschte Richtung
console.log(transceiver.currentDirection); // noch nicht ausgehandelt

recvonly null

Anruf halten (Hold) und fortsetzen

const pc = new RTCPeerConnection();
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
pc.addTrack(stream.getAudioTracks()[0], stream);

// Neuaushandlung automatisch anstoßen
pc.addEventListener('negotiationneeded', async () => {
  await pc.setLocalDescription(); // erzeugt ein Offer mit der neuen Richtung
  // signaling.send({ description: pc.localDescription });
});

const setHold = (onHold) => {
  for (const t of pc.getTransceivers()) {
    if (t.direction === 'stopped') continue;
    t.direction = onHold ? 'inactive' : 'sendrecv';
  }
};

setHold(true);  // Anruf halten
// später: setHold(false);

Kamera abschalten, ohne den Track zu entfernen

const toggleSendVideo = (pc, enabled) => {
  const videoTransceiver = pc.getTransceivers()
    .find((t) => t.receiver.track.kind === 'video' && t.direction !== 'stopped');
  if (!videoTransceiver) return;

  videoTransceiver.direction = enabled ? 'sendrecv' : 'recvonly';
  console.log(`Gewünscht: ${videoTransceiver.direction}, ausgehandelt: ${videoTransceiver.currentDirection}`);
};

// Aufruf, z. B. über einen Button:
// toggleSendVideo(pc, false);

Gewünscht: recvonly, ausgehandelt: sendrecv

// Wichtig · Fallstricke

Wunsch statt Zustand: Eine Änderung wirkt erst, wenn neu ausgehandelt wurde, also nach Offer/Answer und setRemoteDescription(). Den ausgehandelten Zustand zeigt currentDirection.
Wer "stopped" zuweist, bekommt einen TypeError. Ist der Transceiver bereits gestoppt, wirft jede Zuweisung einen InvalidStateError. Ist die RTCPeerConnection geschlossen, gibt es ebenfalls einen InvalidStateError.
Wird derselbe Wert erneut gesetzt, passiert nichts, und es wird auch kein negotiationneeded ausgelöst.
Auf "recvonly" oder "inactive" zu wechseln, stoppt den lokalen Track nicht. Die Kamera-LED bleibt also an. Zum echten Abschalten zusätzlich track.stop() aufrufen oder sender.replaceTrack(null) verwenden.
Kompatibilität: Chrome, Edge, Firefox und Safari unterstützen die Eigenschaft in aktuellen Versionen. Der Wert "stopped" wurde erst später eingeführt. Ältere Implementierungen kennen stattdessen nur die veraltete Eigenschaft stopped.

Siehe auch

RTCRtpTransceiver RTCRtpTransceiver.currentDirection RTCRtpTransceiver.stop() RTCPeerConnection.addTransceiver() RTCRtpSender.replaceTrack() MediaTrackSettings.noiseSuppression