WebRTC: Legacy-Migrationsanleitung für getStats()

Henrik Boström

Die alte getStats() WebRTC API wird in Chrome 117 entfernt. Daher müssen Apps, die sie verwenden, zur Standard-API migriert werden. In diesem Artikel erfahren Sie, wie Sie Ihren Code migrieren und was Sie tun können, wenn Sie mehr Zeit für diese Änderung benötigen.

In der Vergangenheit gab es zwei konkurrierende Versionen der WebRTC getStats() API. Die alte getStats()-API, die aus der Zeit vor dem Standardisierungsprozess stammt und ein Callback-Argument verwendet, und die standardisierte und allgemein unterstützte API, die ein Promise zurückgibt.

Die Standard-API bietet mehr Funktionen und klar definierte Messwerte, die öffentlich in der W3C-Spezifikation Identifiers for WebRTC's Statistics API dokumentiert sind. Die Spezifikation enthält unter anderem Beschreibungen aller in diesem Leitfaden aufgeführten Messwerte.

Ab Chrome 117 löst die alte getStats() API eine Ausnahme in der stabilen Release-Version aus. Diese wird nach und nach eingeführt. Folgen Sie dieser Anleitung, um den Übergang zur Standard-API zu erleichtern.

Bisherige und Standard-Statistiktypen

Die vollständige Liste der Standard-Statistiktypen finden Sie in der RTCStatsType-Enum in der Spezifikation. Dazu gehört, welche Definition des Statistikwörterbuchs die für jeden Typ erfassten Messwerte beschreibt.

Alle Statistikobjekte haben ein ID-Attribut, das das zugrunde liegende Objekt über mehrere getStats()-Aufrufe hinweg eindeutig identifiziert. Dasselbe Objekt hat bei jedem Aufruf der Methode dieselbe ID. Dies ist nützlich, um die Änderungsrate von Messwerten zu berechnen. Im nächsten Abschnitt finden Sie ein Beispiel. Die IDs bilden auch Beziehungen von Referenzen. Beispielsweise verweist das Statistikobjekt outbound-rtp über das Attribut outbound-rtp.mediaSourceId auf das zugehörige Statistikobjekt media-source. Wenn Sie alle ...Id-Beziehungen zeichnen, erhalten Sie ein Diagramm.

Die alte API hat die folgenden Statistiktypen, die den Standardtypen wie folgt entsprechen:

Zuordnung von Legacy- zu Standardmesswerten

Diese Zuordnung soll Entwicklern helfen, herauszufinden, welcher alte Messwert welchem Standardmesswert entspricht. Für den entsprechenden Messwert können jedoch andere Einheiten verwendet oder als Gesamtzähler und nicht als momentaner Wert ausgedrückt werden. Die Messwertdefinitionen finden Sie in der Spezifikation.
Die Standard-API bevorzugt die Angabe von Gesamtzählern anstelle von Preisen. Das bedeutet: Um die entsprechende Rate (z. B. die Bitrate) wie in der Legacy-API zu erhalten, muss die App die durchschnittliche Rate anhand der Differenz zwischen zwei getStats()-Aufrufen berechnen. Beispiel:

// Periodically (e.g. every second or every 10 seconds)...
const currReport = await pc.getStats();
// Calculate bitrate since the last getStats() call.
// Handling of undefined is omitted for clarity.
const currOutboundRtp = currReport.values().find(s => s.type == 'outbound-rtp');
const prevOutboundRtp = prevReport.get(currOutboundRtp.id);
const deltaBits = (currOutboundRtp.bytesSent - prevOutboundRtp.bytesSent) * 8;
const deltaSeconds = (currOutboundRtp.timestamp - prevOutboundRtp.timestamp) / 1000;
logBitrateMeasurement(deltaBits / deltaSeconds);
// Remember the report for next time.
prevReport = currReport;

Raten und Durchschnittswerte selbst berechnen zu müssen, mag wie ein umständlicher zusätzlicher Schritt erscheinen, bietet aber den Vorteil, dass Sie über jedes gewünschte Zeitintervall Durchschnittswerte ermitteln können. Wenn die Standard-API seltener aufgerufen wird, als dies bei der alten API sonst der Fall wäre, hat dies einige Leistungsvorteile.

Die Standard-API ist Simulcast-fähig

Wenn Sie Simulcast verwenden, haben Sie vielleicht bemerkt, dass die Legacy-API nur einen einzelnen SSRC meldet, auch wenn Sie Simulcast verwenden, um zum Beispiel drei RTP-Streams über drei separate SSRCs zu senden.

Die Standard-API teilt diese Einschränkung nicht und gibt drei outbound-rtp-Statistikobjekte zurück, eines für jeden der SSRCs. Das bedeutet, dass Sie jeden RTP-Stream einzeln analysieren können. Um die Gesamtbitrate aller RTP-Sendestreams zu erhalten, müssen Sie sie aber selbst aggregieren.

SVC-Streams oder RTP-Streams mit mehreren über die scalabilityMode API konfigurierten räumlichen Ebenen werden dagegen weiterhin als einzelne outbound-rtp angezeigt, da sie über einen einzelnen SSRC gesendet werden.

Wenn Sie mehr Zeit für die Migration benötigen

Wenn die alte API in Chrome 117 entfernt wird, wird durch ihre Verwendung eine Ausnahme generiert. Wenn Sie Ihren Code nicht rechtzeitig migrieren können, gibt der Ursprungstest für die RTCPeerConnection-Callback-basierte getStats() API registrierten Websites mehr Zeit für die Migration. Mit einem Ursprungstesttoken kann die alte getStats() API bis Chrome 121 weiter verwendet werden.