Restricciones de vídeo para editores — Web

Una vez que haya Se ha inicializado un Publisher, puedes controlar la resolución y la frecuencia de fotogramas preferidas de la pista de vídeo de salida. Esto te permite optimizar el ancho de banda y el uso de la CPU para diferentes tamaños de interfaz de usuario (miniaturas, mosaicos, pantalla completa) y dispositivos de los suscriptores.

Este tema incluye las siguientes secciones:

Comprender las limitaciones de los vídeos de los editores

La editorial puede anunciar un preferido resolución y frecuencia de fotogramas de su pista de vídeo: el SDK aplica restricciones al dispositivo de captura y a la pista de salida. Los suscriptores se benefician de un menor consumo de ancho de banda y CPU cuando el editor establece tamaños más reducidos o frecuencias de fotogramas más bajas para dispositivos con interfaces de usuario pequeñas. Ten en cuenta que la calidad ofrecida puede verse modificada en función de las capacidades del dispositivo y las condiciones de la red.

Configuración de la resolución preferida

Llame a publisher.setPreferredResolution(preferredResolution) Para configurar las dimensiones en píxeles deseadas:

await publisher.setPreferredResolution({ width: 640, height: 360 });
  • preferredResolution es un objeto: { width: number, height: number }.
  • La resolución seleccionada no debe superar la resolución de publicación inicial.
  • Solo se aplica cuando el editor está grabando vídeo (publishVideo: true).

Lanza un error si:

  • El Publisher es solo de audio.
  • width o height no es un número entero positivo.
  • La resolución solicitada supera la resolución de publicación inicial.
try {
  // If the initial publish was 640x480, this will throw:
  await publisher.setPreferredResolution({ width: 1920, height: 1080 });
} catch (error) {
  console.error('Failed to set preferred resolution:', error.message);
}

Configuración de la frecuencia de fotogramas preferida

Llame a publisher.setPreferredFrameRate(frameRate) Para establecer un valor de fotogramas por segundo preferido:

await publisher.setPreferredFrameRate(15);
  • frameRate Debe ser un número entero positivo (≥ 1).
  • Requiere una pista de vídeo activa.

Lanza un error si:

  • El Publisher es solo de audio.
  • frameRate no es un número entero válido ≥ 1.

Cómo afectan las restricciones a la entrega

Las restricciones preferidas influyen en la pista de vídeo de salida para todos los suscriptores a la transmisión. Sin embargo, la resolución y la frecuencia de fotogramas finales que se transmiten pueden ser inferiores debido a:

  • Limitaciones del dispositivo de captura
  • Limitaciones del navegador o del sistema operativo
  • Condiciones de la red y decisiones adaptativas sobre los medios

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 un solo abonado recibe/decodifica/representa 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 el Editorial envía. Esto afecta a todos los suscriptores de ese flujo, que recibirán automáticamente la configuración actualizada. Es posible que desees reducir la resolución del editor mediante el método `preferredResolution` en varios casos, como 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.
  • Utiliza frecuencias de fotogramas adecuadas:
    • 5 fps — paneles estáticos, diapositivas, interfaz de usuario sensible al ancho de banda
    • 15 fps — contenido con poco movimiento
    • 30 fps — vídeo en movimiento completo/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 se admiten estas API solo en el SDK de JavaScript.

Ejemplos

// Lower quality for mobile users
if (isMobileUser) {
  publisher.setPreferredResolution({ width: 320, height: 180 });
  publisher.setPreferredFrameRate(15);
}

// Higher quality for desktop
if (isDesktopUser) {
  publisher.setPreferredResolution({ width: 1280, height: 720 });
  publisher.setPreferredFrameRate(30);
}

// Error when using resolution above initial publish
try {
  await publisher.setPreferredResolution({ width: 1920, height: 1080 }); // If initial was 640x480, throws error
} catch (error) {
  console.error(error.message);
}

// Debugging: Current track settings
const videoTrack = publisher.getVideoSource().track;
const { width, height, frameRate } = videoTrack.getSettings();
console.log('Current resolution:', width, 'x', height);
console.log('Current frame rate:', frameRate);

Solución de problemas

Gestión de errores

Encerrar las llamadas en try/catch y mostrar mensajes claros y comprensibles cuando las restricciones no sean válidas o el entorno no pueda cumplirlas.

async function setPublisherQuality(publisher, preferredResolution, preferredFrameRate) {
  try {
    await publisher.setPreferredResolution(preferredResolution);
    await publisher.setPreferredFrameRate(preferredFrameRate);
  } catch (err) {
    showMessage('Unable to apply video constraints. Check your device and network.');
    console.error(err);
  }
}

Consideraciones sobre la red

Si la red tiene limitaciones, el canal de transmisión multimedia podría reducir la resolución o la frecuencia de fotogramas, independientemente de la configuración elegida. Se recomienda implementar indicadores en la interfaz de usuario para los modos de calidad reducida.

Recursos adicionales