Una Video API más inteligente y segura

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 está construida en torno a un conjunto de funciones inteligentes y complementarias para adaptar continuamente la sesión a las condiciones cambiantes, y esas funciones están organizadas en tres capas, cada una dirigida a un nivel diferente de la pila:

  • 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 negocian los clientes individuales con el Media Router. Estos ajustes se aplican una vez por cliente, pero puede haber varios clientes dentro del mismo dispositivo de usuario final.
  • A nivel de arroyo: Controles de calidad por flujo: códec, resolución, velocidad de bits y más. Pueden ajustarse independientemente para cada editor y abonado.

Los componentes 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.

Bajo el capó: la pila 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 tarifas

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)

Los flujos de audio intentan negociar Opus FEC por defecto. El códec Opus incrusta una copia de menor calidad de cada fotograma de audio dentro de la trama de audio. siguiente trama. Si la primera trama se pierde en tránsito, el receptor la reconstruye a partir de la copia del paquete siguiente, a costa de una pequeña sobrecarga de ancho de banda. Esto es especialmente eficaz en caso de pérdida aleatoria de paquetes, como ocurre en las redes móviles o Wi-Fi 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 del SDK de su elección 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 función 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 de cifrado de extremo a extremo para más detalles.

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 topológico

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 medios: Enrutado frente a retransmitido

La decisión topológica más fundamental 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 programadas: 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, utilice siempre una sesión enrutada. Consulte la Creación de una guía de sesión.

Enrutamiento adaptable de medios

En las sesiones enrutadas (a partir de SDK v2.24.7+ para Web y v2.27.0+ para nativa), la plataforma utiliza automáticamente enrutamiento adaptable de medios para optimizar el tráfico entre los participantes. Cuando los editores sólo tienen un abonado y no hay activada ninguna función de enrutamiento exclusivo (archivo, transmisión en directo, SIP, etc.), los medios se enrutan directamente entre editores y abonados, sin declarar una sesión de retransmisión por adelantado. En cuanto un editor tiene más de un abonado, o se activa una función de enrutamiento exclusivo, el enrutador de medios asume el enrutamiento sin problemas. Por ejemplo, en casos de uso conversacional (todos los participantes publican y se suscriben al mismo tiempo) sin funciones de sólo enrutamiento, en cuanto se incorpore el tercer participante, la sesión se trasladará sin problemas 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 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 nube nunca es estática. Los servidores se parchean, se amplían y se reducen, y se sustituyen. Sin la migración de sesión, la rotación de servidores obliga a todos los participantes a desconectarse y volver a conectarse, lo que puede resultar molesto cuando la sesión dura más de 8 horas. Con la migración de sesión activada (SDK v2.30.0+), la transición es invisible: los flujos continúan, no se producen eventos de reconexión y el audio/vídeo existente no se interrumpe.

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 habilitarlo: Pase sessionMigration: true en las opciones de inicialización de sesión de cada cliente. Por defecto, es false. Ver el Guía de rotación de servidores y migración de sesiones para conocer la sintaxis completa específica del SDK, activarlo manualmente y para obtener más detalles sobre el manejo de la devolución de llamada de notificación de sesión.

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 reconexión automática, un breve contratiempo en la red obligaría al usuario a reincorporarse manualmente a la sesión. Con la reconexión automática, el SDK gestiona la recuperación de forma transparente. Los flujos a los que se estaba suscrito se pausarán y 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 se puede 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 durante la desconexión temporal se ponen en cola y se entregan una vez restablecida la conexión. Consulte la sección Unirse a una guía de sesión para ver ejemplos completos y nombres de eventos específicos del SDK.

Estrategias de conexión entre iguales

Las funciones de nivel de conexión entre pares rigen cómo se estructuran las conexiones WebRTC de un cliente con el enrutador de medios y qué códecs negocian. Estos ajustes se aplican una vez por cliente (no por flujo) y tienen un amplio efecto sobre el consumo de recursos y la compatibilidad.

Conexión entre pares única (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 adicional añade sobrecarga: candidatos ICE separados, apretones de manos DTLS y estado del socket a nivel de 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. SPC reduce esto a una conexión, lo que disminuye el consumo de recursos y permite sesiones más largas en clientes móviles nativos.

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

Cómo habilitarlo: El SPC está desactivado por defecto. Configure singlePeerConnection: true al inicializar la sesión. Para el SDK web, páselo como una propiedad en el archivo OT.initSession() objeto opciones. Para otros SDK:

  • Android: Session.Builder.setSinglePeerConnection(true)
  • iOS: OTSessionSettings.singlePeerConnection = YES
  • Ventanas: 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: Active SPC siempre que tenga más de un puñado de abonados en una sesión enrutada, especialmente en plataformas móviles. Las ventajas aumentan con el número de flujos.

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 afecta a la calidad a una tasa de bits determinada, al uso de la CPU, a la disponibilidad de aceleración por hardware y a la compatibilidad con vídeo escalable. VP8 es el más seguro por defecto: universalmente soportado, acelerado por hardware en la mayoría de las plataformas y compatible con vídeo escalable. VP9 ofrece mejor calidad con la misma tasa de bits, pero con un mayor coste de CPU. H.264 se beneficia de los codificadores de hardware en iOS y algunos dispositivos Android, reduciendo el consumo de batería, pero no es compatible con 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: Véase 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 Media Router puede acceder a los medios sin cifrar (lo que es necesario para funciones como el archivado, la transcodificación y la selección escalable de la capa de vídeo). E2EE impide que el Media Router acceda al contenido multimedia, lo que es necesario para casos de uso en los que debe mantenerse una estricta privacidad de los datos de extremo a extremo.

Limitaciones importantes: Cuando E2EE está activado, las funciones que requieren descodificación de medios en el enrutador de medios no están disponibles: archivado, emisiones de streaming en directo, Experience Composer, Audio Connector e interconexión SIP. Asegúrese de tener en cuenta estas limitaciones antes de activar E2EE.

Cómo habilitarlo: E2EE es una función adicional que primero debe estar habilitada para tu cuenta de Vonage Video. Una vez habilitada, crea la sesión con e2ee: true utilizando la API de Video API de Vonage del lado del servidor, y establecer el secreto de cifrado al inicializar la sesión en el cliente:

vonage.video.createSession({ mediaMode: "routed", e2ee: true });

Todos los participantes en la sesión deben utilizar el mismo secreto de cifrado para recibir medios inteligibles. El secreto puede rotarse sobre la marcha una vez conectada la sesión. Ver el Guía de cifrado de extremo a extremo para obtener instrucciones completas de configuración y ejemplos específicos del SDK.

Controles de calidad en los arroyos

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 editor codifica varias capas espaciales y temporales del mismo flujo. Cada abonado recibe la capa que se ajusta a su ancho de banda disponible y a sus requisitos de visualización, sin que el editor envíe flujos duplicados 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: Para los flujos de pantalla compartida, active explícitamente el vídeo escalable cuando desee que el Media Router los reduzca para los abonados con un ancho de banda inferior. Consulte la Guía de vídeo escalable.

Preajustes 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 techo, no un suelo.

No utilices preajustes de bitrate para compartir pantalla. Los codificadores de pantalla compartida funcionan de forma diferente; aplicar un límite de velocidad de bits a una pantalla compartida puede producir una salida borrosa y con baja velocidad de fotogramas sin el esperado ahorro de ancho de banda. Véase la Guía de tasas de bits máximas del editor.

Controles de resolución y velocidad 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.

Ajuste de la resolución y la velocidad 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
});

Inicialice siempre el editor en el máximo resolución y velocidad de fotogramas que puedas necesitar (el SDK sólo puede reducir a partir del valor inicial, no aumentarlo más allá).

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:

  • Responder a qualityLimitationReason: "cpu" de las estadísticas del editor: reducir la velocidad de fotogramas para aliviar la presión 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): Para los flujos de pantalla compartida, establezca la sugerencia de contenido para guiar 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 Publicar un flujo - 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).

Relación con el contenido Sugerencia: Sugerencias 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. Cuando se establece 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:

Consulte las guías de publicación específicas de cada plataforma para ver ejemplos completos: Android, iOS, iOS (Swift), Linux, Windows.

Resolución y frecuencia de imagen preferidas por el abonado

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

En "auto" se recomienda en la mayoría de los casos: el SDK web deriva automáticamente obtiene automáticamente la resolución preferida del tamaño renderizado del elemento de y solicita la capa de vídeo escalable más adecuada. Tenga en cuenta que "auto" es sensible al diseño. Si su aplicación cambia con frecuencia el tamaño de los mosaicos de abonado (por ejemplo, conmutación de altavoz activo, flujos pin/unpin o transiciones animadas), el SDK puede actualizar repetidamente la resolución preferida. actualizar repetidamente la resolución preferida. Esto puede provocar y ciclos de "aumento/disminución" del ancho de banda en el enrutador de medios, lo que puede aumentar la rotación de la red y reducir la estabilidad visual. Para diseños diseños muy dinámicos, considere la posibilidad de preferredResolution (y actualización sólo cuando la interfaz de usuario se asiente), o cambios en la resolución del límite de velocidad 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 la guía de calidad.

Audio Fallback

Para qué sirve: Cuando la red de un editor o abonado ya no puede mantener el vídeo, el SDK desactiva automáticamente el vídeo para ese flujo, manteniendo vivo el audio, 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: Activado por la propia evaluación de red del cliente de publicación. Cuando las métricas de congestión del editor muestran que el vídeo es insostenible, el editor desactiva su pista de vídeo. Disponible tanto en sesiones retransmitidas como 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 de audio fallback.

Control y observabilidad

La capa de supervisión abarca las tres capas de la pila y proporciona visibilidad de la calidad a todos los niveles, desde la topología de la infraestructura hasta las métricas de flujo individuales.

Control de calidad y observabilidad de los clientes

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 visibilidad de lo que ocurre en cada punto final, no se puede distinguir "la red del usuario es mala" de "el dispositivo del usuario está sobrecargado". Las estadísticas permiten a tu aplicación tomar decisiones inteligentes: avisar al usuario antes de que la calidad se degrade aún más, ajustar los diseños o activar acciones basadas en políticas.

Capacidades clave:

  • API estadística de alto nivel: Métricas agregadas por editor o por suscriptor, normalizadas a través de las transiciones de conexión entre pares. Utilícelo para la supervisión de la producción y la UX adaptable.
  • 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 estándar del sector de 1 a 5 (sólo web). Intégrelo con su pila de observabilidad para realizar un seguimiento de las tendencias de 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 (sólo web). Responde desactivando funciones que consumen mucha 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 estimar el MOS y comprobar la publicabilidad de audio/vídeo 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.

Lecturas complementarias