API-интерфейсы модуля расширения класса USB-видео для оборудования Google Meet

В этом документе описаны поддерживаемые API USB Video Class Extension Unit (XU), используемые конференц-системами Google Meet для реализации интеллектуальных функций камеры. Цель создания данной спецификации — повлиять на практику реализации этих функций и обеспечить нашим партнёрам более эффективную асинхронную масштабируемость и тестирование.

Подробную информацию о последних изменениях в этом документе см. в Примечаниях к выпуску .

Испытательный центр

Чтобы помочь партнёрам проверить соответствие этой спецификации, мы предоставляем тестовую платформу на устройствах 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 — это стандарт с прямым порядком байтов. В этом документе:

• Многобайтовые числа отображаются в формате big endian (и передаются в формате little endian).
• Массивы байтов располагаются в памяти с прямым порядком байтов.

Например, 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

Тип запроса управления

Типы запросов управления определены в Главе 4: Запросы, специфичные для класса , Спецификации классов UVC 1.5 .

Операция	УФ-контроль
GET	GET_CUR , GET_MIN , GET_MAX , GET_RES , GET_LEN , GET_INFO , GET_DEF
SET	SET_CUR

Режимы камеры

Режимы камеры используются для кадрирования людей в конференц-зале и представляют собой tuple из следующих режимов:

• Стратегия (вид камеры)
• Предвзятость (оратор или комната)
• Ленты (одиночные или множественные потоки)

Каждое измерение может принимать значения, описанные в следующих разделах.

Примечания :

• Периферийные устройства должны оставаться в состоянии, установленном клиентом. За исключением GOOGXU_FRAME_STRATEGY , в случае, если элемент управления влияет на стратегию, камера обычно должна по умолчанию иметь значение None , если не указано иное.
• Физические PTZ-камеры с функцией панорамирования, наклона и масштабирования (CAZ, Split Frames, Dynamic View) не должны перемещаться для отслеживания людей, если не включена потоковая передача. В частности, если потоковая передача отключена и включен подсчёт занятости, камера не должна физически перемещаться, наклоняться или масштабироваться для отслеживания людей в помещении.

Стратегия автоматического фрейминга

Во всех режимах автоматического кадрирования, кроме «Нет», ручное панорамирование, наклон и масштабирование отключены.

Особенность	Описание
Никто	Камера отключает все функции интеллектуального кадрирования и позволяет клиенту свободно управлять значениями PTZ. Примечание: при выборе этой стратегии кадрирования камера остается в текущем положении панорамирования, наклона и масштабирования.
Непрерывное кадрирование (CAZ)	Используя метод кадрирования, камера непрерывно отслеживает людей в помещении.
Разделенные кадры	Камера создаёт необходимое количество видеовидов. В зависимости от опции автоматического кадрирования видео , она либо объединяет их в один поток, либо создаёт отдельные видеопотоки для каждого вида.
Динамический вид	Одна или несколько камер пытаются обеспечить наилучший обзор помещения. Система может решить, объединять ли несколько изображений в одно или предоставить «интересный» вид текущего помещения. Целью данного представления является обеспечение наиболее справедливого обзора участников вызова, находящихся в помещении.
Предпочтительный поставщик	Система камер использует собственную логику для определения наилучшего обзора помещения. Базовая стратегия кадрирования может быть изменена без предварительного уведомления. Например, если количество людей в помещении меняется или камера обнаруживает разницу между режимами «Высокоуровневый докладчик» и «Совместная работа», система может адаптировать или изменить стратегию кадрирования по своему усмотрению в этом режиме. В этом режиме вызов getCur должен возвращать значение VENDOR_PREFERRED, а не базовый режим кадрирования, выбранный системой.

Предвзятость автофрейминга

Особенность	Описание
Ведущий с высокими ставками (отслеживание спикеров)	Камера пытается наилучшим образом запечатлеть человека, активно говорящего в комнате. В этом случае камера должна быть направлена ​​в сторону докладчика. Например, когда генеральный директор проводит презентацию в зале заседаний.
Сотрудничество (Отслеживание номеров)	Камера пытается наилучшим образом охватить всех участников в комнате. В этом случае камера должна относиться к каждому участнику одинаково.

Автоматическое кадрирование лент

Особенность	Описание
Однопоточный	Камера отправляет один видеопоток на хост-устройство.
Многопоточный (Работа в процессе)	Камера разделяет поток и создает несколько видеопотоков для отправки на хост. Примечание: Полная спецификация и ожидаемое поведение этой функции ожидают рассмотрения и не будут поддерживаться до последующих версий этого документа.

Значения растрового изображения в режиме автоматического кадрирования

За исключением состояния по умолчанию None , которое представлено пустым массивом байтов, каждый бит в массиве байтов представляет отдельный режим камеры, который является определенной комбинацией стратегии автоматического кадрирования , смещения автоматического кадрирования и каналов автоматического кадрирования .

Автоматическое кадрирование лент	КАЗ	Раздельная рамка	Динамичный	Предпочтительный поставщик	Предвзятость автофрейминга
Однопоточный	Д1 Д2	- Д3	Д5 Д7	D9 (динамик или комната)	Спикер Комната
Многопоточный	- -	- Д4	Д6 Д8	-	Спикер Комната

Режимы кадра	Значение режима кадра (младший байт)
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 должна возвращать 0x0000000000000000085 (т. е. 0b10000101 за которым следуют семь нулевых байтов).

Команда SET_CUR используется для отправки растровых изображений, сообщающих камере, какой режим SINGLE камеры следует включить.

Примечания :

• Недопустимо устанавливать несколько бит в массиве байтов.
• Если выбранный клиентом режим не поддерживается, камера игнорирует запрос и возвращает ошибку.

Селектор управления	1
Операция	GET / SET
wLength	8
Компенсировать	Поле	Размер	Ценить	Описание
0	bActiveMode	8	Растровое изображение	Установить или вернуть активный режим камеры
Примечания: Значения растрового изображения обсуждаются в разделе Значения растрового изображения в режиме автоматического кадрирования . D9-D64: Зарезервировано, установлено на ноль.

Поведение поддерживаемых типов запросов следующее:

Компенсировать	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. Если покадровое кадрирование не поддерживается, камера не должна определять этот элемент управления.

Примечания :

• Эта команда считается элементом управления EXECUTE_ON_WRITE и выполняется каждый раз при установке элемента управления.
• Перефрейминг может быть запущен только в том случае, если стратегия фрейминга установлена ​​на NONE .

Селектор управления	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 и их взаимодействие с видеопотоком камеры и светодиодным индикатором камеры.

Когда подсчет занятости	& видеопоток с камеры:	Светодиодный индикатор камеры должен быть	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 Идентификатор поставщика данного типа спутника. 3-4 Идентификатор продукта для этого типа спутника.

Поведение поддерживаемых типов запросов следующее:

Компенсировать	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 для эмуляции горячего подключения нецелесообразно.)

Примечание: при сбросе настроек устройство должно запустить повторную нумерацию.

Внимание: отсутствие повторной регистрации нарушает ожидания UVC.

Селектор управления	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 .

Примечания :

• Эта команда считается элементом управления EXECUTE_ON_WRITE и выполняется каждый раз при установке элемента управления.
• Переход к предустановке возможен только в том случае, если для стратегии кадрирования установлено значение 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	Н-1	Поддерживается N max предустановок
GET_RES	0x01	0x01
GET_LEN	0x02	0x00	0x0002
GET_INFO	0x02		Только писать
GET_DEF	0x00	0x00

Вспомогательное картографирование панорамирования и наклона

Некоторые камеры оснащены специальными компонентами, например, двигателями для механических камер или цифровыми функциями PTZ. Для этого используйте стандартные элементы управления 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 .

Похожие темы

• Драйвер Linux USB Video Class (UVC)
• Набор документов Video Class v1.5
• Спецификация USB 2.0
• Справочный центр оборудования Google Meet
• Раздел «Оборудование Google Meet» в справочном центре администратора Google Workspace

Примечания к выпуску

В этих примечаниях к выпуску отражены улучшения и новые функции в каждой редакции данного документа.

13 августа 2025 г.

• Исправлены данные об испытательном центре .

27 января 2025 г.

• Добавлена Vendor-preferred стратегия кадрирования в GOOGXU_FRAME_STRATEGY .
• Добавлен новый элемент управления: GOOGXU_SATELLITE_INFO .

21 мая 2024 г.

• Удален тестовый сценарий в пользу нового испытательного комплекса CfM , который отрабатывает SET , а также поддерживает проверку камер серии One.
• Уточнены поля в GOOGXU_STATUS_INFO .
• Уточнено поведение GOOGXU_STATUS_RESET .
• Устаревшие GOOGXU_PAN_TILT_ABSOLUTE и GOOGXU_PAN_TILT_RELATIVE .

15 ноября 2023 г.

Обновлён тестовый скрипт для проверки и интерпретации допустимых режимов кадрирования. Уточнены байтовые представления.

21 июля 2023 г.

Добавлен тестовый сценарий для партнеров, позволяющий проверить реализации на соответствие данной спецификации.

25 мая 2023 г.

Исправлено примечание GOOGXU_PRESETS относительно количества предустановок. Должно быть N, а не N-1.

17 апреля 2023 г.

Первоначальный выпуск.