本文档简要介绍了 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 |
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（单个或多个视频流）
每个维度都可以采用下面几部分中介绍的值。
自动取景策略
| 功能 | 说明 |
|---|---|
| 无 | 摄像头会停用所有智能取景功能，并允许客户端自由控制云台拍摄值。 注意：设置为此取景策略时，相机会保持当前的平移、倾斜度和缩放位置。 |
| 连续取景 (CAZ) | 基于取景偏差，相机会持续跟踪房间里的人物。 注意：此模式下会停用云台摄像头。 |
| 分割 | 摄像头会根据需要创建任意数量的视频视图。该功能会根据自动取景 Feed 选项，在单个视频流中将 Feed 合成为图块，或者为每个视图创建单独的视频流。 注意：此模式下会停用云台摄像头。 |
| 动态视图 | 一个或多个摄像头试图提供房间的最佳视角。它可以决定是否将多个 Feed 合成为一个 Feed，或者是否提供当前房间的“有趣”视图。 此视图的目的是提供最公平的会议室内参与者对通话的了解。 注意：
|
自动取景偏差
| 功能 | 说明 |
|---|---|
| 高风险演示者（演讲者跟踪） | 摄像头会尝试以最佳取景方式框出正在聊天室中发言的人。 在这种情况下，摄像头应偏向于演示者。例如，首席执行官在会议室中演示。 |
| 协作 （会议室跟踪） |
摄像头会尝试以最佳方式取景框内的所有参与者。在这种情况下，摄像头应公平对待每位参与者。大多数会议都应使用此策略。 |
自动取景 Feed
| 功能 | 说明 |
|---|---|
| 单流 | 摄像头将单个视频串流发送到主机设备。 |
| 多数据流 （进行中） |
摄像头会拆分视频串流并创建多个要发送给主机的视频流。 注意：此功能的完整规范和预期行为正在等待审核，并且只有在本文档后续修订之后才支持此功能。 |
自动取景模式位图值
除了由空字节数组表示的 None 默认状态外，字节数组中的每个位都表示不同的相机模式，这是自动取景策略、自动取景偏差和自动取景 Feed 的特定组合。
| 位索引 | 加拿大银行 | 分割 | 动态 | - |
|---|---|---|---|---|
| 免提 | 第 1 天 - |
- - |
第 5 天 第 6 天 |
单流 多流 |
| Room | 第 2 天 - |
第 3 天 第 4 天 |
第 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 后跟 7 个零字节）。
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 | 自动更新 / 写入 / 读取 |
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 | 自动更新 / 写入 / 读取 |
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；当镜头移动时为非零值。供应商可随意将不同的轴或电机映射到不同的位。 |
| 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 |
0x08 | 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 |
0x03 | 写入 / 读取 |
GET_DEF |
0x00 |
云台预设
用于配置摄像头的视野范围并将其恢复到预设位置。
对照组：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 |
平移和倾斜辅助地图
某些相机具有特殊组件，例如机械相机的电机，这些组件需要将 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 |
0x0B | 自动更新 / 写入 / 读取 | |
GET_DEF |
0x00000000 | 0x00000000 |
对照组：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 | 签名数 | 针对目标倾斜（相对）控制的属性设置： 0：停止 1：将成像平面朝上 0xFF：使成像平面朝下 |
| 3 | bTiltSpeed |
1 | 数字 | 倾斜移动的速度。 |
受支持的请求类型的行为如下：>
| 偏移值 | 0 | 1 | 2 | 3 | 说明 |
|---|---|---|---|---|---|
GET_MIN |
依赖于摄像头 | ||||
GET_MAX |
依赖于摄像头 | ||||
GET_RES |
依赖于摄像头 | ||||
GET_LEN |
0x04 | 0x00 | 0x0004 | ||
GET_INFO |
0x0B | 自动更新 / 写入 / 读取 | |||
GET_DEF |
0x00 | 0x00 | 0x00 | 0x00 |
相关主题
- Linux USB Video Class (UVC) 驱动程序
- Video Class v1.5 文档集
- USB 2.0 规范
- Google Meet 设备帮助中心
- Google Workspace 管理员帮助中心的“Google Meet 设备”部分
- Google Meet 设备 USB Video Class Extension Unit API 测试脚本
版本说明
以下版本说明反映了本文档各个修订版本中的改进和新功能。
2023 年 11 月 15 日
更新了测试脚本，以检查和解释有效的取景模式。阐明了字节表示法。
2023 年 7 月 21 日
添加了测试脚本，供合作伙伴验证实现是否符合本规范。
2023 年 5 月 25 日
更正了关于预设数量的 GOOGXU_PRESETS 备注。应为 N，而不是 N-1。
2023 年 4 月 17 日
初始版本。