Google Meet 設備 USB Video Class Extension Unit API

本文件概述了 Google Meet 會議系統用於啟用智慧相機功能支援的 USB Video Class Extension Unit (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

控制要求類型

控制要求類型定義於第 4 章：UVC 1.5 類別規格的類別特定要求。

作業 UVC 控制
GET GET_CUR，GET_MIN，GET_MAX，GET_RES，GET_LEN，GET_INFO，GET_DEF
SET SET_CUR

相機模式

相機模式可用於拍攝會議室中的個人，也是以下項目的 tuple：

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

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

自動取景策略

功能 說明
無 攝影機會停用所有智慧構圖功能，並允許客戶自由控制 PTZ 值。
注意：設定為這項構圖策略時，攝影機會維持在目前的平移、傾斜和縮放位置。
追蹤定焦 (CAZ) 攝影機會根據取景偏誤，持續追蹤房間內的人。
注意：在這個模式中，PTZ 會停用。
分割影格 相機會視需要建立多個影像檢視畫面。系統會根據「自動設定影像構圖」選項，將影像構圖組合成單一串流中的圖塊，或是為每個檢視畫面建立個別的影片串流。
注意：在這個模式中，PTZ 會停用。
動態檢視 一或多部攝影機會嘗試提供房間的最佳視野。它可以決定是否要將多個動態饋給合成一個，或提供目前房間的「有趣」檢視畫面。
這個檢視畫面的目的，是讓參與者在通話中獲得最公平的畫面。
注意事項：
  • 大部分會議都應採用這項策略。
  • 在這個模式下，PTZ 會停用。

自動取景偏誤

功能 說明
高風險講者 (追蹤講者) 攝影機會盡力將房間內正在說話的人納入畫面。
在這種情況下，攝影機應偏向講者。例如，執行長在董事會會議室中進行簡報。
協同合作
(會議室追蹤)		 攝影機會盡可能為會議室中的所有參與者取景，在這種情況下，攝影機應公平對待每位參與者。大部分會議都應採用這項策略。

自動取景動態饋給

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

自動取景模式點陣圖值

除了由空白位元組陣列表示的 None 預設狀態之外，位元組陣列中的每個位元都代表不同的相機模式，這些模式是自動對焦策略、自動對焦偏差和自動對焦動態饋給的特定組合。

位元索引 CAZ 分割畫面 動態 -
喇叭 D1
-		 -
-		 D5
D6		 單一串流
多串流
Room D2
-		 D3
D4		 D7
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 會傳回 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_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 類別規格。

版本資訊

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

2024 年 5 月 21 日

2023 年 11 月 15 日

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

2023 年 7 月 21 日

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

2023 年 5 月 25 日

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

2023 年 4 月 17 日

第 1 版。