本頁面由 Cloud Translation API 翻譯而成。

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

攝影機的平移、傾斜和縮放功能終於可在網頁上控制。

François Beaufort

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

使用 API

特徵偵測

硬體功能偵測與您可能習慣的方式不同。如果 navigator.mediaDevices.getSupportedConstraints() 中出現 "pan"、"tilt" 和 "zoom" 限制名稱，表示瀏覽器支援用於控制攝影機 PTZ 的 API，但不代表攝影機硬體支援該 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 存取權，請呼叫 navigator.mediaDevices.getUserMedia()，並附上 PTZ 限制條件，如下所示。這會提示使用者同時授予一般攝影機和具備 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，也一樣適用。必須再次要求權限。幸好，您可以使用權限 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 攝影機支援功能。

控制攝影機 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...
}

您也可以呼叫 navigator.mediaDevices.getUserMedia() 並使用某些攝影機 PTZ 理想限制值，設定攝影機平移、傾斜和縮放功能。這在你事先知道攝影機的 PTZ 功能時很實用。請注意，此處不允許使用強制限制 (最小值、最大值、精確值)。

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