RTCPeerConnection.localDescription — Eigenschaft · JavaScript-Referenz

Signatur

RTCPeerConnection.localDescription

Beschreibung

Die Eigenschaft localDescription einer RTCPeerConnection enthält die Sitzungsbeschreibung (SDP) des lokalen Endes der Verbindung. Sie ist ein RTCSessionDescription-Objekt mit den Feldern type ("offer", "answer", "pranswer" oder "rollback") und sdp (der SDP-Text). Solange noch keine Beschreibung gesetzt wurde, ist der Wert null.

Verwendet wird die Eigenschaft vor allem beim Signalisieren: Nach setLocalDescription() liest man pc.localDescription aus und schickt sie über einen eigenen Kanal (z. B. WebSocket) an die Gegenstelle. Anders als das von createOffer() gelieferte Objekt enthält localDescription bereits gesammelte ICE-Kandidaten. Das ist nützlich, wenn man ohne Trickle-ICE arbeitet und erst nach Abschluss der Kandidatensuche (iceGatheringState === "complete") die vollständige Beschreibung verschicken möchte.

Intern liefert die Eigenschaft die pendingLocalDescription, falls gerade eine Verhandlung läuft, andernfalls die currentLocalDescription. Wer gezielt zwischen ausgehandeltem und noch schwebendem Zustand unterscheiden will, sollte diese beiden Eigenschaften direkt verwenden.

Rückgabewert

Typ

RTCSessionDescription | null

Beschreibung

Die aktuelle bzw. schwebende lokale Sitzungsbeschreibung mit type und sdp, oder null, wenn noch keine lokale Beschreibung gesetzt wurde.

Beispiele

Angebot erzeugen und lokale Beschreibung signalisieren

const pc = new RTCPeerConnection();
const ws = new WebSocket('wss://signal.example.com');

pc.addTransceiver('audio');

const sendOffer = async () => {
  // Ohne Argument erzeugt setLocalDescription() automatisch ein Offer
  await pc.setLocalDescription();
  console.log(pc.localDescription.type);
  ws.send(JSON.stringify({ description: pc.localDescription }));
};

ws.addEventListener('open', sendOffer);

offer

Vor dem Setzen ist der Wert null

const pc = new RTCPeerConnection();
console.log(pc.localDescription); // null

const offer = await pc.createOffer({ offerToReceiveVideo: true });
await pc.setLocalDescription(offer);
console.log(pc.localDescription.type, pc.localDescription.sdp.startsWith('v=0'));

null offer true

Vollständige SDP inkl. ICE-Kandidaten (ohne Trickle-ICE)

const waitForIceGathering = (pc) =>
  new Promise((resolve) => {
    if (pc.iceGatheringState === 'complete') return resolve();
    const onChange = () => {
      if (pc.iceGatheringState === 'complete') {
        pc.removeEventListener('icegatheringstatechange', onChange);
        resolve();
      }
    };
    pc.addEventListener('icegatheringstatechange', onChange);
  });

const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
});
pc.createDataChannel('chat');

await pc.setLocalDescription();
await waitForIceGathering(pc);

// localDescription enthält jetzt alle a=candidate-Zeilen
const candidates = pc.localDescription.sdp
  .split('\r\n')
  .filter((line) => line.startsWith('a=candidate'));
console.log(`${candidates.length} Kandidaten in der SDP`);

3 Kandidaten in der SDP

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an pc.localDescription hat keine Wirkung. Zum Setzen immer setLocalDescription() verwenden.
Nicht das Offer-Objekt verschicken: Das Ergebnis von createOffer() enthält keine ICE-Kandidaten. Besser nach setLocalDescription() die localDescription senden.
Kein Snapshot: Jeder Zugriff kann ein neues Objekt mit aktualisierter SDP liefern, z. B. nachdem neue Kandidaten gesammelt wurden. Den Wert daher nicht dauerhaft zwischenspeichern.
Serialisierung: RTCSessionDescription hat eine toJSON()-Methode, deshalb funktioniert JSON.stringify(pc.localDescription) direkt.
Sicherheit/Datenschutz: Die SDP kann lokale und öffentliche IP-Adressen enthalten (moderne Browser verschleiern lokale Adressen per mDNS). Den Signalisierungskanal über TLS (wss://) absichern.
Kompatibilität: Wird von allen modernen Browsern unterstützt. setLocalDescription() ohne Argument (implizites Offer/Answer) gibt es erst in neueren Versionen: Chrome 80+, Firefox 75+, Safari 14.1+. Nach close() bleibt der zuletzt gesetzte Wert erhalten.

Siehe auch

RTCPeerConnection RTCPeerConnection.setLocalDescription() RTCPeerConnection.remoteDescription RTCPeerConnection.currentLocalDescription RTCPeerConnection.pendingLocalDescription RTCSessionDescription RTCPeerConnection.createOffer()