카메라 이동, 기울이기, 확대/축소를 제어합니다.

카메라의 화면 이동, 기울이기, 확대/축소 기능을 웹에서 제어할 수 있게 되었습니다.

François Beaufort
François Beaufort

회의실 규모의 화상 회의 솔루션은 팬, 틸트, 줌(PTZ) 기능이 있는 카메라를 배포하여 소프트웨어가 회의 참석자에게 카메라를 가리킬 수 있도록 합니다. Chrome 87부터 MediaDevices.getUserMedia() 및 MediaStreamTrack.applyConstraints()에서 미디어 트랙 제약 조건을 사용하는 웹사이트에서 카메라의 팬, 틸트, 확대/축소 기능을 사용할 수 있습니다.

API 사용

특성 인식

하드웨어의 기능 감지는 익숙한 것과 다릅니다. navigator.mediaDevices.getSupportedConstraints()에 "pan", "tilt", "zoom" 제약 조건 이름이 있으면 브라우저가 카메라 PTZ를 제어하는 API를 지원하지만 카메라 하드웨어가 이를 지원하는지는 알 수 없습니다. Chrome 87부터 카메라 PTZ 제어는 데스크톱에서 지원되며 Android는 여전히 확대/축소만 지원합니다.

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

카메라 PTZ 액세스 요청

웹사이트는 사용자가 메시지를 통해 PTZ 권한이 있는 카메라를 명시적으로 부여한 경우에만 카메라 PTZ를 제어할 수 있습니다.

카메라 PTZ 액세스를 요청하려면 아래와 같이 PTZ 제약 조건과 함께 navigator.mediaDevices.getUserMedia()를 호출합니다. 이렇게 하면 사용자에게 일반 카메라와 PTZ 카메라 권한을 모두 부여하라는 메시지가 표시됩니다.

macOS용 Chrome의 카메라 PTZ 사용자 프롬프트 스크린샷
카메라 PTZ 사용자 프롬프트

반환된 프로미스는 사용자에게 카메라 동영상 스트림을 표시하는 데 사용되는 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 액세스 권한을 얻지 않습니다. 이는 카메라 자체가 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 기반 브라우저가 카메라의 PTZ를 지원하는지 확인하려면 내부 about://media-internals 페이지로 이동하여 '동영상 캡처' 탭의 '팬-틸트-줌' 열을 확인합니다. '팬 틸트'와 '줌'은 각각 카메라가 'PanTilt (절대)' 및 'Zoom (절대)' UVC 컨트롤을 지원함을 의미합니다. 'PanTilt (Relative)' 및 'Zoom (Relative)' UVC 컨트롤은 Chromium 기반 브라우저에서 지원되지 않습니다.

내부 ChromeOS 디버그 페이지입니다.
PTZ 카메라 지원을 디버그하기 위한 내부 페이지입니다.

카메라 PTZ 제어

앞서 가져온 stream 객체의 미리보기 MediaStreamTrack를 사용하여 카메라 PTZ 기능과 설정을 조작합니다. MediaStreamTrack.getCapabilities()는 지원되는 기능과 범위 또는 허용되는 값이 포함된 사전을 반환합니다. 이에 따라 MediaStreamTrack.getSettings()는 현재 설정을 반환합니다.

팬, 틸트, 확대/축소 기능 및 설정은 카메라에서 지원하고 사용자가 카메라에 PTZ 권한을 부여한 경우에만 사용할 수 있습니다.

카메라 PTZ 제어

예시에 표시된 대로 적절한 PTZ 고급 제약 조건으로 videoTrack.applyConstraints()를 호출하여 카메라 팬, 틸트, 줌을 제어합니다. 성공하면 반환된 프로미스가 해결됩니다. 다음 중 하나에 해당하는 경우 거부됩니다.

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

일부 카메라 PTZ 이상적인 제약 조건 값으로 navigator.mediaDevices.getUserMedia()를 호출하여 카메라 팬, 틸트, 줌을 구성할 수도 있습니다. 이는 카메라 PTZ 기능을 미리 알고 있는 경우에 유용합니다. 필수 제약 조건 (최소, 최대, 정확)은 여기에서 허용되지 않습니다.

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와 동일한 권한 모델에 의해 제어됩니다. 사용자 프롬프트에 대한 응답으로, 웹사이트는 페이지가 사용자에게 표시되는 경우에만 카메라 PTZ를 제어할 수 있습니다.

브라우저 호환성

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

유용한 링크

감사의 말씀

이 도움말은 조 메들리와 토마스 슈타이너가 검토했습니다. 사양 및 구현에 기여한 Intel의 Rijubrata Bhaumik과 Eero Häkkinen에게 감사의 말씀을 전합니다.