WebRTC: Legacy getStats() migration guide

Henrik Boström

The legacy getStats() WebRTC API will be removed in Chrome 117, therefore apps using it will need to migrate to the standard API. This article explains how to migrate your code, and what to do if you need more time to make this change.

Historically there have been two competing versions of the WebRTC getStats() API. The legacy getStats() API, that pre-dates the standardization process and takes a callback argument, and the standardized and widely supported API which returns a promise.

The standard API is more feature rich and has well-defined metrics publicly documented in the W3C specification Identifiers for WebRTC's Statistics API. The specification includes descriptions of each metric listed in this guide and many more.

From Chrome 117 the legacy getStats() API will throw an exception in the Stable release channel (the exception throwing will be gradually rolled out). Follow this guide to ease your transition to the standard API.

Legacy versus standard stats types

The complete list of standard stats types can be found by looking at the RTCStatsType enum in the specification. This includes which stats dictionary definition describes the metrics collected for each type.

The stats objects all have an id attribute which uniquely identifies the underlying object across multiple getStats() calls. The same object will have the same ID every time the method is called. This is useful for calculating the rate of change of metrics (there's an example in the next section). The IDs also form relationships of references. For example the outbound-rtp stats object references the associated media-source stats object via the outbound-rtp.mediaSourceId attribute. If you draw all ...Id relationships you get a graph.

The legacy API has the following stats types, corresponding to the standard types as follows:

Legacy to standard metrics mapping

This mapping is aimed to help developers find which legacy metric corresponds to which standard metric, but note that the corresponding metric may use different units or be expressed as a total counter rather than an instantaneous value. Refer to the specification for metric definitions.
The standard API prefers exposing total counters rather than rates. This means that to get the corresponding rate (for example, bitrate) as in the legacy API, the app must calculate the average rate by taking the delta between two getStats() calls. For example:

// 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;

Having to calculate rates and averages yourself like this may seem like a cumbersome additional step but it has the upside of allowing you to get averages over any desired time interval. Calling the standard API less often than you may otherwise have had to do with the legacy API has some performance benefits.

The standard API is simulcast-aware

If you use simulcast you may have noticed that the legacy API only reports a single SSRC even when you're using simulcast to send (for example) three RTP streams over three separate SSRCs.

The standard API does not share this limitation and will return three outbound-rtp stats objects, one for each of the SSRCs. This means that you can analyze each RTP stream individually, but it also means that to obtain the total bitrate of all RTP send streams you'll need to aggregate them yourself.

SVC streams or RTP streams with multiple spatial layers configured via the scalabilityMode API on the other hand still show up as a single outbound-rtp because these are sent over a single SSRC.

If you need more time for migration

When the legacy API is removed in Chrome 117, using it will generate an exception. If you are unable to migrate your code in time, the origin trial for RTCPeerConnection callback-based getStats() API gives registered websites more time to migrate. With an origin trial token, the legacy getStats() API may continue to be used until Chrome 121.