Cómo controlar el desplazamiento lateral, la inclinación y el zoom de la cámara

Por fin se pueden controlar en la Web las funciones de desplazamiento, inclinación y zoom de las cámaras.

François Beaufort
François Beaufort

Las soluciones de videoconferencia a escala de sala implementan cámaras con funciones de panorámica, inclinación y zoom (PTZ) para que el software pueda apuntar la cámara a los participantes de la reunión. A partir de Chrome 87, las funciones de panorámica, inclinación y zoom de las cámaras están disponibles para los sitios web que usan restricciones de pistas multimedia en MediaDevices.getUserMedia() y MediaStreamTrack.applyConstraints().

Usa la API

Detección de atributos

La detección de funciones para el hardware es diferente de lo que probablemente estés acostumbrado. La presencia de los nombres de restricción "pan", "tilt" y "zoom" en navigator.mediaDevices.getSupportedConstraints() te indica que el navegador admite la API para controlar el PTZ de la cámara, pero no si el hardware de la cámara lo admite. A partir de Chrome 87, el control de PTZ de la cámara es compatible con computadoras, mientras que Android solo admite el zoom.

const supports = navigator.mediaDevices.getSupportedConstraints();
if (supports.pan && supports.tilt && supports.zoom) {
  // Browser supports camera PTZ.
}

Solicitar acceso a la cámara PTZ

Un sitio web puede controlar la PTZ de la cámara solo si el usuario otorgó de forma explícita el permiso de PTZ a la cámara a través de un mensaje.

Para solicitar acceso a la PTZ de la cámara, llama a navigator.mediaDevices.getUserMedia() con las restricciones de PTZ, como se muestra a continuación. Esto le pedirá al usuario que otorgue permisos para la cámara normal y la cámara con PTZ.

Captura de pantalla de un mensaje de usuario de PTZ de la cámara en Chrome para macOS.
Mensaje para el usuario de la cámara PTZ.

La promesa que se devuelve se resuelve con un objeto MediaStream que se usa para mostrar la transmisión de video de la cámara al usuario. Si la cámara no admite PTZ, el usuario recibe un mensaje de cámara normal.

try {
  // User is prompted to grant both camera and PTZ access in a single call.
  // If camera doesn't support PTZ, it falls back to a regular camera prompt.
  const stream = await navigator.mediaDevices.getUserMedia({
    // Website asks to control camera PTZ as well without altering the
    // current pan, tilt, and zoom settings.
    video: { pan: true, tilt: true, zoom: true }
  });

  // Show camera video stream to user.
  document.querySelector("video").srcObject = stream;
} catch (error) {
  // User denies prompt or matching media is not available.
  console.log(error);
}

Un permiso de acceso a la cámara otorgado anteriormente, en particular uno sin acceso a PTZ, no obtiene automáticamente acceso a PTZ si está disponible. Esto se aplica incluso cuando la cámara admite PTZ. Se debe volver a solicitar el permiso. Por suerte, puedes usar la API de Permissions para consultar y supervisar el estado del permiso de PTZ.

try {
  const panTiltZoomPermissionStatus = await navigator.permissions.query({
    name: "camera",
    panTiltZoom: true
  });

  if (panTiltZoomPermissionStatus.state == "granted") {
    // User has granted access to the website to control camera PTZ.
  }

  panTiltZoomPermissionStatus.addEventListener("change", () => {
    // User has changed PTZ permission status.
  });
} catch (error) {
  console.log(error);
}

Para saber si un navegador basado en Chromium admite PTZ para una cámara, ve a la página interna about://media-internals y consulta la columna "Pan-Tilt-Zoom" en la pestaña "Video Capture". "pan tilt" y "zoom" significan, respectivamente, que la cámara admite los controles de UVC "PanTilt (Absolute)" y "Zoom (Absolute)". Los controles de UVC "PanTilt (Relative)" y "Zoom (Relative)" no son compatibles con los navegadores basados en Chromium.

Es la página de depuración interna de ChromeOS.
Página interna para depurar la compatibilidad con cámaras PTZ.

Controlar la PTZ de la cámara

Manipula las capacidades y los parámetros de configuración de PTZ de la cámara con la vista previa de MediaStreamTrack del objeto stream que obtuviste antes. MediaStreamTrack.getCapabilities() devuelve un diccionario con las capacidades admitidas y los rangos o valores permitidos. En consecuencia, MediaStreamTrack.getSettings() devuelve la configuración actual.

Las funciones y los parámetros de configuración de panorámica, inclinación y zoom solo están disponibles si la cámara los admite y el usuario le otorgó permiso de PTZ.

Controlar la cámara PTZ.

Llama a videoTrack.applyConstraints() con las restricciones avanzadas de PTZ adecuadas para controlar el desplazamiento lateral, la inclinación y el zoom de la cámara, como se muestra en el ejemplo. La promesa que se devuelve se resuelve si se completa correctamente. Se rechaza si se cumple alguna de las siguientes condiciones:

  • No se otorgó el permiso de PTZ para la cámara.
  • El hardware de la cámara no admite la restricción de PTZ.
  • La página no es visible para el usuario. Usa la API de visibilidad de páginas para detectar cambios en la visibilidad de las páginas.
// Get video track capabilities and settings.
const [videoTrack] = stream.getVideoTracks();
const capabilities = videoTrack.getCapabilities();
const settings = videoTrack.getSettings();

// Let the user control the camera pan motion if the camera supports it
// and PTZ access is granted.
if ("pan" in settings) {
  const input = document.querySelector("input[type=range]");
  input.min = capabilities.pan.min;
  input.max = capabilities.pan.max;
  input.step = capabilities.pan.step;
  input.value = settings.pan;

  input.addEventListener("input", async () => {
    await videoTrack.applyConstraints({ advanced: [{ pan: input.value }] });
  });
}

if ("tilt" in settings) {
  // similar for tilt...
}
if ("zoom" in settings) {
  // similar for zoom...
}

También es posible configurar el desplazamiento lateral, la inclinación y el zoom de la cámara llamando a navigator.mediaDevices.getUserMedia() con algunos valores de restricción ideales de PTZ de la cámara. Esto es útil cuando se conocen de antemano las capacidades de PTZ de la cámara. Ten en cuenta que aquí no se permiten las restricciones obligatorias (mín., máx., exactas).

const stream = await navigator.mediaDevices.getUserMedia({
  // Website asks to reset known camera pan.
  video: { pan: 0, deviceId: { exact: "myCameraDeviceId" } }
});

Área de juegos

Puedes probar la API ejecutando la demostración.

Consideraciones de seguridad

Los autores de las especificaciones diseñaron e implementaron esta API con el núcleo, incluidos el control del usuario, la transparencia y la ergonomía. La capacidad de usar esta API se rige principalmente por el mismo modelo de permisos que la API de Media Capture and Streams. En respuesta a un mensaje del usuario, el sitio web puede controlar la PTZ de la cámara solo cuando la página es visible para el usuario.

Compatibilidad del navegador

API de MediaStream

Browser Support

  • Chrome: 55.
  • Edge: 12.
  • Firefox: 15.
  • Safari: 11.

Source

API de Permissions

Browser Support

  • Chrome: 43.
  • Edge: 79.
  • Firefox: 46.
  • Safari: 16.

Source

API de Page Visibility

Browser Support

  • Chrome: 33.
  • Edge: 12.
  • Firefox: 18.
  • Safari: 7.

Source

MediaDevices.getUserMedia()

Browser Support

  • Chrome: 53.
  • Edge: 12.
  • Firefox: 36.
  • Safari: 11.

Source

MediaDevices.getSupportedConstraints()

Browser Support

  • Chrome: 53.
  • Edge: 12.
  • Firefox: 44.
  • Safari: 11.

Source

MediaStreamTrack.applyConstraints()

Browser Support

  • Chrome: 59.
  • Edge: 12.
  • Firefox: 43.
  • Safari: 11.

Source

MediaStreamTrack.getCapabilities()

Browser Support

  • Chrome: 59.
  • Edge: 12.
  • Firefox: 132.
  • Safari: 11.

Source

MediaStreamTrack.getSettings()

Browser Support

  • Chrome: 59.
  • Edge: 12.
  • Firefox: 50.
  • Safari: 11.

Source

Vínculos útiles

Agradecimientos

Joe Medley y Thomas Steiner revisaron este artículo. Agradecemos a Rijubrata Bhaumik y Eero Häkkinen de Intel por su trabajo en la especificación y la implementación.