Google Meet 設備 USB Video Class Extension Unit API

本文件概述 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 0 x 3
GOOGXU_OCCUPANCY_COUNTING_READ 0x04
GOOGXU_STATUS_INFO 0 x 5
GOOGXU_STATUS_RESET 0 x 6
GOOGXU_PRESETS 0x07
GOOGXU_PAN_TILT_ABSOLUTE 0 x 8
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 預設狀態以外，位元組陣列中的每個位元都代表不同的相機模式，該模式是自動取景策略、自動取景偏誤和自動取景動態饋給的具體組合。

位元索引 加利福尼亞州 分割畫面 動態 -
喇叭 D1
-		 -
-		 第 5 天
D6		 單一串流
多串流
Room D2
：		 D3
D4		 第 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 0 x 8
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 (0) 或一 (1) 的 8 位元組位元遮罩，分別表示裝置是否支援或支援該功能。舉例來說，如果相機支援 CAZ, Speaker, Single-Stream、Split-Frame, Room, Single-Stream 和 Dynamic, Room, Multi-Stream，但沒有其他模式，則 GET_RES 應傳回 0x00000000000000085 (也就是 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 0 x 00 億 自動更新 / 寫入 / 讀取
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 0 x 00 億 自動更新 / 寫入 / 讀取
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 時為 0，移動時則不為 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 0 x 8 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 0 x 3 寫入 / 讀取
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 0 x 3 N-1 支援 N 個預設預設值
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 唯寫
GET_DEF 0x00 0x00

平移及傾斜輔助對應

部分相機有特殊元件 (例如機械相機的馬達)，需要將 XU 指令對應至標準 V4L2 控制項，才能正常運作。

這些控制項模仿 UVC 規格說明文件中的平移和傾斜控制項，為主機裝置提供正確對應這些控制項的標準方法。

控制組：GOOGXU_PAN_TILT_ABSOLUTE

平移和傾斜輔助對應控制項定義於 UVC 1.5 類別規格的第 4 章：類別專屬要求第 4.2.2.1.14 PanTilt (絕對) 控制項。

控制項選取器 8
作業 GET/SET
wLength 8
偏移 欄位 大小 值 說明
0 dwPanAbsolute 4 已簽署的數字 所處理平移 (絕對) 控制項的屬性設定。
4 dwTiltAbsolute 4 已簽署的數字 處理的傾斜 (絕對) 控制項屬性設定。

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

偏移 0 4 說明
GET_MIN 相機裝置
GET_MAX 相機裝置
GET_RES 相機裝置
GET_LEN 0x0008
GET_INFO 0 x 00 億 自動更新 / 寫入 / 讀取
GET_DEF 000000000 000000000

控制組：GOOGXU_PAN_TILT_RELATIVE

平移和傾斜輔助對應控制項定義於 UVC 1.5 類別規格的第 4 章：類別專屬要求第 4.2.2.1.15 PanTilt (相對) 控制項。

控制項選取器 9
作業 GET/SET
wLength 4
偏移 欄位 大小 值 說明
0 bPanRelative 1 已簽署的數字 對應平移 (相對) 控制項的屬性設定：
0: 停止
1：往順時針方向移動
0xFF：往逆時針方向移動
1 bPanSpeed 1 編號 平移移動的速度。
2 bTiltRelative 1 已簽署的數字 所定傾斜 (Relative) 控制項的屬性設定：
0: 停止
1：將影像平面往上
0xFF：將影像面朝下
3 bTiltSpeed 1 編號 傾斜移動速度。

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

偏移 0 1 2 3 說明
GET_MIN 相機裝置
GET_MAX 相機裝置
GET_RES 相機裝置
GET_LEN 0x04 0x00 0x0004
GET_INFO 0 x 00 億 自動更新 / 寫入 / 讀取
GET_DEF 0x00 0x00 0x00 0x00

版本資訊

這些版本資訊反映了本文件各修訂版本的改善項目和新功能。

2023 年 11 月 15 日

更新測試指令碼，以便檢查並解讀有效的取景模式。說明位元組表示法。

2023 年 7 月 21 日

為合作夥伴新增測試指令碼，用於驗證實作項目是否符合這項規範。

2023 年 5 月 25 日

已更正有關預設數的 GOOGXU_PRESETS 附註。其應為 N，而非 N-1。

2023 年 4 月 17 日

第 1 版。