控制相機的平移、傾斜和縮放功能

現在,你可以在網頁上控制攝影機的平移、傾斜和縮放功能。

François Beaufort
François Beaufort

會議室規模的視訊會議解決方案會部署具備平移、傾斜和變焦 (PTZ) 功能的攝影機,讓軟體能將攝影機對準會議參與者。自 Chrome 87 起,網站可透過 MediaDevices.getUserMedia() 和 MediaStreamTrack.applyConstraints() 中的媒體軌限制,使用攝影機的平移、傾斜和縮放功能。

使用 API

特徵偵測

硬體的功能偵測與您可能習慣的方式不同。navigator.mediaDevices.getSupportedConstraints() 中有 "pan"、"tilt" 和 "zoom" 限制名稱,表示瀏覽器支援 API 控制攝影機 PTZ,但不代表攝影機硬體支援。自 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 使用者提示。

傳回的 Promise 會解析為 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 瀏覽器是否支援攝影機的 PTZ 功能,請前往內部 about://media-internals 頁面,然後查看「Video Capture」分頁中的「Pan-Tilt-Zoom」欄;「pan tilt」和「zoom」分別代表攝影機支援「PanTilt (Absolute)」和「Zoom (Absolute)」UVC 控制項。Chromium 瀏覽器不支援「PanTilt (Relative)」和「Zoom (Relative)」UVC 控制項。

ChromeOS 內部偵錯頁面。
用於偵錯 PTZ 攝影機支援的內部頁面。

控制攝影機 PTZ

使用先前取得的 stream 物件中的預覽 MediaStreamTrack,操控相機 PTZ 功能和設定。MediaStreamTrack.getCapabilities() 會傳回字典,其中包含支援的功能和範圍或允許的值。MediaStreamTrack.getSettings() 則會傳回目前的設定。

只有在攝影機支援,且使用者已授予攝影機 PTZ 權限時,才能使用平移、傾斜和縮放功能及設定。

控制相機 PTZ。

使用適當的 PTZ 進階限制呼叫 videoTrack.applyConstraints(),即可控制相機的平移、傾斜和縮放,如範例所示。如果成功,傳回的 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 的能力主要受限於與媒體擷取和串流 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

實用連結

特別銘謝

本文由 Joe Medley 和 Thomas Steiner 審查。感謝 Intel 的 Rijubrata Bhaumik 和 Eero Häkkinen 在規格和實作方面的工作。