Как управлять панорамированием, наклоном и масштабированием камеры

Теперь в веб-версии можно управлять панорамированием, наклоном и масштабированием камеры.

François Beaufort
François Beaufort

Решения для видеоконференций в масштабе комнаты развертывают камеры с возможностями панорамирования, наклона и масштабирования (PTZ), чтобы программное обеспечение могло наводить камеру на участников встречи. Начиная с версии Chrome 87, функции панорамирования, наклона и масштабирования на камерах доступны для сайтов, использующих ограничения медиадорожек в MediaDevices.getUserMedia() и MediaStreamTrack.applyConstraints().

Использование API

Распознавание объектов

Обнаружение функций для аппаратного обеспечения отличается от того, к чему вы, вероятно, привыкли. Наличие названий ограничений "pan", "tilt" и "zoom" в navigator.mediaDevices.getSupportedConstraints() указывает на то, что браузер поддерживает API для управления PTZ-камерой, но не на то, что это поддерживается аппаратным обеспечением камеры. Начиная с Chrome 87, управление панорамированием, наклоном и масштабированием камеры поддерживается на компьютерах, а на устройствах Android по-прежнему поддерживается только масштабирование.

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

Запросить доступ к управлению PTZ-камерой

Сайт может управлять панорамированием, наклоном и масштабированием камеры, только если пользователь явно предоставил ему такое разрешение в окне запроса.

Чтобы запросить доступ к PTZ-камере, вызовите метод navigator.mediaDevices.getUserMedia() с ограничениями PTZ, как показано ниже. Пользователю будет предложено предоставить разрешения на доступ к обычной камере и камере с PTZ.

Скриншот запроса на управление камерой в Chrome для macOS.
Запрос на управление камерой.

Возвращенный промис разрешается с помощью объекта MediaStream, который используется для показа пользователю видеопотока с камеры. Если камера не поддерживает PTZ, пользователь увидит обычный запрос на доступ к камере.

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);
}

Если разрешение на доступ к камере было предоставлено ранее, в частности без доступа к PTZ, то доступ к PTZ не будет предоставлен автоматически, если он станет доступен. даже если сама камера поддерживает PTZ. Разрешение нужно запросить снова. К счастью, вы можете использовать Permissions API, чтобы запрашивать и отслеживать статус разрешения на 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);
}

Чтобы узнать, поддерживает ли браузер на основе Chromium панорамирование, наклон и масштабирование для камеры, перейдите на внутреннюю страницу about://media-internals и посмотрите столбец Pan-Tilt-Zoom (Панорамирование, наклон и масштабирование) на вкладке Video Capture (Запись видео). Значения pan tilt (панорамирование и наклон) и zoom (масштабирование) означают, что камера поддерживает элементы управления UVC PanTilt (Absolute) (Панорамирование и наклон (абсолютное)) и Zoom (Absolute) (Масштабирование (абсолютное)). Элементы управления UVC "Панорамирование/наклон (относительно)" и "Масштаб (относительно)" не поддерживаются в браузерах на основе Chromium.

Внутренняя страница отладки ChromeOS.
Внутренняя страница для отладки поддержки PTZ-камер.

Управление PTZ-камерой

Управляйте возможностями и настройками PTZ-камеры с помощью предварительного просмотра MediaStreamTrack из объекта stream, полученного ранее. MediaStreamTrack.getCapabilities() возвращает словарь с поддерживаемыми возможностями и диапазонами или допустимыми значениями. Соответственно, MediaStreamTrack.getSettings() возвращает текущие настройки.

Функции и настройки панорамирования, наклона и масштабирования доступны, только если они поддерживаются камерой и пользователь предоставил камере разрешение на их использование.

Управление панорамированием, наклоном и масштабированием камеры.

Вызовите videoTrack.applyConstraints() с соответствующими расширенными ограничениями PTZ, чтобы управлять панорамированием, наклоном и масштабированием камеры, как показано в примере. Возвращенный объект Promise распознается, если операция выполнена успешно. Запрос отклоняется, если:

  • Разрешение на использование камеры с PTZ не предоставлено.
  • Аппаратное обеспечение камеры не поддерживает ограничение PTZ.
  • Страница не видна пользователю. Используйте Page Visibility API, чтобы отслеживать изменения видимости страницы.
// 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...
}

Вы также можете настроить панорамирование, наклон и масштаб камеры, вызвав navigator.mediaDevices.getUserMedia() с некоторыми идеальными значениями ограничений PTZ камеры. Это удобно, если возможности PTZ-камеры известны заранее. Обратите внимание, что обязательные ограничения (min, max, exact) здесь не допускаются.

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

Детская площадка

Вы можете протестировать API, запустив демоверсию.

Безопасность

Авторы спецификации разработали и реализовали этот API, используя основные принципы, включая пользовательский контроль, прозрачность и эргономику. Возможность использовать этот API в основном регулируется той же моделью разрешений, что и Media Capture and Streams API. В ответ на запрос пользователя сайту разрешается управлять панорамированием, наклоном и масштабированием камеры, только когда страница видна пользователю.

Совместимость браузеров

MediaStream API

Browser Support

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

Source

Permissions API

Browser Support

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

Source

Page Visibility API

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

Полезные ссылки

Благодарности

Рецензенты статьи: Джо Медли (Joe Medley) и Томас Штайнер (Thomas Steiner). Благодарим Риджубрату Бхаумика (Rijubrata Bhaumik) и Ээро Хяккинена (Eero Häkkinen) из Intel за работу над спецификацией и реализацией.