カメラのパン、ティルト、ズームを制御する

カメラのパン、ティルト、ズーム機能が、ウェブ上で制御できるようになりました。

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 ユーザー プロンプト。

返された 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 アクセス権を取得することはありません。これは、カメラ自体が 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 コントロールをサポートしていることを意味します。「PanTilt(相対)」と「Zoom(相対)」の UVC コントロールは、Chromium ベースのブラウザではサポートされていません。

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

また、カメラの PTZ の理想的な制約値を指定して navigator.mediaDevices.getUserMedia() を呼び出すことで、カメラのパン、ティルト、ズームを構成することもできます。これは、カメラの 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 を使用できるかどうかは、主に 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

関連情報

謝辞

この記事は、Joe Medley と Thomas Steiner によってレビューされました。仕様と実装に携わってくださった Intel の Rijubrata Bhaumik 氏と Eero Häkkinen 氏に感謝いたします。