Conector de vídeo

Vonage Video Connector te permite participar mediante programación en sesiones de la Video API de Vonage como participante del lado del servidor. Te permite conectarte a sesiones de vídeo, publicar y suscribirte a transmisiones, y procesar datos de audio y vídeo en tiempo real.

La biblioteca se encarga de la conectividad WebRTC, el procesamiento de medios y la gestión de sesiones de forma automática, lo que le permite centrarse en la creación de la lógica de su aplicación. en crear la lógica de su aplicación. El audio se transmite como datos PCM lineales de 16 bits, y el vídeo como fotogramas de 8 bits en formatos YUV420P, RGB24 o ARGB32. en formatos YUV420P, RGB24 o ARGB32, todo ello con frecuencias de muestreo, resoluciones y configuraciones de canal configurables.

En esta página se describen los conceptos y el comportamiento comunes a todas las bibliotecas de Video Connector. Para obtener instrucciones de instalación, firmas de API y ejemplos de código, consulta la guía correspondiente a tu lenguaje de programación.

Elige tu biblioteca

Ambas bibliotecas ofrecen las mismas funcionalidades y se basan en la misma implementación nativa. Se diferencian en las convenciones de nomenclatura y en la forma en que se exponen las operaciones asíncronas: la biblioteca de Python utiliza callbacks de finalización, mientras que la biblioteca de Node.js devuelve promesas. Las guías de los lenguajes describen estas diferencias con detalle.

Este tema incluye las siguientes secciones:

• Cómo funciona
• Requisitos
• Conceptos fundamentales
• Formatos multimedia
• Configuración de la sesión
• Medios de comunicación
• Suscripción a flujos
• Gestión de la memoria intermedia
• Modelo de eventos
• Límites

Cómo funciona

El Video Connector se une a una sesión como un participante habitual de WebRTC. Desde el punto de vista de los demás participantes, es indistinguible de un navegador o un cliente móvil: tiene su propia conexión, puede emitir un flujo y puede suscribirse a los flujos de los demás.

La diferencia radica en que los datos multimedia se intercambian con el código de tu aplicación, en lugar de con una cámara, un micrófono o una pantalla. Envías fotogramas de audio y vídeo sin procesar al conector para publicarlos, y recibes audio y vídeo sin procesar de las transmisiones a las que te suscribes. Esto hace que el conector sea adecuado para cargas de trabajo del lado del servidor, tales como:

• Agentes de IA de voz y vídeo en tiempo real
• Transcripción, traducción y subtitulado en directo
• Registro, archivo y captura para el cumplimiento normativo
• Visión artificial y moderación de contenidos
• Tratamiento de efectos de audio y vídeo

El ciclo de vida habitual es el siguiente:

1. Conéctate a una sesión utilizando tu ID de aplicación, tu ID de sesión y un token.
2. Publica un flujo y, a continuación, envía fotogramas de audio y/o vídeo a dicho flujo.
3. Suscríbete a las transmisiones de otros participantes a medida que vayan llegando y procesa los archivos multimedia que recibas.
4. Darte de baja, eliminar la publicación y desconectarte cuando hayas terminado.

Requisitos

Video Connector se distribuye como una biblioteca nativa con binarios precompilados. Se ejecuta en Linux en x86_64 (AMD64) y ARM64 sólo.

Recomendamos Debian Bookworm, ya que es la distribución en la que el conector se ha probado más a fondo.

Conceptos fundamentales

Video Connector utiliza un pequeño conjunto de objetos para representar sesiones, participantes, transmisiones y contenidos multimedia. Es fundamental comprenderlos para poder trabajar de forma eficaz con cualquiera de las dos bibliotecas.

Sesión

Una sesión de la Video API de Vonage a la que se conectan los clientes. La sesión se identifica mediante su ID y se transmite a los controladores de eventos a nivel de sesión, lo que permite identificar qué sesión ha desencadenado un evento.

Conexión

La conexión de un participante a una sesión. Cada participante, incluido el propio conector, tiene exactamente una conexión. Una conexión transporta:

• Un identificador único
• Una marca de tiempo de creación
• Los datos de conexión, que están codificados en el token utilizado para conectarse

Los datos de conexión resultan útiles para almacenar metadatos personalizados sobre los participantes, como los identificadores de usuario o los roles.

Transmisión

Una transmisión multimedia (audio, vídeo o ambos) publicada por un participante. Cada transmisión tiene un identificador único y una referencia a la conexión que la ha publicado. Se te notifican las transmisiones a medida que los participantes comienzan a publicarlas, y son a las que te suscribes para recibir contenido multimedia.

Editorial

Tu propio flujo publicado en la sesión. Hay como máximo un editor por instancia de conector. El editor mantiene una referencia al flujo que ha creado, que es como te ven los demás participantes.

Suscriptor

Una suscripción a la transmisión de otro participante. Se crea un suscriptor por cada transmisión de la que se deseen recibir contenidos multimedia, y cada suscriptor contiene una referencia a la transmisión a la que está suscrito. Los contenidos multimedia y los eventos de subtítulos se envían junto con el suscriptor que los ha generado, por lo que se puede saber de qué participante proceden los datos.

Cómo se relacionan

Session
├── Connection (multiple participants)
│   └── Stream (participant's published media)
│       ├── Publisher (your published stream)
│       └── Subscriber (your subscription to their stream)
├── Audio data (flowing through streams)
└── Video frames (flowing through streams)

Formatos multimedia

Audio

El audio siempre se transmite como PCM lineal, enteros con signo de 16 bits. Un fotograma de audio equivale a una muestra por canal, por lo que un búfer debe contener al menos (número de fotogramas × número de canales) muestras.

• Tasas de muestreo: 8000, 12000, 16000, 24000, 32000, 44100 o 48000 Hz
• Canales: 1 (mono) o 2 (estéreo)
• Tamaño del marco: normalmente en bloques de 20 ms, aunque esto varía en función de la frecuencia de muestreo

La frecuencia de muestreo y el número de canales se pueden configurar de forma independiente para el audio que publicas y el audio mezclado que recibes. Consulta Configuración de la sesión.

Vídeo

El vídeo se comparte como Valores sin signo de 8 bits en uno de estos tres formatos de píxeles:

• Resoluciones: hasta 1920 x 1080 (2 073 600 píxeles en total)
• Frecuencia de imagen: de 1 a 30 FPS

Configuración de la sesión

El audio para la publicación frente al audio para la suscripción

El conector te permite configurar dos formatos de audio independientes:

• Audio del editor define el formato de los datos de audio que se proporcionan al publicar. El audio que se envíe debe coincidir con esta frecuencia de muestreo y este número de canales.
• Mezcla de audio de los suscriptores define el formato del audio mezclado que recibes de todas las transmisiones a las que estás suscrito. La biblioteca se encarga de mezclar a varios participantes y de realizar el remuestreo o la conversión de canales para adaptarlos al formato que hayas solicitado.

Esta separación te permite optimizar la configuración según tu caso de uso. Por ejemplo:

• Publica en estéreo para obtener un resultado de alta calidad y, al mismo tiempo, recibe una mezcla en mono para simplificar el procesamiento
• Transmite a 16 kHz para voz y recibe a 48 kHz para una reproducción de alta fidelidad
• Utiliza diferentes velocidades en cada lado para adaptarte a los requisitos de un proceso de procesamiento de audio

Resolución y frecuencia de fotogramas recomendadas para los suscriptores

Al suscribirse a transmisiones enrutadas que utilizan la emisión simultánea, la SFU (unidad de reenvío selectivo) de la Video API de Vonage puede enviar diferentes niveles de calidad del vídeo. La configuración del suscriptor te permite solicitar un nivel específico:

• Resolución preferida solicita una capa espacial. El SFU envía la capa que más se ajusta a la solicitud.
• Frecuencia de fotogramas recomendada solicita una capa temporal. La SFU envía la capa que más se ajusta a la solicitud.

Estas preferencias ayudan a optimizar el ancho de banda y el procesamiento por parte del abonado, ya que permiten solicitar únicamente el nivel de calidad que se necesita, en lugar de recibir siempre la máxima calidad disponible.

Migración de sesiones

Se puede activar la migración de sesión para que el conector se migre automáticamente en caso de rotación de la SFU. Está desactivada por defecto.

Tala de árboles

El nivel de detalle de los mensajes de registro de la consola se puede configurar en cinco niveles: ERROR, WARN, INFO, DEBUGy TRACE.

Medios de comunicación

Un servidor de publicación debe publicar contenido de audio, vídeo o ambos. Configurar un servidor de publicación sin ninguno de los dos constituye un error.

Esperando a que el audio esté listo

Continuidad del audio

Cuando publicas contenido de audio, la biblioteca mantiene una transmisión continua en tu nombre:

Primera publicación. La biblioteca envía silencio (tramas rellenadas con ceros) hasta que facilites tus primeros datos de audio. Esto hace que la transmisión esté disponible de inmediato para los suscriptores, sin tener que esperar a que tu aplicación genere audio.

Tolerancia al silencio. Si se interrumpe temporalmente la transmisión de audio, la biblioteca tolera breves interrupciones dejando de enviar paquetes de audio por completo. Esta histéresis evita el envío de paquetes de silencio innecesarios durante retrasos momentáneos en el procesamiento.

Silencio explícito. Una vez finalizado el periodo de tolerancia, si no hay audio nuevo disponible, la biblioteca pasa a enviar tramas de silencio explícito. De este modo se mantiene la transmisión, al tiempo que se indica que no se está proporcionando ningún audio activo.

Vaciado del búfer. Si se proporciona una cantidad de audio inferior a la correspondiente a un periodo completo, la biblioteca vacía los datos restantes y los rellena con silencio para mantener la sincronización correcta y evitar la deriva del audio.

Continuidad del vídeo

Cuando publicas un vídeo, la biblioteca se encarga de mantener la continuidad de los fotogramas por ti:

Primera publicación. La biblioteca envía fotogramas negros hasta que se proporciona el primer fotograma, de modo que la transmisión está disponible de inmediato para los suscriptores.

Repetición del último fotograma. Si dejas de enviar fotogramas, la biblioteca repite el último fotograma que has enviado durante un máximo de 2 segundos, lo que garantiza una reproducción fluida para los suscriptores.

Opción alternativa con marco negro. Tras 2 segundos de repetición, la biblioteca pasa a mostrar fotogramas en negro. Esto indica a los suscriptores que ya no se está transmitiendo el vídeo de forma activa, al tiempo que se mantiene activa la transmisión.

Buenas prácticas

• Envía los datos multimedia a intervalos regulares que se ajusten a la frecuencia de muestreo y la frecuencia de fotogramas que hayas configurado.
• Supervisa las estadísticas del búfer para asegurarte de que estás proporcionando suficientes datos
• Gestiona el evento de agotamiento del búfer para detectar cuándo se agotan los búferes multimedia.
• Adapta tu estrategia de generación de contenidos multimedia a las diferentes cargas de procesamiento

Suscripción a flujos

Cuando un participante empieza a publicar, se activa un evento de recepción de flujo y tú decides si deseas suscribirte. Los contenidos multimedia de tus suscripciones se distribuyen a través de tres canales distintos.

Vídeo se transmite por cada flujo. Cada fotograma llega acompañado de la información del suscriptor que identifica su origen, por lo que puedes procesar el vídeo de cada participante de forma independiente —para la gestión de la disposición, la grabación por flujo o la aplicación de efectos por flujo—.

Audio mixto se transmite como un único flujo a nivel de sesión. La biblioteca mezcla automáticamente el audio de todos los flujos a los que se está suscrito en un único flujo, en el formato que hayas configurado para la mezcla del suscriptor. No es posible distinguir a los participantes individuales en este audio mezclado.

Audio individual Se transmite por flujo, a nivel de suscriptor. El audio llega en el formato recibido del flujo —PCM lineal de 16 bits— y ni la frecuencia de muestreo ni el número de canales pueden configurarse antes de la recepción.

Leyendas se envían por cada flujo. Cada evento de subtítulo incluye el identificador del suscriptor que identifica el flujo de origen, el texto del subtítulo y si el resultado es definitivo o provisional:

• Provisional Los resultados son parciales y pueden actualizarse a medida que se procesen más datos de voz. Útil para la visualización en directo.
• Final Los resultados son definitivos y no cambiarán. Utilízalos para su almacenamiento o para su procesamiento posterior.

Gestión de la memoria intermedia

El conector mantiene búferes internos para el audio y el vídeo que publicas. Puedes consultar la cantidad de contenido multimedia en cola en cualquier momento y vaciar ambos búferes cuando necesites descartar el contenido pendiente; por ejemplo, cuando interrumpas a un bot en mitad de una expresión oral.

Eventos de vaciado del búfer

Un evento de agotamiento del búfer se activa cuando se agota un búfer interno de audio o vídeo. Esto ocurre cuando el contenido multimedia se transmite a la sesión a un ritmo más rápido del que tu aplicación es capaz de suministrar. Considera este evento como una señal para aumentar tu ritmo de producción de contenido multimedia o ajustar tu estrategia de publicación.

El evento aplica histéresis para evitar una activación excesiva: tras un vaciado inicial, no se activará de nuevo hasta que el búfer se haya rellenado con nuevos contenidos y, posteriormente, se vuelva a vaciar. Esto evita una avalancha de notificaciones repetidas mientras el búfer permanezca vacío.

Modelo de eventos

Ambas bibliotecas exponen el mismo conjunto de eventos, agrupados según el objeto al que pertenecen.

La forma en que se muestran estos eventos varía según el lenguaje. En Python, cada evento es una función de devolución de llamada que se registra. En Node.js, los eventos de ciclo de vida de una sola ejecución —conexión de sesión, creación de un flujo de editor y conexión de suscriptor— son consumidos por la promesa devuelta por el método correspondiente, y el resto de eventos son funciones de devolución de llamada. Consulta las guías de cada lenguaje para obtener más detalles.

Límites