В этом документе описываются поддерживаемые 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 — это стандарт с порядком байтов little endian. В этом документе:
- Многобайтовые числа отображаются в порядке байтов big-endian (и передаются в порядке байтов little-endian).
- Байтовые массивы имеют структуру памяти с порядком байтов little-endian.
Например, 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 |
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 из:
- Стратегия (вид камеры)
- Асимметрия (динамика или акустика помещения)
- Потоки (один или несколько потоков)
Каждое измерение может принимать значения, описанные в следующих разделах.
Стратегия автоматического кадрирования
Во всех автоматических режимах кадрирования, кроме "Нет", ручное панорамирование, наклон и масштабирование отключены.
| Особенность | Описание |
|---|---|
| Никто | Камера отключает все интеллектуальные функции кадрирования и позволяет клиенту свободно управлять значениями 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 |
Control: 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 | Растровое изображение | Установить или вернуть активный режим камеры |
Примечания:
| ||||
Поведение поддерживаемых типов запросов следующее:
| Компенсировать | 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 | Установить режим активной кадрирующей камеры |
Control: GOOGXU_REFRAME
Этот параметр используется для запуска покадровой съемки (One-Shot Framing, 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 и их взаимодействие с видеопотоком камеры и светодиодным индикатором камеры.
| Когда подсчет заполняемости | Видеопоток с камеры: | Светодиодный индикатор камеры должен быть | 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_SATELLITE_INFO
Этот элемент управления используется для запроса информации о спутниковых устройствах, подключенных к данной системе видеонаблюдения.
| селектор управления | 0x0A | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Операция | GET | |||||||||||
wLength | 20 | |||||||||||
| Компенсировать | Поле | Размер | Ценить | Описание | ||||||||
| 0 | bSatelliteList | 20 | Растровое изображение | Список типов спутников, подключенных к системе. Включает четыре отдельных 5-байтовых слота. Каждый из слотов описывается следующим образом:
|
Поведение поддерживаемых типов запросов следующее:
| Компенсировать | 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 |
Предустановки 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 | Н-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)
- Комплект документов «Видеоурок» версии 1.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 г.
Первый релиз.