Cette page a été traduite par l'API Cloud Translation.

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 vous explique comment migrer votre code et la procédure à suivre si vous avez besoin de plus de temps.

Jusqu'à présent, il existe deux versions concurrentes de l'API WebRTC getStats(). L'ancienne API getStats(), qui est antérieure au processus de standardisation et qui accepte un argument de rappel, et l'API standardisée et largement prise en charge qui renvoie une promesse.

L'API standard offre davantage de fonctionnalités et dispose de métriques bien définies publiquement documentées dans la spécification W3C Identifiers for WebRTC's Statistics API (Identifiants pour l'API Statistics de WebRTC). Les spécifications incluent des descriptions de chaque métrique listée dans ce guide et bien d'autres.

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

Remarque:Vous pouvez comparer les anciennes métriques et les métriques standards en temps réel pendant l'exécution de votre application. Pour ce faire, accédez à chrome://webrtc-internals/ dans un onglet distinct, puis sélectionnez les métriques anciennes ou standards à l'aide du tableau déroulant.

Types de statistiques hérités et 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 "stats" comportent 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 appel de la méthode. Cette donnée est utile pour calculer le taux de variation des métriques (un exemple est présenté 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:

Ancien type	Type standard
`ssrc`	Représente un flux RTP et les métriques sur le `MediaStreamTrack` associé. Les types standards sont `inbound-rtp` (pour les flux RTP de réception et les flux RTP distants associés), `outbound-rtp` (pour les flux RTP d'envoi) et `media-source` (pour les métriques `MediaStreamTrack` locales associées à un flux RTP d'envoi).`MediaStreamTrack` Les métriques de flux RTP contiennent également des informations sur l'encodeur ou le décodeur utilisé par le flux RTP.
`VideoBwe`	Métriques d'estimation de la bande passante, débit cible, débit de l'encodeur et débit réel. Ces types de métriques font partie des métriques TRP (`outbound-rtp` et `inbound-rtp`) et des métriques de paire de candidats ICE (`candidate-pair`).
`googComponent`	Représente le transport (ICE et DTLS). La version standard est `transport`.
`localcandidate and remotecandidate`	Représente un candidat ICE. La version standard est `local-candidate` et `remote-candidate`.
`googCandidatePair`	Représente une paire de candidats ICE, c'est-à-dire une paire d'un candidat local et d'un candidat à distance. La version standard est `candidate-pair`.
`googCertificate`	Représente un certificat utilisé par le transport DTLS. La version standard est `certificate`.
`googLibjingleSession`	Représente l'élément `RTCPeerConnection`. Bien que son contenu ne corresponde à aucun élément de la norme, un type est associé à `RTCPeerConnection`: `peer-connection`.
Manquant dans l'ancienne API	Les types de statistiques suivants ont été ajoutés à l'API standard, sans ancien type correspondant: `codec`: codec actuellement utilisé par un flux RTP pour l'encodage ou le décodage. Il s'agit d'un sous-ensemble des codecs qui ont été négociés dans le SDP. `remote-inbound-rtp`: flux RTP entrant d'un point de terminaison distant correspondant à un flux RTP sortant envoyé par ce point de terminaison (`outbound-rtp`). Il est mesuré au point de terminaison distant et signalé dans un rapport RTCP (RTCP) ou RTCP Extended Report (XR). `remote-outbound-rtp`: flux RTP sortant d'un point de terminaison distant correspondant à un flux RTP entrant reçu par ce point de terminaison (`inbound-rtp`). Il est mesuré au niveau du point de terminaison distant et consigné dans un rapport RTCP Sender Report (SR). `media-playout`: métriques sur la lecture d'un `MediaStreamTrack` distant associé à un flux RTP entrant (`inbound-rtp`). `data-channel`: représente un `RTCDataChannel`.

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

L'objectif de cette mise en correspondance est d'aider les développeurs à identifier quelle ancienne métrique correspond à quelle 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 aux spécifications pour connaître les définitions des métriques.
L'API standard préfère afficher les compteurs totaux plutôt que les taux. Cela signifie que pour obtenir le débit correspondant (par exemple, le débit) comme dans l'ancienne API, l'application doit calculer le taux moyen en prenant 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;

Le calcul des taux et des moyennes vous-même peut sembler fastidieux, mais cela présente 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.

Ancienne métrique `googCertificate`	Correspondance standard `certificate`
`.googFingerprint`	`.fingerprint`
`.googFingerprintAlgorithm`	`.fingerprintAlgorithm`
`.googDerBase64`	`.base64Certificate`

Ancienne métrique `googComponent`	Correspondance standard `transport`
`.localCertificateId`	`.localCertificateId`
`.remoteCertificateId`	`.remoteCertificateId`
`.selectedCandidatePairId`	`.selectedCandidatePairId`
`.dtlsCipher`	`.dtlsCipher`
`.srtpCipher`	`.srtpCipher`

Ancienne métrique `localcandidate`	Correspondance standard `local-candidate` ou `candidate-pair`
`.stunKeepaliveRequestsSent`	`candidate-pair.requestsSent` (recherche inverse de `candidate-pair` via `candidate-pair.localCandidateId`)
`.portNumber`	`local-candidate.port`
`.networkType`	`local-candidate.networkType`
`.ipAddress`	`local-candidate.address`
`.stunKeepaliveResponsesReceived`	`candidate-pair.responsesReceived`
`.stunKeepaliveRttTotal`	`candidate-pair.totalRoundTripTime`
`.transport`	`local-candidate.protocol`
`.candidateType`	`local-candidate.candidateType`
`.priority`	`local-candidate.priority`

Ancienne métrique `remotecandidate`	Correspondance standard `remote-candidate`
Identique à `localcandidate` ci-dessus.	Identique à `local-candidate` ci-dessus.

Ancienne métrique `googCandidatePair`	Correspondance standard `candidate-pair`
`.responsesSent`	`candidate-pair.responsesSent`
`.requestsReceived`	`candidate-pair.requestsReceived`
`.googRemoteCandidateType`	`remote-candidate.candidateType` (recherche `remote-candidate` via `candidate-pair.remoteCandidateId`)
`.googReadable`	`googReadable` est une valeur booléenne indiquant si nous avons récemment incrémenté `candidate-pair.requestsReceived` ou `candidate-pair.responsesReceived`.
`.googLocalAddress`	`local-candidate.address` (recherche `local-candidate` via `candidate-pair.localCandidateId`)
`.consentRequestsSent`	`candidate-pair.consentRequestsSent`
`.googTransportType`	Identique à `local-candidate.protocol` et `remote-candidate.protocol`.
`.googChannelId`	`candidate-pair.transportId`
`.googLocalCandidateType`	`local-candidate.candidateType`
`.googWritable`	`googWritable` est une valeur booléenne indiquant si nous avons récemment incrémenté `candidate-pair.responsesReceived` ou non.
`.googRemoteAddress`	`remote-candidate.address`
`.googRtt`	`candidate-pair.currentRoundTripTime`
`.googActiveConnection`	La connexion active fait référence à la paire candidate actuellement sélectionnée par le transport, par exemple, où `candidate-pair.id == transport.selectedCandidatePairId`
`.packetsDiscardedOnSend`	`candidate-pair.packetsDiscardedOnSend`
`.bytesReceived`	`candidate-pair.bytesReceived`
`.responsesReceived`	`candidate-pair.responsesReceived`
`.remoteCandidateId`	`candidate-pair.remoteCandidateId`
`.localCandidateId`	`candidate-pair.localCandidateId`
`.bytesSent`	`candidate-pair.bytesSent`
`.packetsSent`	`candidate-pair.packetsSent`
`.bytesReceived`	`candidate-pair.bytesReceived`
`.bytesReceived`	`candidate-pair.bytesReceived`

Ancienne métrique `ssrc`	Correspondance standard `inbound-rtp`, `outbound-rtp`, `media-source`
`.audioInputLevel`	`media-source.audioLevel`. L'ancienne métrique est comprise dans la plage [0..32768], tandis que la métrique standard est comprise dans la plage [0..1].
`.audioOutputLevel`	`inbound-rtp.audioLevel` L'ancienne métrique est comprise dans la plage [0..32768], tandis que la métrique standard est comprise dans la plage [0..1].
`.packetsLost`	`inbound-rtp.packetsLost`
`.googTrackId`	`media-source.trackIdentifier` pour les `MediaStreamTrack` locales et `inbound-rtp.trackIdentifier` pour les `MediaStreamTrack` distantes
`.googRtt`	`remote-inbound-rtp.roundTripTime` (voir `outbound-rtp.remoteId`)
`.googEchoCancellationReturnLossEnhancement`	`inbound-rtp.echoReturnLossEnhancement`
`.googCodecName`	Le nom du codec est le sous-type du type MIME "type/sous-type", `codec.mimeType` (voir `inbound-rtp.codecId` et `outbound-rtp.codecId`).
`.transportId`	`inbound-rtp.transportId` et `outbound-rtp.transportId`
`.mediaType`	`inbound-rtp.kind` et `outbound-rtp.kind` ou `media-source.kind`
`.googEchoCancellationReturnLoss`	`inbound-rtp.echoReturnLoss`
`.totalAudioEnergy`	`inbound-rtp.totalAudioEnergy` et `media-source.totalAudioEnergy`
`ssrc.totalSamplesDuration`	`inbound-rtp.totalSamplesDuration` et `media-source.totalSamplesDuration`
`.ssrc`	`inbound-rtp.ssrc` et `outbound-rtp.ssrc`
`.googJitterReceived`	`inbound-rtp.jitter`
`.packetsSent`	`outbound-rtp.packetsSent`
`.bytesSent`	`outbound-rtp.bytesSent`
`.googContentType`	`inbound-rtp.contentType` et `outbound-rtp.contentType`
`.googFrameWidthInput`	`media-source.width`
`.googFrameHeightInput`	`media-source.height`
`.googFrameRateInput`	`media-source.framesPerSecond`
`.googFrameWidthSent`	`outbound-rtp.frameWidth`
`.googFrameHeightSent`	`outbound-rtp.frameHeight`
`.googFrameRateSent`	Bien que le FPS d'envoi corresponde au taux de changement de `outbound-rtp.framesSent`, il est en réalité implémenté en tant que `outbound-rtp.framesPerSecond`, qui encode les FPS.
`.googFrameWidthReceived`	`inbound-rtp.frameWidth`
`.googFrameHeightReceived`	`inbound-rtp.frameHeight`
`.googFrameRateDecoded`	Taux de variation de `inbound-rtp.framesDecoded`
`.googFrameRateOutput`	Taux de variation de `inbound-rtp.framesDecoded` à `inbound-rtp.framesDropped`
`.hugeFramesSent`	`outbound-rtp.hugeFramesSent`
`.qpSum`	`inbound-rtp.qpSum` et `outbound-rtp.qpSum`
`.framesEncoded`	`outbound-rtp.framesEncoded`
`.googAvgEncodeMs`	`outbound-rtp.totalEncodeTime`/`outbound-rtp.framesEncoded`
`.codecImplementationName`	`inbound-rtp.decoderImplementation` et `outbound-rtp.encoderImplementation`
`.googCpuLimitedResolution`	Vrai si `outbound-rtp.qualityLimitationReason == "cpu"`
`.googBandwidthLimitedResolution`	Vrai si `outbound-rtp.qualityLimitationReason == "bandwidth"`
`.googAdaptationChanges`	L'ancienne métrique comptabilise le nombre de fois où la résolution ou la fréquence d'images ont changé pour des raisons liées à `qualityLimitationReason`. Cela peut être déduit d'autres métriques (par exemple, la résolution d'envoi ou la fréquence d'images est différente de la résolution source ou de la fréquence d'images), mais la durée pour laquelle nous avons été limitées, `outbound-rtp.qualityLimitationDurations`, peut être plus utile que la fréquence de reconfiguration de la résolution ou de la fréquence d'images.
`.googNacksReceived`	`inbound-rtp.nackCount`
`.googNacksSent`	`inbound-rtp.nackCount`
`.googPlisReceived`	`inbound-rtp.pliCount`
`.googPlisSent`	`inbound-rtp.pliCount`
`.googFirsReceived`	`inbound-rtp.firCount`
`.googFirsSent`	`inbound-rtp.firCount`
`.googSecondaryDecodedRate`	Ratio récent de paquets contenant une correction d'erreur: `inbound-rtp.fecPacketsReceived`-`inbound-rtp.fecPacketsDiscarded`
`.packetsReceived`	`inbound-rtp.packetsReceived`
`.googJitterBufferMs`	`inbound-rtp.jitterBufferDelay`/`inbound-rtp.jitterBufferEmittedCount`
`.googTargetDelayMs` (vidéo)	`inbound-rtp.jitterBufferTargetDelay`/`inbound-rtp.jitterBufferEmittedCount`
`.googPreferredJitterBufferMs` (audio)	`inbound-rtp.jitterBufferTargetDelay`/`inbound-rtp.jitterBufferEmittedCount`
`.googExpandRate`	Ratio récent d'échantillons masqués: `inbound-rtp.concealedSamples` / `inbound-rtp.totalSamplesReceived`
`.googSpeechExpandRate`	Ratio récent d'échantillons masqués lorsque le flux n'était pas silencieux : (`inbound-rtp.concealedSamples` - `inbound-rtp.silentConcealedSamples`) / `inbound-rtp.concealedSamples`
`.googAccelerateRate`	Le ratio récent d'échantillons supprimés afin d'accélérer la vitesse de lecture: `inbound-rtp.removedSamplesForAcceleration` / `inbound-rtp.totalSamplesReceived`
`.googPreemptiveExpandRate`	Ratio récent d'échantillons synthétisés pour ralentir la vitesse de lecture: `inbound-rtp.insertedSamplesForDeceleration` / `inbound-rtp.totalSamplesReceived`
`.googSecondaryDiscardedRate`	`inbound-rtp.fecPacketsDiscarded`
`.bytesReceived`	`inbound-rtp.bytesReceived`
`s.googCurrentDelayMs`	`inbound-rtp.jitterBufferDelay` + media-playout.totalPlayoutDelay
`.googDecodeMs`	`inbound-rtp.totalDecodeTime`/`inbound-rtp.framesDecoded`
`.googTimingFrameInfo`	La seule métrique goog-metric. `inbound-rtp.googTimingFrameInfo`
`.framesDecoded`	`inbound-rtp.framesDecoded`

Ancienne métrique `VideoBwe`	Correspondance standard `outbound-rtp` et `candidate-pair`
`.googTargetEncBitrate`	`outbound-rtp.targetBitrate` en tant que valeur instantanée ou `outbound-rtp.totalEncodedBytesTarget` / `outbound-rtp.framesEncoded` en tant que moyenne
`.googActualEncBitrate`	Les octets produits par l'encodeur correspondent aux octets de charge utile, à l'exception des retransmissions: taux de changement de `outbound-rtp.bytesSent` - `outbound-rtp.retransmittedBytesSent`.
`.googBucketDelay`	`outbound-rtp.totalPacketSendDelay`/`outbound-rtp.packetsSent`
`.googTransmitBitrate`	Taux de changement de `outbound-rtp.headerBytesSent` + `outbound-rtp.bytesSent` pour le débit de flux par RTP, `candidate-pair.bytesSent` pour le débit candidat par ICE ou `transport.bytesSent` pour le débit par transport
`.googRetransmitBitrate`	Plage de variation de `outbound-rtp.retransmittedBytesSent`
`.googAvailableSendBandwidth`	`candidate-pair.availableOutgoingBitrate`
`.googAvailableReceiveBandwidth`	`candidate-pair.availableIncomingBitrate`

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

Si vous utilisez la diffusion en simulcast, vous avez peut-être remarqué que l'ancienne API ne signale qu'une seule chaîne SSRC, même lorsque vous utilisez la diffusion simultanée pour envoyer (par exemple) trois flux RTP sur trois chaînes SSRC distinctes.

L'API standard ne partage pas cette limite et affichera trois objets de statistiques outbound-rtp, un pour chacun des SSRC. Cela signifie que vous pouvez analyser chaque flux RTP individuellement, mais que pour obtenir le débit total de tous les flux d'envoi RTP, vous devez les agréger vous-même.

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

Si vous avez besoin de plus de temps pour la migration

Lorsque l'ancienne API sera supprimée dans Chrome 117, son utilisation générera 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. Avec un jeton pour la phase d'évaluation, l'ancienne API getStats() peut continuer à être utilisée jusqu'à Chrome 121.