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

カメラのパン、チルト、ズーム機能をウェブで操作できるようになりました。

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 カメラの両方の権限を付与するようユーザーに求めるメッセージが表示されます。

カメラの 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 ページに移動し、[動画キャプチャ] タブの [パン / チルト / ズーム] 列を確認します。「パン / チルト」と「ズーム」は、カメラが「パン / チルト（絶対）」と「ズーム（絶対）」の UVC コントロールをサポートしていることを意味します。Chromium ベースのブラウザでは、「PanTilt（相対）」と「Zoom（相対）」の UVC コントロールはサポートされていません。

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 機能が事前にわかっている場合に便利です。必須の制約（最小値、最大値、正確な値）は使用できません。

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

遊び場

Glitch でデモを実行して、API を試すことができます。ソースコードを確認してください。

ヒント: PTZ 対応のカメラをお持ちでない場合は、スイッチを使用して Chrome を実行 --use-fake-device-for-media-stream して、マシンでシミュレートできます。ぜひお楽しみください。

セキュリティに関する考慮事項

仕様作成者は、ユーザー コントロール、透明性、人間工学などのコアを使用して、この API を設計して実装しました。この API の使用は、主に Media Capture and Streams API と同じ権限モデルによって制限されます。ユーザーからのメッセージに応答して、ウェブサイトがカメラの PTZ を制御できるのは、ページがユーザーに表示されている場合のみです。

ブラウザの互換性

MediaStream API

対応ブラウザ

• 55
• 12
• 15
• 11

ソース

Permissions API

対応ブラウザ

• 43
• 79
• 46
• 16

ソース

Page Visibility API

対応ブラウザ

• 33
• 12
• 18
• 7

ソース

MediaDevices.getUserMedia()

対応ブラウザ

• 53
• 12
• 36
• 11

ソース

MediaDevices.getSupportedConstraints()

対応ブラウザ

• 53
• 12
• 44
• 11

ソース

MediaStreamTrack.applyConstraints()

対応ブラウザ

• 59
• 12
• 43
• 11

ソース

MediaStreamTrack.getCapabilities()

対応ブラウザ

• 59
• 12
• 132
• 11

ソース

MediaStreamTrack.getSettings()

対応ブラウザ

• 59
• 12
• 50
• 11

ソース

関連情報

• PTZ の説明
• 仕様の下書き
• GitHub リポジトリ
• ChromeStatus エントリ
• Chrome のトラッキング バグ

謝辞

この記事は、Joe Medley と Thomas Steiner が確認しました。仕様と実装に携わっていただいた Intel の Rijubrata Bhaumik 氏と Eero Häkkinen 氏に感謝いたします。Unsplash の Christina @ wocintechchat.com によるヒーロー画像。