Google Meet 設備 USB Video Class Extension Unit API

本文件概述 Google Meet 會議系統用來啟用智慧攝影機功能的支援 USB 視訊類別擴充單元 (XU) API。建立此規格的主要目的，是為了影響實務做法，讓這些功能能夠啟用，並為合作夥伴提供更完善的非同步可擴充性和測試功能。

如要進一步瞭解本文件的最新異動內容，請參閱「版本資訊」。

測試設施

為協助合作夥伴驗證是否符合此規格，我們在開發人員模式的 Chromebox 視訊會議解決方案裝置中提供測試設施。啟用寫入檔案系統。在 /etc/chrome_dev.conf 中新增下列行：

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

重新啟動裝置、連接相機和 USB 鍵盤，然後按下 Ctrl-Alt-X，系統就會執行使用中的相機規格相容性，並記錄到 /home/chronos/user/log/chrome。

小端慣例

USB 是 little-endian 標準。本文件內：

  • 多位元數字會以大端序顯示 (並以小端序傳輸)。
  • 位元組陣列位於位元組由小到大記憶體配置中。

舉例來說，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：

  • 策略 (攝影機檢視畫面)
  • 偏差 (講者或房間)
  • 動態饋給 (單一或多個串流)

每個維度可接受下列各節所述的值。

自動取景策略

在「無」以外的所有自動取景模式中，系統會停用手動平移、傾斜和縮放功能。

功能 說明
無 攝影機會停用所有智慧構圖功能，並允許客戶自由控制 PTZ 值。
注意：設定為這項構圖策略時，攝影機會維持在目前的平移、傾斜和縮放位置。
持續取景 (CAZ) 攝影機會根據取景偏誤，持續追蹤房間內的人。
分割影格 相機會視需要建立多個影像檢視畫面。系統會根據「自動設定影像構圖」選項，將影像構圖組合成單一串流中的圖塊，或是為每個檢視畫面建立個別的影片串流。
動態檢視畫面 一或多部攝影機會嘗試提供房間的最佳視野。它可以決定是否要將多個動態饋給合成一個，或提供目前房間的「有趣」檢視畫面。
這個檢視畫面的目的，是讓會議參與者都能在畫面上獲得最公平的畫面。
供應商偏好 相機系統會根據自身邏輯判斷房間的最佳視野。基礎框架策略如有變更，恕不另行通知。舉例來說，如果房間內的人數有所變動，或是攝影機偵測到「重要講者」與「協作」會議的差異，系統就會視情況調整或變更構圖策略。在這個模式下，呼叫 getCur 應傳回 VENDOR_PREFERRED，而非系統選取的基礎構圖模式。

自動取景偏誤

功能 說明
重要講者 (追蹤講者) 攝影機會盡力將房間內正在說話的人納入畫面。
在這種情況下，攝影機應偏向主講者。例如，執行長在董事會會議室中進行簡報。
協同合作
(會議室追蹤)		 攝影機會盡量以最佳角度拍攝會議室內的所有參與者。在這種情況下，攝影機應公平對待每位參與者。

自動取景動態饋給

功能 說明
單一串流 相機會將單一影片串流傳送至主機裝置。
多串流
(處理中)		 相機會將串流內容拆分，並建立多個視訊串流傳送給主機。
注意：這項功能的完整規格和預期行為仍在審查中，不支援，直到本文件的後續修訂版本為止。

自動構圖模式的點陣圖值

除了由空白位元組陣列表示的 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 後面接著七個零位元組)。

指令 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 AutoUpdate / Write / Read
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 預設值
SET_CUR 設定攝影機的 Active Framing 模式

控制組：GOOGXU_REFRAME

這個控制項可用於觸發一次性構圖 (One-Shot Framing)，也稱為 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 設定 One-Shot Framing 要求

人車數量

入座率計算 (OC) 功能可用於估算會議室中的參與者人數，即使攝影機的畫面經過裁剪也一樣。

下表列出 OC 控制項的預期行為，以及與攝影機影像串流和攝影機 LED 指示燈的互動情形。

人車數量計算功能 攝影機影片串流： 攝影機 LED 指示燈應為 GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR 應為 GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR 應為
已啟用 未播放音訊且未設為靜音 開啟 0x01 攝影機完整視野範圍內的人數。
已啟用 串流 開啟 0x01 攝影機完整視野範圍內的人數。
已啟用 已略過 關閉 0x01 已關閉
已關閉 未播放音訊且未設為靜音 關閉 0x00 已關閉
已關閉 串流 開啟 0x00 已關閉
已關閉 已略過 關閉 0x00 已關閉

控制組：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 點陣圖 系統附加的衛星類型清單。包含四個獨立的 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 座標。零 (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

平移和傾斜輔助對應

部分攝影機具有特殊元件，例如機械式攝影機的馬達或數位 PTZ 功能。針對這些功能，請使用標準的 V4L2 控制項來平移、傾斜和縮放。

控制項：GOOGXU_PAN_TILT_ABSOLUTE (已淘汰)

平移和傾斜輔助對應控制項的定義，請參閱「第 4 章：類別特定要求」一節，第 4.2.2.1.14 節「UVC 1.5 類別規範」中的「平移和傾斜 (絕對) 控制項」。

控制項：GOOGXU_PAN_TILT_RELATIVE (已淘汰)

平移和傾斜輔助對應控制項的定義，請參閱「第 4 章：類別特定要求」第 4.2.2.1.15 節「UVC 1.5 類別規格」的「平移和傾斜 (相對) 控制項」。

版本資訊

以下版本資訊列載這份文件各修訂版的新功能和改善項目。

2025 年 1 月 27 日

2024 年 5 月 21 日

2023 年 11 月 15 日

更新測試指令碼，以便檢查及解讀有效的構圖模式。闡明位元組表示法。

2023 年 7 月 21 日

新增測試指令碼，方便合作夥伴驗證導入作業是否符合此規格。

2023 年 5 月 25 日

修正GOOGXU_PRESETS關於預設值數量的註解。應該是 N，而不是 N-1。

2023 年 4 月 17 日

第 1 版。