Signatur
Beschreibung
Die Eigenschaft remoteDescription einer RTCPeerConnection gibt die Sitzungsbeschreibung der entfernten Gegenstelle zurück. Das ist ein RTCSessionDescription-Objekt mit dem Typ (offer, answer, pranswer oder rollback) und dem eigentlichen SDP-Text, der unter anderem Codecs, Medienspuren, ICE-Anmeldedaten und DTLS-Fingerabdrücke beschreibt.
Gesetzt wird der Wert ausschließlich über setRemoteDescription(), typischerweise wenn über den Signalisierungskanal (z. B. WebSocket) ein Offer oder Answer der Gegenseite eintrifft. Ist noch keine Beschreibung gesetzt, liefert die Eigenschaft null.
Während einer laufenden Neuverhandlung gilt: remoteDescription gibt pendingRemoteDescription zurück, wenn es eine ausstehende Beschreibung gibt, ansonsten currentRemoteDescription. Wer genau wissen muss, ob die Beschreibung schon ausgehandelt ist, sollte deshalb direkt diese beiden Eigenschaften abfragen.
In der Praxis dient remoteDescription vor allem als Prüfung, ob schon ICE-Kandidaten per addIceCandidate() hinzugefügt werden dürfen (das geht erst nach gesetzter Remote-Beschreibung), sowie zur Fehlersuche und Analyse des ausgehandelten SDP.
Rückgabewert
type und sdp, oder null, wenn noch keine gesetzt wurde.Beispiele
Remote-Beschreibung setzen und auslesen
const pc = new RTCPeerConnection();
// Offer der Gegenseite kam über den Signalisierungskanal
const handleOffer = async (offer) => {
console.log(pc.remoteDescription); // null
await pc.setRemoteDescription(offer);
console.log(pc.remoteDescription.type);
const answer = await pc.createAnswer();
await pc.setLocalDescription(answer);
return pc.localDescription;
};ICE-Kandidaten puffern, bis remoteDescription gesetzt ist
const pc = new RTCPeerConnection();
const pendingCandidates = [];
const onRemoteCandidate = async (candidate) => {
if (pc.remoteDescription) {
await pc.addIceCandidate(candidate);
} else {
// addIceCandidate() würde sonst mit InvalidStateError fehlschlagen
pendingCandidates.push(candidate);
}
};
const onRemoteDescription = async (desc) => {
await pc.setRemoteDescription(desc);
for (const c of pendingCandidates.splice(0)) {
await pc.addIceCandidate(c);
}
};Ausgehandelte Codecs aus dem Remote-SDP ermitteln
const logRemoteCodecs = (pc) => {
const desc = pc.remoteDescription;
if (!desc) {
console.log('Noch keine Remote-Beschreibung');
return;
}
const codecs = desc.sdp
.split('\r\n')
.filter((line) => line.startsWith('a=rtpmap:'))
.map((line) => line.split(' ')[1]);
console.log(codecs);
};// Wichtig · Fallstricke
- Schreibgeschützt: Eine Zuweisung an
pc.remoteDescriptionhat keine Wirkung (im Strict Mode gibt es einenTypeError). Setzen geht nur übersetRemoteDescription(). - Ausstehend oder aktuell: Während einer Neuverhandlung kann der Wert eine noch nicht bestätigte Beschreibung sein. Für den tatsächlich ausgehandelten Stand
currentRemoteDescriptionverwenden. - Kein Snapshot: Nach jedem erfolgreichen
setRemoteDescription()kann sich das zurückgegebene Objekt ändern. Den Wert also nicht dauerhaft zwischenspeichern. - Nach
close(): Der zuletzt gesetzte Wert bleibt lesbar, lässt sich aber nicht mehr ändern. - SDP-Munging: Den SDP-Text von Hand zu bearbeiten ist fehleranfällig und läuft je nach Browser unterschiedlich. Besser Standard-APIs wie
RTCRtpTransceiver.setCodecPreferences()verwenden. - Sicherheit: Das SDP enthält IP-Adressen (ICE-Kandidaten) und ICE-Anmeldedaten. Nicht unbedacht protokollieren oder an Dritte senden.
- Kompatibilität: In Chrome, Firefox, Safari und Edge verfügbar. Sehr alte Implementierungen lieferten den Wert erst nach vollständigem Verbindungsaufbau oder mit Präfix (
webkitRTCPeerConnection).