Google Meet 設備 USB Video Class Extension Unit API

本文列出 Google Meet 會議系統支援的 USB 視訊類別擴充單元 (XU) API，這些 API 可啟用智慧攝影機功能。建立這項規格的目的，是為了影響做法，以啟用這些功能，並讓合作夥伴能進行更完善的非同步擴充性和測試。

如要瞭解這份文件的最新異動，請參閱「版本資訊」。

測試設施

為協助合作夥伴驗證是否符合這項規格，我們在設為開發人員模式的 Chromebox for Meetings 裝置中提供測試設施。啟用寫入檔案系統。在 /etc/chrome_dev.conf 中新增下列程式碼：

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

重新啟動裝置，連接攝影機和 USB 鍵盤，按下 Ctrl-Alt-X，系統會執行並記錄有效攝影機的規格相容性至 /var/log/chrome/chrome (如果使用已簽署的映像檔，則為 /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 (講者或會議室) 喇叭
Room
多重串流 -
-		 -
D4		 D6
D8		 - 喇叭
Room
影格模式 影格模式值 (最低有效位元組)
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 點陣圖 設定或返回「Active Camera Mode」(作用中攝影機模式)
注意：

支援的要求類型行為如下：

偏移 0 說明
GET_CUR 取得 Active Framing 攝影機模式
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 已關閉
已關閉 未串流且未設為靜音 關閉 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 類別規格」的「PanTilt (Relative) Control」。

版本資訊

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

2025 年 8 月 13 日

2025 年 1 月 27 日

2024 年 5 月 21 日

2023 年 11 月 15 日

更新測試指令碼，以檢查及解讀有效的取景模式。清楚闡釋位元組表示法。

2023 年 7 月 21 日

新增測試指令碼，供合作夥伴驗證導入項目是否符合這項規格。

2023 年 5 月 25 日

已修正預設集數量相關的GOOGXU_PRESETS附註。應為 N，而非 N-1。

2023 年 4 月 17 日

第 1 版。