このドキュメントでは、インテリジェントなカメラ機能を有効にするために Google Meet の会議システムで使用される、サポートされている USB Video Class Extension Unit(XU)API の概要について説明します。この仕様を作成する目的は、これらの機能を実現するための手法に影響を与え、パートナーに非同期のスケーラビリティとテストを改善することです。
パートナーがこの仕様に準拠していることを検証するため、このテスト スクリプトは実装を分析し、報告します。
このドキュメントの最新の変更点について詳しくは、リリースノートをご覧ください。
リトル エンディアン規則
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 |
コントロール リクエスト タイプ
制御リクエストのタイプは、UVC 1.5 クラス仕様の「4 章: クラス固有のリクエスト」で定義されています。
オペレーション | UVC コントロール |
---|---|
GET |
GET_CUR 、GET_MIN 、GET_MAX 、GET_RES 、GET_LEN 、GET_INFO 、GET_DEF |
SET |
SET_CUR |
カメラモード
カメラモードは、会議室内にいる人をフレームに収めるために使用され、次の tuple
になります。
- 戦略(カメラビュー)
- バイアス(スピーカーまたは部屋)
- フィード(単一または複数の配信)
各ディメンションには、以降のセクションで説明する値を指定できます。
オート フレーミング戦略
機能 | 説明 |
---|---|
なし | カメラではすべてのインテリジェント フレーミング機能が無効になり、クライアントは PTZ 値を自由に制御できます。 注: このフレーミング戦略を設定した場合、カメラのパン、傾斜、ズームの現在の位置が維持されます。 |
追尾フレーミング(CAZ) | そのフレーミングのバイアスに基づき、カメラが室内にいる人物を継続的に追跡します。 注: このモードでは PTZ は無効になります。 |
分割フレーム | カメラは必要なだけ動画ビューを作成します。[オート フレーミング フィード] オプションに基づいて、フィードを 1 つのストリームとして合成するか、ビューごとに個別の動画ストリームを作成します。 注: このモードでは PTZ は無効になります。 |
動的ビュー | 1 台以上のカメラが、室内の最適なビューを提供しようと試みています。また、複数のフィードを 1 つに合成するか、現在の部屋の「興味深い」ビューを提供するかどうかを決定できます。 このビューの目的は、通話の参加者を最も公平に把握できるようにすることです。 注:
|
オート フレーミングのバイアス
機能 | 説明 |
---|---|
重要なプレゼンター(スピーカー トラッキング) | カメラは、室内で積極的に話している人物をできる限りフレームに収めようとしています。 このシナリオでは、カメラをプレゼンターにバイアスする必要があります。たとえば、役員室内の CEO がプレゼンテーションを行っている場合などです。 |
コラボレーション (会議室のトラッキング) |
カメラは、室内にいる参加者全員を最適な位置に収めるよう試みます。この場合、カメラはすべての参加者を公平に扱う必要があります。ほとんどの会議でこの戦略を使用すべきです。 |
オート フレーミング フィード
機能 | 説明 |
---|---|
シングル ストリーム | カメラは単一の動画ストリームをホストデバイスに送信します。 |
マルチストリーム (作業中) |
カメラはストリームを分割し、複数の動画ストリームを作成してホストに送信します。 注: この機能の完全な仕様と予想される動作は、現在レビュー中であり、このドキュメントの今後のリビジョンまでサポートされていません。 |
オート フレーミング モードのビットマップ値
空のバイト配列で表される None
のデフォルト状態を除き、バイト配列の各ビットはオート フレーミング戦略、オート フレーミング バイアス、オート フレーミング フィードの特定の組み合わせである、異なるカメラモードを表します。
ビット インデックス | カナダ | 分割フレーム | 動的 | - |
---|---|---|---|---|
スピーカー | 1 日目 ~ |
- - |
D5 D6 |
シングル ストリーム マルチストリーム |
Room | 2 日目 ~ |
3 日目 、4 日目 |
7 日 D8 日 |
シングル ストリーム マルチストリーム |
フレームモード | フレームモード値(最下位バイト) |
---|---|
None |
0x00 |
CAZ, Speaker, Single-Stream |
0x01 |
CAZ, Room, Single-Stream |
0x02 |
Split-Frame, Room, Single-Stream |
0x04 |
Split-Frame, Room, Multi-Stream |
0x08 |
Dynamic, Speaker, Single-Stream |
0x10 |
Dynamic, Speaker, Multi-Stream |
0x20 |
Dynamic, Room, Single-Stream |
0x40 |
Dynamic, Room, Multi-Stream |
0x80 |
コントロール: GOOGXU_FRAME_STRATEGY
このコントロールは、オート フレーミング モードのビットマップ値に記載されているカメラのフレーミング モードを取得または設定するために使用されます。各モードは、それぞれのビットマップでビットとして表されます。コマンド GET_RES
は、値が 0 または 1 の 8 バイトの長いビットマスクを返します。ビットマスクによって、機能がそれぞれサポートされていないか、またはデバイスでサポートされているかが示されます。たとえば、カメラが CAZ, Speaker, Single-Stream
、Split-Frame, Room, Single-Stream
、Dynamic, Room, Multi-Stream
をサポートしていて、他のモードをサポートしていない場合、GET_RES
は 0x000000000000000085(つまり、0b10000101
の後に 7 個の 0 バイトが続く)を返します。
SET_CUR
コマンドは、ビットマップを送信してカメラにどの SINGLE カメラモードを有効にするかを指定するために使用します。
コントロール セレクタ | 1 | |||
---|---|---|---|---|
オペレーション | GET / SET |
|||
wLength |
8 | |||
オフセット | 項目 | サイズ | 値 | 説明 |
0 | bActiveMode |
8 | ビットマップ | アクティブ カメラモードを設定する、または返す |
注:
|
サポートされているリクエスト タイプの動作は次のとおりです。
オフセット | 0 | 説明 |
---|---|---|
GET_CUR |
アクティブ フレーミング カメラ モードを取得する | |
GET_MIN |
カメラに依存 | |
GET_MAX |
カメラに依存 | |
GET_RES |
サポートされているカメラモードの 8 バイト長のビットマスクを返します | |
GET_LEN |
0x0008 | 期間 |
GET_INFO |
0x0B | 自動更新 / 書き込み / 読み取り |
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 は以下の値にする必要があります |
---|---|---|---|---|
有効 | ストリーミングおよびミュートされていない | On | 0x01 |
カメラの視野全体に入っている人の数。 |
有効 | ストリーミング | On | 0x01 |
カメラの視野全体に入っている人の数。 |
有効 | ミュートされました | Off | 0x01 |
通知 OFF |
通知 OFF | ストリーミングおよびミュートされていない | Off | 0x00 |
通知 OFF |
通知 OFF | ストリーミング | On | 0x00 |
通知 OFF |
通知 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 | 自動更新 / 書き込み / 読み取り |
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 | 自動更新 / 読み取り |
GET_DEF |
0x0000 |
デバイスのテレメトリーと診断
これらのコントロールは Meet ハードウェアでのデバッグを改善するためのもので、通常はユーザーには表示されません。
コントロール: GOOGXU_STATUS_INFO
このコントロールは、デバッグのためにホストカメラから情報をクエリしてパートナーと共有するために使用されます。
コントロール セレクタ | 5 | |||
---|---|---|---|---|
オペレーション | GET |
|||
wLength |
8 | |||
オフセット | 項目 | サイズ | 値 | 説明 |
0 | bNumCameras |
1 | 数値 | メインデバイスに接続されている追加のカメラの数。 |
1 | bIsMoving |
1 | ビットマップ | カメラがアイドル状態の場合は 0、移動中はゼロ以外の値になります。ベンダーは、さまざまな軸やモーターを異なるビットにマッピングできます。 |
2 | Undef |
6 | 未定義 | 将来延長される予定。 |
サポートされているリクエスト タイプの動作は次のとおりです。
オフセット | 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 | 自動更新 / 読み取り | ||
GET_DEF |
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 座標を指定するために使用されます。ゼロ(0)の Preset index
はホーム座標にマッピングされ、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 | 最大 N 個のプリセットをサポート |
GET_RES |
0x01 | 0x01 | |
GET_LEN |
0x02 | 0x00 | 0x0002 |
GET_INFO |
0x02 | 書き込みのみ | |
GET_DEF |
0x00 | 0x00 |
パンとチルトの補助マッピング
一部のカメラは特殊なコンポーネント(機械式カメラ用のモーターなど)を備えており、パンとチルトを意図したとおりに機能させるには、標準の V4L2 コントロールに XU コマンドをマッピングする必要があります。
これらのコントロールは、UVC 仕様のドキュメントにあるパンとチルトの絶対コントロールと相対コントロールを模倣し、ホストデバイスでこれらのコントロールを正しくマッピングするための標準的な方法を提供します。
コントロール: GOOGXU_PAN_TILT_ABSOLUTE
パンとチルトの補助マッピング コントロールは、UVC 1.5 クラス仕様の「第 4 章: クラス固有のリクエスト」セクション 4.2.2.1.14 パンチルト(絶対)コントロールで定義されています。
コントロール セレクタ | 8 | |||
---|---|---|---|---|
オペレーション | GET/SET |
|||
wLength |
8 | |||
オフセット | 項目 | サイズ | 値 | 説明 |
0 | dwPanAbsolute |
4 | 署名付き番号 | アドレス指定されるパン(絶対)コントロールの属性の設定。 |
4 | dwTiltAbsolute |
4 | 署名付き番号 | 指定された傾斜(絶対)コントロールの属性の設定。 |
サポートされているリクエスト タイプの動作は次のとおりです。
オフセット | 0 | 4 | 説明 |
---|---|---|---|
GET_MIN |
カメラに依存 | ||
GET_MAX |
カメラに依存 | ||
GET_RES |
カメラに依存 | ||
GET_LEN |
0x0008 | ||
GET_INFO |
0x0B | 自動更新 / 書き込み / 読み取り | |
GET_DEF |
0x00000000 | 0x00000000 |
コントロール: GOOGXU_PAN_TILT_RELATIVE
パンと傾斜の補助マッピング コントロールは、UVC 1.5 クラス仕様の「第 4 章: クラス固有のリクエスト」セクション 4.2.2.1.15「パンチルト(相対)コントロール」で定義されています。
コントロール セレクタ | 9 | |||
---|---|---|---|---|
オペレーション | GET/SET |
|||
wLength |
4 | |||
オフセット | 項目 | サイズ | 値 | 説明 |
0 | bPanRelative |
1 | 署名付き番号 | アドレス指定されるパン(相対)コントロールの属性の設定: 0: 停止 1: 時計回り方向 0xFF: 反時計回り方向 |
1 | bPanSpeed |
1 | 数値 | パンの動きの速度。 |
2 | bTiltRelative |
1 | 署名付き番号 | アドレス指定される傾斜(相対)コントロールの属性の設定: 0: 停止 1: イメージング プレーンを上を指す 0xFF: イメージング プレーンを下を指す |
3 | bTiltSpeed |
1 | 数値 | 傾斜の動きの速度。 |
サポートされているリクエスト タイプの動作は次のとおりです。>
オフセット | 0 | 1 | 2 | 3 | 説明 |
---|---|---|---|---|---|
GET_MIN |
カメラに依存 | ||||
GET_MAX |
カメラに依存 | ||||
GET_RES |
カメラに依存 | ||||
GET_LEN |
0x04 | 0x00 | 0x0004 | ||
GET_INFO |
0x0B | 自動更新 / 書き込み / 読み取り | |||
GET_DEF |
0x00 | 0x00 | 0x00 | 0x00 |
関連トピック
- Linux USB ビデオクラス(UVC)ドライバ
- 動画クラス v1.5 ドキュメント セット
- USB 2.0 仕様
- Google Meet ハードウェア ヘルプセンター
- Google Workspace 管理者ヘルプセンターの「Google Meet ハードウェア」セクション
- Google Meet ハードウェア USB 動画クラス拡張機能ユニット API のテスト スクリプト
リリースノート
このリリースノートには、このドキュメントの各リビジョンの改善と新機能が反映されています。
2023 年 11 月 15 日
有効なフレーミング モードを確認して解釈するようにテスト スクリプトを更新しました。バイト表現を明確にしました。
2023 年 7 月 21 日
パートナーがこの仕様に準拠しているかどうかを検証するためのテスト スクリプトを追加しました。
2023 年 5 月 25 日
プリセット数に関する GOOGXU_PRESETS の注記を修正しました。N-1 ではなく N にする必要があります。
2023 年 4 月 17 日
初回リリース。