Restricciones de vídeo: Ajuste de la resolución y la frecuencia de imagen preferidas

Vonage Video API permite a los editores optimizar las transmisiones de video al establecer restricciones preferidas en la resolución de video y la velocidad de cuadros. Estas restricciones ayudan a administrar el uso del ancho de banda, adaptarse a las capacidades de los dispositivos y ofrecer una experiencia de usuario personalizada a los suscriptores.

Esta guía explica cómo utilizar el preferredResolution y preferredFrameRate API para editores.

Visión general

Al publicar una transmisión de video, es posible que desees ajustar dinámicamente la calidad del video por varias razones: ahorro de ancho de banda, alineación con los requisitos de la interfaz de usuario o restricción del consumo de recursos para ciertos roles de suscriptor (como miniaturas o pantallas con poco movimiento). El editor API de Vonage expone métodos que te permiten ajustar la resolución y la frecuencia de cuadros preferidas para tus pistas de video. Estas restricciones se aplican en el dispositivo de entrada de video mediante API WebRTC estándar para obtener resultados óptimos, pero en última instancia influyen en lo que recibirán todos los suscriptores.

Control de la resolución y la frecuencia de fotogramas del vídeo

El editor puede especificarlo:

• Resolución preferida: La anchura y la altura deseadas (en píxeles) para el flujo de vídeo.
• Frecuencia de fotogramas recomendada: El número deseado de fotogramas por segundo (fps) para el flujo de vídeo.

Puedes controlarlos de forma dinámica mediante los siguientes métodos después de Se inicializa el editor:

// Set preferred resolution (width x height)
await publisher.setPreferredResolution({ width: 640, height: 360 });

// Set preferred frame rate
await publisher.setPreferredFrameRate(15);

Configuración de la resolución preferida

Método: publisher.setPreferredResolution(preferredResolution)

• preferredResolution es un objeto con width y height propiedades (ambas son números enteros positivos, expresados en píxeles).
• La resolución no puede ser superior a la resolución de publicación inicial. Por ejemplo, si has publicado a 640×480, no puedes establecer una resolución superior a esa.

Uso habitual:

publisher.setPreferredResolution({ width: 320, height: 240 });

Validaciones:

• Debe invocarse en un editor que esté capturando vídeo (publishVideo: true).
• Ambos width y height deben ser números enteros positivos.
• La resolución no puede ser mayor que la resolución de publicación inicial.

Casos de error:

• Lanza si se llama en un editor de sólo audio o si los valores de entrada no son válidos.

Configuración de la frecuencia de fotogramas preferida

Método: publisher.setPreferredFrameRate(frameRate)

• frameRate Debe ser un número entero mayor o igual que 1.

Uso habitual:

publisher.setPreferredFrameRate(15);

Validaciones:

• Debe llamarse en un editor con una pista de vídeo activa.
• La frecuencia de fotogramas debe ser un número entero válido ≥ 1.

Casos de error:

• Lanza una excepción si se invoca en un editor de solo audio o si el valor de frameRate no es válido.

Buenas prácticas

• Si conoce de antemano la resolución y la frecuencia de imagen ideales, defínalas al crear el editor mediante OT.initPublisher() (por ejemplo, a través de resolution y frameRate). Para los abonados, puede omitir estos ajustes o utilizar preferredResolution: 'auto' al llamar a Session.subscribe().
• Utilice las API de abonado (subscriber.setPreferredResolution() / subscriber.setPreferredFrameRate()) para modificar la forma en que un único suscriptor recibe, decodifica o reproduce un flujo. Esto solo afecta a ese suscriptor y no modifica lo que envía el editor ni lo que reciben los demás suscriptores.
• Utilice las API de publicación (publisher.setPreferredResolution() / publisher.setPreferredFrameRate()) para cambiar lo que envía el Editor. Esto afecta a todos los suscriptores de ese flujo, que recibirán automáticamente la configuración actualizada. Si lo desea, puede reducir la resolución del editor utilizando la función preferredResolution en varios casos, por ejemplo:
  • Cuando observes que el dispositivo editor tiene dificultades, ya sea por limitaciones de la CPU o por problemas de red, y quieras aliviar la carga más rápidamente de lo que lo haría normalmente la pila WebRTC.
  • Si el dispositivo se está quedando sin batería y quieres minimizar el consumo para prolongar la duración de la llamada.
  • Cuando inicias el uso compartido de pantalla o pones en marcha emisores adicionales desde el mismo dispositivo y necesitas liberar recursos informáticos para esas actividades.
• La resolución y la frecuencia de fotogramas preferidas por el Publisher nunca pueden superar los valores especificados al inicializarlo. Inicializa el Publisher con la resolución y la frecuencia de fotogramas máximas que puedas necesitar y, a continuación, redúcelas o auméntalas dinámicamente dentro de esos límites, en función de tu caso de uso.
• Elige las velocidades de fotogramas adecuadas para el contenido; por ejemplo:
  • 5 fps para diapositivas estáticas, cuadros de mando, pantallas con muy poco movimiento o un uso mínimo del ancho de banda.
  • 15 fps para pantallas con poco movimiento o situaciones en las que el ancho de banda es un factor importante
  • 30 fps para vídeo a cámara completa o requisitos de alta calidad
• Las condiciones de la red pueden impedir que el SDK mantenga la resolución y la velocidad de fotogramas que hayas elegido. Considera los valores preferidos como objetivos: si el ancho de banda o la CPU se ven limitados, el SDK puede reducir automáticamente la calidad del vídeo publicado o suscrito (por ejemplo, una preferencia de 1080p puede bajar temporalmente a una resolución inferior cuando las condiciones de la red sean deficientes).
• Actualmente, la resolución y la frecuencia de imagen preferidas sólo están disponibles en el SDK de JavaScript. No hay plazos para añadir esta función a otros SDK.

Notas adicionales

• Las restricciones que establezcas influyen en todos los suscriptores a tu transmisión, no solo a la interfaz de usuario local.
• La red y el backend determinarán en última instancia la calidad de vídeo real suministrada, en función del estado actual de la conexión y del ancho de banda disponible.
• Estas API sólo están disponibles utilizando el SDK de JavaScript; otros SDK no admiten cambios dinámicos de restricciones de vídeo por el momento.

Recursos adicionales

• Flujos de publicación
• Documentos de referencia del editor
• Restricciones de WebRTC MediaTrack