RTCPeerConnection.currentLocalDescription — Eigenschaft · JavaScript-Referenz

Signatur

RTCPeerConnection.currentLocalDescription

Beschreibung

Die schreibgeschützte Eigenschaft currentLocalDescription gibt ein RTCSessionDescription-Objekt zurück. Es beschreibt die lokale Seite der Verbindung so, wie sie beim letzten erfolgreichen Abschluss einer Aushandlung festgelegt wurde, also nachdem die Gegenstelle ein Offer oder Answer bestätigt hat und signalingState wieder "stable" ist. Zusätzlich enthält die Beschreibung alle lokalen ICE-Kandidaten, die der ICE-Agent seit der Aushandlung gesammelt hat.

Im Unterschied dazu gibt pendingLocalDescription eine Beschreibung zurück, die gerade ausgehandelt wird und noch nicht bestätigt ist. localDescription liefert die ausstehende Beschreibung, falls es eine gibt, und sonst die aktuelle. Wer also wissen will, welche lokale Konfiguration tatsächlich gilt, fragt currentLocalDescription ab.

Typische Einsatzfälle sind das Debugging von Codec- und Medienparametern im SDP, das Prüfen, ob schon eine erste Aushandlung stattgefunden hat, und die Protokollierung bei einer Neuverhandlung (z. B. nach einem ICE-Restart oder beim Hinzufügen neuer Spuren).

Rückgabewert

Typ

RTCSessionDescription | null

Beschreibung

Die zuletzt ausgehandelte lokale Sitzungsbeschreibung mit den Eigenschaften type ("offer" oder "answer") und sdp. Solange noch keine Aushandlung abgeschlossen ist, ist der Wert null.

Beispiele

Aktuelle und ausstehende Beschreibung vergleichen

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

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

// Das Offer ist gesetzt, aber noch nicht von der Gegenstelle bestätigt
console.log(pc.signalingState);                 // "have-local-offer"
console.log(pc.currentLocalDescription);        // null
console.log(pc.pendingLocalDescription?.type);  // "offer"
console.log(pc.localDescription?.type);         // "offer"

have-local-offer null offer offer

Lokale Verbindung zwischen zwei Peers vollständig aushandeln

const caller = new RTCPeerConnection();
const callee = new RTCPeerConnection();
caller.addTransceiver('video');

// ICE-Kandidaten direkt austauschen (nur für die lokale Demo)
caller.onicecandidate = ({ candidate }) => candidate && callee.addIceCandidate(candidate);
callee.onicecandidate = ({ candidate }) => candidate && caller.addIceCandidate(candidate);

await caller.setLocalDescription();
await callee.setRemoteDescription(caller.localDescription);
await callee.setLocalDescription();
await caller.setRemoteDescription(callee.localDescription);

// Die Aushandlung ist abgeschlossen, jetzt gilt die Beschreibung als aktuell
console.log(caller.signalingState);                 // "stable"
console.log(caller.currentLocalDescription.type);   // "offer"
console.log(callee.currentLocalDescription.type);   // "answer"

stable offer answer

Ausgehandelte Codecs aus dem SDP auslesen

const getNegotiatedCodecs = (pc) => {
  const desc = pc.currentLocalDescription;
  if (!desc) return [];
  // Zeilen der Form "a=rtpmap:111 opus/48000/2" auswerten
  return desc.sdp
    .split('\r\n')
    .filter((line) => line.startsWith('a=rtpmap:'))
    .map((line) => line.split(' ')[1]);
};

pc.addEventListener('signalingstatechange', () => {
  if (pc.signalingState === 'stable') {
    console.log('Aktive Codecs:', getNegotiatedCodecs(pc));
  }
});

Aktive Codecs: ["opus/48000/2", "red/48000/2", ...]

// Wichtig · Fallstricke

Häufiger Fehler: Direkt nach setLocalDescription() ist currentLocalDescription meist noch null (beim Offerer) oder enthält den alten Stand. Einen Wert gibt es erst, wenn die Gegenstelle geantwortet hat. Beim Answerer wird der Wert dagegen sofort mit dem Setzen des Answers gültig.
Wenn die Verbindung wieder auf signalingState "stable" zurückgesetzt wird, etwa per Rollback mit setLocalDescription({ type: 'rollback' }), behält currentLocalDescription den zuletzt bestätigten Stand.
Jeder Zugriff liefert ein neues Objekt. Ein Vergleich mit === ist deshalb nicht sinnvoll, vergleiche stattdessen sdp und type.
Nach dem Sammeln weiterer ICE-Kandidaten kann sich der SDP-Text ändern, obwohl keine neue Aushandlung stattgefunden hat.
Der SDP-Text kann IP-Adressen enthalten. Protokolliere ihn nicht ungefiltert in Logs, die Dritte einsehen können.
Kompatibilität: unterstützt in Chrome/Edge ab 70, Firefox ab 57 und Safari ab 11. In sehr alten Browsern gibt es nur localDescription.

Siehe auch

RTCPeerConnection RTCPeerConnection.localDescription RTCPeerConnection.pendingLocalDescription RTCPeerConnection.currentRemoteDescription RTCPeerConnection.setLocalDescription() RTCPeerConnection.signalingState RTCSessionDescription