Google Meet ハードウェア USB Video Class Extension Unit API

このドキュメントでは、Google Meet 会議システムでインテリジェントなカメラ機能を有効にするために使用される、サポートされている USB Video Class Extension Unit（XU）API について概説します。この仕様の作成目的は、これらの機能を有効にする方法に影響を与え、パートナーが非同期スケーラビリティとテストを改善できるようにすることです。

このドキュメントの最新の変更内容については、リリースノートをご覧ください。

テスト施設

パートナーがこの仕様に準拠していることを確認できるように、デベロッパー モードで設定された Chromebox-for-Meetings デバイスにテスト機能を用意しています。ファイル システムへの書き込みを有効にします。/etc/chrome_dev.conf に次の行を追加します。

--enable-logging
--log-level=0

デバイスを再起動し、カメラと USB キーボードを接続して Ctrl-Alt-X を押すと、アクティブなカメラの仕様への準拠が確認され、/home/chronos/user/log/chrome に記録されます。

リトル エンディアン規則

USB はリトル エンディアンの規格です。このドキュメント内:

  • マルチバイト数はビッグエンディアンで表示され（リトルエンディアンで送信されます）。
  • バイト配列はリトル エンディアンのメモリ レイアウトです。

たとえば、0x12345678 は [0x78, 0x56, 0x34, 0x12] と同じです。

拡張機能ユニットの GUID

この Meet XU コントロール仕様をサポートする拡張機能ユニットは、この GUID を使用する必要があります。

拡張ユニット GUID
周辺機器制御 XU {74D7E924-49C9-4A45-98A3-8A9F60061E83}

周辺機器制御 XU セレクタ

これらは、定義されたペリフェラル制御 XU セレクタです。

コントロール セレクタ 値
GOOGXU_FRAME_STRATEGY 0x01
GOOGXU_REFRAME 0x02
GOOGXU_OCCUPANCY_COUNTING_TOGGLE 0x03
GOOGXU_OCCUPANCY_COUNTING_READ 0x04
GOOGXU_STATUS_INFO 0x05
GOOGXU_STATUS_RESET 0x06
GOOGXU_PRESETS 0x07
GOOGXU_PAN_TILT_ABSOLUTE 0x08
GOOGXU_PAN_TILT_RELATIVE 0x09
GOOGXU_SATELLITE_INFO 0x0A

コントロール リクエストのタイプ

コントロール リクエストのタイプは、UVC 1.5 クラス仕様の第 4 章「クラス固有のリクエスト」で定義されています。

オペレーション UVC コントロール
GET GET_CUR、GET_MIN、GET_MAX、GET_RES、GET_LEN、GET_INFO、GET_DEF
SET SET_CUR

カメラモード

カメラモードは、会議室内の個人をフレームに収めるために使用され、次のいずれかのtupleです。

  • 戦略（カメラビュー）
  • バイアス（スピーカーまたは部屋）
  • フィード（1 つまたは複数のストリーム）

各ディメンションには、以降のセクションで説明する値を指定できます。

オート フレーミング戦略

[なし] 以外のすべての自動フレーミング モードでは、手動のパン、チルト、ズームは無効になります。

機能 説明
なし カメラでは、すべてのインテリジェント フレーミング機能が無効になり、クライアントは PTZ 値を自由に制御できます。
注: このフレーミング戦略に設定すると、カメラは現在のパン、チルト、ズームの位置に固定されます。
追尾フレーミング（CAZ） フレーミング バイアスに基づいて、カメラは部屋内の人物を継続的に追跡します。
フレームの分割 カメラは、必要な数の動画ビューを作成します。自動フレーミング フィード オプションに基づいて、1 つのストリーム内のタイルに統合するか、ビューごとに個別の動画ストリームを作成します。
動的ビュー 1 つ以上のカメラが部屋のベストショットを撮影しようとします。複数のフィードを 1 つに統合するかどうか、または現在の部屋の「興味深い」ビューを提供するかどうかを判断できます。
このビューの目的は、会議に参加している部屋内の参加者を最も公平に表示することです。
ベンダー優先 カメラシステムは独自のロジックを使用して、部屋のベストショットを決定します。基盤となるフレーミング戦略は予告なく変更される場合があります。たとえば、部屋にいる人数が変わったり、カメラが「重要なプレゼンター」と「コラボレーション」の会議の違いを検出したりした場合、このモードではシステムが適切と思われるようにフレーミング戦略を適応または変更できます。このモードでは、getCur を呼び出すと、システムによって選択された基盤となるフレーミング モードではなく、VENDOR_PREFERRED が返されます。

オート フレーミングのバイアス

機能 説明
重要なプレゼンター（スピーカー トラッキング） カメラは、部屋の中で発言している人を最適なフレーム内に収めようとします。
このシナリオでは、カメラはプレゼンターの方を向ける必要があります。たとえば、会議室でプレゼンテーションを行う CEO などです。
コラボレーション
（部屋の追跡）		 カメラは、部屋内のすべての参加者をフレームに収めるよう最善を尽くします。このシナリオでは、カメラはすべての参加者を公平に扱う必要があります。

オート フレーミング フィード

機能 説明
シングル ストリーム カメラは 1 つの動画ストリームをホストデバイスに送信します。
マルチストリーム
（開発中）		 カメラはストリームを分割し、複数の動画ストリームを作成してホストに送信します。
注: この機能の完全な仕様と想定される動作は審査中であり、このドキュメントの今後の改訂版までサポートされていません。

自動フレーミング モードのビットマップ値

空のバイト配列で表されるデフォルトの状態 None を除き、バイト配列の各ビットは、自動フレーミング戦略、自動フレーミング バイアス、自動フレーミング フィードの特定の組み合わせである、異なるカメラモードを表します。

オート フレーミング フィード CAZ スプリット フレーム ダイナミック ベンダー優先 オート フレーミングのバイアス
シングル ストリーム D1
D2		 -
D3		 D5
D7		 D9（スピーカーまたは部屋） スピーカー
部屋
マルチストリーム -
-		 -
D4		 D6
D8		 - スピーカー
部屋
フレームモード フレームモード値（最下位バイト）
None 0x0000
CAZ, Speaker, Single-Stream 0x0001
CAZ, Room, Single-Stream 0x0002
Split-Frame, Room, Single-Stream 0x0004
Split-Frame, Room, Multi-Stream 0x0008
Dynamic, Speaker, Single-Stream 0x0010
Dynamic, Speaker, Multi-Stream 0x0020
Dynamic, Room, Single-Stream 0x0040
Dynamic, Room, Multi-Stream 0x0080
Vendor-preferred, Single-Stream 0x0100

コントロール: GOOGXU_FRAME_STRATEGY

このコントロールは、自動フレーミング モードのビットマップ値に記載されているように、カメラのフレーミング モードを取得または設定するために使用されます。各モードは、それぞれのビットマップ内のビットで表されます。コマンド GET_RES は、8 バイトの長さのビットマスクを返します。このビットマスクの値は 0 または 1 で、デバイスで機能がサポートされているかどうかを示します。たとえば、カメラが CAZ, Speaker, Single-Stream、Split-Frame, Room, Single-Stream、Dynamic, Room, Multi-Stream をサポートし、他のモードをサポートしていない場合、GET_RES は 0x000000000000000085（0b10000101 の後に 7 つのゼロバイト）を返します。

コマンド SET_CUR は、ビットマップを送信して、有効にするシングル カメラモードをカメラに指示するために使用されます。

コントロール セレクタ 1
オペレーション GET / SET
wLength 8
オフセット フィールド サイズ 値 説明
0 bActiveMode 8 ビットマップ アクティブ カメラ モードを設定または復元する
注:

サポートされているリクエスト タイプの動作は次のとおりです。

オフセット 0 説明
GET_CUR アクティブ フレーミング カメラ モードを取得する
GET_MIN カメラに依存
GET_MAX カメラに依存
GET_RES サポートされているカメラモードの 8 バイトの長さのビットマスクを返します。
GET_LEN 0x0008 長さ
GET_INFO 0x0B AutoUpdate / Write / Read
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 デフォルト値
SET_CUR アクティブ フレーミング カメラ モードを設定する

コントロール: GOOGXU_REFRAME

このコントロールは、ワンショット フレーミング（OTAZ）をトリガーするために使用します。OTAZ がトリガーされると、カメラ ビューは部屋のベスト ビューにスナップされます。その後、クライアントは PTZ 値を制御できるようになります。ワンショット フレーミングがサポートされていない場合、カメラはこのコントロールを定義しないでください。

コントロール セレクタ 2
オペレーション SET
wLength 1
オフセット フィールド サイズ 値 説明
0 bReframe 1 数値 0x01 フレーム変更リクエストの実行

サポートされているリクエスト タイプの動作は次のとおりです。

オフセット 0 説明
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x02 書き込みのみ
GET_DEF 0x00
SET_CUR ワンショット フレーミングのリクエストを設定する

占有人数のカウント

人数カウント（OC）は、カメラの切り抜きビューに関係なく、会議室内の参加者数を推定するのに使用される機能です。

次の表に、OC コントロールの想定される動作と、カメラの動画ストリームとカメラの LED インジケータとの相互作用を示します。

占有人数のカウントが カメラの動画ストリームが次の状態である場合: カメラの LED インジケーターは GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR は GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR は
有効 ストリーミングされておらず、ミュートされていない オン 0x01 カメラの全視野に写っている人物の数。
有効 ストリーミング オン 0x01 カメラの全視野に写っている人物の数。
有効 ミュート中 オフ 0x01 通知 OFF
通知 OFF ストリーミングされておらず、ミュートされていない オフ 0x00 通知 OFF
通知 OFF ストリーミング オン 0x00 通知 OFF
通知 OFF ミュート中 オフ 0x00 通知 OFF

コントロール: GOOGXU_OCCUPANCY_COUNTING_TOGGLE

このコントロールは、部屋の居住者数をカウントする機能を有効または無効にするために使用します。値を 0 に設定すると、この機能は無効になり、1 に設定すると有効になります。この機能がサポートされていない場合、カメラはこのコントロールを定義しないでください。

コントロール セレクタ 3
オペレーション GET / SET
wLength 1
オフセット フィールド サイズ 値 説明
0 bOccupancy 1 ブール値 在室人数カウント機能を設定
0x00 機能をオフ
0x01 機能をオン

サポートされているリクエスト タイプの動作は次のとおりです。

オフセット 0 説明
GET_CUR 利用人数のカウントがオンかどうかを返します
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x0B AutoUpdate / Write / Read
GET_DEF 0x00
SET_CUR 利用人数の検出機能を有効または無効にする

コントロール: GOOGXU_OCCUPANCY_COUNTING_READ

このコントロールは、利用人数のカウントが有効になっているときに、カメラから報告される部屋内の参加者数を読み取るために使用されます。利用人数の検出が無効になっている場合、カメラはこのコントロールを無効にする必要があります。在室人数のカウントがサポートされていない場合、カメラはこのコントロールを定義しないでください。

コントロール セレクタ 4
オペレーション GET
wLength 2
オフセット フィールド サイズ 値 説明
0 bNumPeople 2 数値 検出された室内にいる人数。（読み取り専用）

サポートされているリクエスト タイプの動作は次のとおりです。

オフセット 0 説明
GET_CUR 検出された居住者の数を返す
GET_MIN 0x0000
GET_MAX 0x00FF
GET_RES 0x0001
GET_LEN 0x0002
GET_INFO 0x09 AutoUpdate / Read
GET_DEF 0x0000

デバイスのテレメトリーと診断

これらのコントロールは、Meet ハードウェアでより優れたデバッグ手法を促進することを目的としており、通常はユーザー向けではありません。

コントロール: GOOGXU_STATUS_INFO

このコントロールは、ホストカメラから情報をクエリして、デバッグのためにパートナーと共有するために使用されます。

コントロール セレクタ 5
オペレーション GET
wLength 8
オフセット フィールド サイズ 値 説明
0 bNumCameras 1 数値 ホストに返されるカメラ ストリームに影響する可能性がある、メインカメラに接続されている追加のサテライトの数。
1 bIsMoving 1 ビットマップ カメラがアイドル状態のときは 0、PTZ 値が変化しているときはゼロ以外です。ベンダーは、異なる軸またはモーターを異なるビットにマッピングできます。
2 Undef 6 Undef 今後拡大される予定です。

サポートされているリクエスト タイプの動作は次のとおりです。

オフセット 0 1 2 説明
GET_MIN 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00
GET_MAX 0xFF 0xFF 0xFF 0xFF 0xFF
0xFF 0xFF 0xFF
GET_RES 0x01 0x01 0x01 0x00 0x00
0x00 0x00 0x00
GET_LEN 0x08 0x00 0x0008
GET_INFO 0x09 AutoUpdate / Read
GET_DEF 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00

コントロール: GOOGXU_SATELLITE_INFO

このコントロールは、このカメラシステムに接続されているサテライト デバイスをクエリするために使用されます。

コントロール セレクタ 0x0A
オペレーション GET
wLength 20
オフセット フィールド サイズ 値 説明
0 bSatelliteList 20 ビットマップ システムに接続されているサテライト タイプのリスト。4 つの 5 バイト スロットがあります。各スロットについて、以下で説明します。
オフセット 説明
0 この衛星タイプの数量。
1-2 この衛星タイプのベンダー ID。
3～4 この衛星タイプのプロダクト ID。

サポートされているリクエスト タイプの動作は次のとおりです。

オフセット 0 説明
GET_MIN 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
GET_MAX 0xFF 0xFF 0xFF 0xFF 0xFF
0xFF 0xFF 0xFF 0xFF 0xFF
0xFF 0xFF 0xFF 0xFF 0xFF
0xFF 0xFF 0xFF 0xFF 0xFF
GET_RES 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
GET_LEN 0x14 20 バイト
GET_INFO 0x09 AutoUpdate / Read
GET_DEF 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00

コントロール: GOOGXU_STATUS_RESET

このコントロールは、カメラにリセット リクエストを送信するために使用されます。値を 1 に設定すると、カメラの再起動がリクエストされます。前回の再起動以降にカメラの再起動リクエストがない場合、カメラはゼロ（0）を返します。再起動中の場合は 1 を返します。リセットによってカメラの再起動がトリガーされる必要があります。（これは、ホットプラグをエミュレートするために USB 接続を強制的に切断することが有用でない、自己給電式デバイスに必要です）。

コントロール セレクタ 6
オペレーション GET / SET
wLength 1
オフセット フィールド サイズ 値 説明
0 bResetRequest 1 ブール値 ホストと接続されたカメラにリセット リクエストを送信します。
前回の再起動以降にリセット リクエストが発行された場合は 0x01、それ以外の場合は 0x00 を返します。

サポートされているリクエスト タイプの動作は次のとおりです。

オフセット 0 説明
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x03 書き込み / 読み取り
GET_DEF 0x00

PTZ プリセット

カメラの画角を構成してプリセットの位置に戻すために使用します。

コントロール: GOOGXU_PRESETS

このコントロールは、カメラのパン、チルト、ズーム（PTZ）の値をプリセット構成に設定するために使用します。

Preset Action は、コマンドの目的のアクションを指定するために使用されます。値を 1 に設定すると、現在のパン、チルト、ズームの値が指定されたプリセット インデックスにマッピングされます。値を 2 に設定すると、カメラのパン、チルト、ズームが、指定されたインデックスの以前にマッピングされた値、またはデフォルトの工場座標（以前にマッピングされていない場合）に移行します。値を 3 に設定すると、インデックスは出荷時のデフォルトの座標にリセットされます。

Preset Index は、インデックスにマッピングされた PTZ 座標を指定するために使用します。Preset index が 0 の場合、ホーム座標にマッピングされ、GOOGXU_FRAME_STRATEGY が NONE に設定されている場合、カメラの起動時のデフォルトの位置になります。

コントロール セレクタ 7
オペレーション SET
wLength 2
オフセット フィールド サイズ 値 説明
0 bPresetAction 1 数値 0x01: プリセット
を保存します。 0x02: プリセット
を復元します。 0x03: プリセットをデフォルトにリセットします。（デフォルトは有効なプリセット座標です）。
1 bPresetIndex 1 数値 アクティブなプリセットのインデックス。0 ～ N-1
0 はデフォルトのカメラ開始位置と見なされ、N-1 はプリセット数のベンダー定義定数です。

サポートされているリクエスト タイプの動作は次のとおりです。

オフセット 0 1 説明
GET_MIN 0x00 0x00
GET_MAX 0x03 N-1 サポートされる最大プリセット数
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 書き込みのみ
GET_DEF 0x00 0x00

パンとチルトの補助マッピング

カメラによっては、メカニカル カメラ用のモーターやデジタル PTZ 機能など、特別なコンポーネントが搭載されています。これらの場合、パン、チルト、ズームには標準の V4L2 コントロールを使用します。

コントロール: GOOGXU_PAN_TILT_ABSOLUTE（非推奨）

パンとチルトの補助マッピング コントロールは、UVC 1.5 クラス仕様の第 4 章: クラス固有のリクエスト、セクション 4.2.2.1.14 パンチルト（絶対）コントロールで定義されています。

コントロール: GOOGXU_PAN_TILT_RELATIVE（非推奨）

パンとチルトの補助マッピング コントロールは、UVC 1.5 クラス仕様の第 4 章: クラス固有のリクエスト セクション 4.2.2.1.15 パンチルト（相対）コントロールで定義されています。

リリースノート

このリリースノートでは、このドキュメントの各リビジョンの改善点と新機能について説明します。

2025 年 1 月 27 日

2024 年 5 月 21 日

2023 年 11 月 15 日

有効なフレーミング モードをチェックして解釈するようにテスト スクリプトを更新しました。バイト表現を明確にしました。

2023 年 7 月 21 日

パートナーがこの仕様に準拠しているかどうか実装を検証するためのテスト スクリプトを追加しました。

2023 年 5 月 25 日

プリセットの数に関する GOOGXU_PRESETS の注記を修正しました。N-1 ではなく N にする必要があります。

2023 年 4 月 17 日

初回リリース。