攝影機的平移、傾斜和縮放功能終於可在網頁上控制。
房間規模視訊會議解決方案會部署具備平移、傾斜和變焦 (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 權限的攝影機權限。
傳回的承諾會以 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 控制項。
控制攝影機 PTZ
使用先前取得的 stream
物件中的預覽 MediaStreamTrack
操控攝影機 PTZ 功能和設定。MediaStreamTrack.getCapabilities()
會傳回字典,其中包含支援的功能和範圍或允許的值。MediaStreamTrack.getSettings()
會傳回目前的設定。
只有在相機支援平移、傾斜和縮放功能,且使用者已授予相機 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" } }
});
遊樂場
您可以在 Glitch 上執行範例,試用這個 API。請務必查看原始碼。
安全性考量
規格作者使用核心設計和實作此 API,包括使用者控制、資訊公開和人體工學。使用這個 API 的能力,主要受到與 Media Capture and Streams API 相同的權限模型限制。在回應使用者提示時,只有在使用者可見網頁時,網站才能控制攝影機 PTZ。
瀏覽器相容性
MediaStream API
Permissions API
Page Visibility API
MediaDevices.getUserMedia()
MediaDevices.getSupportedConstraints()
MediaStreamTrack.applyConstraints()
MediaStreamTrack.getCapabilities()
MediaStreamTrack.getSettings()
實用連結
特別銘謝
本文由 Joe Medley 和 Thomas Steiner 審查。感謝 Intel 的 Rijubrata Bhaumik 和 Eero Häkkinen 在規格和實作方面付出的努力。主頁橫幅圖片由 Christina @ wocintechchat.com 提供,圖片來源:Unsplash。