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 de vídeo y la frecuencia de imagen

El editor puede especificarlo:

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

Puede controlarlas dinámicamente 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 (ambos enteros positivos, en píxeles).
• La resolución no puede ser mayor que la resolución de publicación inicial. Por ejemplo, si publicaste a 640×480, no puedes establecer una resolución mayor que esa.

Uso típico:

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

Ajuste de la frecuencia de imagen preferida

Método: publisher.setPreferredFrameRate(frameRate)

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

Uso típico:

publisher.setPreferredFrameRate(15);

Validaciones:

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

Casos de error:

• Lanza si se llama en un editor de sólo audio o si 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 cambiar la forma en que un único abonado recibe/decodifica/reproduce un flujo. Esto sólo afecta a ese suscriptor, y no cambia lo que el Editor envía o lo que otros suscriptores reciben.
• 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 note que el dispositivo del editor tiene dificultades, ya sea por limitaciones de la CPU o problemas de red, y quiera aliviar la tensión 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 la compartición de pantalla o inicias editores adicionales desde el mismo dispositivo y necesitas liberar recursos computacionales para esas actividades.
• La resolución/velocidad de fotogramas preferida por el editor nunca puede superar los valores especificados al inicializar el editor. Inicialice el editor con la resolución y la frecuencia de imagen máximas que pueda necesitar y, a continuación, redúzcalas o auméntelas dinámicamente dentro de esos límites en función de su caso de uso.
• Elija frecuencias de imagen adecuadas al 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 escenarios sensibles al ancho de banda
  • 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 su resolución y frecuencia de imagen preferidas. Trate los valores preferidos como objetivos: si el ancho de banda o la CPU se ven limitados, el SDK puede reducir automáticamente la calidad de vídeo publicada/suscrita (por ejemplo, una preferencia de 1080p puede bajar temporalmente a una resolución inferior si las condiciones de la red son malas).
• 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 abonados a su flujo, no sólo 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