RTCStatsReport.get() — Methode · JavaScript-Referenz

Signatur

RTCStatsReport.prototype.get(id)

Beschreibung

RTCStatsReport ist ein schreibgeschütztes, Map-ähnliches Objekt. Es enthält alle Statistiken, die RTCPeerConnection.getStats(), RTCRtpSender.getStats() oder RTCRtpReceiver.getStats() liefern. Jeder Eintrag ist ein Wörterbuch-Objekt (z. B. RTCInboundRtpStreamStats, RTCIceCandidatePairStats). Der Schlüssel ist die eindeutige id dieses Objekts.

Mit get(id) greifst du gezielt auf einen Eintrag zu, dessen ID du schon kennst. In der Praxis brauchst du das vor allem, um Verweise zwischen Statistik-Objekten aufzulösen. Viele Statistiken zeigen nämlich über ID-Felder auf andere Einträge, zum Beispiel codecId, transportId, localCandidateId, remoteCandidateId oder selectedCandidatePairId.

Die ID-Werte werden vom Browser vergeben und sind nicht genormt. Rate sie also nicht, sondern lies sie immer aus einem anderen Statistik-Objekt aus. Innerhalb einer Verbindung bleiben die IDs über mehrere getStats()-Aufrufe hinweg gleich. Deshalb eignen sie sich gut, um Werte zwischen zwei Messungen zu vergleichen, etwa um Bitraten zu berechnen.

Parameter

Name	Typ	Default	Beschreibung
$id Pflicht	string		Die eindeutige ID des gesuchten Statistik-Objekts, also der Wert seiner Eigenschaft `id`. Meist liest du sie aus einem Verweisfeld wie `transportId` oder `codecId` aus.

Rückgabewert

Typ

RTCStats | undefined

Beschreibung

Das Statistik-Objekt mit der angegebenen ID. Es hat mindestens die Felder id, type und timestamp sowie weitere Felder, die vom Typ abhängen. Gibt es keinen Eintrag mit dieser ID, ist der Rückgabewert undefined.

Beispiele

Aktives ICE-Kandidatenpaar über den Transport ermitteln

const getSelectedPair = async (pc) => {
  const report = await pc.getStats();
  for (const stats of report.values()) {
    if (stats.type === 'transport' && stats.selectedCandidatePairId) {
      // Verweis per get() auflösen
      const pair = report.get(stats.selectedCandidatePairId);
      const local = report.get(pair.localCandidateId);
      const remote = report.get(pair.remoteCandidateId);
      console.log(`RTT: ${pair.currentRoundTripTime}s`);
      console.log(`Lokal: ${local.candidateType}, Remote: ${remote.candidateType}`);
      return pair;
    }
  }
  return undefined;
};

await getSelectedPair(peerConnection);

RTT: 0.034s Lokal: host, Remote: srflx

Verwendeten Codec eines eingehenden Videostreams anzeigen

const report = await peerConnection.getStats();

report.forEach((stats) => {
  if (stats.type === 'inbound-rtp' && stats.kind === 'video') {
    const codec = stats.codecId ? report.get(stats.codecId) : undefined;
    console.log(codec?.mimeType ?? 'Codec unbekannt');
  }
});

video/VP8

Eingehende Bitrate zwischen zwei Messungen berechnen

let previous = null;

const measureBitrate = async (receiver) => {
  const report = await receiver.getStats();
  for (const stats of report.values()) {
    if (stats.type !== 'inbound-rtp') continue;
    // Gleiche ID im vorherigen Bericht per get() nachschlagen
    const old = previous?.get(stats.id);
    if (old) {
      const bits = (stats.bytesReceived - old.bytesReceived) * 8;
      const seconds = (stats.timestamp - old.timestamp) / 1000;
      console.log(`${Math.round(bits / seconds / 1000)} kbit/s`);
    }
  }
  previous = report;
};

setInterval(() => measureBitrate(videoReceiver), 1000);

1482 kbit/s

// Wichtig · Fallstricke

Nicht genormte IDs: Das Format der IDs ist von Browser zu Browser verschieden (Chrome z. B. "IT01V1234", Firefox eher UUID-ähnlich). Schreibe IDs nie fest in den Code, sondern lies sie immer aus Verweisfeldern oder aus stats.id aus.
Auf undefined prüfen: Verweisfelder wie codecId oder remoteId können fehlen. Ein referenziertes Objekt kann auch in einem gefilterten Bericht fehlen, etwa bei RTCRtpSender.getStats(). Nutze deshalb optionale Verkettung (?.) oder prüfe vorher mit has().
Schreibgeschützt: RTCStatsReport ist ein Map-ähnliches Objekt, aber keine echte Map. Es gibt get, has, keys, values, entries, forEach und size, aber kein set, delete und kein clear.
Momentaufnahme: Jeder getStats()-Aufruf liefert einen neuen, festen Bericht. Wenn du Werte über die Zeit vergleichen willst, hebe den vorherigen Bericht auf.
Kompatibilität: In allen modernen Browsern verfügbar. Sehr alte Chrome-Versionen hatten eine veraltete, callback-basierte getStats()-API mit anderem Aufbau, die heute nicht mehr verwendet werden sollte.

Siehe auch

RTCStatsReport RTCStatsReport.has() RTCStatsReport.forEach() RTCStatsReport.values() RTCPeerConnection.getStats() RTCRtpReceiver.getStats() Map.prototype.get()