Observabilidad del cliente: iOS

El SDK de video de Vonage expone métricas detalladas de la calidad de la transmisión a través de una API de estadísticas de alto nivel, recomendada para la mayoría de los casos de uso, que proporciona estadísticas de audio, video, red y del lado del emisor en una forma unificada y consciente de la sesión que permanece estable a través de las transiciones de conexión entre pares. Para la depuración avanzada, el SDK también ofrece acceso al informe de estadísticas WebRTC sin procesar, que refleja los datos de la conexión entre pares sin procesar.

El SDK también proporciona métricas sobre el estado de la red que ofrecen una evaluación general del estado de la conexión, tanto para los emisores como para los suscriptores. Estas métricas incluyen una puntuación del estado de la red, el motivo que explica dicha puntuación y, en el caso de los suscriptores, una fuente de degradación que indica qué lado de la conexión es responsable de los problemas observados. Véase Estado de la red y origen de la degradación Para más información.

API de estadísticas de audio, vídeo y enlaces multimedia

El SDK de Vonage Video para iOS envía estadísticas periódicas sobre audio, vídeo y enlaces multimedia, tanto para los emisores como para los suscriptores. Entre ellas se incluyen el recuento de paquetes, las velocidades de bits, los datos sobre la frecuencia de fotogramas, las métricas de pausa y congelación, la información sobre códecs y las métricas de red a nivel de transporte, como la estimación del ancho de banda y la puntuación del estado de la red.

Las estadísticas se entregan a través de:

OTPublisherKitNetworkStatsDelegate - estadísticas del editor (audio, vídeo)
OTSubscriberKitNetworkStatsDelegate — estadísticas del lado del suscriptor (audio, vídeo)

Para recibirlos, activa el delegado correspondiente en el editor o en el suscriptor.

Estadísticas para editores

Adjunta una clase que adopte OTPublisherKitNetworkStatsDelegate:

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

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

Implementa las funciones de devolución de llamada:

- (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));
    }
}

- (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);
}

- (void)publisher:(OTPublisherKit *)publisher
mediaLinkStatsUpdated:(NSArray<OTPublisherKitMediaLinkStats*>*)mediaLinkStats {
    
    if (mediaLinkStats.count == 0) return;
    OTPublisherKitMediaLinkStats *stats = mediaLinkStats.firstObject;
    
    NSLog(@"Publisher uplink bandwidth: %lld bps", stats.transport.connectionEstimatedBandwidth);
    NSLog(@"Network condition: %ld", (long)stats.transport.networkCondition);
    NSLog(@"Condition reason: %ld", (long)stats.transport.networkConditionReason);
}

Para un editor en una sesión enrutada (que utiliza la función Router multimedia de vídeo de Vonage), la matriz «stats» incluye un objeto que define las estadísticas de la única secuencia multimedia de audio o vídeo que se envía al Vonage Video Media Router. En una sesión retransmitida, la matriz «stats» incluye un objeto por cada suscriptor de la secuencia publicada.

Recepción de eventos de calidad de vídeo en los editores

Si también te interesan los eventos relacionados con la calidad del vídeo, implementa esta función de devolución de llamada:

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

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

Recepción de eventos de estado de la red en los editores

Para recibir eventos de cambio de estado de la red para el editor, implemente la función publisher:networkConditionChanged:mediaLinkStats:reason: función de devolución de llamada:

- (void)publisher:(OTPublisherKit *)publisher
networkConditionChanged:(OTPublisherKitMediaLinkStats *)mediaLinkStats
             reason:(OTNetworkReason)reason {

    NSLog(@"Publisher network condition changed: %ld", (long)mediaLinkStats.transport.networkCondition);
    NSLog(@"Reason: %ld", (long)mediaLinkStats.transport.networkConditionReason);
}

Esta llamada de retorno se activa cuando se detecta un cambio significativo en las condiciones de la red para el editor. Incluye las estadísticas actuales del enlace multimedia con métricas de transporte. Véase Estado de la red y origen de la degradación para más detalles sobre la interpretación de las puntuaciones y razones del estado de la red.

Activar las estadísticas para abonados

Adjunta una clase que adopte OTSubscriberKitNetworkStatsDelegate:

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

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

Implementa las funciones de devolución de llamada:

- (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);
}

- (void)subscriber:(OTSubscriberKit *)subscriber
mediaLinkStatsUpdated:(OTSubscriberKitMediaLinkStats *)mediaLinkStats {
    
    NSLog(@"Local downlink bandwidth: %lld bps", mediaLinkStats.transport.connectionEstimatedBandwidth);
    NSLog(@"Remote publisher uplink bandwidth: %lld bps", mediaLinkStats.remotePublisherTransport.connectionEstimatedBandwidth);
    NSLog(@"Degradation source: %ld", (long)mediaLinkStats.networkDegradationSource);
}

Recepción de eventos de calidad de vídeo en los abonados

Además, gestiona los eventos relacionados con cambios en la calidad de vídeo de los suscriptores:

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

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

Recepción de eventos de estado de la red en los abonados

Para recibir eventos de cambio en el estado de la red del abonado, implementa el subscriber:networkConditionChanged:mediaLinkStats:reason: función de devolución de llamada:

- (void)subscriber:(OTSubscriberKit *)subscriber
networkConditionChanged:(OTSubscriberKitMediaLinkStats *)mediaLinkStats
             reason:(OTNetworkReason)reason {

    NSLog(@"Local network condition: %ld", (long)mediaLinkStats.transport.networkCondition);
    NSLog(@"Remote publisher network condition: %ld", (long)mediaLinkStats.remotePublisherTransport.networkCondition);
    NSLog(@"Degradation source: %ld", (long)mediaLinkStats.networkDegradationSource);
}

Esta llamada de retorno se activa cuando se detecta un cambio significativo en las condiciones de la red para el abonado o el editor remoto. Incluye las estadísticas actuales del enlace multimedia con las métricas de transporte local y remoto y la fuente de degradación. Véase Estado de la red y origen de la degradación para más detalles sobre la interpretación de las puntuaciones y razones del estado de la red.

Estadística y estructuras de datos

En esta sección se describen las estructuras y propiedades que proporciona la API de estadísticas de audio y vídeo de iOS. Aunque todas las plataformas Video SDK exponen el mismo conjunto de estadísticas, puede haber pequeñas diferencias en la forma en que cada plataforma estructura o nombra los campos individuales. Estas variaciones reflejan convenciones de diseño del SDK específicas de cada plataforma más que diferencias en las métricas subyacentes.

`OTTransportStats`

Representa métricas compartidas a nivel de transporte.

connectionEstimatedBandwidth – Ancho de banda de conexión disponible estimado (bps).
networkCondition – Puntuación del estado actual de la red (OTNetworkConditionUnknown, OTNetworkConditionCritical, OTNetworkConditionWarning, OTNetworkConditionFair, OTNetworkConditionGood, o OTNetworkConditionExcellent).
networkConditionReason - Razón principal que afecta al estado de la red (OTNetworkReasonNone, OTNetworkReasonUnknown, OTNetworkReasonBandwidth, o OTNetworkReasonPacketLoss).

`OTPublisherKitVideoNetworkStats`

Proporciona estadísticas sobre la trayectoria de los vídeos de un editor. Incluye:

connectionId - En una sesión retransmitida, el identificador de conexión del cliente que se suscribe al flujo. No definido en una sesión enrutada.
subscriberId - En una sesión retransmitida, el ID suscrito del cliente que se suscribe al flujo. No definido en una sesión enrutada.
videoPacketsLost - Estimación de paquetes de vídeo perdidos.
videoPacketsSent - Paquetes de vídeo enviados.
videoBytesSent - Bytes de vídeo enviados.
timestamp - Marca de tiempo Unix en milisegundos cuando se recopilaron las estadísticas.
startTime - La marca de tiempo, en milisegundos desde la época Unix, a partir de la cual comenzaron a acumularse los totales acumulados.
videoLayers - La matriz de estadísticas de la capa de vídeo (véase OTPublisherKitVideoLayerStats).

`OTPublisherKitAudioNetworkStats`

Ofrece estadísticas sobre la pista de audio de un editor. Incluye:

connectionId - En una sesión retransmitida, el identificador de conexión del cliente que se suscribe al flujo. No definido en una sesión enrutada.
subscriberId - En una sesión retransmitida, el ID suscrito del cliente que se suscribe al flujo. No definido en una sesión enrutada.
audioPacketsLost - Estimación de paquetes perdidos.
audioPacketsSent – Paquetes de audio enviados.
audioBytesSent - Bytes de audio enviados.
timestamp – Marca de tiempo Unix en milisegundos.
startTime - La marca de tiempo, en milisegundos desde la época Unix, a partir de la cual comenzaron a acumularse los totales acumulados.
transport - Estadísticas de red a nivel de transporte.

`OTPublisherKitVideoLayerStats`

Representa una capa de emisión simultánea o una capa SVC.

width - Anchura de trama codificada.
height – Altura del fotograma codificado.
encodedFrameRate – Fotogramas por segundo codificados.
bitrate – Velocidad de transmisión de la capa (bps).
totalBitrate – Velocidad de transmisión de la capa, incluida la sobrecarga de RTP (bps).
scalabilityMode - Descriptor SVC/escalabilidad (por ejemplo, "L3T3").
qualityLimitationReason - Motivo de la limitación de calidad (ancho de banda, CPU, códec, resolución o cambio de capa).
codec – El códec utilizado por esta capa de vídeo.

`OTSenderStats`

Métricas de estimación del lado del emisor (aplicadas tanto al audio como al vídeo).

connectionMaxAllocatedBitrate – Velocidad de transmisión máxima estimada para la conexión del remitente.
connectionEstimatedBandwidth – Estimación del ancho de banda actual (bps).

`OTSubscriberKitVideoNetworkStats`

Proporciona estadísticas sobre la pista de vídeo de un abonado. Incluye:

videoPacketsLost - Estimación de paquetes de vídeo perdidos.
videoPacketsReceived - Paquetes de vídeo recibidos.
videoBytesReceived - Bytes de vídeo recibidos.
timestamp - Marca de tiempo Unix en milisegundos cuando se recopilaron las estadísticas.
senderStats – Métricas del lado del remitente (opcional).
width - Anchura del fotograma descodificado en píxeles.
height – Altura del fotograma descodificado en píxeles.
decodedFrameRate – Fotogramas por segundo decodificados.
bitrate - Velocidad de bits de vídeo (bps).
totalBitrate - Bitrate incluyendo la sobrecarga RTP (bps).
pauseCount - Numbers de pausas (>5s desde el último fotograma). Incluye desactivaciones intencionadas y casos de audio-fallback.
totalPausesDuration - Duración total de la pausa (ms).
freezeCount - Recuento de congelaciones (evento de congelación definido por WebRTC).
totalFreezesDuration - Duración total de la congelación (ms).
codec - Códec decodificador actual.

`OTSubscriberKitAudioNetworkStats`

Proporciona estadísticas sobre la pista de audio de un suscriptor. Incluye:

audioPacketsLost - Estimación de paquetes perdidos.
audioPacketsReceived - Paquetes recibidos.
audioBytesReceived - Bytes recibidos.
timestamp – Marca de tiempo Unix en milisegundos.
senderStats – Métricas del lado del remitente (opcional).

`OTPublisherKitMediaLinkStats`

Proporciona estadísticas a nivel de transporte para la conexión de un editor.

transport - Estadísticas de transporte de este editor (véase OTTransportStats)

`OTSubscriberKitMediaLinkStats`

Proporciona estadísticas a nivel de transporte para las conexiones de un abonado, incluida la visibilidad del rendimiento de la red del editor remoto. Esto permite a las aplicaciones diagnosticar si los problemas de conexión se originan en el enlace descendente del abonado o en el enlace ascendente del editor.

transport – Estadísticas de tráfico de la conexión de bajada de este abonado (véase OTTransportStats)
remotePublisherTransport - Estadísticas de transporte de la conexión de enlace ascendente del editor remoto (obtenidas mediante estadísticas del lado del remitenteVer OTTransportStats). Estas estadísticas pueden estar limitadas si las estadísticas del lado del remitente no están activadas.
networkDegradationSource - Indica la fuente de degradación de la red (OTNetworkDegradationSourceLocal, OTNetworkDegradationSourceRemote, OTNetworkDegradationSourceBothOrUnclear, o OTNetworkDegradationSourceUnknown)

Estadísticas del lado del remitente

Véase el Resumen de las estadísticas del lado del remitente.

Activación de las estadísticas del remitente

Las estadísticas del lado del emisor se reciben en los abonados. Para recibir las estadísticas del lado del emisor, habilítelas para el editor del flujo estableciendo el parámetro senderStatsTrack propiedad a true para la OTPublisherKitSettings utilizado para crear el editor.

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

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

Si senderStatsTrack no está activado, no se publicará ningún canal de estadísticas del remitente para este editor. El valor por defecto es NO.

Suscribirse a las estadísticas del remitente

Si el editor del flujo ha activado las estadísticas del lado del remitente, los abonados empezarán a recibirlas automáticamente en cuanto un oyente se registre para recibir estadísticas de vídeo o audio, como se ha descrito anteriormente.

Implementa el método delegado para las estadísticas de vídeo:

- (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.");
    }
}

Del mismo modo -subscriber:audioNetworkStatsUpdated: para consultar las estadísticas de audio, que también incluyen un senderStats propiedad.

Eventos de estadísticas de recepción

Las estadísticas del lado del remitente se envían a través de OTSubscriberKitNetworkStatsDelegate funciones de devolución de llamada para vídeo y audio, tal y como se muestra más arriba. El OTSenderStatsincluido como senderStats miembro en ambos OTSubscriberKitVideoNetworkStats y OTSubscriberKitAudioNetworkStats, ofrece dos propiedades:

connectionMaxAllocatedBitrate - El bitrate máximo que puede estimarse para la conexión
connectionEstimatedBandwidth - El ancho de banda estimado actual para la conexión

Estas dos métricas se calculan por paquete de audio y vídeo, por lo que los mismos valores aparecen en las estadísticas de vídeo y audio. Como reflejan el transporte y no las pistas individuales, las métricas se comparten tanto en audio como en vídeo.

Estado de la red y origen de la degradación

El SDK proporciona métricas en tiempo real sobre el estado de la red tanto para los editores como para los suscriptores, incluyendo una puntuación de estado, el motivo que la determina y, en el caso de los suscriptores, la fuente de la degradación. Para obtener una explicación detallada del modelo de estado de la red, las puntuaciones, los motivos y cómo activarlo, consulta el visión general de la observabilidad del cliente.

Los datos sobre el estado de la red están disponibles a través de dos canales:

Estadísticas periódicas: Los eventos de estadísticas de enlaces multimedia incluyen métricas de transporte con networkCondition y networkConditionReason. Para los abonados, las estadísticas de los enlaces multimedia también incluyen remotePublisherTransport y networkDegradationSource.
Eventos relacionados con cambios en el estado de la red: Las funciones de devolución de llamada específicas, tanto en el emisor como en el suscriptor, se activan cuando se detecta un cambio significativo en las condiciones de la red.

El siguiente ejemplo muestra cómo utilizar los datos de estado de la red del abonado para identificar la fuente de degradación:

- (void)subscriber:(OTSubscriberKit *)subscriber
networkConditionChanged:(OTSubscriberKitMediaLinkStats *)mediaLinkStats
             reason:(OTNetworkReason)reason {

    OTNetworkCondition localCondition = mediaLinkStats.transport.networkCondition;
    OTNetworkCondition remoteCondition = mediaLinkStats.remotePublisherTransport.networkCondition;
    OTNetworkDegradationSource source = mediaLinkStats.networkDegradationSource;

    if (source == OTNetworkDegradationSourceLocal) {
        NSLog(@"Local network is degraded (condition: %ld)", (long)localCondition);
    } else if (source == OTNetworkDegradationSourceRemote) {
        NSLog(@"Remote publisher network is degraded (condition: %ld)", (long)remoteCondition);
    } else if (source == OTNetworkDegradationSourceBothOrUnclear) {
        NSLog(@"Degradation source unclear — local: %ld, remote: %ld", (long)localCondition, (long)remoteCondition);
    }
}

Informe de estadísticas de RTC

Para obtener las estadísticas de conexión entre pares de bajo nivel del editor, utilice la función [OTPublisherKit getRtcStatsReport:] método. Esto proporciona informes de estadísticas de RTC para la transmisión multimedia.

Esta es una operación asíncrona. Configura el >[OTPublisherKit rtcStatsReportDelegate]> e implementar la propiedad >[OTPublisherKitRtcStatsReportDelegate publisher:rtcStatsReport:]> método antes de llamar a [OTPublisherKit getRtcStatsReport:].

Cuando las estadísticas estén disponibles, la implementación de la >[OTPublisherKitRtcStatsReportDelegate publisher:rtcStatsReport:]> se envía el mensaje. El mensaje incluye una matriz de OTPublisherRtcStats objetos, entre los que se incluye un jsonArrayOfReports propiedad.

Se trata de una matriz JSON de informes de estadísticas de RTC, cuyo formato es similar al del objeto `RtcStatsReport` implementado en los navegadores web (véase estos documentos de Mozilla).

Para obtener estadísticas de conexión entre pares de bajo nivel de los abonados, utiliza el [OTSubscriberKit getRtcStatsReport:] método. Esto proporciona un informe de estadísticas RTC para el flujo de medios.

Esta es una operación asíncrona. Configura el [OTSubscriberKit rtcStatsReportDelegate]> e implementar la propiedad >[OTSubscriberKitRtcStatsReportDelegate subscriber:rtcStatsReport:]> método antes de llamar a [OTSubscriberKit getRtcStatsReport:].

Cuando las estadísticas estén disponibles, la implementación de la >[OTSubscriberKitRtcStatsReportDelegate subscriber:rtcStatsReport:]> Se envía el mensaje. El mensaje incluye un a jsonArrayOfReports parámetro.

Se trata de una matriz JSON de informes de estadísticas de RTC, cuyo formato es similar al del objeto `RtcStatsReport` implementado en los navegadores web (véase estos documentos de Mozilla).

Véase también esta documentación del W3C.

Muestra

El Aplicación de muestra de observabilidad del Client SDK de Vonage Video para iOS muestra las funciones de observabilidad del cliente en una aplicación móvil desarrollada con el Client SDK para iOS.