RTCIceCandidatePairStats.priority — Eigenschaft · JavaScript-Referenz

Signatur

RTCIceCandidatePairStats.priority

Beschreibung

Die schreibgeschützte Eigenschaft priority eines RTCIceCandidatePairStats-Objekts gibt an, wie wichtig ein Kandidatenpaar für den ICE-Agenten ist. Ein höherer Wert bedeutet, dass der Agent das Paar früher prüft und bei der Auswahl der Verbindung eher nimmt. Solche Objekte erhältst du über RTCPeerConnection.getStats(). Es sind die Einträge, deren type den Wert "candidate-pair" hat.

Die Priorität wird nach RFC 8445, Abschnitt 6.1.2.3 berechnet. G ist die Priorität des Kandidaten des steuernden Agenten (controlling), D die des gesteuerten Agenten (controlled):
2^32 · MIN(G, D) + 2 · MAX(G, D) + (G > D ? 1 : 0).
Das Ergebnis ist eine vorzeichenlose 64-Bit-Zahl.

Nützlich ist die Eigenschaft vor allem beim Debuggen der Verbindung. Du siehst daran, warum ICE ein bestimmtes Paar gewählt hat, zum Beispiel eine direkte Host-Verbindung statt eines TURN-Relays. Die Eigenschaft wurde aus der Spezifikation entfernt. Portabler Code sollte die Priorität deshalb selbst aus localCandidateId und remoteCandidateId berechnen: Die zugehörigen RTCIceCandidateStats haben eine eigene priority.

Rückgabewert

Typ

number | undefined

Beschreibung

Eine ganze Zahl mit der Priorität des Kandidatenpaars. In Browsern, die die Eigenschaft nicht unterstützen, ist der Wert undefined.

Beispiele

Prioritäten aller Kandidatenpaare ausgeben

const logPairPriorities = async (pc) => {
  const stats = await pc.getStats();
  stats.forEach((report) => {
    if (report.type === 'candidate-pair') {
      console.log(
        `Paar ${report.id}: Zustand=${report.state}, priority=${report.priority ?? 'nicht verfügbar'}`
      );
    }
  });
};

// Aufruf, z. B. nach erfolgreichem Verbindungsaufbau
// await logPairPriorities(peerConnection);

Paar RTCIceCandidatePair_abc: Zustand=succeeded, priority=9115038255631187967

Priorität portabel mit BigInt berechnen (RFC 8445)

const pairPriority = (controllingPrio, controlledPrio) => {
  const G = BigInt(controllingPrio);
  const D = BigInt(controlledPrio);
  const min = G < D ? G : D;
  const max = G > D ? G : D;
  return (1n << 32n) * min + 2n * max + (G > D ? 1n : 0n);
};

const computePriorities = async (pc, isControlling) => {
  const stats = await pc.getStats();
  for (const report of stats.values()) {
    if (report.type !== 'candidate-pair') continue;
    const local = stats.get(report.localCandidateId);
    const remote = stats.get(report.remoteCandidateId);
    if (!local || !remote) continue;
    const [g, d] = isControlling
      ? [local.priority, remote.priority]
      : [remote.priority, local.priority];
    console.log(report.id, pairPriority(g, d).toString());
  }
};

console.log(pairPriority(2122260223, 1686052607).toString());

7241541142572187135

Priorität des aktiv genutzten Paars ermitteln

const getSelectedPair = async (pc) => {
  const stats = await pc.getStats();
  for (const report of stats.values()) {
    if (report.type === 'transport' && report.selectedCandidatePairId) {
      return stats.get(report.selectedCandidatePairId);
    }
  }
  // Fallback: nominiertes Paar im Zustand „succeeded“
  return [...stats.values()].find(
    (r) => r.type === 'candidate-pair' && r.nominated && r.state === 'succeeded'
  );
};

const pair = await getSelectedPair(peerConnection);
console.log('Aktives Paar:', pair?.id, 'Priorität:', pair?.priority);

Aktives Paar: RTCIceCandidatePair_xyz Priorität: 9115038255631187967

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: Die Eigenschaft wurde aus der WebRTC-Statistik-Spezifikation gestrichen. Firefox liefert sie noch, Chromium-Browser und Safari nicht. Rechne immer mit undefined und prüfe den Wert, zum Beispiel mit ?? .
Genauigkeit: Die Priorität nach RFC 8445 kann bis zu 2⁶⁴ groß werden. Das liegt weit über Number.MAX_SAFE_INTEGER (2⁵³ − 1). Deshalb ist der gelieferte number-Wert möglicherweise gerundet, und zwei Paare mit fast gleicher Priorität lassen sich nicht mehr sicher unterscheiden. Für genaue Berechnungen und Vergleiche verwende BigInt.
Welcher Kandidat als G und welcher als D zählt, hängt davon ab, ob der eigene Agent steuert (controlling) oder gesteuert wird (controlled). Dieselbe Verbindung hat auf beiden Seiten also dieselbe Paar-Priorität. Die Rollen der lokalen und entfernten Kandidaten sind dabei aber vertauscht.
Die Statistik ist nur eine Momentaufnahme. Nach einem ICE-Restart oder neu eintreffenden Trickle-Kandidaten musst du getStats() erneut aufrufen.

Siehe auch

RTCIceCandidatePairStats RTCPeerConnection.getStats() RTCIceCandidatePairStats.nominated RTCIceCandidatePairStats.state RTCIceCandidate.priority RTCStatsReport RTCIceCandidatePairStats.readable