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 , и соответствие спецификации активной камеры будет проверено и зарегистрировано в /home/chronos/user/log/chrome .

Соглашение с прямым порядком байтов

USB — это стандарт с прямым порядком байтов. В этом документе:

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

Например, 0x12345678 — это то же самое, что [0x78, 0x56, 0x34, 0x12] .

GUID модуля расширения

Блоки расширения, поддерживающие эту спецификацию управления Meet XU, должны использовать этот 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

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

Типы запросов управления определены в Главе 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, разделенные кадры, динамический просмотр) не должны перемещаться для отслеживания людей, если не включена потоковая передача. В частности, если потоковая передача отключена и включен подсчет присутствия, камера не должна физически поворачиваться, наклоняться или масштабироваться, чтобы следить за людьми в комнате.

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

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

Смещение автоматического кадрирования

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

Ленты с автокадрированием

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

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

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

Битовый индекс	КАЗ	Разделенный кадр	Динамический	-
Спикер	Д1 -	- -	Д5 Д6	Однопоточный Многопотоковая
Комната	Д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 за которым следуют семь нулей). байты).

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

Примечания :

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

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

Этот элемент управления используется для запуска One-Shot Framing, также известного как 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		Установить запрос на кадрирование One-Shot

Подсчет занятости

Подсчет присутствия (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	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			Автообновление/чтение
GET_DEF	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 пресетов
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

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

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

21 мая 2024 г.

• Удален тестовый сценарий в пользу нового средства тестирования CfM , которое выполняет SET , а также поддерживает проверку камер Series 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 г.

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