RTCIceCandidatePairStats.transportId — Eigenschaft · JavaScript-Referenz

Signatur

RTCIceCandidatePairStats.transportId

Beschreibung

Die schreibgeschützte Eigenschaft transportId eines RTCIceCandidatePairStats-Objekts (Statistik-Typ "candidate-pair") ist ein String. Er bezeichnet eindeutig den Transport, also den zugrunde liegenden RTCIceTransport bzw. RTCDtlsTransport, über den dieses Kandidatenpaar geprüft wurde. Der Wert stimmt mit der id eines Eintrags vom Typ "transport" (RTCTransportStats) im selben RTCStatsReport überein.

Nützlich ist die Eigenschaft vor allem, um Statistiken miteinander zu verknüpfen. Zu einem Kandidatenpaar findest du so den Transport-Eintrag, etwa den DTLS-Zustand, die gesendeten und empfangenen Bytes oder das gerade ausgewählte Paar (selectedCandidatePairId). Umgekehrt kannst du alle Kandidatenpaare heraussuchen, die zu einem bestimmten Transport gehören.

Wenn mehrere Medienspuren gebündelt über eine Verbindung laufen (bundlePolicy: "max-bundle"), gibt es meist nur einen Transport. Dann haben alle Kandidatenpaare dieselbe transportId. Ohne Bündelung kann es mehrere Transporte geben, und die Paare verteilen sich auf sie.

Rückgabewert

Typ

string

Beschreibung

Die ID des zugehörigen RTCTransportStats-Eintrags im selben RTCStatsReport. Mit report.get(transportId) kannst du ihn direkt abrufen.

Beispiele

transportId aller Kandidatenpaare ausgeben

const pc = new RTCPeerConnection();
// ... Signalisierung und Verbindungsaufbau ...

const report = await pc.getStats();
report.forEach((stats) => {
  if (stats.type === 'candidate-pair') {
    console.log(`Paar ${stats.id} → Transport ${stats.transportId} (Status: ${stats.state})`);
  }
});

Paar CP1a2b3c → Transport T01 (Status: succeeded)

Vom Kandidatenpaar zum Transport-Eintrag

const getPairTransport = async (pc) => {
  const report = await pc.getStats();
  for (const stats of report.values()) {
    if (stats.type === 'candidate-pair' && stats.nominated) {
      const transport = report.get(stats.transportId);
      return {
        pairId: stats.id,
        dtlsState: transport?.dtlsState,
        bytesSent: transport?.bytesSent
      };
    }
  }
  return null;
};

console.log(await getPairTransport(pc));

{ pairId: 'CP1a2b3c', dtlsState: 'connected', bytesSent: 184320 }

Kandidatenpaare nach Transport gruppieren

const groupPairsByTransport = async (pc) => {
  const report = await pc.getStats();
  const groups = new Map();
  for (const stats of report.values()) {
    if (stats.type !== 'candidate-pair') continue;
    const list = groups.get(stats.transportId) ?? [];
    list.push(stats.id);
    groups.set(stats.transportId, list);
  }
  return groups;
};

const groups = await groupPairsByTransport(pc);
groups.forEach((pairs, transportId) => {
  console.log(transportId, '→', pairs.length, 'Paare');
});

T01 → 4 Paare

// Wichtig · Fallstricke

Die ID ist ein undurchsichtiger Bezeichner. Ihr Format unterscheidet sich je nach Browser (z. B. "T01" in Chrome, eine UUID-ähnliche Zeichenkette in Firefox). Werte ihn nicht inhaltlich aus, sondern nutze ihn nur als Schlüssel für report.get().
Die ID ist nur innerhalb derselben RTCPeerConnection gültig. Zwischen zwei getStats()-Aufrufen bleibt sie in der Regel gleich, bei einem ICE-Neustart oder einer Neuverhandlung kann sich der Transport aber ändern.
Firefox hat lange keine "transport"-Einträge geliefert. Dann gibt report.get(transportId) undefined zurück, deshalb optionale Verkettung (?.) verwenden.
Ein Paar mit nominated: true ist nicht automatisch das aktive Paar. Zuverlässiger ist RTCTransportStats.selectedCandidatePairId.
getStats() ist asynchron und nicht kostenlos. Für die Überwachung in Intervallen von etwa einer Sekunde abfragen, nicht in jedem Frame.

Siehe auch

RTCIceCandidatePairStats RTCPeerConnection.prototype.getStats() RTCStatsReport RTCIceTransport RTCIceCandidatePairStats.remoteCandidateId RTCIceCandidatePairStats.selected