WebRTC: Guía de migración getStats() heredada

Henrik Boström

Se quitará la API heredada de getStats() de WebRTC en Chrome 117, por lo que las apps que la usen deberán migrar a la API estándar. En este artículo, se explica cómo migrar tu código y qué hacer si necesitas más tiempo para realizar este cambio.

Históricamente, ha habido dos versiones que compiten de la API de getStats() de WebRTC. La API heredada de getStats(), que es anterior al proceso de estandarización y toma un argumento de devolución de llamada, y la API estandarizada y ampliamente admitida que muestra una promesa.

La API estándar cuenta con más funciones y tiene métricas bien definidas que se documentan públicamente en la especificación de W3C Identifiers for WebRTC's Statistics API. La especificación incluye descripciones de cada métrica que aparece en esta guía y muchas más.

A partir de Chrome 117, la API de getStats() heredada arrojará una excepción en el canal de versiones estable (la excepción se lanzará de forma gradual). Sigue esta guía para facilitar tu transición a la API estándar.

Tipos de estadísticas heredados frente a los estándar

Puedes encontrar la lista completa de los tipos de estadísticas estándar en la enum RTCStatsType de la especificación. Esto incluye qué definición del diccionario de estadísticas describe las métricas recopiladas para cada tipo.

Todos los objetos de estadísticas tienen un atributo de ID que identifica de forma única el objeto subyacente en varias llamadas a getStats(). El mismo objeto tendrá el mismo ID cada vez que se llame al método. Esto es útil para calcular la tasa de cambio de las métricas (encontrarás un ejemplo en la siguiente sección). Los ID también forman relaciones de referencias. Por ejemplo, el objeto de estadísticas outbound-rtp hace referencia al objeto de estadísticas media-source asociado a través del atributo outbound-rtp.mediaSourceId. Si dibujas todas las relaciones ...Id, obtienes un gráfico.

La API heredada tiene los siguientes tipos de estadísticas, correspondientes a los tipos estándar:

Asignación de métricas heredadas a estándar

El objetivo de esta asignación es ayudar a los desarrolladores a encontrar qué métrica heredada corresponde a qué métrica estándar, pero ten en cuenta que la métrica correspondiente puede usar diferentes unidades o se puede expresar como un contador total en lugar de un valor instantáneo. Consulta las especificaciones para las definiciones de métricas.
La API estándar prefiere exponer los contadores totales en lugar de las tarifas. Esto significa que, para obtener la tarifa correspondiente (por ejemplo, la tasa de bits) como en la API heredada, la app debe calcular la tarifa promedio tomando el valor delta entre dos llamadas getStats(). Por ejemplo:

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

Tener que calcular las tasas y los promedios por tu cuenta puede parecer un paso adicional engorroso, pero tiene la ventaja de permitirte obtener promedios durante cualquier intervalo de tiempo deseado. Llamar a la API estándar con menos frecuencia de la que tendrías que ver con la API heredada tiene algunos beneficios de rendimiento.

La API estándar es compatible con la transmisión simultánea

Si usas la transmisión simultánea, es posible que hayas notado que la API heredada solo informa un solo SSRC, incluso cuando usas la transmisión simultánea para enviar (por ejemplo) tres transmisiones de RTP a través de tres SSRC diferentes.

La API estándar no comparte esta limitación y mostrará tres objetos de estadísticas outbound-rtp, uno para cada uno de los SSRC. Esto significa que puedes analizar cada transmisión RTP individualmente, pero también significa que para obtener la tasa de bits total de todas las transmisiones de envío RTP, deberás agregarlas tú mismo.

Las transmisiones SVC o RTP con múltiples capas espaciales configuradas a través de la API de scalabilityMode, por otro lado, siguen apareciendo como un único outbound-rtp porque se envían a través de un solo SSRC.

Si necesitas más tiempo para la migración

Cuando se quite la API heredada en Chrome 117, usarla generará una excepción. Si no puedes migrar tu código a tiempo, la prueba de origen para la API getStats() basada en devoluciones de llamada de RTCPeerConnection, con más tiempo para migrar a los sitios web registrados. Con un token de prueba de origen, se puede seguir usando la API de getStats() heredada hasta Chrome 121.