WebRTC: ancien guide de migration de getStats()

Henrik Boström

L'ancienne API WebRTC getStats() sera supprimée dans Chrome 117. Les applications qui l'utilisent devront donc migrer vers l'API standard. Cet article explique comment migrer votre code et que faire si vous avez besoin de plus de temps pour effectuer cette modification.

Deux versions de l'API WebRTC getStats() ont toujours été concurrentes. L'ancienne API getStats() qui est antérieure au processus de normalisation et qui accepte un argument de rappel, ainsi que l'API standardisée et largement prise en charge qui renvoie une promesse.

L'API standard offre davantage de fonctionnalités et possède des métriques bien définies, documentées publiquement dans la spécification W3C, intitulée Identifiants de l'API Statistics de WebRTC. Cette spécification comprend, entre autres, une description de chaque métrique répertoriée dans ce guide.

À partir de Chrome 117, l'ancienne API getStats() générera une exception dans la version disponible stable (l'exception générée sera progressivement déployée). Suivez ce guide pour faciliter votre transition vers l'API standard.

Anciens types de statistiques et types de statistiques standards

La liste complète des types de statistiques standards est disponible en consultant l'énumération RTCStatsType dans la spécification. Cela inclut la définition du dictionnaire de statistiques qui décrit les métriques collectées pour chaque type.

Les objets statistiques possèdent tous un attribut "id" qui identifie de manière unique l'objet sous-jacent dans plusieurs appels getStats(). Le même objet aura le même identifiant chaque fois que la méthode est appelée. Cela s'avère utile pour calculer le taux de variation des métriques (voir un exemple dans la section suivante). Les identifiants forment également des relations de références. Par exemple, l'objet de statistiques outbound-rtp fait référence à l'objet de statistiques media-source associé via l'attribut outbound-rtp.mediaSourceId. Si vous dessinez toutes les relations ...Id, vous obtenez un graphique.

L'ancienne API comporte les types de statistiques suivants, correspondant aux types standards:

Mappage des anciennes métriques vers les métriques standards

Ce mappage a pour but d'aider les développeurs à identifier l'ancienne métrique qui correspond à chaque métrique standard. Notez toutefois que la métrique correspondante peut utiliser des unités différentes ou être exprimée sous la forme d'un compteur total plutôt que d'une valeur instantanée. Reportez-vous à la spécification pour obtenir la définition des métriques.
L'API standard préfère exposer les compteurs totaux plutôt que les taux. Comme dans l'ancienne API, pour obtenir le débit correspondant (par exemple, le débit), l'application doit calculer le tarif moyen en calculant le delta entre deux appels getStats(). Exemple :

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

Avoir à calculer vous-même les taux et les moyennes de cette manière peut sembler une étape supplémentaire fastidieuse, mais cela a l'avantage de vous permettre d'obtenir des moyennes sur n'importe quel intervalle de temps souhaité. Appeler l'API standard moins souvent qu'avec l'ancienne API présente des avantages en termes de performances.

L'API standard est compatible avec la diffusion simultanée

Si vous utilisez la diffusion simultanée, vous avez peut-être remarqué que l'ancienne API ne signale qu'un seul numéro SSRC, même si vous utilisez la diffusion simultanée pour envoyer (par exemple) trois flux RTP sur trois fichiers SSRC distincts.

L'API standard ne partage pas cette limitation et renvoie trois objets de statistiques outbound-rtp, une pour chacune des chaînes SSRC. Cela signifie que vous pouvez analyser chaque flux RTP individuellement, mais cela signifie également que pour obtenir le débit total de tous les flux d'envoi RTP, vous devrez les agréger vous-même.

En revanche, les flux SVC ou RTP avec plusieurs couches spatiales configurées via l'API scalabilityMode apparaissent toujours sous la forme d'un outbound-rtp unique, car ils sont envoyés via une seule SSRC.

Si vous avez besoin de plus de temps pour la migration

Lorsque l'ancienne API est supprimée dans Chrome 117, son utilisation génère une exception. Si vous ne parvenez pas à migrer votre code à temps, la phase d'évaluation pour l'API getStats() basée sur le rappel RTCPeerConnection accorde plus de temps aux sites Web enregistrés pour la migration. Avec un jeton d'évaluation de l'origine, l'ancienne API getStats() peut continuer d'être utilisée jusqu'à Chrome 121.