Una Video API más inteligente y segura

Acerca de las funciones inteligentes de la Video API de Vonage.

El vídeo en tiempo real puede ser todo un reto. Los participantes se conectan desde diferentes dispositivos, en diferentes redes y en diferentes partes del mundo. Las condiciones cambian en medio de la llamada: un dispositivo móvil puede cambiar de Wi-Fi a datos celulares (por ejemplo, de 5G a 4G), un cortafuegos corporativo puede bloquear ciertas rutas UDP y un portátil de gama baja puede tener problemas con la carga de la CPU.

La Video API de Vonage se basa en un conjunto de funciones inteligentes y complementarias que permiten adaptar continuamente la sesión a las condiciones cambiantes, y dichas funciones se organizan en tres capas, cada una de las cuales aborda un nivel diferente de la pila:

  • A nivel de topología: Infraestructura de sesión, optimizaciones de enrutamiento y ciclo de vida del servidor. Afectan a todos los participantes en una sesión y no requieren configuración por flujo.
  • Nivel de conexión entre pares: Cómo se conectan y se comunican los clientes individuales con el Media Router. Estos ajustes se aplican una vez por cliente, aunque puede haber varios clientes en un mismo dispositivo de usuario final.
  • A nivel de flujo: Controles de calidad por flujo: códec, resolución, velocidad de bits y más. Pueden ajustarse independientemente para cada editor y abonado.

Este tema incluye las siguientes secciones:

Los elementos básicos

Las funciones se organizan en tres capas concéntricas. Las capas exteriores afectan a todos los participantes; las interiores pueden ajustarse por flujo.

╔══════════════════════════════════════════════════════════════════════╗
║  TOPOLOGY LAYER                                                      ║
║  Routed vs. Relayed · Adaptive media routing · Media Mesh            ║
║  Session migration                                                   ║
║  ┌──────────────────────────────────────────────────────────────┐    ║
║  │  PEER-CONNECTION LAYER                                       │    ║
║  │  Single peer connection (SPC) · Codec negotiation            │    ║
║  │  ┌────────────────────────────────────────────────────┐      │    ║
║  │  │  STREAM LAYER                                      │      │    ║
║  │  │  Scalable video · Bitrate presets                  │      │    ║
║  │  │  Publisher resolution/frame rate                   │      │    ║
║  │  │  Subscriber preferred resolution/frame rate        │      │    ║
║  │  │  Audio fallback · FEC / NACK / DTX                 │      │    ║
║  │  └────────────────────────────────────────────────────┘      │    ║
║  └──────────────────────────────────────────────────────────────┘    ║
║  Monitoring: client observability · sender-side stats · MOS          ║
╚══════════════════════════════════════════════════════════════════════╝

La capa de supervisión abarca las tres, proporcionando visibilidad de la calidad a todos los niveles.

Entre bastidores: la pila de WebRTC

Muchas de las garantías de fiabilidad proceden de funciones integradas en la pila WebRTC que no requieren ninguna llamada explícita a la API. Comprenderlas ayuda a razonar sobre el comportamiento de la calidad y a utilizar las API de nivel superior de forma más eficaz.

Control de congestión y adaptación de la velocidad de transmisión

Las implementaciones de WebRTC utilizan Google Congestion Control (GCC) por defecto. GCC sondea continuamente el ancho de banda disponible, calcula el cuello de botella actual y envía señales al codificador para que aumente o reduzca su tasa de bits objetivo. Este es el mecanismo principal que mantiene viva una sesión a través de la congestión transitoria. Cualquier configuración de Video API de Vonage que afecte la tasa de bits actúa como una techo sobre GCC, y GCC sigue adaptándose dinámicamente por debajo de ese techo.

Corrección de errores hacia delante (FEC)

Las transmisiones de audio intentan negociar el FEC de Opus de forma predeterminada. El códec Opus incorpora una copia de menor calidad de cada trama de audio dentro del siguiente trama. Si la primera trama se pierde durante la transmisión, el receptor la reconstruye a partir de la copia que figura en el paquete siguiente, lo que supone una pequeña sobrecarga de ancho de banda. Esto resulta especialmente eficaz en caso de pérdida aleatoria de paquetes, como la que se produce en redes Wi-Fi o móviles congestionadas.

Para vídeo, todos los códecs soportan RTP RED FEC cuando se negocia. FEC es transparente para su aplicación, añadiendo redundancia al flujo de medios, lo que permite al receptor recuperar paquetes perdidos o dañados sin necesidad de retransmisión. Para más información, puede leer el RFC 8854.

NACK y RTX (Retransmisión)

Cuando se pierde un paquete de vídeo, el receptor envía un ACK negativo (NACK) para solicitar la retransmisión. NACK/RTX añade una latencia proporcional al tiempo de ida y vuelta (normalmente entre 50 y 200 ms).

Transmisión discontinua (DTX)

Opus DTX detecta el silencio en el micrófono y deja de enviar paquetes de audio durante los periodos de silencio, reduciendo el ancho de banda de audio casi a cero. Puedes activar DTX a través de la enableDtx configuración del SDK que elijas al inicializar el editor.

DTLS-SRTP y protocolo de transporte seguro en tiempo real

Todos los medios se cifran por defecto mediante DTLS-SRTP. La negociación de las claves de cifrado se produce como parte del protocolo WebRTC, antes de que fluya cualquier medio. Para mayor seguridad, se utiliza la clave AES-256 funcionalidad adicional proporciona un cifrado de 256 bits. Estos métodos de cifrado de la capa de transporte (DTLS-SRTP y AES-256) funcionan junto con la función opcional de cifrado de extremo a extremo (E2EE), que añade una capa adicional de cifrado a nivel de aplicación. Consulte la Guía sobre el cifrado de extremo a extremo Para más información.

ICE y TURN

El establecimiento de conectividad interactivo (ICE) prueba varias rutas entre los extremos (UDP directo, STUN-reflexivo, retransmisión TURN) y elige la mejor. Si la mejor ruta cambia en mitad de la llamada (algo habitual cuando un dispositivo móvil cambia de red), ICE puede reiniciarse y encontrar una nueva ruta sin interrumpir la llamada. Para las sesiones que atraviesan cortafuegos restrictivos, véase la sección Guía de servidores TURN configurables y el Guía de redes restringidas.

Optimizaciones a nivel de topología

Las características a nivel de topología determinan la infraestructura a través de los cuales fluyen los medios de comunicación. Se establecen al crear una sesión o conectarse a ella, y afectan a todos los participantes por igual. Una topología correcta es la base sobre la que se construye todo lo demás.

Modo de transmisión: por ruta frente a por retransmisión

La decisión más fundamental en materia de topología es modo multimedia.

  • Sesiones retransmitidas: Los clientes intentan enviar flujos de audio y vídeo directamente entre sí (peer-to-peer), recurriendo a la retransmisión TURN si un cortafuegos bloquea la ruta directa. Las sesiones retransmitidas tienen una latencia más baja para grupos pequeños, pero no pueden utilizar vídeo escalable, fallback de audio de abonado, conexión entre pares única o estadísticas del lado del emisor.
  • Sesiones enrutadas: Los medios fluyen a través del router de medios de vídeo de Vonage. Esto desbloquea toda la pila de funciones inteligentes: vídeo escalable, fallback de audio del suscriptor, Single Peer Connection (SPC), estadísticas del lado del emisor, emisiones en directo, archivado, interconexión SIP y mucho más.

Para sesiones con tres o más participantes, utiliza siempre una sesión enrutada. Consulta la Creación de una guía de sesión.

Enrutamiento de medios adaptable

En las sesiones enrutadas (a partir de la versión 2.24.7 del SDK para web y 2.27.0 para aplicaciones nativas), la plataforma utiliza automáticamente enrutamiento adaptable de medios para optimizar el tráfico entre los participantes. Cuando los emisores solo tienen un suscriptor y no hay activadas funciones exclusivas de enrutamiento (archivo, retransmisión en directo, SIP, etc.), los datos multimedia se enrutan directamente entre los emisores y los suscriptores, sin necesidad de declarar previamente una sesión de retransmisión. En cuanto un emisor tiene más de un suscriptor, o se activa una función exclusiva del enrutador, el enrutador de medios se hace cargo del enrutamiento de forma transparente. A modo de ejemplo, en casos de uso conversacionales (en los que todos los participantes publican y se suscriben al mismo tiempo) sin funciones exclusivas del enrutador, en cuanto se incorpore un tercer participante, la sesión se trasladará de forma transparente al enrutador de medios.

Esto significa que, en la práctica, se puede declarar una sesión enrutada para todos los casos y seguir obteniendo una latencia cercana al retardo para las llamadas 1:1. El enrutamiento adaptable de medios está activado por defecto y no requiere configuración. Consulte la página Creación de una guía de sesión.

Malla de medios

La plataforma utiliza Malla de medios para conectar automáticamente a cada participante al centro de datos del Media Router más cercano (puede comprobar aquí la lista de todos los centros de datos disponibles). Para una sesión distribuida geográficamente (por ejemplo, participantes en Nueva York, Fráncfort y Sídney), Media Mesh garantiza que cada cliente enruta los medios a través de su servidor regional más cercano en lugar de atravesar un único centro de datos potencialmente distante. El resultado es una latencia más baja y una mejor calidad para todos los participantes, especialmente en grandes sesiones internacionales.

La malla multimedia está activada por defecto y no requiere configuración. Si necesitas más control sobre dónde se enrutan los medios, tienes dos opciones de personalización:

  • Sugerencia de ubicación (mejor esfuerzo): puede proporcionar un centro de datos de señalización preferido como sugerencia. La plataforma intentará utilizar la ubicación solicitada siempre que sea posible, pero no está garantizado y puede recurrir a otro centro de datos en función de la disponibilidad, la capacidad u otras consideraciones operativas. Consulte la sección Creación de una guía de sesión para más información.

  • Zona regional de medios (forzada): si debe mantener el enrutamiento de medios dentro de una región específica (por requisitos de residencia o cumplimiento de datos), configure una Zona regional de medios. Esta configuración es forzada: la señalización y los medios se enrutarán a través de la zona seleccionada en lugar de elegir automáticamente el centro de datos más cercano. Puede consultar documentación adicional en la página Guía de las zonas regionales de medios de comunicación.

Migración de sesiones

Para qué sirve: Transfiere de forma transparente a todos los participantes de una sesión a un nuevo servidor Media Router cuando se produce una rotación de servidor planificada, sin desconectar a nadie. No se requiere ninguna gestión por parte de la aplicación (es decir, las aplicaciones no necesitan implementar su propia lógica de transferencia/reconexión; la plataforma lo hace por ellas).

Por qué es importante: La infraestructura en la nube nunca es estática. Los servidores reciben parches, se amplían o reducen y se sustituyen. Sin la migración de sesiones, una rotación de servidores obliga a todos los participantes a desconectarse y volver a conectarse, lo que puede resultar una experiencia molesta cuando la sesión supera las 8 horas. Con la migración de sesiones activada (SDK v2.30.0+), la transición es imperceptible: las transmisiones continúan, no se activan eventos de reconexión y el audio y el vídeo existentes no se interrumpen.

Lo que aún requiere un reinicio: Las grabaciones (archivos), las retransmisiones de flujo continuo en directo y las instancias de Experience Composer finalizan cuando se migra una sesión y deben reiniciarse mediante la devolución de llamada de notificación de sesión. Archivos automáticos reiniciarse automáticamente.

Cómo activarlo: Pase sessionMigration: true en las opciones de inicialización de sesión de cada cliente. Por defecto, es false. Consulta el Guía sobre la rotación de servidores y la migración de sesiones para obtener una visión general, y el Migración de sesiones: Guía de instalación y configuración para ver la sintaxis completa específica del SDK, ejemplos de API y detalles sobre el manejo de la devolución de llamada de notificación de sesión.

Llamadas de aviso por interrupciones del servicio

Para qué sirve: Cuando se produce una interrupción imprevista del servicio, la plataforma envía una llamada de respuesta al servidor de tu aplicación con la información pertinente. Esto permite que tu aplicación reinicie cualquier función que no pueda seguir funcionando durante una interrupción (archivos, retransmisiones en directo, instancias de Experience Composer).

Por qué es importante: Sin una función de devolución de llamada, tu aplicación no tendría forma de saber que un archivo o una emisión ha finalizado y que debe reiniciarse.

Cómo funciona: Cuando se produce una interrupción del servicio, la plataforma envía una solicitud HTTP POST a la URL de devolución de llamada que hayas configurado, con una carga útil en formato JSON que describe el evento. A continuación, tu aplicación puede tomar las medidas oportunas, como reiniciar un archivo o una emisión. Consulta la Guía de llamadas de aviso en caso de interrupción del servicio para consultar los pasos detallados de recuperación de cada servicio.

Reconexión automática

Para qué sirve: Cuando un cliente pierde inesperadamente la conexión a una sesión, el SDK intenta reconectarse automáticamente sin necesidad de código de aplicación.

Por qué es importante: Sin la reconexión automática, un breve fallo en la red obligaría al usuario a volver a conectarse manualmente a la sesión. Con la reconexión automática, el SDK se encarga de la recuperación de forma transparente. Las transmisiones a las que se estaba suscrito se pausarán y se reanudarán automáticamente cuando se restablezca la conexión.

Cómo funciona: No es necesaria ninguna configuración. Cuando se interrumpe la conexión y el cliente intenta volver a conectarse:

  • El objeto «Session» envía un sessionReconnecting evento.
  • Si se restablece la conexión, el objeto Session envía un comando sessionReconnected evento.
  • Si no es posible restablecer la conexión, el cliente se desconecta de la sesión y el sessionDisconnected se dispara.

Opcionalmente, su aplicación puede escuchar estos eventos para mostrar indicadores de estado al usuario:

session.on({
  sessionReconnecting: function() {
    // Display a "reconnecting..." indicator
  },
  sessionReconnected: function() {
    // Hide the indicator
  },
  sessionDisconnected: function() {
    // Handle permanent disconnection
  }
});

Las señales enviadas mientras la conexión está temporalmente interrumpida se almacenan en cola y se transmiten una vez restablecida la conexión. Consulta el Cómo conectarse a una guía de sesión para ver ejemplos completos y nombres de eventos específicos del SDK.

Estrategias a nivel de conexión entre pares

Las características a nivel de conexión entre pares determinan cómo se estructuran las conexiones WebRTC de un cliente con el Media Router y qué códecs se negocian. Estos ajustes se aplican una vez por cliente (no por flujo) y tienen un amplio impacto en el consumo de recursos y la compatibilidad.

Conexión con un único par (SPC)

Para qué sirve: Agrupa todos los flujos de abonados de un cliente en una única conexión WebRTC peer con el enrutador de medios, en lugar de una conexión por flujo.

Por qué es importante: Cada conexión entre pares adicional supone una sobrecarga: candidatos ICE independientes, protocolos de establecimiento de conexión DTLS y estado de los sockets a nivel del sistema operativo. En un dispositivo móvil suscrito a diez flujos, diez conexiones entre pares pueden sobrecargar el dispositivo y consumir una cantidad significativa de energía. El SPC reduce esto a una sola conexión, lo que disminuye el consumo de recursos y permite sesiones más amplias en clientes móviles nativos.

Ventaja adicional: control de la velocidad: Con una sola conexión, el controlador de congestión de WebRTC detecta todos los flujos entrantes como un único paquete y puede tomar decisiones de adaptación de velocidad mejor fundamentadas. En el modelo de conexiones múltiples, cada conexión realiza pruebas y se adapta de forma independiente, lo que puede provocar oscilaciones y un reparto subóptimo del ancho de banda.

Cómo activarlo: El SPC está desactivado por defecto. Configure singlePeerConnection: true al inicializar la sesión. En el caso del SDK web, pásalo como propiedad en el OT.initSession() objeto de opciones. Para otros SDK:

  • Android: Session.Builder.setSinglePeerConnection(true)
  • iOS: OTSessionSettings.singlePeerConnection = YES
  • Windows: SinglePeerConnection propiedad en Session.Builder
  • Linux/macOS: otc_session_settings_set_single_peer_connection()
  • React Native: enableSinglePeerConnection en la OTSession options puntal

Véase el Creación de una guía de sesión para ver ejemplos completos.

Cuándo utilizarlo: Activa SPC siempre que tengas más de unos pocos suscriptores en una sesión enrutada, sobre todo en plataformas móviles. Las ventajas aumentan a medida que crece el número de transmisiones.

Selección de códecs

Para qué sirve: Selecciona el códec de vídeo utilizado entre cada par editor-suscriptor.

Por qué es importante: La elección del códec influye en la calidad a una tasa de bits determinada, en el uso de la CPU, en la disponibilidad de aceleración por hardware y en la compatibilidad con el vídeo escalable. VP8 es la opción predeterminada más segura: es compatible con todos los dispositivos, cuenta con aceleración por hardware en la mayoría de las plataformas y es compatible con el vídeo escalable. VP9 ofrece mejor calidad con la misma tasa de bits, pero a costa de un mayor consumo de CPU. H.264 se beneficia de los codificadores de hardware en iOS y en algunos dispositivos Android, lo que reduce el consumo de batería, pero no es compatible con el vídeo escalable.

Cómo funciona automáticamente: La plataforma de Vonage negocia el códec para cada par de editor-suscriptor, respetando la preferencia a nivel de proyecto y volviendo a VP8 si el códec preferido no es compatible con ambos extremos.

Cuándo intervenir: Consulta el Guía de códecs de vídeo para los criterios de decisión completos, el Guía de vídeo escalable VP9 para el comportamiento específico de VP9, y el API de preferencias de códecs del SDK para anular por editor.

Cifrado de extremo a extremo (E2EE)

Para qué sirve: Cifra las cargas útiles multimedia en el cliente para que permanezcan cifradas en todo el router multimedia y sólo puedan ser descifradas por otros participantes en la misma sesión. Esto proporciona una capa de cifrado adicional sobre el cifrado de transporte DTLS-SRTP estándar.

Por qué es importante: En las sesiones enrutadas estándar, el enrutador multimedia puede acceder a contenidos multimedia sin cifrar (lo cual es necesario para funciones como el archivado, la transcodificación y la selección de capas de vídeo escalables). El cifrado de extremo a extremo (E2EE) impide que el enrutador multimedia acceda al contenido multimedia, lo cual es necesario para casos de uso en los que debe mantenerse una estricta privacidad de los datos de extremo a extremo.

Limitaciones importantes: Cuando el cifrado de extremo a extremo (E2EE) está activado, las funciones que requieren la decodificación de contenidos multimedia en el Media Router no están disponibles: archivado, retransmisiones en directo, Experience Composer, Audio Connector e interconectividad SIP. Asegúrate de tener en cuenta estas limitaciones antes de activar el E2EE.

Cómo activarlo: E2EE es una función adicional que primero debes activar en tu Account de Vonage Video. Una vez activada, configura e2ee: true al crear la sesión a través de la API REST del lado del servidor, y configurar la clave de cifrado al inicializar la sesión en el cliente:

opentok.createSession({ mediaMode: 'routed', e2ee: true }, callback);

Todos los participantes en la sesión deben utilizar la misma clave de cifrado para recibir datos multimedia inteligibles. La clave se puede cambiar sobre la marcha una vez establecida la sesión. Consulte el Guía sobre el cifrado de extremo a extremo para consultar las instrucciones completas de configuración y los ejemplos específicos del SDK.

Controles de calidad a nivel de flujo

Las funciones a nivel de flujo son las más granulares disponibles. Pueden configurarse independientemente para cada editor y abonado, y muchas pueden cambiarse dinámicamente en mitad de la llamada. Esta es la capa en la que la aplicación participa activamente en la gestión de la calidad.

Vídeo escalable

Para qué sirve: El emisor codifica varias capas espaciales y temporales de la misma transmisión. Cada suscriptor recibe la capa que se ajusta a su ancho de banda disponible y a sus requisitos de visualización, sin que el emisor tenga que enviar transmisiones duplicadas a resolución completa.

Por qué es importante: En una sesión con diez abonados, enviar diez flujos full-HD independientes desde el editor es un despilfarro, mientras que adaptar un único flujo al abonado con más limitaciones dista mucho de ser óptimo. El vídeo escalable envía un flujo con varias capas de calidad; el enrutador de medios selecciona y reenvía la capa adecuada a cada abonado. Cuando la red de un abonado se degrada, el enrutador de medios reduce su capa en tiempo real, mientras que el editor no se ve afectado y continúa transmitiendo todas sus capas para que el enrutador de medios tome la decisión.

Cómo funciona automáticamente: En las sesiones enrutadas con más de dos participantes, el enrutador de medios habilita automáticamente el vídeo escalable (el Auto configuración del proyecto). El SDK de cada editor negocia la estructura de escalabilidad (VP8 simulcast utiliza capas L1T1/L2T1/L3T1; VP9 SVC puede utilizar también capas espaciales).

Cuándo intervenir: En el caso de las transmisiones con pantalla compartida, activa explícitamente el vídeo escalable cuando quieras que Media Router reduzca la resolución para los suscriptores con menor ancho de banda. Consulta el Guía de vídeo escalable.

Configuraciones predefinidas de velocidad de bits y velocidad de bits máxima del editor

Para qué sirve: Le permite limitar la tasa de bits máxima que utiliza un editor para el vídeo de la cámara, utilizando preajustes con nombre (DEFAULT, BW_SAVER, EXTRA_BW_SAVER) o valores brutos.

Por qué es importante: En una conexión con contador o congestionada, un editor sin restricciones competirá por el ancho de banda con todas las demás aplicaciones del dispositivo. Establecer un preajuste más bajo reduce su huella de vídeo, dejando más espacio para otras aplicaciones en el mismo dispositivo. Fundamentalmente, cuando se utiliza VP8 con vídeo escalable activado, el preajuste también controla qué capas de codificación están activas, por lo que BW_SAVER limita efectivamente el flujo a dos capas espaciales (baja y media), y EXTRA_BW_SAVER lo limita a uno (bajo).

Interacción con el control de la tasa: Google Congestion Control (GCC) sigue adaptándose dinámicamente por debajo del límite preestablecido. Configuración de BW_SAVER es un límite máximo, no un mínimo.

No utilices los ajustes predefinidos de velocidad de bits para compartir pantalla. Los codificadores de pantalla compartida funcionan de manera diferente; aplicar un límite de velocidad de bits a una pantalla compartida puede dar lugar a una salida borrosa y con una baja frecuencia de fotogramas, sin el ahorro de ancho de banda esperado. Consulta el Guía de tasas de bits máximas del editor.

Controles de resolución y frecuencia de fotogramas del editor

Además de las tasas de bits predefinidas, puede controlar directamente la resolución y la frecuencia de imagen con las que un editor codifica el vídeo. Existen dos métodos: establecerlos en el momento de la publicación o ajustarlos dinámicamente una vez iniciada la publicación.

Configuración de la resolución y la frecuencia de fotogramas en el momento de la publicación (Web SDK):

const publisher = OT.initPublisher(targetElement, {
  resolution: '1280x720', // '1920x1080', '1280x720', '640x480', '320x240'
  frameRate: 15,          // 30, 15, 7, or 1
});

Inicializa siempre el editor en el máximo la resolución y la frecuencia de fotogramas que puedas necesitar (el SDK solo puede reducir el valor inicial, no aumentarlo por encima de ese valor).

Ajuste dinámico de la resolución y la frecuencia de imagen (SDK web):

Una vez iniciada la publicación, puede cambiar la resolución y la frecuencia de imagen preferidas por el editor sin reiniciar el flujo:

// Reduce resolution
await publisher.setPreferredResolution({ width: 320, height: 180 });

// Reduce frame rate
await publisher.setPreferredFrameRate(7);

Escenarios habituales en los que ayuda el ajuste dinámico:

  • En respuesta a qualityLimitationReason: "cpu" Según las estadísticas del editor: reducir la frecuencia de fotogramas para aliviar la carga de la CPU.
  • Respuesta a una caída repentina del ancho de banda antes de que se active el audio fallback.

Sugerencias de contenido de vídeo (Web SDK): En el caso de las transmisiones con pantalla compartida, configura la sugerencia de contenido para orientar la estrategia de codificación del navegador:

publisher.setVideoContentHint("text");    // Prioritises sharp text/static content
publisher.setVideoContentHint("motion");  // Prioritises smooth motion (default camera behaviour)
publisher.setVideoContentHint("detail");  // Prioritises fine detail at lower frame rates

Véase el Guía de restricciones de vídeo para editores y el Publicación de una transmisión — Guía web.

Preferencia de degradación de vídeo del editor

Para qué sirve: Controla el modo en que el motor de vídeo prioriza entre reducir la resolución y reducir la frecuencia de imagen cuando el ancho de banda o los recursos de la CPU son limitados.

Por qué es importante: Cuando la red o el dispositivo no pueden mantener la calidad de vídeo actual, el codificador debe degradar algo. Por defecto, el motor de vídeo decide de forma autónoma. La preferencia de degradación te permite expresar la prioridad de tu aplicación: por ejemplo, una sesión de pantalla compartida se beneficia de mantener la resolución (el texto nítido importa más que el movimiento suave), mientras que una cámara se beneficia de mantener la frecuencia de imagen (el movimiento suave es más natural que las imágenes fijas en bloque).

Sugerencia sobre la relación con el contenido: Consejos sobre contenidos de vídeo y la preferencia de degradación sirven a propósitos diferentes pero relacionados. Indicación de contenido describe el tipo de contenido que se transmite (por ejemplo, "text" (para compartir pantalla), mientras que la preferencia de degradación controla explícitamente la estrategia de codificación. Al establecer una sugerencia de contenido, el motor de vídeo selecciona automáticamente una preferencia de degradación adecuada; por ejemplo, "text" selecciona automáticamente para mantener la resolución. Una preferencia de degradación establecida explícitamente anula la selección automática de Content Hint.

Relación con el vídeo escalable: Cuando el vídeo escalable está activo, el motor de vídeo puede decidir eliminar una capa temporal o espacial en lugar de degradar la resolución del flujo restante. La preferencia de degradación sigue aplicándose como guía dentro de las capas activas.

API específicas del SDK:

Consulta las guías de audio y vídeo específicas para cada plataforma para ver ejemplos completos: Android, iOS, iOS (Swift), Linux, Windows.

Resolución y frecuencia de fotogramas preferidas por el suscriptor

Al suscribirse a un flujo de vídeo escalable, puede indicar al enrutador de medios qué capa de calidad debe entregar a cada suscriptor. Esta es la herramienta principal para construir diseños adaptables. Por ejemplo, una gran parrilla de conferencia en la que las miniaturas deberían recibir una capa de baja resolución y el orador activo debería recibir la resolución completa.

Configuración de la resolución preferida en el momento de la suscripción (Web SDK):

session.subscribe(stream, targetElement, {
  preferredResolution: 'auto', // Recommended: SDK picks the layer based on element size
  // Or specify explicitly:
  // preferredResolution: { width: 320, height: 240 },
  // preferredFrameRate: 7,
});

El "auto" Se recomienda esta configuración en la mayoría de los casos: el SDK web deduce automáticamente la resolución preferida a partir de la tamaño final del elemento de vídeo del suscriptor y solicita la capa de vídeo escalable más adecuada. Ten en cuenta que "auto" depende del diseño. Si tu aplicación cambia con frecuencia el tamaño de los mosaicos de los suscriptores (por ejemplo, al cambiar de interlocutor activo, en los flujos de fijar/desfijar, en los rediseños adaptativos de la cuadrícula o en las transiciones animadas), el SDK podría actualizar repetidamente la resolución preferida. Esto puede provocar cambios de capa más frecuentes y ciclos de «aumento/disminución» del ancho de banda en el Media Router, lo que puede aumentar la fluctuación de la red y reducir la estabilidad visual. Para diseños muy dinámicos, considera establecer un valor explícito preferredResolution (y actualizarla solo cuando la interfaz de usuario se estabilice), o limitar la frecuencia de los cambios de resolución para evitar oscilaciones rápidas.

Ajuste dinámico tras la suscripción:

// Downgrade a tile when moving it to a thumbnail position
subscriber.setPreferredResolution({ width: 320, height: 240 });
subscriber.setPreferredFrameRate(7);

// Upgrade when the subscriber becomes the active speaker
subscriber.setPreferredResolution({ width: 1280, height: 720 });
subscriber.setPreferredFrameRate(30);

Restricción de la velocidad de fotogramas (Web SDK): subscriber.restrictFrameRate(true) limita el abonado a un fotograma por segundo o menos. Puede ser útil para los participantes no activos en grandes sesiones para ahorrar CPU y ancho de banda sin dejar de mostrar un mosaico de "presencia". Llamada restrictFrameRate(false) para restablecer la frecuencia de imagen normal.

Para obtener información sobre las API entre SDK, consulte la página Guía de vídeo escalable y el Suscribirse a un canal — Guía web.

Alternativa de audio

Para qué sirve: Cuando la red de un editor o de un suscriptor ya no puede soportar la transmisión de vídeo, el SDK desactiva automáticamente el vídeo de esa transmisión, manteniendo el audio activo, y lo vuelve a activar cuando las condiciones mejoran.

Por qué es importante: Un fotograma de vídeo congelado es discordante; un flujo de audio interrumpido rompe por completo la conversación. El audio fallback garantiza que, cuando se agote el ancho de banda, los participantes puedan seguir oyéndose. Combinado con Opus FEC y DTX, el audio sigue siendo inteligible incluso a velocidades de bits muy bajas.

Dos modos complementarios:

  • Retorno de audio del editor: Se activa a raíz de la evaluación de la red realizada por el propio cliente de publicación. Cuando los indicadores de congestión del editor indican que la transmisión de vídeo es insostenible, el editor desactiva su pista de vídeo. Disponible tanto en sesiones retransmitidas como en sesiones enrutadas.
  • Repetición de audio del abonado: Activado por el Media Router en nombre de un abonado específico. Sólo el abonado afectado pierde el vídeo; los demás abonados siguen recibiéndolo. Disponible sólo en sesiones enrutadas.

Ambas funciones se activan automáticamente. Para más información, consulte el Guía sobre soluciones alternativas de audio.

Supervisión y observabilidad

La capa de supervisión abarca las tres capas de la pila, lo que proporciona visibilidad sobre la calidad en todos los niveles, desde la topología de la infraestructura hasta las métricas de cada flujo individual.

Control de calidad y observabilidad del cliente

Para qué sirve: La API de observabilidad del cliente proporciona un flujo continuo de estadísticas por flujo -pérdida de paquetes, velocidad de bits, frecuencia de imagen, resolución descodificada, recuento de congelaciones, etc.- tanto para editores como para abonados. El SDK web proporciona además una puntuación media de opinión (MOS) para vídeo, que es una puntuación de calidad que simula la escala de puntuación MOS de audio, y un control del rendimiento de la CPU.

Por qué es importante: Sin información sobre lo que ocurre en cada terminal, no es posible distinguir entre «la red del usuario funciona mal» y «el dispositivo del usuario está sobrecargado». Las estadísticas permiten que tu aplicación tome decisiones inteligentes: advertir al usuario antes de que la calidad se deteriore aún más, ajustar los diseños o activar acciones basadas en políticas.

Capacidades clave:

  • API de estadísticas de alto nivel: Métricas agregadas por editor o por suscriptor, normalizadas en función de las transiciones entre conexiones entre pares. Utilízalas para la supervisión en entorno de producción y una experiencia de usuario adaptativa.
  • La calidad del vídeo cambió eventos: Se activa cuando cambia la calidad con un código de motivo (ancho de banda, CPU, cambio de códec, cambio de resolución). Utilícelos para controlar el estado de la interfaz de usuario sin sondeo.
  • Puntuación media de opinión (MOS): Una puntuación de calidad del 1 al 5, según el estándar del sector (solo en la web). Intégrala en tu pila de observabilidad para realizar un seguimiento de las tendencias de la calidad de las llamadas a lo largo del tiempo.
  • Supervisión del rendimiento de la CPU: Detecta la sobrecarga de la CPU del dispositivo antes de que provoque la pérdida de fotogramas (solo en la web). Responde desactivando funciones que consumen muchos recursos de la CPU, como el desenfoque de fondo.
  • Pruebas previas a la llamada: Utilice el botón Biblioteca de prueba de la red de vídeo de Vonage para calcular el MOS y comprobar si el audio y el vídeo se pueden publicar antes de que el usuario se una a una sesión.

Véase el Guía de observabilidad del cliente para consultar la referencia estadística completa y ejemplos de código específicos del SDK.

Para más información: