Google Meet 设备 USB Video Class Extension Unit API

本文档简要介绍了 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_CURGET_MINGET_MAXGET_RESGET_LENGET_INFOGET_DEF
SET SET_CUR

相机模式

摄像头模式用于对会议室中的人员进行取景,是以下几项的 tuple

  • 策略(镜头视图)
  • 偏差(音箱或房间)
  • Feed(单个或多个信息流)

每个维度都可以采用以下各部分介绍的值。

自动取景策略

功能 说明
摄像头会停用所有智能取景功能,并允许客户自由控制 PTZ 值。
注意:设置为此取景策略后,摄像头会保持当前的平移、倾斜和缩放位置。
持续取景 (CAZ) 摄像头会根据取景偏差,持续跟踪房间中的人员。
注意:在此模式下,系统会停用 PTZ。
拆分帧 摄像头会根据需要创建任意数量的视频视图。它会根据自动取景画面选项,将这些画面合成单个画面中的功能块,或为每个视图创建单独的视频画面。
注意:在此模式下,系统会停用 PTZ。
动态视图 一个或多个摄像头会尝试提供最佳客房视图。它可以决定是否将多个 Feed 合并为一个 Feed,或者提供当前房间的“有趣”视图。
此视图旨在为通话提供最公平的房间内参与者视图。
注意
  • 大多数会议都应采用此策略。
  • 在此模式下,PTZ 功能处于停用状态。

自动取景偏差

功能 说明
高风险演讲者(演讲者跟踪) 摄像头会尝试以最佳方式拍摄会议室中正在发言的人。
在此场景中,摄像头应偏向于演示者。例如,首席执行官在董事会议室中做演示。
协作
(房间跟踪)
摄像头会尝试以最佳方式取景,将会议室中的所有参与者都纳入画面。在这种情况下,摄像头应平等对待每位参与者。大多数会议都应采用此策略。

自动取景 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-StreamSplit-Frame, Room, Single-StreamDynamic, 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(相对)控制”中定义了平移和倾斜辅助映射控件。

版本说明

以下版本说明反映了本文档各个修订版中的改进和新功能。

2024 年 5 月 21 日

2023 年 11 月 15 日

更新了测试脚本,以检查和解读有效的取景模式。阐明了字节表示法。

2023 年 7 月 21 日

添加了测试脚本,供合作伙伴验证实现是否符合此规范。

2023 年 5 月 25 日

更正了有关预设数量的 GOOGXU_PRESETS 备注。它应为 N,而不是 N-1。

2023 年 4 月 17 日

初始版本。