Steruj przesuwaniem, przechylaniem i powiększaniem kamery

Funkcje przesuwania, pochylania i powiększania w kamerach można wreszcie kontrolować w przeglądarce.

François Beaufort
François Beaufort

Rozwiązania do obsługi rozmów wideo w całej sali wykorzystują kamery z funkcją przesuwania, pochylania i powiększania, dzięki czemu oprogramowanie może skierować kamerę na uczestników spotkania. Od wersji Chrome 87 funkcje przesuwania, pochylania i powiększania w kamerach są dostępne dla witryn, które używają ograniczeń ścieżki multimedialnej w MediaDevices.getUserMedia() i MediaStreamTrack.applyConstraints().

Korzystanie z interfejsu API

Wykrywanie funkcji

Wykrywanie funkcji sprzętu różni się od tego, do czego prawdopodobnie jesteś przyzwyczajony(-a). Obecność nazw ograniczeń "pan", "tilt" i "zoom" w navigator.mediaDevices.getSupportedConstraints() informuje, że przeglądarka obsługuje interfejs API do sterowania kamerą PTZ, ale nie informuje, czy obsługuje go sprzęt kamery. Od wersji Chrome 87 sterowanie funkcją PTZ kamery jest obsługiwane na komputerach, natomiast na urządzeniach z Androidem nadal obsługiwane jest tylko powiększanie.

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

Prośba o dostęp do funkcji PTZ kamery

Witryna może sterować funkcją PTZ kamery tylko wtedy, gdy użytkownik wyraźnie przyznał kamerze uprawnienia do PTZ w odpowiedzi na prośbę.

Aby poprosić o dostęp do funkcji PTZ kamery, wywołaj navigator.mediaDevices.getUserMedia() z ograniczeniami PTZ, jak pokazano poniżej. Użytkownik zostanie poproszony o przyznanie uprawnień do zwykłej kamery i kamery z funkcją PTZ.

Zrzut ekranu z prośbą o dostęp do funkcji PTZ kamery w Chrome na macOS.
Prośba o zezwolenie na sterowanie kamerą PTZ.

Zwrócona obietnica jest rozwiązywana za pomocą obiektu MediaStream, który służy do wyświetlania użytkownikowi strumienia wideo z kamery. Jeśli kamera nie obsługuje PTZ, użytkownik zobaczy standardowy komunikat dotyczący kamery.

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

Przyznane wcześniej uprawnienia dostępu do aparatu, zwłaszcza bez dostępu do funkcji PTZ, nie dają automatycznie dostępu do funkcji PTZ, gdy stanie się ona dostępna. Dotyczy to również sytuacji, gdy kamera obsługuje funkcję PTZ. Należy ponownie poprosić o uprawnienia. Na szczęście możesz użyć interfejsu Permissions API, aby sprawdzać i monitorować stan uprawnień 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);
}

Aby sprawdzić, czy przeglądarka oparta na Chromium obsługuje funkcję PTZ w przypadku danej kamery, otwórz wewnętrzną stronę about://media-internals i sprawdź kolumnę „Pan-Tilt-Zoom” na karcie „Video Capture”. „Pan tilt” i „zoom” oznaczają, że kamera obsługuje odpowiednio elementy sterujące UVC „PanTilt (Absolute)” i „Zoom (Absolute)”. Elementy sterujące UVC „PanTilt (Relative)” i „Zoom (Relative)” nie są obsługiwane w przeglądarkach opartych na Chromium.

Wewnętrzna strona debugowania ChromeOS.
Strona wewnętrzna do debugowania obsługi kamery PTZ.

Sterowanie kamerą PTZ

Możesz manipulować funkcjami i ustawieniami PTZ kamery, korzystając z podglądu MediaStreamTrack z uzyskanego wcześniej obiektu stream. MediaStreamTrack.getCapabilities() zwraca słownik z obsługiwanymi funkcjami i zakresami lub dozwolonymi wartościami. Odpowiednio MediaStreamTrack.getSettings() zwraca bieżące ustawienia.

Funkcje i ustawienia przesuwania, pochylania i powiększania są dostępne tylko wtedy, gdy są obsługiwane przez kamerę, a użytkownik przyznał jej uprawnienia PTZ.

Sterowanie kamerą PTZ.

Wywołaj videoTrack.applyConstraints() z odpowiednimi zaawansowanymi ograniczeniami PTZ, aby sterować przesuwanie, pochylaniem i powiększaniem kamery, jak pokazano w przykładzie. Zwrócona obietnica zostanie spełniona, jeśli operacja się powiedzie. Odrzuca, jeśli:

  • Kamera nie ma uprawnień PTZ.
  • Sprzęt kamery nie obsługuje ograniczenia PTZ.
  • Strona nie jest widoczna dla użytkownika. Używaj interfejsu Page Visibility API do wykrywania zmian widoczności strony.
// 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...
}

Możesz też skonfigurować przesuwanie, pochylanie i powiększanie obrazu z kamery, wywołując funkcję navigator.mediaDevices.getUserMedia() z pewnymi idealnymi wartościami ograniczeń PTZ kamery. Jest to przydatne, gdy możliwości PTZ kamery są znane z wyprzedzeniem. Pamiętaj, że obowiązkowe ograniczenia (min, max, exact) nie są tu dozwolone.

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

Plac zabaw

Możesz przetestować interfejs API, uruchamiając wersję demonstracyjną.

Bezpieczeństwo

Autorzy specyfikacji zaprojektowali i wdrożyli ten interfejs API, korzystając z podstawowych zasad, takich jak kontrola użytkownika, przejrzystość i ergonomia. Możliwość korzystania z tego interfejsu API jest ograniczona głównie przez ten sam model uprawnień co w przypadku interfejsu Media Capture and Streams API. W odpowiedzi na prompt użytkownika witryna może sterować funkcjami PTZ kamery tylko wtedy, gdy strona jest widoczna dla użytkownika.

Zgodność z przeglądarką

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

Przydatne linki

Podziękowania

Ten artykuł sprawdzili Joe Medley i Thomas Steiner. Dziękujemy Rijubracie Bhaumikowi i Eero Häkkinenowi z firmy Intel za pracę nad specyfikacją i implementacją.