本文档简要介绍了 Google Meet 会议系统用于启用智能摄像头功能的受支持 USB 视频类扩展单元 (XU) API。制定此规范的目的是影响实践,以启用这些功能,并为合作伙伴提供更好的异步可伸缩性和测试功能。
如需详细了解本文档的最新更改,请参阅版本说明。
测试设施
为了帮助合作伙伴验证是否符合此规范,我们在设置为开发者模式的 Chromebox for Meetings 设备中提供了测试设施。启用写入文件系统。将以下行添加到 /etc/chrome_dev.conf
:
--enable-logging
--log-level=0
重启设备,连接摄像头和 USB 键盘,然后按 Ctrl-Alt-X
,系统会执行有效摄像头的规范合规性检查,并将结果记录到 /home/chronos/user/log/chrome
。
小端字节序惯例
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
:
- 策略(镜头视图)
- 偏差(音箱或房间)
- Feed(单个或多个信息流)
每个维度都可以采用以下各部分介绍的值。
自动取景策略
功能 | 说明 |
---|---|
无 | 摄像头会停用所有智能取景功能,并允许客户自由控制 PTZ 值。 注意:设置为此取景策略后,摄像头会保持当前的平移、倾斜和缩放位置。 |
持续取景 (CAZ) | 摄像头会根据取景偏差,持续跟踪房间中的人员。 注意:在此模式下,系统会停用 PTZ。 |
拆分帧 | 摄像头会根据需要创建任意数量的视频视图。它会根据自动取景画面选项,将这些画面合成单个画面中的功能块,或为每个视图创建单独的视频画面。 注意:在此模式下,系统会停用 PTZ。 |
动态视图 | 一个或多个摄像头会尝试提供最佳客房视图。它可以决定是否将多个 Feed 合并为一个 Feed,或者提供当前房间的“有趣”视图。 此视图旨在为通话提供最公平的房间内参与者视图。 注意:
|
自动取景偏差
功能 | 说明 |
---|---|
高风险演讲者(演讲者跟踪) | 摄像头会尝试以最佳方式拍摄会议室中正在发言的人。 在此场景中,摄像头应偏向于演示者。例如,首席执行官在董事会议室中做演示。 |
协作 (房间跟踪) |
摄像头会尝试以最佳方式取景,将会议室中的所有参与者都纳入画面。在这种情况下,摄像头应平等对待每位参与者。大多数会议都应采用此策略。 |
自动取景 Feed
功能 | 说明 |
---|---|
单串流 | 摄像头会向主机设备发送单个视频流。 |
多串流 (正在开发中) |
摄像头会拆分视频流,并创建多个视频流以发送到主机。 注意:此功能的完整规范和预期行为正在等待审核,在本文档的后续修订版本中不受支持。 |
自动取景模式位图值
除了由空字节数组表示的默认状态 None
之外,字节数组中的每个位都代表一种不同的相机模式,这是自动取景策略、自动取景偏差和自动取景 Feed 的特定组合。
位索引 | CAZ | 分屏 | 动态 | - |
---|---|---|---|---|
扬声器 | D1 - |
- - |
D5 D6 |
单串流 多串流 |
Room | D2 - |
D3 D4 |
第 7 天 第 8 天 |
单串流 多串流 |
帧模式 | 帧模式值(最低有效字节) |
---|---|
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 | 位图 | 设置或返回“Active Camera Mode”(主动摄像头模式) |
注意:
|
受支持的请求类型的行为如下所示:
偏移值 | 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 |
设置主动取景相机模式 |
对照组: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_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 坐标。Preset index
为零 (0) 时,系统会将其映射到主屏幕坐标,并且当 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 控件进行平移、倾斜和缩放。
对照组:GOOGXU_PAN_TILT_ABSOLUTE
(已废弃)
UVC 1.5 类规范第 4 章“类专用请求”的 4.2.2.1.14 节“PanTilt(绝对)控制”中定义了平移和倾斜辅助映射控件。
对照组:GOOGXU_PAN_TILT_RELATIVE
(已废弃)
UVC 1.5 类规范第 4 章“类专用请求”的 4.2.2.1.15 节“PanTilt(相对)控制”中定义了平移和倾斜辅助映射控件。
相关主题
- Linux USB 视频类 (UVC) 驱动程序
- “视频课程”v1.5 文档集
- USB 2.0 规范
- Google Meet 设备帮助中心
- Google Workspace 管理员帮助中心的“Google Meet 硬件”部分
版本说明
以下版本说明反映了本文档各个修订版中的改进和新功能。
2024 年 5 月 21 日
- 移除了测试脚本,改用新的 CfM 测试设施,该设施会运行
SET
,并且还支持对 Series One 摄像头进行验证。 - 阐明了
GOOGXU_STATUS_INFO
中的字段。 - 阐明了
GOOGXU_STATUS_RESET
的行为。 - 废弃了
GOOGXU_PAN_TILT_ABSOLUTE
和GOOGXU_PAN_TILT_RELATIVE
。
2023 年 11 月 15 日
更新了测试脚本,以检查和解读有效的取景模式。阐明了字节表示法。
2023 年 7 月 21 日
添加了测试脚本,供合作伙伴验证实现是否符合此规范。
2023 年 5 月 25 日
更正了有关预设数量的 GOOGXU_PRESETS
备注。它应为 N,而不是 N-1。
2023 年 4 月 17 日
初始版本。