WebRTC: Legacy-Migrationsanleitung für getStats()

Henrik Boström

Die alte getStats() WebRTC API wird in Chrome 117 entfernt. Apps, die sie verwenden, müssen daher 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.

Bisher gab es zwei konkurrierende Versionen der WebRTC getStats() API. Die alte getStats()-API, die vor dem Standardisierungsprozess datiert ist und ein Callback-Argument annimmt, und die standardisierte und weit verbreitete 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 Beschreibungen aller in diesem Handbuch aufgeführten Messwerte und viele weitere.

Ab Chrome 117 löst die alte getStats() API eine Ausnahme in der stabilen Release-Version aus. Die Ausnahme wird nach und nach eingeführt. Befolgen Sie diese Anleitung, um Ihnen die Umstellung auf die Standard-API zu erleichtern.

Legacy- und Standard-Statistiktypen

Die vollständige Liste der Standard-Statistiktypen findest du unter dem Enum RTCStatsType in der Spezifikation. Dazu gehört auch, welche Statistikwörterbuchdefinition die für jeden Typ erfassten Messwerte beschreibt.

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

Die Legacy-API hat die folgenden Statistiktypen, die den folgenden Standardtypen entsprechen:

Zuordnung von Legacy- zu Standard-Messwerten

Diese Zuordnung soll Entwicklern helfen, herauszufinden, welcher alte Messwert zu welchem Standardmesswert gehört. Der entsprechende Messwert kann jedoch andere Einheiten verwenden oder als Summenzähler und nicht als sofortiger Wert ausgedrückt werden. Messwertdefinitionen finden Sie in der Spezifikation.
Bei der Standard-API werden lieber Gesamtzähler anstelle von Raten bereitgestellt. Das bedeutet, dass die App wie bei der Legacy-API die durchschnittliche Rate anhand des Deltas zwischen zwei getStats()-Aufrufen berechnen muss, um die entsprechende Rate (z. B. Bitrate) zu ermitteln. 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 so berechnen zu müssen, mag wie ein lästiger zusätzlicher Schritt erscheinen, hat aber den Vorteil, dass Sie Durchschnittswerte für jedes gewünschte Zeitintervall ermitteln können. Wenn Sie die Standard-API seltener aufrufen als mit der Legacy-API, ergeben sich einige Leistungsvorteile.

Die Standard-API ist simulcast-fähig.

Wenn Sie Simulcast verwenden, haben Sie vielleicht bemerkt, dass die alte API nur einen einzelnen SSRC meldet, selbst wenn Sie mithilfe von Simulcast drei RTP-Streams über drei separate SSRCs senden.

Die Standard-API nutzt 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. Es bedeutet aber auch, dass Sie die Gesamtbitrate aller RTP-Sendestreams selbst aggregieren müssen, um die Gesamtbitrate aller RTP-Sendestreams zu ermitteln.

SVC- oder RTP-Streams mit mehreren räumlichen Ebenen, die über die scalabilityMode API konfiguriert wurden, werden hingegen als eine 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 bei ihrer 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 weiterhin verwendet werden.