Observabilité du client : iOS

Le SDK Video de Vonage expose des mesures détaillées de la qualité du flux par le biais d'une API de statistiques de haut niveau - recommandée pour la plupart des cas d'utilisation - qui fournit des statistiques audio, vidéo, réseau et côté expéditeur sous une forme unifiée et consciente de la session, qui reste stable lors des transitions de connexion entre pairs. Pour le débogage avancé, le SDK permet également d'accéder au rapport de statistiques WebRTC brut, qui reflète les données de connexion entre pairs non traitées.

API pour les statistiques audio et vidéo

Le SDK iOS vidéo de Vonage envoie des statistiques périodiques sur le réseau audio et vidéo pour les éditeurs et les abonnés. Ces statistiques comprennent le nombre de paquets, les débits binaires, les données sur la fréquence d'images, les mesures de pause et de gel, les informations sur les codecs et l'estimation optionnelle du réseau côté expéditeur.

Les statistiques sont fournies par l'intermédiaire de :

  • OTPublisherKitNetworkStatsDelegate - statistiques côté éditeur

  • OTSubscriberKitNetworkStatsDelegate - statistiques relatives aux abonnés

Pour les recevoir, activez le délégué approprié sur l'éditeur ou l'abonné.

Activation des statistiques pour les éditeurs

Attachez une classe qui adopte OTPublisherKitNetworkStatsDelegate :

@interface MyViewController () <OTPublisherKitDelegate, OTPublisherKitNetworkStatsDelegate>
@end

OTPublisher *publisher = [[OTPublisher alloc] initWithDelegate:self
                                                      settings:settings];
publisher.networkStatsDelegate = self;

Mettre en œuvre les rappels :

- (void)publisher:(OTPublisherKit *)publisher
videoNetworkStatsUpdated:(NSArray<OTPublisherKitVideoNetworkStats *> *)statsArray {

    OTPublisherKitVideoNetworkStats *stats = statsArray.firstObject;
    if (!stats) return;

    // For routed sessions, the first element is sufficient.
    // For relayed sessions, iterate all elements if you want per-subscriber stats.
    NSString *connectionId = stats.connectionId ?: @"<none>";
    NSString *subscriberId = stats.subscriberId ?: @"<none>";

    NSLog(@"Publisher Video Stats for connectionId: %@, subscriberId: %@", connectionId, subscriberId);
    NSLog(@"Video bytes sent: %lld", stats.videoBytesSent);
    NSLog(@"Video packets sent: %lld", stats.videoPacketsSent);
    NSLog(@"Video packets lost: %lld", stats.videoPacketsLost);
    NSLog(@"Stats timestamp: %f ms", stats.timestamp);

    for (OTPublisherKitVideoLayerStats *layer in stats.videoLayers) {
        NSLog(@"Layer: %dx%d", layer.width, layer.height);
        NSLog(@"  Encoded FPS: %f", layer.encodedFrameRate);
        NSLog(@"  Bitrate: %lld bps", layer.bitrate);
        NSLog(@"  Total bitrate (incl. RTP overhead): %lld bps", layer.totalBitrate);
        NSLog(@"  Codec: %@", layer.codec ?: @"unknown");
        NSLog(@"  Scalability mode: %@", layer.scalabilityMode ?: @"none");
        NSLog(@"  Quality limitation: %@", @(layer.qualityLimitationReason));
    }

    if (stats.transport) {
        NSLog(@"Estimated uplink bandwidth: %lld bps", stats.transport.connectionEstimatedBandwidth);
    }
}

- (void)publisher:(OTPublisherKit *)publisher
audioNetworkStatsUpdated:(NSArray<OTPublisherKitAudioNetworkStats *> *)statsArray {

    OTPublisherKitAudioNetworkStats *stats = statsArray.firstObject;
    if (!stats) return;

    // For routed sessions, the first element is sufficient.
    // For relayed sessions, iterate all elements if you want per-subscriber stats.
    NSString *connectionId = stats.connectionId ?: @"<none>";
    NSString *subscriberId = stats.subscriberId ?: @"<none>";

    NSLog(@"Publisher Audio Stats for connectionId: %@, subscriberId: %@", connectionId, subscriberId);
    NSLog(@"Audio bytes sent: %lld", stats.audioBytesSent);
    NSLog(@"Audio packets sent: %lld", stats.audioPacketsSent);
    NSLog(@"Audio packets lost: %lld", stats.audioPacketsLost);
    NSLog(@"Stats timestamp: %f ms", stats.timestamp);
    
    if (stats.transport) {
        NSLog(@"Estimated uplink bandwidth: %lld bps", stats.transport.connectionEstimatedBandwidth);
    }
}

Pour un éditeur dans une session acheminée (qui utilise l'option Routeur vidéo multimédia de Vonage), le tableau stats comprend un objet, définissant les statistiques pour le flux audio ou vidéo unique envoyé au routeur vidéo de Vonage. Dans une session relayée, le tableau de statistiques comprend un objet pour chaque abonné au flux publié. le flux publié.

Réception d'événements de qualité vidéo sur les éditeurs

Si vous êtes également intéressé par les événements relatifs à la qualité de la vidéo, implémentez ce callback :

- (void)publisher:(OTPublisherKit *)publisher
videoQualityChanged:(OTPublisherKitVideoNetworkStats *)stats
           reason:(OTPublisherVideoEventReason)reason {

    NSLog(@"Publisher video quality event: %ld", (long)reason);
}

Activation des statistiques pour les abonnés

Joindre une classe qui adopte OTSubscriberKitNetworkStatsDelegate:

@interface MyViewController () <OTSubscriberKitDelegate, OTSubscriberKitNetworkStatsDelegate>
@end

OTSubscriber *subscriber = [[OTSubscriber alloc] initWithStream:stream
                                                       delegate:self];
subscriber.networkStatsDelegate = self;
[session subscribe:subscriber error:nil];

Mettre en œuvre les rappels :

- (void)subscriber:(OTSubscriberKit *)subscriber
videoNetworkStatsUpdated:(OTSubscriberKitVideoNetworkStats *)stats {
    NSLog(@"Video bytes received: %llu", stats.videoBytesReceived);
}

- (void)subscriber:(OTSubscriberKit *)subscriber
audioNetworkStatsUpdated:(OTSubscriberKitAudioNetworkStats *)stats {
    NSLog(@"Audio packets received: %llu", stats.audioPacketsReceived);
}

Réception d'événements relatifs à la qualité vidéo sur les abonnés

En outre, gérer les événements de modification de la qualité vidéo de l'abonné :

- (void)subscriber:(OTSubscriberKit *)subscriber
videoQualityChanged:(OTSubscriberKitVideoNetworkStats *)stats
            reason:(OTSubscriberVideoEventReason)reason {

    NSLog(@"Subscriber video quality event: %ld", (long)reason);
}

Statistiques Structures de données

Cette section présente les structures et les propriétés fournies par l'API de statistiques audio et vidéo d'iOS. Bien que toutes les plateformes SDK vidéo exposent le même ensemble de statistiques, il peut y avoir des différences mineures dans la façon dont chaque plateforme structure ou nomme les champs individuels. Ces variations reflètent les conventions de conception du SDK propres à chaque plateforme plutôt que des différences dans les mesures sous-jacentes.

OTTransportStats

Représente l'estimation partagée au niveau du transport.

  • connectionEstimatedBandwidth - Estimation de la largeur de bande disponible de la connexion de liaison montante (bps).

OTPublisherKitVideoNetworkStats

Fournit des statistiques sur la piste vidéo d'un éditeur. Elles comprennent :

  • connectionId - Dans une session relayée, l'identifiant de connexion du client souscrivant au flux. Indéfini dans une session routée.
  • subscriberId - Dans une session relayée, l'identifiant du client abonné au flux. Indéfini dans une session routée.
  • videoPacketsLost - Estimation des paquets vidéo perdus.
  • videoPacketsSent - Paquets vidéo envoyés.
  • videoBytesSent - Octets vidéo envoyés.
  • timestamp - Date Unix en millisecondes à laquelle les statistiques ont été recueillies.
  • startTime - Le timestamp, en millisecondes depuis l'époque Unix, à partir duquel les totaux cumulés ont commencé à s'accumuler.
  • videoLayers - Tableau de statistiques sur la couche vidéo (voir OTPublisherKitVideoLayerStats).
  • transport - Statistiques de réseau au niveau du transport.

OTPublisherKitAudioNetworkStats

Fournit des statistiques sur la piste audio d'un éditeur. Elle comprend :

  • connectionId - Dans une session relayée, l'identifiant de connexion du client souscrivant au flux. Indéfini dans une session routée.
  • subscriberId - Dans une session relayée, l'identifiant du client abonné au flux. Indéfini dans une session routée.
  • audioPacketsLost - Estimation des paquets perdus.
  • audioPacketsSent - Paquets audio envoyés.
  • audioBytesSent - Octets audio envoyés.
  • timestamp - Horodatage Unix en millisecondes.
  • startTime - Le timestamp, en millisecondes depuis l'époque Unix, à partir duquel les totaux cumulés ont commencé à s'accumuler.
  • transport - Statistiques de réseau au niveau du transport.

OTPublisherKitVideoLayerStats

Représente une couche simulcast ou une couche SVC.

  • width - Largeur de la trame encodée.
  • height - Hauteur du cadre codé.
  • encodedFrameRate - Images codées par seconde.
  • bitrate - Débit binaire de la couche (bps).
  • totalBitrate - Débit de la couche incluant le surdébit RTP (bps).
  • scalabilityMode - Descripteur SVC/scalability (par exemple, "L3T3").
  • qualityLimitationReason - Raison de la limitation de la qualité (bande passante, CPU, codec, résolution ou changement de couche).
  • codec - Le codec utilisé par cette couche vidéo.

OTSenderStats

Mesures d'estimation du côté de l'expéditeur (reflétées à la fois sur l'audio et la vidéo).

  • connectionMaxAllocatedBitrate - Débit maximum estimé pour la connexion de l'expéditeur.
  • connectionEstimatedBandwidth - Estimation de la largeur de bande actuelle (bps).

OTSubscriberKitVideoNetworkStats

Fournit des statistiques sur la piste vidéo d'un abonné. Elles comprennent :

  • videoPacketsLost - Estimation des paquets vidéo perdus.
  • videoPacketsReceived - Paquets vidéo reçus.
  • videoBytesReceived - Octets vidéo reçus.
  • timestamp - Date Unix en millisecondes à laquelle les statistiques ont été recueillies.
  • senderStats - Mesures du côté de l'expéditeur (facultatif).
  • width - Largeur de la trame décodée en pixels.
  • height - Hauteur de l'image décodée en pixels.
  • decodedFrameRate - Images décodées par seconde.
  • bitrate - Débit binaire vidéo (bps).
  • totalBitrate - Débit binaire incluant l'overhead RTP (bps).
  • pauseCount - Nombre de pauses (>5s depuis la dernière image). Inclut les désactivations intentionnelles et les cas de retour audio.
  • totalPausesDuration - Durée totale de la pause (ms).
  • freezeCount - Compte de gel (événement de gel défini par WebRTC).
  • totalFreezesDuration - Durée totale de l'arrêt sur image (ms).
  • codec - Codec du décodeur actuel.

OTSubscriberKitAudioNetworkStats

Fournit des statistiques sur la piste audio d'un abonné. Elles comprennent :

  • audioPacketsLost - Estimation des paquets perdus.
  • audioPacketsReceived - Paquets reçus.
  • audioBytesReceived - Octets reçus.
  • timestamp - Horodatage Unix en millisecondes.
  • senderStats - Mesures du côté de l'expéditeur (facultatif).

Statistiques côté expéditeur

Voir le aperçu des statistiques côté expéditeur.

Activation des statistiques côté expéditeur

Les statistiques côté émetteur sont reçues par les abonnés. Pour recevoir les statistiques côté émetteur, il faut les activer pour l'éditeur du flux en définissant l'attribut senderStatsTrack à la propriété true pour les OTPublisherKitSettings utilisé pour créer l'éditeur.

OTPublisherKitSettings *settings = [[OTPublisherKitSettings alloc] init];
settings.senderStatsTrack = YES;

OTPublisher *publisher = [[OTPublisher alloc] initWithDelegate:self
                                                      settings:settings];

Si senderStatsTrack n'est pas activé, aucun canal de statistiques sur les expéditeurs ne sera publié pour cet éditeur. La valeur par défaut est NO.

Abonnement aux statistiques côté expéditeur

Si l'éditeur du flux a activé les statistiques côté émetteur, les abonnés commencent à les recevoir automatiquement dès qu'un auditeur est enregistré pour les statistiques vidéo ou audio, comme décrit ci-dessus.

Mettre en œuvre la méthode de délégation pour les statistiques vidéo :

- (void)subscriber:(OTSubscriberKit *)subscriber
videoNetworkStatsUpdated:(OTSubscriberKitVideoNetworkStats *)stats
{
    // The property may be nil if no sender statistics have been received yet.
    if (stats.senderStats) {
        OTSenderStats *sender = stats.senderStats;
        NSLog(@"Connection max allocated bitrate: %lld bps", (long long)sender.connectionMaxAllocatedBitrate);
        NSLog(@"Connection current estimated bandwidth: %lld bps", (long long)sender.connectionEstimatedBandwidth);
    } else {
        NSLog(@"Sender-side stats not available yet.");
    }
}

De même, mettre en œuvre -subscriber:audioNetworkStatsUpdated: pour les statistiques audio, qui comprend également un senderStats propriété.

Statistiques de réception Événements

Les statistiques du côté de l'expéditeur sont fournies par l'intermédiaire de l'application OTSubscriberKitNetworkStatsDelegate pour la vidéo et l'audio, comme indiqué ci-dessus. Les OTSenderStats, inclus dans le senderStats dans les deux OTSubscriberKitVideoNetworkStats et OTSubscriberKitAudioNetworkStatsLe système de gestion de l'information de l'Union européenne (UE), offre deux propriétés :

  • connectionMaxAllocatedBitrate - Le débit maximum qui peut être estimé pour la connexion
  • connectionEstimatedBandwidth - La largeur de bande actuelle estimée pour la connexion

Ces deux mesures sont calculées par paquet audio-vidéo, de sorte que les mêmes valeurs apparaissent dans les statistiques audio et vidéo. Parce qu'elles reflètent le transport plutôt que les pistes individuelles, les mesures sont partagées entre l'audio et la vidéo.

Rapport statistique RTC

Pour obtenir les statistiques de bas niveau de l'éditeur sur les connexions entre pairs, utilisez la commande [OTPublisherKit getRtcStatsReport:] méthode. Cette méthode fournit des rapports de statistiques RTC pour le flux multimédia.

Il s'agit d'une opération asynchrone. Définir le >[OTPublisherKit rtcStatsReportDelegate]> et mettre en œuvre la propriété >[OTPublisherKitRtcStatsReportDelegate publisher:rtcStatsReport:]> avant d'appeler la méthode [OTPublisherKit getRtcStatsReport:].

Lorsque les statistiques sont disponibles, la mise en œuvre de la fonction >[OTPublisherKitRtcStatsReportDelegate publisher:rtcStatsReport:]> est envoyé. Le message comprend un tableau de OTPublisherRtcStats qui comprend un jsonArrayOfReports propriété.

Il s'agit d'un tableau JSON de rapports de statistiques RTC, qui sont similaires au format de l'objet RtcStatsReport mis en œuvre dans les navigateurs web (voir ces documents de Mozilla).

Pour obtenir des statistiques de bas niveau sur la connexion d'un abonné à un homologue, utilisez la commande [OTSubscriberKit getRtcStatsReport:] méthode. Cette méthode permet d'obtenir un rapport de statistiques RTC pour le flux multimédia.

Il s'agit d'une opération asynchrone. Définir le [OTSubscriberKit rtcStatsReportDelegate]> et mettre en œuvre la propriété >[OTSubscriberKitRtcStatsReportDelegate subscriber:rtcStatsReport:]> avant d'appeler la méthode [OTSubscriberKit getRtcStatsReport:].

Lorsque les statistiques sont disponibles, la mise en œuvre de la fonction >[OTSubscriberKitRtcStatsReportDelegate subscriber:rtcStatsReport:]> est envoyé. Le message comprend un a jsonArrayOfReports paramètre.

Il s'agit d'un tableau JSON de rapports de statistiques RTC, qui sont similaires au format de l'objet RtcStatsReport mis en œuvre dans les navigateurs web (voir ces documents de Mozilla).

Voir aussi cette documentation du W3C.

Échantillon

Les Exemple d'application d'observabilité du client SDK iOS de Vonage Video démontre les fonctionnalités d'observabilité du client dans une application mobile construite avec le Client SDK iOS.