RTCSessionDescription.toJSON() — Methode · JavaScript-Referenz

Signatur

RTCSessionDescription.prototype.toJSON()

Beschreibung

Die Methode toJSON() einer RTCSessionDescription erzeugt ein einfaches JavaScript-Objekt (RTCSessionDescriptionInit) mit den beiden Eigenschaften type (z. B. "offer" oder "answer") und sdp (der SDP-Text der Sitzungsbeschreibung).

Wichtig ist sie beim Signaling: Bevor eine WebRTC-Verbindung zustande kommt, müssen Offer und Answer über einen eigenen Kanal (WebSocket, HTTP, BroadcastChannel …) ausgetauscht werden. Dafür muss die Beschreibung als Text vorliegen. JSON.stringify() ruft toJSON() automatisch auf, deshalb übergibt man die Beschreibung meist einfach direkt an JSON.stringify().

Auf der Empfängerseite kann man das geparste Objekt direkt an RTCPeerConnection.setRemoteDescription() übergeben. Einen eigenen new RTCSessionDescription()-Aufruf braucht man dafür nicht.

Rückgabewert

Typ

RTCSessionDescriptionInit ({ type: string, sdp: string })

Beschreibung

Ein einfaches Objekt mit den Eigenschaften type ("offer", "answer", "pranswer" oder "rollback") und sdp (SDP-Zeichenkette). Es ist kein JSON-String.

Beispiele

Offer erzeugen und als einfaches Objekt ausgeben

const pc = new RTCPeerConnection();
pc.createDataChannel('chat');

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

const plain = pc.localDescription.toJSON();
console.log(plain.type);
console.log(typeof plain.sdp, plain.sdp.startsWith('v=0'));

offer string true

Signaling über WebSocket – JSON.stringify ruft toJSON() automatisch auf

const ws = new WebSocket('wss://signaling.example.com');
const pc = new RTCPeerConnection({ iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] });
pc.createDataChannel('daten');

ws.addEventListener('open', async () => {
  await pc.setLocalDescription(await pc.createOffer());
  // toJSON() wird implizit aufgerufen
  ws.send(JSON.stringify({ kind: 'sdp', description: pc.localDescription }));
});

ws.addEventListener('message', async ({ data }) => {
  const msg = JSON.parse(data);
  if (msg.kind === 'sdp' && msg.description.type === 'answer') {
    // Das geparste Objekt direkt übergeben
    await pc.setRemoteDescription(msg.description);
  }
});

Beschreibung in sessionStorage zwischenspeichern

const pc = new RTCPeerConnection();
pc.createDataChannel('test');
await pc.setLocalDescription(await pc.createOffer());

sessionStorage.setItem('offer', JSON.stringify(pc.localDescription.toJSON()));

const restored = JSON.parse(sessionStorage.getItem('offer'));
console.log(Object.keys(restored));

["type", "sdp"]

// Wichtig · Fallstricke

Kein String: toJSON() gibt ein Objekt zurück, keinen JSON-Text. Für den Versand brauchst du trotzdem JSON.stringify().
ICE-Kandidaten: Direkt nach createOffer() enthält die SDP oft noch keine Kandidaten. Diese musst du dann per Trickle ICE über das icecandidate-Ereignis getrennt senden (RTCIceCandidate.toJSON()). Alternativ wartest du, bis iceGatheringState den Wert "complete" hat.
Sicherheit: Die SDP enthält unter anderem Fingerprints und je nach Situation IP-Adressen. Signaling-Kanäle sollten deshalb verschlüsselt sein (wss://, HTTPS). Empfangene Beschreibungen gelten als nicht vertrauenswürdig und sollten nie ungeprüft per innerHTML ausgegeben werden.
Kompatibilität: In allen aktuellen Browsern verfügbar. localDescription kann null sein, solange noch keine Beschreibung gesetzt ist. Prüfe das vor dem Aufruf.

Siehe auch

RTCSessionDescription RTCPeerConnection.setRemoteDescription() RTCPeerConnection.setLocalDescription() RTCPeerConnection.createOffer() RTCIceCandidate.toJSON() JSON.stringify() LargestContentfulPaint.toJSON()