Google Meet 设备 USB Video Class Extension Unit API

本文档概述了 Google Meet 会议系统使用的受支持的 USB 视频类扩展单元 (XU) API，这些 API 可实现智能摄像头功能。创建此规范的目的是影响实践，以实现这些功能，并为我们的合作伙伴提供更好的异步可伸缩性和测试。

如需详细了解本文档的最新更改，请参阅版本说明。

测试设施

为了帮助合作伙伴验证是否符合此规范，我们在设置为开发者模式的 Chromebox for Meetings 设备中提供了一个测试工具。启用写入文件系统。 将以下行添加到 /etc/chrome_dev.conf 中：

--enable-logging
--log-level=0

重启设备，连接摄像头和 USB 键盘，按 Ctrl-Alt-X，系统将执行并记录有效摄像头的规范合规性到 /var/log/chrome/chrome（如果使用已签名的映像，则记录到 /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
GOOGXU_SATELLITE_INFO 0x0A

控制请求类型

控制请求类型在 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) 根据取景偏好，摄像头会持续跟踪聊天室中的人物。
分屏帧 摄像头会根据需要创建尽可能多的视频视图。根据自动取景 Feed 选项，系统会将这些视图组合成单个视频流中的平铺视图，或者为每个视图创建单独的视频流。
动态视图 一个或多个摄像头会尝试提供房间的最佳视角。它可以决定是否将多个 Feed 合成为一个，或者提供当前房间的“有趣”视图。
此视图旨在为通话提供最公平的会议室参与者视图。
供应商首选 摄像头系统会使用自己的逻辑来确定房间的最佳视角。基础框架策略可能会发生变更，恕不另行通知。例如，如果房间内的人数发生变化，或者摄像头可以检测到“高风险演示者”会议与“协作”会议之间的区别，则系统可以在此模式下随意调整或更改取景策略。在此模式下，调用 getCur 应返回 VENDOR_PREFERRED，而不是系统选择的基础取景模式。

自动取景偏差

功能 说明
高风险演示者（演讲者追踪） 摄像头会尝试以最佳方式将会议室中正在说话的人纳入画面。
在这种情况下，摄像头应偏向演示者。例如，会议室中的 CEO 正在做演示。
协作
（会议室跟踪）		 摄像头会尝试以最佳方式将会议室中的所有参会者纳入画面。在这种情况下，摄像头应公平对待每位参与者。

自动取景 Feed

功能 说明
单流 摄像头向主机发送单个视频流。
多数据流
（正在开发中）		 摄像头会拆分视频流，并创建多个视频流以发送给主机。
注意：此功能的完整规范和预期行为正在等待审核，在本文档的后续修订版本发布之前，不支持此功能。

自动取景模式位图值

除了以空字节数组表示的默认状态 None 之外，字节数组中的每个位都表示一种不同的相机模式，该模式是自动取景策略、自动取景偏差和自动取景 Feed 的特定组合。

自动取景 Feed CAZ 分帧 动态 供应商首选 自动取景偏差
单流 D1
D2		 -
D3		 D5
D7		 D9（音箱或会议室） 音箱
房间
多数据流 -
-		 -
D4		 D6
D8		 - 音箱
房间
帧模式 帧模式值（最低有效字节）
None 0x0000
CAZ, Speaker, Single-Stream 0x0001
CAZ, Room, Single-Stream 0x0002
Split-Frame, Room, Single-Stream 0x0004
Split-Frame, Room, Multi-Stream 0x0008
Dynamic, Speaker, Single-Stream 0x0010
Dynamic, Speaker, Multi-Stream 0x0020
Dynamic, Room, Single-Stream 0x0040
Dynamic, Room, Multi-Stream 0x0080
Vendor-preferred, Single-Stream 0x0100

对照组：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 自动更新 / 写入 / 读取
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，当其 PTZ 值发生变化时为非零值。供应商可以自由地将不同的轴或电机映射到不同的位。
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_SATELLITE_INFO

此控制变量用于查询连接到相应相机系统的卫星设备。

控制选择器 0x0A
操作 GET
wLength 20
偏移值 字段 大小 值 说明
0 bSatelliteList 20 位图 附加到系统的卫星类型的列表。包括四个单独的 5 字节插槽。各个卡槽的说明如下：
偏移值 说明
0 相应卫星类型的数量。
1-2 相应卫星类型的供应商 ID。
3-4 相应卫星类型的商品 ID。

受支持的请求类型的行为如下：

偏移值 0 说明
GET_MIN 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
GET_MAX 0xFF 0xFF 0xFF 0xFF 0xFF
0xFF 0xFF 0xFF 0xFF 0xFF
0xFF 0xFF 0xFF 0xFF 0xFF
0xFF 0xFF 0xFF 0xFF 0xFF
GET_RES 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
GET_LEN 0x14 20 个字节
GET_INFO 0x09 自动更新 / 读取
GET_DEF 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 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

平移和倾斜辅助地图

有些摄像头具有特殊组件，例如机械摄像头的电机，或数字云台功能。对于这些设备，请使用标准 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 类规范的平移/倾斜（相对）控制”中定义。

版本说明

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

2025 年 8 月 13 日

2025 年 1 月 27 日

2024 年 5 月 21 日

2023 年 11 月 15 日

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

2023 年 7 月 21 日

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

2023 年 5 月 25 日

更正了有关预设数量的 GOOGXU_PRESETS 注释。应该是 N，而不是 N-1。

2023 年 4 月 17 日

初始版本。