API de códecs de vídeo preferidos por los editores

Una guía práctica para establecer las preferencias de códec por editor, comprender cómo interactúan esas preferencias con la negociación y confirmar el códec que se está utilizando realmente durante una sesión en directo.

Este tema incluye las siguientes secciones:

• Requisitos previos
• Visión general
• Elegir un modo
• Pedidos de códecs recomendados para situaciones habituales
• Cómo funciona la negociación de códecs
• Establecer preferencias por plataforma
• Verificación del códec en uso
• Buenas prácticas

Requisitos previos

Antes de utilizar la API Preferred Video Codec a través del SDK, debe activarla en la configuración de su proyecto:

1. Ve al panel de la API de Vonage y selecciona tu proyecto.
2. En la configuración del proyecto, selecciona el códec de vídeo preferido a nivel de proyecto.
3. Aplique los ajustes necesarios para activar las preferencias de códecs a nivel del SDK.

Visión general

La API del códec de vídeo preferido por el editor permite a cada editor declarar su propia prioridad de códec, independientemente del códec preferido a nivel de proyecto configurado en la aplicación Panel de Vonage. Puede proporcionar una lista ordenada explícita de códecs o delegar la decisión en el SDK en modo automático.

Utilice esta API cuando la configuración a nivel de proyecto no sea lo suficientemente específica para sus necesidades. Los escenarios comunes incluyen:

• Sesiones mixtas. Los distintos editores de una misma sesión se benefician de códecs diferentes. Con las preferencias por editor, cada dispositivo puede expresar el orden de códecs que más le convenga.

• Editores con funciones específicas. Un editor de pantalla compartida puede beneficiarse de VP9, mientras que un editor de cámara en la misma sesión prefiere VP8 por su mayor compatibilidad.

• Dejar que el SDK decida. Si no desea codificar una lista, el modo automático delega la elección en el SDK.

Si todos los editores de su aplicación deben utilizar el mismo códec, y la configuración a nivel de proyecto ya refleja esa elección, no necesita esta API.

VP8 es un códec de implementación obligatoria compatible con todos los terminales. Dado que todos los códecs compatibles se añaden automáticamente como fallbacks, VP8 siempre está disponible como el último fallback incluso si no lo incluyes explícitamente en tu lista.

Para obtener más información sobre los códecs VP8, H.264 y VP9, las tablas de cobertura de códecs y la configuración del códec preferido a nivel de proyecto, consulte la página Códecs de vídeo guía.

Elegir un modo

Automático

Pasar la cadena 'automatic' (Web, React Native) o llamar al método de fábrica correspondiente en los SDK nativos. El SDK evalúa el entorno local y determina un orden de prioridad de códecs adecuado.

Utilice el modo automático cuando:

• Quiere que el SDK se adapte a diferentes navegadores y dispositivos sin mantener su propia lógica por dispositivo.
• Prefiere un enfoque compatible con el futuro. El modo automático incorporará una heurística de selección más sofisticada en futuras versiones del SDK, por lo que las aplicaciones que lo adopten hoy se beneficiarán de las mejoras sin cambios en el código.

Manual

Proporciona una matriz ordenada de códecs. El primer elemento tiene la prioridad más alta:

['vp9', 'vp8']          prefer VP9, fall back to VP8, then remaining codecs
['h264']                 prefer H.264; remaining codecs (VP8, VP9) are appended automatically as fallbacks
['vp8', 'h264', 'vp9']  explicit full ordering: VP8 first, then H.264, then VP9

Utilice el modo manual cuando sepa exactamente qué orden de códec es el mejor para un editor o dispositivo determinado. Este ajuste anula el códec preferido a nivel de proyecto configurado en el panel.

Por defecto

Si no establece preferredVideoCodecs el editor utiliza el códec preferido a nivel de proyecto configurado en el panel de control. Este es el mismo comportamiento que antes de que existiera esta API.

Comparación

Pedidos de códecs recomendados para situaciones habituales

Cuando se utiliza el modo manual, el orden de los códecs depende del tipo de sesión, el público y el caso de uso. En la tabla siguiente se enumeran los escenarios más habituales con una preferredVideoCodecs y el razonamiento en que se basa.

Cómo funciona la negociación de códecs

Establecer un códec preferido no no garantiza que se utilizará el códec. El códec final se determina mediante un proceso de negociación que depende del tipo de sesión.

Sesiones enrutadas (enrutador de medios)

En un sesión enrutadael editor negocia con el enrutador de medios:

1. El editor envía una oferta SDP con los códecs ordenados según la preferencia (el códec preferido aparece en primer lugar).
2. El Media Router considera la oferta y selecciona un códec compatible.
3. Si se admite el códec preferido, se utiliza. De lo contrario, el Media Router pasa al siguiente códec de la oferta.

Dado que el Media Router gestiona la distribución de medios, todos los abonados de una sesión enrutada reciben vídeo codificado con el mismo códec que el editor haya negociado.

Sesiones retransmitidas (peer-to-peer)

En un sesión retransmitidaNo hay Media Router. Cada par editor-suscriptor negocia de forma independiente:

1. El editor envía una oferta SDP con los códecs ordenados por preferencia.
2. El abonado responde con una respuesta SDP que enumera los códecs que admite.
3. La pareja selecciona el códec de mayor prioridad que admitan ambos extremos.

Esto significa que distintos pares de abonados en la misma sesión retransmitida podrían acabar utilizando distintos códecs, en función de las capacidades de cada abonado.

¿Qué puede provocar un retroceso?

Un "fallback" significa que no se ha utilizado el códec preferido y que, en su lugar, se ha seleccionado otro códec para la publicación. Esto puede ocurrir cuando:

• El extremo remoto (en sesiones retransmitidas) o el enrutador de medios (en sesiones enrutadas) no admiten el códec preferido.
• El navegador o dispositivo no admite la codificación con el códec preferido (por ejemplo, H.264 en algunos dispositivos Android, VP9 en versiones antiguas de Safari).

Dado que pueden producirse retrocesos, verifique siempre el códec en uso en lugar de asumir que se ha respetado la preferencia. Conocer el códec activo te ayudará:

• Depurar y controlar la calidad. Registra qué códec está en uso para diagnósticos y análisis de calidad a través de Insights.
• Adaptar en tiempo de ejecución. Ajuste la resolución o la tasa de bits en función de los puntos fuertes del códec negociado (por ejemplo, VP9 puede lograr la misma calidad a una tasa de bits inferior que VP8).
• Garantizar la coherencia de la sesión. Confirme que todos los editores de una sesión utilizan el códec esperado, especialmente en sesiones enrutadas en las que el Media Router distribuye un único códec por editor a todos los abonados.

Véase Verificación del códec en uso para obtener instrucciones específicas de la plataforma.

Establecer preferencias por plataforma

SDK web

export type VideoCodec = 'vp8' | 'vp9' | 'h264';
export type PreferredVideoCodecs = 'automatic' | [VideoCodec, ...VideoCodec[]];

// Automatic mode
const publisher = OT.initPublisher('publisherContainer', {
  preferredVideoCodecs: 'automatic'
});

// Manual mode
const publisher = OT.initPublisher('publisherContainer', {
  preferredVideoCodecs: ['vp9', 'vp8']
});

// Default (uses project-level preferred codec)
const publisher = OT.initPublisher('publisherContainer', {});

Si se pasa una matriz vacía o una cadena de códecs no válida, el editor falla con un mensaje OT_INVALID_PARAMETER error.

SDK para iOS

// Automatic mode
OTVideoCodecPreference *pref = [OTVideoCodecPreference automatic];
OTPublisherKitSettings *settings = [[OTPublisherKitSettings alloc] init];
settings.videoCodecPreference = pref;
OTPublisherKit *publisher = [[OTPublisherKit alloc] initWithDelegate:self
                                                            settings:settings];

// Manual mode
OTVideoCodecPreference *pref = [OTVideoCodecPreference manualWithCodecs:@[
    @(OTVideoCodecTypeVP9),
    @(OTVideoCodecTypeH264),
    @(OTVideoCodecTypeVP8)
]];
OTPublisherKitSettings *settings = [[OTPublisherKitSettings alloc] init];
settings.videoCodecPreference = pref;

SDK para Android

// Automatic mode
PublisherKit.PreferredVideoCodecs preferredVideoCodecs =
    PublisherKit.PreferredVideoCodecs.automatic();

Publisher publisher = new Publisher.Builder(context)
    .preferredVideoCodecs(preferredVideoCodecs)
    .build();

// Manual mode
PublisherKit.PreferredVideoCodecs preferredVideoCodecs =
    PublisherKit.PreferredVideoCodecs.manual(
        new ArrayList<PublisherKit.PreferredVideoCodecs.Codec>(
            List.of(PublisherKit.PreferredVideoCodecs.Codec.VP9,
                    PublisherKit.PreferredVideoCodecs.Codec.H264)));

Publisher publisher = new Publisher.Builder(context)
    .preferredVideoCodecs(preferredVideoCodecs)
    .build();

Pasar un null o lista vacía a manual() lanza IllegalArgumentException.

SDK para Windows

// Automatic mode
builder.PreferredVideoCodecs = PreferredVideoCodecs.Automatic();

// Manual mode
builder.PreferredVideoCodecs = new PreferredVideoCodecs(
    new List<PreferredVideoCodecs.Codec> {
        PreferredVideoCodecs.Codec.VP9,
        PreferredVideoCodecs.Codec.H264,
        PreferredVideoCodecs.Codec.VP8
    });

// Default (uses project-level setting)
builder.PreferredVideoCodecs = null;

Si se pasa una lista vacía, se lanza ArgumentException.

SDK para Linux

// Automatic mode
otc_publisher_settings* settings = otc_publisher_settings_new();
otc_publisher_settings_set_preferred_video_codecs_automatic(settings);

otc_publisher_callbacks callbacks = {0};
struct otc_publisher* publisher =
    otc_publisher_new_with_settings(&callbacks, settings);
otc_publisher_settings_delete(settings);

// Manual mode
otc_publisher_settings* settings = otc_publisher_settings_new();

otc_video_codec_type codecs[] = {
    OTC_VIDEO_CODEC_VP9,
    OTC_VIDEO_CODEC_H264,
    OTC_VIDEO_CODEC_VP8
};

otc_publisher_settings_set_preferred_video_codecs(
    settings, codecs, sizeof(codecs) / sizeof(codecs[0]));

otc_publisher_callbacks callbacks = {0};
struct otc_publisher* publisher =
    otc_publisher_new_with_settings(&callbacks, settings);
otc_publisher_settings_delete(settings);

SDK de React Native

// Automatic mode
<OTPublisher properties={{ preferredVideoCodecs: 'automatic' }} />

// Manual mode
<OTPublisher properties={{ preferredVideoCodecs: ['vp9', 'vp8'] }} />

Verificación del códec en uso

Después de que un editor inicie la transmisión, utilice las API de estadísticas del SDK para confirmar qué códec se negoció realmente. No dé por sentado que se ha respetado la preferencia.

Comprobación de los códecs compatibles antes de publicar

Puede comprobar proactivamente qué códecs admite un cliente antes de establecer una preferencia.

SDK web:

const supportedCodecs = await OT.getSupportedCodecs();
console.log('Encoders:', supportedCodecs.videoEncoders);
console.log('Decoders:', supportedCodecs.videoDecoders);

SDK para Android:

MediaUtils.SupportedCodecs supported =
    MediaUtils.SupportedCodecs.getSupportedCodecs(context);
Log.d("Codecs", "Encoders: " + supported.videoEncoders);
Log.d("Codecs", "Decoders: " + supported.videoDecoders);

SDK para Linux:

otc_media_utils_codecs* supported_codecs = NULL;
otc_status status = otc_media_utils_get_supported_codecs(&supported_codecs);
if (status == OTC_SUCCESS) {
  for (size_t i = 0; i < supported_codecs->number_encoder_video_codecs; i++) {
    printf("Encoder: %d\n", supported_codecs->encoder_video_codecs[i]);
  }
  for (size_t i = 0; i < supported_codecs->number_decoder_video_codecs; i++) {
    printf("Decoder: %d\n", supported_codecs->decoder_video_codecs[i]);
  }
  otc_media_utils_codecs_delete(supported_codecs);
}

Lectura del códec activo en las estadísticas del SDK

SDK web

Editorial:

setInterval(() => {
  publisher.getStats((error, statsArray) => {
    if (error) return;
    statsArray.forEach(({ stats }) => {
      if (stats.video && stats.video.layers) {
        stats.video.layers.forEach((layer) => {
          console.log('Publisher video codec:', layer.codec);
        });
      }
    });
  });
}, 5000);

Abonado:

setInterval(() => {
  subscriber.getStats((error, stats) => {
    if (error) return;
    if (stats.video) {
      console.log('Subscriber video codec:', stats.video.codec);
    }
  });
}, 5000);

Para obtener información sobre WebRTC de nivel inferior, utilice getRtcStatsReport():

publisher.getRtcStatsReport()
  .then(statsArray => {
    // Each entry contains a standard RTCStatsReport.
    // Look for type "codec" entries with mimeType.
    statsArray.forEach(console.log);
  });

SDK para Android

publisher.setNetworkStatsListener(new PublisherKit.NetworkStatsListener() {
    @Override
    public void onVideoStats(PublisherKit publisher,
                             PublisherKit.PublisherVideoStats[] statsArray) {
        if (statsArray != null && statsArray.length > 0) {
            for (PublisherKit.VideoLayerStats layer : statsArray[0].videoLayers) {
                Log.d("Codec", "Publisher codec: " + layer.codec);
            }
        }
    }
});

SDK para iOS

- (void)publisher:(OTPublisherKit *)publisher
videoNetworkStatsUpdated:(NSArray<OTPublisherKitVideoNetworkStats *> *)statsArray {
    OTPublisherKitVideoNetworkStats *stats = statsArray.firstObject;
    for (OTPublisherKitVideoLayerStats *layer in stats.videoLayers) {
        NSLog(@"Publisher codec: %@", layer.codec ?: @"unknown");
    }
}

SDK de React Native

// Publisher
OTPublisher.getRtcStatsReport();

// Subscriber
OTSubscriber.getRtcStatsReport(streamId);

Uso de Insights y Video Inspector

La herramienta Inspector de vídeo muestra el códec, la resolución y la frecuencia de imagen en el módulo Métricas de calidad. Pase el ratón sobre cualquier punto de una línea trazada para ver el códec en uso en ese momento.

También puede filtrar las estadísticas de flujo por códec en Perspectivas Consultas GraphQL:

Buenas prácticas

1. Tenga en cuenta el tipo de sesión. En las sesiones enrutadas, todos los abonados comparten un códec por editor. En las sesiones retransmitidas, cada par negocia de forma independiente, por lo que un mismo editor podría utilizar distintos códecs con distintos abonados.

2. Alinear los ajustes por editor y a nivel de proyecto. El códec preferido a nivel de proyecto se sigue aplicando a los editores que no establecen su propia preferencia. Asegúrese de que ambos niveles son coherentes para evitar sorpresas.

3. Compruebe la compatibilidad de códecs en el cliente. Antes de establecer una preferencia manual, utilice OT.getSupportedCodecs() (Web) o MediaUtils.SupportedCodecs (Android) para confirmar que el códec preferido está disponible localmente.

4. Comience con el modo automático. A menos que tenga un requisito específico de códec, utilice el modo automático y deje que el SDK elija. Las futuras versiones del SDK perfeccionarán la heurística de selección automática, y tu aplicación se beneficiará sin cambios en el código.

5. Verify the negotiated codec. Utilice getStats() o getRtcStatsReport() para confirmar el códec una vez iniciada la publicación.

6. Pruebas en todos los dispositivos de destino. La compatibilidad de los códecs varía según los navegadores y las plataformas. Consulte el tablas de cobertura de códecs para más detalles. Pruebe su configuración de preferencias en los dispositivos que utilizan realmente sus usuarios.