RTCIceCandidatePairStats.packetsReceived — Eigenschaft · JavaScript-Referenz

Signatur

RTCIceCandidatePairStats.packetsReceived

Beschreibung

Die Eigenschaft packetsReceived des Wörterbuchs RTCIceCandidatePairStats enthält die Gesamtzahl der Pakete, die auf einem bestimmten ICE-Kandidatenpaar empfangen wurden. Sie finden sie in Statistikberichten mit type === "candidate-pair". Diese Berichte liefert RTCPeerConnection.getStats().

Gezählt wird auf der Transportebene. Dazu gehören RTP- und RTCP-Pakete sowie DTLS- und SCTP-Pakete (DataChannel). STUN-Pakete aus den ICE-Konnektivitätsprüfungen zählen nicht mit. Deshalb ist der Wert meist höher als die Summe der packetsReceived-Werte der inbound-rtp-Berichte.

Der Zähler steigt nur an. Nützlich ist er vor allem, wenn man zwei Messungen vergleicht: Aus der Differenz zweier Messungen und ihrem timestamp berechnen Sie die Paketrate. So erkennen Sie auch, ob über ein Kandidatenpaar gerade überhaupt Daten ankommen. Zusammen mit packetsSent, bytesReceived und lastPacketReceivedTimestamp eignet er sich gut, um die Verbindungsqualität zu überwachen und Fehler zu suchen.

Rückgabewert

Typ

number | undefined

Beschreibung

Eine nicht-negative Ganzzahl (unsigned long) mit der Anzahl der bisher auf diesem Kandidatenpaar empfangenen Pakete. Unterstützt der Browser die Eigenschaft nicht, ist sie undefined.

Beispiele

Empfangene Pakete des aktiven Kandidatenpaars auslesen

// pc ist eine bestehende, verbundene RTCPeerConnection
const logReceivedPackets = async (pc) => {
  const stats = await pc.getStats();
  stats.forEach((report) => {
    // nominated + succeeded = das tatsächlich genutzte Paar
    if (report.type === "candidate-pair" && report.nominated && report.state === "succeeded") {
      console.log(`Paar ${report.id}: ${report.packetsReceived ?? "n/a"} Pakete empfangen`);
    }
  });
};

await logReceivedPackets(pc);

Paar CPabc123_def456: 18342 Pakete empfangen

Paketrate pro Sekunde berechnen

const getActivePair = async (pc) => {
  const stats = await pc.getStats();
  for (const report of stats.values()) {
    if (report.type === "transport" && report.selectedCandidatePairId) {
      return stats.get(report.selectedCandidatePairId);
    }
  }
  return null;
};

let previous = null;
setInterval(async () => {
  const pair = await getActivePair(pc);
  if (!pair || pair.packetsReceived === undefined) return;
  if (previous) {
    const seconds = (pair.timestamp - previous.timestamp) / 1000;
    const rate = (pair.packetsReceived - previous.packetsReceived) / seconds;
    console.log(`Empfangsrate: ${rate.toFixed(1)} Pakete/s`);
  }
  previous = pair;
}, 1000);

Empfangsrate: 97.3 Pakete/s

Stillstand des Empfangs erkennen

let lastCount = -1;
const checkIncoming = async () => {
  const stats = await pc.getStats();
  const pair = [...stats.values()].find(
    (r) => r.type === "candidate-pair" && r.nominated && r.state === "succeeded"
  );
  if (!pair) return;
  if (pair.packetsReceived === lastCount) {
    console.warn("Keine neuen Pakete – Verbindung möglicherweise unterbrochen");
  }
  lastCount = pair.packetsReceived;
};
setInterval(checkIncoming, 3000);

Keine neuen Pakete – Verbindung möglicherweise unterbrochen

// Wichtig · Fallstricke

Browser-Kompatibilität: Chromium-Browser unterstützen die Eigenschaft seit langem. Firefox und Safari haben sie erst später eingeführt. Prüfen Sie daher immer auf undefined, zum Beispiel mit ?? 0.
Mehrere Kandidatenpaare: getStats() liefert oft mehrere candidate-pair-Berichte. Das aktive Paar ermitteln Sie zuverlässig über RTCTransportStats.selectedCandidatePairId. Das Feld selected ist nicht standardisiert und nur in Firefox vorhanden.
Kumulativer Wert: Der Zähler wird nicht zurückgesetzt. Für Raten brauchen Sie die Differenz zweier Messungen. Bei einem ICE-Restart oder einem Wechsel des Paars kann ein neues Paar mit eigenem Zähler aktiv werden. Das sieht dann wie ein Rücksprung aus.
Keine STUN-Pakete aus den Konnektivitätsprüfungen enthalten: Für diese gibt es eigene Zähler wie requestsReceived und responsesReceived.
Verlorene Pakete lassen sich aus diesem Wert nicht ableiten. Dafür nutzen Sie RTCInboundRtpStreamStats.packetsLost.

Siehe auch

RTCIceCandidatePairStats RTCIceCandidatePairStats.packetsSent RTCIceCandidatePairStats.bytesReceived RTCIceCandidatePairStats.lastPacketReceivedTimestamp RTCPeerConnection.getStats() RTCInboundRtpStreamStats.packetsReceived