Observabilité du client

Les SDK OpenTok fournissent des méthodes permettant d'accéder aux statistiques réseau et multimédia en temps réel d'une session vidéo, y compris les statistiques côté expéditeur.

L'observabilité du client fournit des mesures détaillées de la qualité du flux, telles que la perte de paquets, les données reçues et la bande passante estimée, et peut être utilisée sur n'importe quel flux publié ou souscrit.

Les statistiques sont accessibles par le biais de deux mécanismes principaux :

  • API de statistiques de haut niveau - le mécanisme préféré dans la plupart des cas. Cette API fournit des mesures de performances audio, vidéo et réseau et tient compte des transitions de connexion entre pairs et d'autres ajustements internes. Le SDK regroupe ces détails de manière à ce que les données s'inscrivent clairement dans une abstraction d'éditeur ou d'abonné. Dans la mesure du possible, utilisez cette API, car elle offre une représentation plus précise et plus stable des performances réelles de la session.
  • Rapport de statistiques WebRTC de bas niveau, qui expose le rapport brut WebRTC RTCStatsReport pour la connexion pair sous-jacente. Ces données ne sont pas ajustées pour les transitions de connexion entre pairs ou les optimisations internes et ne reflètent que les statistiques WebRTC directes. Il est utile pour le débogage avancé ou lorsque des données WebRTC brutes sont explicitement requises.

Ce guide comprend les sections suivantes :

API de statistiques sur les liens audio, vidéo et multimédia

L'API Statistiques audio et vidéo fournit des informations périodiques et détaillées sur les performances des médias, tant pour les éditeurs que pour les abonnés. Ces statistiques permettent aux Applications de surveiller la qualité audio et vidéo en temps réel, de comprendre le comportement du réseau, de détecter les problèmes liés aux appareils et de réagir de manière proactive aux changements de bande passante ou de performances. L'API est disponible dans tous les SDK Video Client et fournit des rappels ou des événements distincts pour les mesures côté éditeur et côté abonné.

Les principaux types de données et d'événements fournis sont les suivants :

  • Statistiques audio et vidéo - tels que la fréquence des images, la résolution, le débit binaire et le nombre de paquets, délivrés périodiquement par le biais de rappels ou d'événements.

  • Statistiques sur les liens avec les médias - fournissent des mesures unifiées au niveau du transport qui complètent les statistiques audio et vidéo périodiques, y compris l'évaluation de l'état du réseau et l'estimation de la bande passante. Pour les abonnés, ces mesures offrent en outre une visibilité sur les performances de transport de l'éditeur distant et sur l'attribution de la dégradation du réseau, ce qui permet aux Applications de diagnostiquer les problèmes de connexion avec précision et de fournir aux utilisateurs un retour d'information significatif et exploitable.

  • Changement de la qualité vidéo - se déclenche dès que la qualité d'un flux vidéo change, fournissant des mesures actualisées ainsi que la raison de la dégradation ou de l'amélioration.

  • Événements de modification de l'état du réseau – déclenchés lorsqu'un changement significatif de l'état du réseau est détecté pour un éditeur ou un abonné. Ces événements signalent les changements dans l'état général du réseau et fournissent un aperçu complet des statistiques audio et vidéo, ainsi que des indicateurs au niveau du transport, tels que le score d'état du réseau et la cause de cet état. Pour les abonnés, ils indiquent également la source de la dégradation du réseau. Voir État du réseau pour plus de détails.

Statistiques de l'éditeur

Les rappels de l'éditeur permettent de connaître la qualité des médias en cours de diffusion. envoyé à chaque abonné (ou au Video Media Router de Vonage pour les sessions routées). Ces mesures permettent de comprendre les conditions du réseau en amont, d'observer les performances d'encodage et de diagnostiquer les problèmes tels que la perte de paquets ou les chutes de débit.

Remarque : Dans les sessions acheminées, les mesures de l'éditeur peuvent ne pas correspondre aux valeurs réelles des médias, car le routeur vidéo de Vonage peut limiter la bande passante pour optimiser les ressources. Dans ce cas, ne vous fiez pas aux mesures côté éditeur tant qu'au moins un abonné n'est pas connecté. Vous pouvez ignorer les raisons de limitation de la qualité liées à la bande passante pour l'éditeur jusqu'à ce qu'un abonné soit présent. Dans les sessions relayées, aucune statistique n'est rapportée tant qu'au moins un abonné n'est pas connecté.

Notez que lorsque l'éditeur est dans une session relayée, il envoie un flux média distinct à chaque abonné. De ce fait, les événements statistiques peuvent inclure plusieurs objets statistiques, un par abonné. Pour chaque objet statistique dans une session relayée, deux champs d'identification sont inclus :

  • ID de connexion: L'identifiant unique de la connexion de l'abonné. Il correspond à la propriété ID de l'objet de connexion fourni dans l'événement de création de connexion pour ce client.
  • Identifiant de l'abonné: L'identifiant unique de l'objet Abonné recevant le flux de cet éditeur. Cela correspond à la propriété ID de l'abonné dans l'application du client qui s'abonne.

Ces champs permettent de déterminer à quel abonné appartient chaque objet de statistiques.

Dans une session routée (utilisant le routeur vidéo de Vonage), il n'y a qu'un seul flux média sortant, donc le tableau stats contient un seul objet, et l'identifiant de connexion et l'identifiant d'abonné sont indéfinis.

Indicateurs audio

  • Paquets perdus : Nombre total de paquets audio qui n'ont pas réussi à atteindre l'abonné.
  • Paquets envoyés : Nombre total de paquets audio transmis à l'abonné ou au routeur média.
  • Octets envoyés : Taille cumulée de toutes les données audio envoyées, y compris la charge utile audio, les en-têtes et le remplissage.
  • Niveau audio : Intensité sonore actuelle du signal audio, normalisée entre 0 et 1.
  • Horodatage : Indique quand chaque mesure a été prise.

Les statistiques de transport et d'état du réseau de l'éditeur sont disponibles via les statistiques du lien média de l'éditeur. Voir Statistiques sur les liens avec les médias pour plus de détails.

Indicateurs vidéo

  • Paquets perdus : Nombre de paquets vidéo qui n'ont pas atteint leur destination.
  • Paquets envoyés : Nombre total de paquets vidéo transmis à l'abonné ou au routeur média.
  • Octets envoyés : Nombre total d'octets transmis à l'abonné ou au routeur média, y compris la charge utile vidéo, les en-têtes et le remplissage.
  • Horodatage : Indique le point de départ et le point actuel de la mesure.
  • Couches vidéo : Informations par couche pour la diffusion simultanée ou le codage vidéo évolutif (SVC). Dans une configuration de diffusion simultanée, chaque objet correspond à un encodage vidéo indépendant (par exemple, des flux à basse, moyenne et haute résolution envoyés en parallèle). Pour le SVC (Scalable Video Coding), l'éditeur envoie généralement un codage vidéo unique, avec une évolutivité (temporelle, spatiale ou les deux) codée en interne et décrite via le champ du mode d'évolutivité. Il comprend :
    • Encoded frame width (largeur des images encodées) : largeur des images vidéo encodées pour cette couche. Cette largeur peut différer de la résolution de capture de la caméra si une mise à l'échelle ou une adaptation est appliquée.
    • Encoded frame height (hauteur des images codées) : hauteur des images vidéo codées pour cette couche. Comme pour la largeur, l'encodeur peut réduire la taille des images en fonction de la bande passante, de l'unité centrale ou de la configuration de la couche simulcast/SVC.
    • Taux de rafraîchissement de la sortie de l'encodeur : Fréquence d'images réelle à laquelle les images vidéo sont encodées avec succès. Elle peut être différente de la fréquence d'images de capture de la caméra (des images peuvent être supprimées avant l'encodage) et de la fréquence d'images effectivement transmise (des images encodées peuvent être supprimées avant l'envoi).
    • Bitrate (charge utile vidéo uniquement) : Débit binaire estimé de la charge utile vidéo codée. Ce débit n'inclut pas les frais généraux RTP et peut varier en fonction des décisions de contrôle du débit de l'encodeur.
    • Débit binaire total (y compris les frais généraux) : Débit binaire comprenant les en-têtes RTP, le rembourrage et les autres frais généraux de transport. Ce débit reflète mieux l'utilisation réelle du réseau que le débit binaire de la charge utile seule.
    • Mode d'extensibilité : Indique la structure d'évolutivité spatiale/temporelle (par exemple, "L3T3").
    • Codec : Le codec utilisé pour encoder cette couche (par exemple, VP8, VP9, H.264, AV1).
    • Raison de la limitation de la qualité : indique pourquoi l'encodeur a limité la qualité (bande passante, CPU, autre). Aide à diagnostiquer si l'adaptation est due à des conditions de réseau ou à des contraintes liées à l'appareil.

Statistiques relatives aux liens vers les médias des éditeurs

Les statistiques sur les liens avec les médias de l'éditeur sont les suivantes :

  • Statistiques sur les transports : Statistiques sur les transports locaux et les réseaux pour l'éditeur, y compris :
    • Estimation de la largeur de bande disponible de la connexion montante.
    • Score de l'état du réseau. Voir État du réseau pour plus de détails.
    • Raison de l'état du réseau. Voir État du réseau pour plus de détails.

Ces mesures sont fournies par l'intermédiaire de :

  • Lien média stats event : Un événement dédié déclenché périodiquement pour rapporter les statistiques des liens médiatiques.
  • Événement de changement de condition du réseau : Déclenché lorsqu'un changement significatif de l'état du réseau est détecté, il fournit les statistiques actuelles de la liaison média ainsi que la raison du changement.

Les statistiques relatives aux liaisons réseau de l'éditeur décrivent la liaison montante propre à l'éditeur. Les statistiques relatives à la liaison média de l'abonné fournissent en outre des informations sur le transport de l'éditeur distant et sur la source de dégradation du réseau. Consultez la section [État du réseau par éditeur et par abonné](#network_condition_by_publisher and_subscriber) pour comprendre le lien entre ces deux perspectives et savoir comment évaluer l'expérience d'un abonné spécifique.

Statistiques sur les abonnés

Les rappels de l'abonné fournissent des informations sur le média en cours de traitement. reçu et rendus, ce qui permet aux Applications de détecter les problèmes de lecture, d'évaluer les performances en aval et de prendre des décisions adaptées.

Indicateurs audio

  • Paquets reçus : Nombre de paquets audio reçus avec succès.
  • Paquets perdus : Combien de paquets audio n'ont pas été reçus avec succès.
  • Octets reçus : Total des données audio reçues de l'éditeur ou du routeur multimédia Video API.
  • Niveau audio : Intensité sonore de l'audio de la télécommande.
  • Horodatage : Quand les données ont-elles été collectées ?
  • Statistiques côté expéditeur: Estimations de la largeur de bande communiquées par l'expéditeur.

Les statistiques de transport et d'état du réseau de l'abonné, y compris les statistiques de transport de l'éditeur distant et les informations sur la source de dégradation du réseau, sont disponibles par l'intermédiaire des statistiques de liaison média de l'abonné. Voir Statistiques sur les liens avec les médias pour plus de détails.

Indicateurs vidéo

  • Paquets reçus : Nombre de paquets vidéo reçus avec succès.
  • Paquets perdus : Combien de paquets vidéo n'ont pas été reçus avec succès.
  • Octets reçus : Total des données vidéo reçues de l'éditeur ou du routeur multimédia Video API.
  • Résolution décodée : Largeur et hauteur des images après décodage.
  • Taux de rafraîchissement décodé : Fréquence d'images réelle produite par le décodeur. Elle peut différer du nombre d'images reçues (certaines peuvent être supprimées avant le décodage) et du nombre d'images rendues (certaines images décodées peuvent ne pas être affichées en fonction des conditions de rendu).
  • Bitrate : Débit actuel des médias reçus, en tenant compte uniquement de la charge utile vidéo.
  • Débit total : Débit actuel du média reçu, y compris les en-têtes et le remplissage.
  • Nombre d'arrêts sur image : Nombre d'arrêts de la vidéo, tel que défini dans l'API de statistiques de WebRTC. freezeCount.
  • Durée totale de l'arrêt de la vidéo : Durée totale de l'arrêt de la vidéo.
  • Nombre de pauses vidéo : Nombre d'interruptions de plus de 5 secondes, y compris les pauses intentionnelles (par exemple lorsque l'éditeur désactive la piste vidéo) et les cas où la vidéo est désactivée en raison d'un repli audio de l'éditeur ou de l'abonné.
  • Durée totale des pauses vidéo : Durée totale des pauses vidéo.
  • Codec : Codec actuellement utilisé pour le flux vidéo.
  • Statistiques côté expéditeur: Estimations de la largeur de bande communiquées par l'expéditeur.

Statistiques relatives aux liens partagés par les abonnés

Les statistiques sur les liens médiatiques de l'abonné sont les suivantes :

  • Statistiques sur les transports locaux : Statistiques de transport et de réseau pour la connexion descendante de l'abonné, y compris :

    • Estimation de la largeur de bande disponible de la connexion descendante.
    • Score de l'état du réseau. Voir État du réseau pour plus de détails.
    • Raison de l'état du réseau. Voir État du réseau pour plus de détails.

  • Statistiques de transport de l'éditeur distant : Statistiques de transport et de réseau pour la connexion montante de l'éditeur distant, avec les mêmes champs que les statistiques de transport locales. Ces statistiques peuvent être limitées si les statistiques côté expéditeur ne sont pas activées.

  • Source de dégradation du réseau : Identifie le côté de la connexion qui est principalement responsable de la dégradation observée :

    • Aucun : Aucune dégradation du réseau n'a été détectée.
    • Localement : Le réseau de l'abonné local en est la cause principale.
    • A distance : Le réseau de l'éditeur distant en est la cause principale.
    • Les deux ou pas clair : La source de la dégradation ne peut être clairement attribuée à une seule partie.

Les statistiques sur les liens médiatiques des abonnés sont transmises par l'intermédiaire de :

  • Lien média stats event : Un événement dédié déclenché périodiquement pour rapporter les statistiques des liens médiatiques.
  • Événement de changement de condition du réseau : Déclenché lorsqu'un changement significatif de l'état du réseau est détecté, il fournit les statistiques actuelles de la liaison média ainsi que la raison du changement.

La qualité de la vidéo a changé événements

Le SDK fournit des événements de changement de qualité vidéo pour donner aux Applications un aperçu détaillé du flux vidéo d'un éditeur ou d'un abonné. Ces événements complètent les statistiques de réseau périodiques fournies pour l'observabilité du client et permettent aux Applications de réagir à la fois aux mesures continues et aux changements de qualité significatifs.

Vous pouvez attacher un gestionnaire à un éditeur ou à un abonné pour accéder aux événements de changement de qualité. Ces événements fournissent des mesures mises à jour ainsi que la raison de la dégradation ou de l'amélioration. Ce mécanisme permet à votre application de surveiller les performances de la vidéo et d'adapter l'interface utilisateur ou le comportement en conséquence, indépendamment de la manière dont les mesures sont fournies en interne.

Les motifs des événements de qualité sont déclenchés selon un ordre de priorité défini. Par exemple, une limitation de la qualité causée par la bande passante est prioritaire par rapport à un changement de résolution. Si vous souhaitez suivre tous les changements de métriques, consultez les statistiques détaillées incluses dans chaque événement. Reportez-vous à la documentation de référence du SDK pour plus de détails.

Pour un éditeur, les raisons sont considérées dans l'ordre de priorité suivant :

  1. Dégradation due à la limitation de la bande passante
  2. Dégradation due à la limitation de l'unité centrale
  3. Autres raisons de dégradation de la qualité
  4. Modifications du codec
  5. Changements de résolution ou de couche vidéo

Pour un abonné, les raisons sont considérées dans l'ordre de priorité suivant :

  1. Interruption de la vidéo
  2. Modifications du codec
  3. Modifications de la résolution

Contrôle de la qualité des appels

Au-delà des API statistiques de base, le SDK OpenTok.js offre des capacités supplémentaires pour surveiller et répondre aux changements de qualité des appels en temps réel. Ces fonctionnalités aident les Applications à optimiser les performances en s'adaptant aux contraintes des appareils et aux conditions du réseau.

Note: Les fonctionnalités de surveillance de la qualité des appels, notamment la surveillance des performances du processeur et le suivi du score d'opinion moyen (MOS), ne sont actuellement disponibles que dans le SDK OpenTok.js pour les applications web.

Principales fonctionnalités

Surveillance des performances de l'unité centrale - Détectez les changements dans la charge du processeur de l'appareil et adaptez votre application en conséquence. Les applications peuvent répondre à la sollicitation du processeur en désactivant les fonctions coûteuses en calcul ou en réduisant la qualité vidéo pour maintenir la stabilité de l'appel.

Score d'opinion moyen (MOS) - Évaluez la qualité de l'expérience que les utilisateurs perçoivent de votre service en utilisant l'échelle MOS standard de l'industrie (1-5). L'algorithme MOS tient compte de la perte de paquets, du débit, de la latence du réseau et d'autres facteurs ayant un impact sur la qualité des médias.

Optimisation combinée - Créez des applications robustes qui réagissent aux performances de l'unité centrale et aux mesures de la qualité du réseau, en ajustant dynamiquement la résolution vidéo, les fréquences d'images et d'autres paramètres pour offrir la meilleure expérience possible à l'utilisateur dans des conditions variables.

Tests préalables à l'appel - Utiliser le Test du réseau de la Video API Vonage bibliothèque permettant de déterminer si un client est capable de prendre en charge la diffusion de contenu audio et vidéo, et d'estimer les scores MOS avant que les utilisateurs ne rejoignent une session.

Pour des conseils de mise en œuvre détaillés, des exemples de code et des bonnes pratiques concernant le contrôle de la qualité des appels dans les applications web, voir le document Documentation du SDK OpenTok.js.

Statistiques côté expéditeur

Lors d'un appel, l'éditeur transmet un flux de médias à un ou plusieurs abonnés. Le média peut être relayé directement ou traité par l'intermédiaire de l'opérateur de téléphonie mobile. Routeur vidéo multimédia de Vonage. Si les abonnés peuvent observer le débit du flux qu'ils reçoivent, ils n'ont généralement pas de visibilité sur leur capacité totale de liaison descendante. L'API Statistiques côté émetteur remédie à cette limitation en fournissant des mesures qui aident les abonnés à évaluer la bande passante dont ils disposent pour recevoir des médias et optimiser la qualité du flux.

L'expéditeur peut être un éditeur ou le Routeur vidéo multimédia de VonageL'API est appelée "statistiques côté expéditeur" car l'expéditeur est la source des mesures rapportées, délivrées au destinataire qui est l'abonné. L'API est appelée "Sender-side Statistics" (statistiques côté émetteur) car l'émetteur est la source des mesures rapportées, transmises au récepteur qui est l'abonné.

L'API rapporte deux paramètres clés par bundle (paire audio-vidéo) : le débit maximum que l'expéditeur peut estimer et l'estimation de la bande passante actuelle. Le débit maximal est une limite à ce qui peut être estimé en raison des limitations de la plateforme. L'estimation de la bande passante actuelle est la bande passante descendante estimée de la capacité du canal de connexion de l'homologue WebRTC qui est disponible pour les médias, indépendamment du débit du flux.

Par exemple, un éditeur peut envoyer un flux VGA en utilisant moins de 1 Mbps, alors que le Video Media Router de Vonage, qui fournit les statistiques côté expéditeur, peut estimer la bande passante actuelle à 8 Mbps, ce qui indique une capacité de canal supplémentaire. Ces informations peuvent être utilisées par l'application pour ajuster les présentations vidéo ou déclencher des actions basées sur des politiques telles que la qualité à la demande (QoD) de Vonage.

Notez que son interprétation diffère lorsqu'un session de connexion à un seul homologue est créée. Dans une session de connexion entre pairs, plusieurs faisceaux audio+vidéo partagent la même connexion, de sorte que l'estimation de la largeur de bande totale doit être calculée en additionnant les estimations des faisceaux individuels. En d'autres termes, la bande passante totale est partagée entre tous les abonnés de la connexion unique.

Activation des statistiques côté expéditeur

Pour activer les statistiques côté expéditeur, utilisez la méthode correspondante dans le Client SDK pour activer les pistes de statistiques côté expéditeur sur l'éditeur. Une fois activées, les mesures suivantes seront incluses dans les événements statistiques audio et vidéo réguliers de l'abonné :

  • Le débit maximum qui peut être estimé pour la connexion.
  • Estimation actuelle de la largeur de bande pour la connexion.

Cas d'utilisation

  • Optimisation de la mise en page pour les abonnés : Utilisez la bande passante estimée par l'API de l'expéditeur ainsi que les statistiques RTC du point d'extrémité local pour afficher un nombre élevé d'abonnés avec une bonne qualité vidéo.

  • Mode média adaptatif : Un abonné peut utiliser les statistiques de l'expéditeur pour déterminer si la largeur de bande estimée de l'expéditeur dépasse un seuil défini (par exemple, 500 kbps) et décider de s'abonner en mode vidéo uniquement ou audio uniquement.

  • Mise à l'échelle de la charge : Utilisez les statistiques côté expéditeur pour vérifier si un abonné peut gérer de manière optimale une augmentation de la charge, par exemple en passant d'un partage d'écran à faible débit à une vidéo en direct à débit élevé.

  • Seuil d'alerte : Utilisez les statistiques côté émetteur pour déclencher des avertissements pour les abonnés si la largeur de bande estimée d'une connexion émetteur tombe en dessous d'un seuil prédéfini.

  • Déclencheurs de qualité à la demande (QoD) : Utilisez les statistiques du côté de l'expéditeur pour déclencher une alerte lorsque la capacité estimée du réseau pour un flux souscrit tombe en dessous d'un seuil donné sur le réseau mobile.

Notes

  • Selon le SDK, les statistiques côté émetteur peuvent ne pas être immédiatement disponibles lors de la première demande de statistiques ou lors du premier événement de statistiques après l'abonnement, en raison de la latence du réseau.
  • Si vous créer une session de connexion avec un seul homologue, la bande passante de la connexion entre pairs est partagée entre tous les abonnés. Le débit maximal correspond au débit le plus élevé que la connexion entre pairs peut estimer, tandis que le débit actuel reflète le débit de chaque flux audio-vidéo. Tous les abonnés de cette connexion entre pairs partagent ce débit binaire maximal. Tenez-en compte lorsque vous évaluez la bande passante disponible de l’expéditeur. Par exemple, un débit binaire actuel de 2 Mbps peut indiquer une bonne qualité si plusieurs abonnés partagent la même connexion entre pairs.

Problèmes connus

Dans certains cas, lorsque la session est relayée - ou dans certaines configurations routées avec seulement deux participants - et que l'éditeur utilise Firefox, les statistiques côté expéditeur peuvent ne pas être disponibles en raison des limitations du navigateur.

État du réseau

L'API sur l'état du réseau fournit une visibilité en temps réel sur l'état de la connexion réseau pour les éditeurs et les abonnés. Elle expose un score d'état du réseau qui reflète la qualité globale de la connexion, la raison principale de ce score et, pour les abonnés, des informations sur le côté de la connexion qui est à l'origine de la dégradation observée.

Les mesures de l'état du réseau sont incluses dans les statistiques sur les liens avec les médias et sont diffusées par deux canaux :

  • Statistiques périodiques : Les champs relatifs à l'état du réseau sont inclus dans les statistiques sur les liaisons de support fournies lors des événements périodiques de statistiques sur les liaisons de support. Voir Statistiques sur les liens avec les médias pour plus de détails.
  • Événements liés à la modification de l'état du réseau : Un rappel ou un événement spécifique est déclenché chaque fois qu'un changement significatif de l'état du réseau est détecté. Cet événement est distinct des événements d'activation/désactivation de la vidéo ou de repli audio, et signale les changements de l'état du réseau plutôt que les changements de l'état de la piste média. Les applications peuvent utiliser cet événement pour répondre aux problèmes de réseau, par exemple en mettant à jour les indicateurs de l'interface utilisateur, en enregistrant des données télémétriques ou en déclenchant un comportement adaptatif. L'événement inclut les statistiques actuelles de la liaison média ainsi que la raison du changement.

Évaluation de l'état du réseau

L'état du réseau est un score qui reflète la santé globale de la connexion réseau pour un transport donné (local ou distant). Le score est dérivé de mesures telles que la perte de paquets et l'estimation de la bande passante disponible. Des valeurs élevées indiquent de meilleures conditions de réseau.

Score Description
Inconnu L'état du réseau n'a pas pu être déterminé.
Excellent Excellentes conditions de réseau. La qualité vidéo est optimale et la bande passante estimée peut supporter le débit maximal pour la résolution actuelle.
Bon Bonnes conditions de réseau. Des problèmes mineurs ou temporaires peuvent survenir.
Juste Conditions de réseau modérées. La qualité vidéo peut être limitée par l'expéditeur.
Avertissement Mauvaises conditions de réseau. La qualité vidéo est fortement affectée et un avertissement de désactivation de la vidéo est déclenché si le repli audio est activé.
Critique Problèmes de réseau graves. Si le repli audio est activé, le SDK désactive la vidéo pour préserver la stabilité de l'appel.

Remarque : Le score de qualité du réseau est relatif à la configuration actuelle du média et aux demandes de bande passante. Elle reflète la manière dont le réseau prend en charge les exigences actives (par exemple, la résolution vidéo, le débit binaire, la fréquence d'images). Par exemple, si l'application est configurée pour utiliser une faible résolution de caméra ou un faible débit binaire, le réseau peut être considéré comme excellent car la demande de bande passante est minimale. Des résolutions ou des débits binaires plus élevés nécessiteront une plus grande capacité de réseau et peuvent donner lieu à des notes de qualité différentes dans les mêmes conditions de réseau.

Motif lié à l'état du réseau

Chaque note d'état du réseau est accompagnée d'une raison indiquant le principal facteur à l'origine de l'évaluation :

  • Aucun : Aucune raison notable.
  • Largeur de bande : État du réseau influencé par la largeur de bande disponible.
  • Perte de paquets : État du réseau affecté par la perte de paquets.

Source de dégradation du réseau

La source de dégradation du réseau identifie le côté de la connexion qui est principalement responsable de la dégradation du réseau observée. Cette mesure est disponible pour les abonnés et permet de savoir si les problèmes de performance proviennent de la liaison descendante de l'abonné ou de la liaison montante de l'éditeur distant.

La source de dégradation du réseau aide les Applications à identifier la cause première des problèmes de réseau, ce qui permet de cibler le dépannage et la communication avec les utilisateurs. Plutôt que de signaler uniquement que les conditions du réseau sont mauvaises, elle indique si le problème est lié à la qualité de la connexion de l'abonné local ou à celle de l'éditeur distant.

Valeurs possibles :

  • Aucun : Aucune dégradation du réseau n'a été détectée. Les connexions locales et distantes fonctionnent bien.
  • Localement : Le réseau de l'abonné local est la première cause de dégradation. Il peut s'agir d'un mauvais signal WiFi, d'une perte de paquets importante sur la liaison descendante ou d'une bande passante disponible limitée sur la connexion de l'abonné.
  • A distance : Le réseau de l'éditeur distant est la cause principale de la dégradation. L'éditeur connaît de mauvaises conditions de réseau sur sa liaison montante, ce qui affecte la qualité du média reçu par cet abonné.
  • Les deux ou pas clair : La dégradation se produit des deux côtés de la connexion, ou la source ne peut pas être clairement attribuée à un côté. Cela se produit généralement lorsque l'abonné et l'éditeur rencontrent simultanément des problèmes de réseau.

État du réseau par éditeur et abonné

Un éditeur peut desservir de nombreux abonnés, tandis que chaque abonné reçoit un seul flux provenant d'un seul éditeur. Le signalement de l'état du réseau suit ce schéma : un éditeur signale l'état de sa propre liaison montante, tandis qu'un abonné signale l'état de sa liaison descendante, celui de la liaison montante de l'éditeur distant, ainsi que la partie responsable de toute dégradation.

Un éditeur signale le lien dont il est propriétaire. Dans une session routée, l'éditeur maintient uniquement une connexion entre pairs avec le Routeur vidéo multimédia de Vonage, quel que soit le nombre d’abonnés recevant le flux. Le Media Router met fin à cette connexion et transfère le flux multimédia à chaque abonné via des connexions distinctes qu’il gère lui-même. Les métriques de transport de l'éditeur décrivent donc le segment du chemin multimédia entre l'éditeur et le routeur multimédia — le segment sur lequel l'éditeur peut exercer une influence directe par le biais de son propre encodage et de son contrôle de débit. C'est également la raison pour laquelle le tableau de statistiques d'un éditeur acheminé contient un seul objet dont l'ID de connexion et l'ID d'abonné ne sont pas définis, comme décrit dans Statistiques de l'éditeur. Dans le cas de sessions comptant plus de deux participants, étendre ces indicateurs à chaque abonné destinataire ne serait pas évolutif et n'aurait qu'une valeur diagnostique limitée : le routeur multimédia transfère le flux vers un nombre indéterminé d'abonnés ; les données côté éditeur ne permettraient donc ni d'isoler un problème réseau, ni d'attribuer une défaillance à un participant spécifique.

Le fait de signaler la liaison locale garantit la transparence des transitions AMR. Alors que Routage adaptatif des médias (AMR) Bien qu’il gère spécifiquement les appels à deux participants où chaque émetteur n’a qu’un seul abonné, un chemin multimédia relayé peut tout de même migrer vers le routeur multimédia en cours d’appel lorsque des participants supplémentaires se joignent à la conversation ou que certaines fonctionnalités sont activées. Comme les statistiques de liaison multimédia de l’éditeur décrivent la liaison réseau propre à l’éditeur — sa liaison montante, que cette liaison aboutisse chez un abonné ou au routeur multimédia —, leur signification et leur structure restent inchangées lors d’une telle transition. Les applications peuvent exploiter les statistiques de l’éditeur de manière cohérente sans avoir à suivre la topologie actuelle ni à s’y adapter en cours d’appel. Cela s’inscrit dans l’objectif de conception énoncé au début de ce guide, selon lequel l’API de statistiques de haut niveau correspond parfaitement aux abstractions de l’éditeur et de l’abonné et reste stable lors des transitions.

Pour les appels à deux participants, référez-vous à la vue de l'abonné. Lorsque chaque participant publie un flux et s'abonne à un flux, les statistiques relatives aux abonnés suffisent pour analyser les deux sens. Si un abonné signale une source de dégradation de Remote, la liaison montante du participant distant est limitée — et l'abonné de ce participant subit probablement lui aussi une dégradation de la qualité de service, car les causes courantes (signal Wi-Fi faible, réseau d'accès encombré, mauvaise couverture mobile) affectent les deux sens d'une liaison. Considérez cela comme une hypothèse plutôt que comme une certitude.

Voir aussi Corréler les mesures de l'éditeur et de l'abonné pour diagnostiquer la cause première.

Relation avec le repli audio

Le rapport sur l'état du réseau est aligné sur le mécanisme de repli audio. Lorsque des événements de repli audio sont déclenchés aux niveaux avertissement ou critique, l'état du réseau signalé reflète la même gravité. L'état du réseau indique l'état d'avertissement ou critique correspondant pour l'éditeur, l'abonné ou les deux, ce qui garantit une signalisation cohérente entre les API de réseau et de repli des médias.

L'inverse peut également se produire : l'état du réseau peut signaler un niveau d'avertissement ou critique sans que le repli audio soit déclenché, ce qui se produit lorsque le repli audio est désactivé.

Activation de l'état du réseau

Les rapports sur l'état du réseau s'appuient sur plusieurs fonctionnalités qui fonctionnent ensemble. Plus vous activez de fonctions, plus les données sur l'état du réseau sont riches et précises :

  • Statistiques côté expéditeur: Activer les statistiques côté émetteur sur l'éditeur pour permettre aux abonnés de recevoir des mesures de transport de l'éditeur à distance et une attribution plus précise de la source de dégradation du réseau.
  • Repli audio de l'éditeur : Activer le repli audio sur l'éditeur pour améliorer la précision de l'évaluation des conditions du réseau côté éditeur.
  • Repli audio de l'abonné : Activer le repli audio sur l'abonné pour améliorer la précision de l'évaluation de l'état du réseau du côté de l'abonné.

Si ces fonctions ne sont pas activées, certaines données relatives à l'état du réseau peuvent être limitées ou indisponibles.

Pour recevoir des événements de modification de l'état du réseau, enregistrez un rappel ou un auditeur pour les modifications de l'état du réseau sur l'éditeur ou l'abonné. L'événement comprend les statistiques actuelles de la liaison média, qui contiennent des mesures de l'état du réseau et du transport. Pour plus de détails, voir le guide du développeur pour chaque Client SDK dans la section Permettre la collecte de statistiques audio et vidéo section.

Utiliser les informations sur l'observabilité des clients

Cette section fournit des conseils pratiques sur la manière d'utiliser efficacement ces signaux, ainsi que sur les erreurs courantes à éviter.

Meilleures pratiques

Laisser le SDK adapter automatiquement la qualité, puis agir en fonction du résultat

Le SDK gère déjà automatiquement l'adaptation de la qualité :

  • Côté éditeur : Lorsque la bande passante ou l'unité centrale est limitée, l'éditeur réduit automatiquement la résolution et la fréquence d'images. Dans les configurations simulcast ou SVC, cela signifie que l'encodeur peut passer à une couche spatiale ou temporelle inférieure.
  • SFU (sessions routées) : Le routeur vidéo de Vonage sélectionne la couche de diffusion simultanée appropriée pour chaque abonné en fonction de la bande passante descendante disponible de l'abonné. Un abonné dont la connexion est faible recevra une couche de résolution inférieure sans aucune intervention de l'application.
  • Sessions relayées : L'éditeur réduit directement l'échelle pour chaque pair, puisqu'il envoie des flux individuels à chaque abonné.

Vous n'avez pas besoin, et ne devriez pas, essayer de reproduire cette logique dans votre application. Au lieu de cela, utilisez les événements d'observabilité pour réagir au résultat : mettez à jour votre interface utilisateur, enregistrez les données télémétriques ou déclenchez des décisions stratégiques de haut niveau sur la base des informations déjà communiquées par le SDK.

Si vous observez un quality_limitation_reason de bandwidth dans les métriques vidéo de l'éditeur, l'encodeur est déjà en train de limiter la sortie. Utilisez ce signal pour informer les décisions UX (telles que le masquage d'une prévisualisation haute résolution) plutôt que d'émettre des dérogations de résolution redondantes. De même, si la raison est cpuDans le cas de l'encodage, envisagez de libérer des ressources CPU ailleurs dans votre application - par exemple, en mettant en pause les animations non essentielles, en reportant le traitement en arrière-plan ou en réduisant la complexité du rendu de l'interface utilisateur - afin de donner plus de marge de manœuvre à l'encodeur.

Afficher un indicateur de qualité du réseau en temps réel

Utilisez le score de l'état du réseau à partir des statistiques des liens multimédias pour afficher un indicateur de qualité dans votre interface utilisateur, par exemple des barres d'intensité du signal ou une icône colorée. Ne mettez l'indicateur à jour que lorsque l'état du réseau changements (en utilisant l'événement de changement de condition du réseau) plutôt qu'à chaque tic de statistiques périodiques. Cela permet d'éviter les re-rendus inutiles tout en gardant l'indicateur réactif aux changements significatifs de qualité.

Pour les abonnés, la source de dégradation du réseau vous indique de quel côté de l'appel est affecté. Faites en sorte que les participants reçoivent des informations ciblées et exploitables - par exemple, "Votre connexion est instable" ou "Le participant distant rencontre des problèmes de réseau" - au lieu d'un avertissement générique sur la qualité de l'appel.

Utiliser les événements pour une interface utilisateur adaptative, pas pour des sondages

Préférez les rappels déclenchés par des événements à l'inspection des tableaux de statistiques périodiques pour la logique de seuil. L'événement de modification des conditions du réseau et l'événement de modification de la qualité vidéo sont conçus pour détecter les transitions significatives. L'interrogation des statistiques périodiques pour les franchissements de seuil à chaque tic introduit un surcoût pour l'unité centrale.

Lorsque vous devez agir sur des statistiques périodiques, débridez votre logique sur plusieurs échantillons consécutifs avant de déclencher une modification de l'interface utilisateur.

Utiliser les statistiques de transport pour l'aménagement du territoire et les décisions politiques

Les statistiques de la liaison média d'abonné exposent les mesures de transport de deux points de vue simultanément :

  • Statistiques sur les transports locaux reflètent la bande passante que l'expéditeur (l'éditeur ou le Video Media Router de Vonage) estime disponible pour la connexion à cet abonné. Étant donné que l'estimation de la bande passante dans WebRTC est effectuée par l'expéditeur sur la base du retour d'information RTCP, cette figure représente l'opinion de l'expéditeur sur la capacité du canal, et non une auto-mesure de l'abonné.
  • Statistiques de transport de l'éditeur à distance reflètent les mesures de transport de la liaison montante de l'éditeur, telles qu'elles sont communiquées par l'éditeur.

Ensemble, ces deux vues vous permettent de raisonner sur le chemin complet entre l'éditeur et l'abonné. Utilisez-les pour prendre des décisions proactives en matière de mise en page et de politique :

  • Limiter le nombre de tuiles vidéo visibles dans une grille lorsque la capacité estimée est faible, en cachant les participants moins prioritaires plutôt que d'afficher une vidéo gelée ou dégradée.
  • Déclencher des politiques de qualité à la demande (QoD) sur les réseaux mobiles lorsque l'estimation de la largeur de bande de transport local tombe en dessous d'un seuil défini, par exemple lorsque l'on passe de flux à haute définition à des flux à définition standard.
  • Afficher un avertissement de capacité avant d'ajouter un nouveau flux à haut débit (tel que le partage d'écran) à une session lorsque l'estimation de la largeur de bande du transport local est déjà limitée.

Dans une grille à plusieurs participants, vous pouvez étendre cette approche en utilisant les statistiques de transport et les signaux de limitation de l'unité centrale pour allouer un budget de qualité entre les éditeurs. Le SDK adapte chaque flux indépendamment et ne sait pas quels sont les participants importants dans votre configuration. Utiliser setPreferredResolution et setPreferredFrameRate sur l'éditeur pour l'exprimer : accorder à la tuile vedette le plafond de résolution complet et limiter les participants de l'arrière-plan à des valeurs inférieures. Lorsque le locuteur actif change ou que les conditions évoluent, rééquilibrez les plafonds en conséquence. Cette démarche est complémentaire de l'adaptation automatique du SDK, qui continue à fonctionner dans les limites du plafond fixé par l'application.

Corréler les mesures de l'éditeur et de l'abonné pour diagnostiquer la cause première

Les problèmes de réseau peuvent provenir des deux côtés de l'appel. Utilisez la combinaison des statistiques du lien média de l'éditeur et du lien média de l'abonné, ainsi que la source de dégradation du réseau, pour raisonner sur la cause première :

  • Un avertissement ou un état critique du réseau sur la liaison montante de l'éditeur combiné à un message d'avertissement ou à un message d'avertissement sur la liaison montante de l'éditeur. Remote La source de dégradation de l'abonné indique un problème de réseau du côté de l'éditeur.
  • Une baisse de la largeur de bande disponible sur la liaison descendante de l'abonné, combinée à une baisse de l'utilisation de la bande passante sur la liaison descendante de l'abonné. Local La source de dégradation pointe vers la connexion de l'abonné.
  • Lorsque les deux parties présentent une dégradation ou que la source est Both or unclearLe problème doit être traité comme un problème commun.

Statistiques du journal pour l'analyse et le débogage après l'appel

Stockez les statistiques périodiques et les événements de changement de condition du réseau dans un pipeline d'analyse dorsal. Les mesures clés qui valent la peine d'être capturées sont les suivantes :

  • Score de l'état du réseau et raison au fil du temps par éditeur et par abonné.
  • Raison de la limitation de la qualité vidéo et couche active (simulcast/SVC).
  • Estimation de la bande passante disponible à partir des statistiques de la liaison média.
  • Nombre et durée totale des arrêts sur image et des pauses.
  • Le score MOS (web SDK) comme indicateur de la qualité perçue de l'appel.

L'analyse de ces journaux après l'appel peut mettre en évidence des schémas tels que des dégradations récurrentes à des moments précis de la journée, sur certains types de réseaux ou pour des modèles d'appareils spécifiques, ce qui permet d'orienter les améliorations de l'infrastructure et de l'interface utilisateur.

Anti-modèles

Ne pas remplacer l'adaptation automatique de la qualité du SDK

Le SDK réduit déjà la résolution et la fréquence d'images lorsque la bande passante ou l'unité centrale est limitée. L'émission d'une résolution manuelle en réponse à chaque événement de statistiques entre généralement en conflit avec le contrôle de la fréquence de l'encodeur et peut provoquer une oscillation (passage rapide d'un niveau de qualité à l'autre) qui dégrade la qualité perçue plus que ne le ferait une rétrogradation automatique sans à-coups.

Si vous avez des exigences de qualité spécifiques (par exemple, une résolution maximale autorisée), configurez-les de manière déclarative lors de la configuration de la session plutôt que de réagir aux événements de statistiques au moment de l'exécution.

Ne pas déclencher manuellement le repli sur le mode audio uniquement sur la base des statistiques de transport

Le SDK repli audio surveille déjà les conditions du réseau et désactive automatiquement la vidéo lorsque la connexion se détériore jusqu'à atteindre un niveau d'alerte ou critique. L'implémentation de votre propre logique pour faire passer un abonné en mode audio uniquement en fonction de l'estimation de la bande passante du transport local duplique ce comportement intégré et peut entrer en conflit avec lui - par exemple, en désactivant prématurément la vidéo avant que les propres seuils du SDK ne soient atteints, ou en la réactivant à un moment différent de celui prévu par le SDK. Si vous avez besoin d'un comportement de repli audio, utilisez la fonction de repli audio du SDK plutôt que de la piloter directement à partir des statistiques de transport.

Ne pas déclencher de modifications de l'interface utilisateur à chaque événement périodique des statistiques

Les statistiques périodiques se déclenchent à intervalles réguliers (généralement toutes les quelques secondes). L'application de mises à jour de l'interface utilisateur ou de la logique métier à chaque événement, en particulier les vérifications de seuils sur des mesures bruyantes telles que la perte instantanée de paquets, se traduit par des indicateurs vacillants et des alertes intempestives. Lissez toujours vos signaux : exigez plusieurs échantillons consécutifs en dessous d'un seuil, ou utilisez l'événement dédié au changement de condition du réseau, avant de mettre à jour l'état de l'interface utilisateur.

Ne pas se fier aux seuls indicateurs de l'éditeur pour diagnostiquer l'expérience de l'abonné

Les mesures de l'éditeur reflètent la qualité de la transmission en amont. Un éditeur peut signaler d'excellentes conditions de réseau alors qu'un ou plusieurs abonnés ont une mauvaise qualité de liaison descendante. Pour évaluer l'expérience d'un abonné spécifique, il faut toujours combiner les statistiques des liens média de l'éditeur avec les mesures de l'abonné, y compris la source de dégradation du réseau.

Ne pas utiliser le nombre d'octets ou de paquets bruts comme signaux de qualité

Totaux cumulés comme bytesReceived ou packetsLost augmentent de manière monotone et n'ont pas de signification intrinsèque. Il faut toujours calculer les taux (delta sur l'intervalle entre les échantillons) ou utiliser les champs de plus haut niveau, tels que le débit binaire estimé ou le score de l'état du réseau, que le SDK dérive déjà des compteurs bruts.

Ne pas utiliser les statistiques RTC de bas niveau pour mesurer la qualité de bout en bout

Le rapport sur les statistiques du CCF reflète l'état d'un système d'information sur les droits de l'homme. unique la connexion pair sous-jacente à un moment donné. Le SDK peut migrer entre les connexions homologues ou les topologies de transition au cours d'une session, de sorte que les statistiques RTC brutes ne s'agrègent pas à travers ces transitions. Pour mesurer la qualité de bout en bout et surveiller les sessions de longue durée, préférez toujours les API de haut niveau pour les statistiques audio, vidéo et les liens multimédias, qui tiennent compte de ces changements internes.

Ne pas ignorer les différences entre les sessions routées et relayées

Dans une session routée, les statistiques côté émetteur sont fournies par le routeur vidéo Vonage, et les estimations de la bande passante face à l'abonné reflètent la liaison descendante de l'abonné vers le routeur média, et non une mesure directe de la liaison montante de l'éditeur. Dans une session relayée (peer-to-peer), l'éditeur envoie des flux individuels à chaque abonné, et les statistiques de l'éditeur représentent des mesures directes des pairs. Lors de l'élaboration d'une logique analytique ou adaptative, il faut tenir compte du mode de session pour éviter de mal interpréter les chiffres.

Rapport statistique RTC

L'API RTC stats report permet d'accéder à des statistiques WebRTC standardisées de bas niveau pour le flux de médias publié et souscrit. Les applications peuvent ainsi récupérer des métriques détaillées dans le format défini par la spécification WebRTC, ce qui permet une surveillance et une analyse avancées au-delà des métriques d'observabilité client personnalisées.

Remarque : Cette API fournit des statistiques de bas niveau sur les connexions entre pairs. Le SDK vidéo peut optimiser les connexions entre pairs, effectuer des transitions entre différentes topologies ou migrer vers un autre serveur backend. Ces statistiques de bas niveau n'agrègent pas les métriques des différentes connexions entre pairs en cours d'utilisation ou depuis lesquelles la transition a été effectuée. Il est donc préférable de s'appuyer sur notre API de statistiques audio et vidéo pour une surveillance de bout en bout.

Permettre la collecte de statistiques audio et vidéo

Dans l'éditeur ou l'abonné, écoutez les événements statistiques correspondants. Pour plus de détails, voir le guide du développeur correspondant pour chaque Client SDK :