RTCPeerConnection.canTrickleIceCandidates — Eigenschaft · JavaScript-Referenz

Signatur

RTCPeerConnection.canTrickleIceCandidates

Beschreibung

Die schreibgeschützte Eigenschaft canTrickleIceCandidates zeigt, ob die Gegenseite einer RTCPeerConnection Trickle ICE unterstützt. Bei Trickle ICE schickt man die ICE-Kandidaten einzeln über den Signalisierungskanal, sobald sie gefunden werden. Man muss also nicht warten, bis die Kandidatensuche (ICE Gathering) fertig ist. Dadurch steht die Verbindung oft deutlich schneller.

Der Browser liest den Wert aus der entfernten Sitzungsbeschreibung (SDP). Steht dort a=ice-options:trickle, ist die Eigenschaft true, sonst false. Solange noch keine entfernte Beschreibung gesetzt ist, ist der Wert null. Sinnvoll auswerten lässt sich die Eigenschaft deshalb erst nach einem erfolgreichen Aufruf von setRemoteDescription().

Nützlich ist die Eigenschaft vor allem, wenn Ihre Anwendung auch mit Gegenstellen ohne Trickle ICE zusammenarbeiten muss, etwa mit älteren SIP-Gateways oder Media-Servern. Unterstützt die Gegenseite Trickle ICE nicht, wartet man, bis iceGatheringState den Wert "complete" erreicht. Danach schickt man die vollständige localDescription mit allen Kandidaten auf einmal.

Rückgabewert

Typ

boolean | null

Beschreibung

true: Der entfernte Peer akzeptiert nachgereichte Kandidaten.
false: Der entfernte Peer akzeptiert sie nicht.
null: Es ist noch keine entfernte Beschreibung gesetzt.

Beispiele

Wert vor und nach setRemoteDescription()

const pc = new RTCPeerConnection();
console.log(pc.canTrickleIceCandidates); // noch keine entfernte Beschreibung

// remoteOffer kommt vom Signalisierungsserver
const handleOffer = async (remoteOffer) => {
  await pc.setRemoteDescription(remoteOffer);
  console.log('Trickle ICE möglich:', pc.canTrickleIceCandidates);
};

null Trickle ICE möglich: true

Antwort abhängig von Trickle-Unterstützung senden

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

// Wartet, bis alle ICE-Kandidaten gesammelt sind
const waitForIceGatheringComplete = (conn) =>
  new Promise((resolve) => {
    if (conn.iceGatheringState === 'complete') return resolve();
    const onChange = () => {
      if (conn.iceGatheringState === 'complete') {
        conn.removeEventListener('icegatheringstatechange', onChange);
        resolve();
      }
    };
    conn.addEventListener('icegatheringstatechange', onChange);
  });

const answerOffer = async (remoteOffer, signaling) => {
  await pc.setRemoteDescription(remoteOffer);
  const answer = await pc.createAnswer();
  await pc.setLocalDescription(answer);

  if (pc.canTrickleIceCandidates) {
    // Antwort sofort senden, Kandidaten folgen einzeln
    pc.addEventListener('icecandidate', ({ candidate }) => {
      if (candidate) signaling.send(JSON.stringify({ candidate }));
    });
    signaling.send(JSON.stringify({ sdp: pc.localDescription }));
  } else {
    // Gegenseite kann kein Trickle ICE: vollständige SDP senden
    await waitForIceGatheringComplete(pc);
    signaling.send(JSON.stringify({ sdp: pc.localDescription }));
  }
};

Robuste Prüfung mit Fallback, wenn die Eigenschaft fehlt

const supportsTrickle = (pc) => {
  // Chromium kennt die Eigenschaft nicht, dort ist sie undefined
  if (!('canTrickleIceCandidates' in pc)) {
    // Fallback: entfernte SDP selbst durchsuchen
    const sdp = pc.remoteDescription?.sdp ?? '';
    return /^a=ice-options:.*\btrickle\b/m.test(sdp);
  }
  return pc.canTrickleIceCandidates === true;
};

const pc = new RTCPeerConnection();
console.log(supportsTrickle(pc)); // noch keine entfernte Beschreibung

false

// Wichtig · Fallstricke

null ist nicht false: Vor setRemoteDescription() ist der Wert null. Wer nur auf Falsy prüft (if (!pc.canTrickleIceCandidates)), behandelt deshalb „noch unbekannt“ genauso wie „nicht unterstützt“. Werten Sie die Eigenschaft erst nach dem Setzen der entfernten Beschreibung aus.
Browser-Unterstützung: Firefox und Safari bieten die Eigenschaft an. Chromium-basierte Browser (Chrome, Edge, Opera) haben sie laut den gängigen Kompatibilitätstabellen nicht, dort liefert sie undefined. Prüfen Sie deshalb mit 'canTrickleIceCandidates' in pc und werten Sie notfalls die Zeile a=ice-options:trickle in remoteDescription.sdp selbst aus.
Zwischen zwei Browsern wird Trickle ICE praktisch immer unterstützt. Relevant ist die Eigenschaft vor allem bei Gegenstellen wie SIP-Gateways oder älteren Media-Servern.
Ohne Trickle ICE sollten Sie ein Zeitlimit für das Warten auf iceGatheringState === "complete" einbauen. Nicht erreichbare STUN- oder TURN-Server können die Kandidatensuche sonst mehrere Sekunden verzögern.

Siehe auch

RTCPeerConnection RTCPeerConnection.prototype.setRemoteDescription() RTCPeerConnection.prototype.addIceCandidate() RTCPeerConnection.iceGatheringState RTCPeerConnection.connectionState