В этом документе описаны поддерживаемые API-интерфейсы USB Video Class Extension Unit (XU), используемые конференц-системами Google Meet для включения функций интеллектуальных камер. Цель создания этой спецификации — повлиять на практику, позволяющую реализовать эти функции и обеспечить лучшую асинхронную масштабируемость и тестирование для наших партнеров.
Чтобы помочь партнерам проверить соответствие этой спецификации, этот тестовый сценарий анализирует вашу реализацию и составляет отчеты о ней.
Подробную информацию о последних изменениях в этом документе см. в Примечаниях к выпуску .
Соглашение с прямым порядком байтов
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 :
- Стратегия (вид с камеры)
- Предвзятость (динамик или комната)
- Ленты (один или несколько потоков)
Каждое измерение может принимать значения, описанные в следующих разделах.
Стратегия автоматического кадрирования
| Особенность | Описание |
|---|---|
| Никто | Камера отключает все функции интеллектуального кадрирования и позволяет клиенту свободно управлять значениями PTZ. Примечание. При выборе этой стратегии кадрирования камера остается в текущем положении панорамирования, наклона и масштабирования. |
| Непрерывный кадр (CAZ) | В зависимости от смещения кадра камера постоянно отслеживает людей в комнате. Примечание. 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 | Битовая карта | Установить или вернуть режим активной камеры |
Примечания:
| ||||
Поведение поддерживаемых типов запросов следующее:
| Компенсировать | 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. Если покадровое кадрирование не поддерживается, камера не должна определять этот элемент управления.
| Селектор управления | 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, когда камера находится в режиме ожидания, и ненулевое значение, когда она движется. Поставщики могут свободно сопоставлять разные оси или двигатели с разными битами. |
| 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 для эмуляции горячего подключения бесполезно.
| Селектор управления | 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 |
Вспомогательное картографирование панорамирования и наклона
Некоторые камеры имеют специальные компоненты, такие как двигатели для механических камер, которые требуют сопоставления команд XU со стандартными элементами управления V4L2, чтобы панорамирование и наклон работали должным образом.
Эти элементы управления имитируют абсолютные и относительные элементы управления панорамированием и наклоном в документации спецификации UVC, предоставляя хост-устройствам стандартный способ правильного сопоставления этих элементов управления.
Элемент управления: GOOGXU_PAN_TILT_ABSOLUTE
Вспомогательные элементы управления отображением панорамирования и наклона определены в Главе 4: Запросы, специфичные для класса, раздел 4.2.2.1.14 Управление панорамированием (абсолютное) спецификации класса UVC 1.5 .
| Селектор управления | 8 | |||
|---|---|---|---|---|
| Операция | GET/SET | |||
wLength | 8 | |||
| Компенсировать | Поле | Размер | Ценить | Описание |
| 0 | dwPanAbsolute | 4 | Подписанный номер | Настройка атрибута адресуемого элемента управления панорамированием (абсолютным). |
| 4 | dwTiltAbsolute | 4 | Подписанный номер | Настройка атрибута адресного элемента управления наклоном (абсолютным). |
Поведение поддерживаемых типов запросов следующее:
| Компенсировать | 0 | 4 | Описание |
|---|---|---|---|
GET_MIN | Зависит от камеры | ||
GET_MAX | Зависит от камеры | ||
GET_RES | Зависит от камеры | ||
GET_LEN | 0x0008 | ||
GET_INFO | 0x0B | Автообновление/запись/чтение | |
GET_DEF | 0x00000000 | 0x00000000 |
Элемент управления: GOOGXU_PAN_TILT_RELATIVE
Вспомогательные элементы управления отображением панорамирования и наклона определены в Главе 4: Запросы, специфичные для класса, раздел 4.2.2.1.15 Управление панорамированием (относительное) спецификации класса UVC 1.5 .
| Селектор управления | 9 | |||
|---|---|---|---|---|
| Операция | GET/SET | |||
wLength | 4 | |||
| Компенсировать | Поле | Размер | Ценить | Описание |
| 0 | bPanRelative | 1 | Подписанный номер | Настройка атрибута адресуемого элемента управления панорамой (относительно): 0: Стоп 1: движение по часовой стрелке 0xFF: движение против часовой стрелки. |
| 1 | bPanSpeed | 1 | Число | Скорость движения панорамы. |
| 2 | bTiltRelative | 1 | Подписанный номер | Настройка атрибута адресного элемента управления наклоном (относительным): 0: Стоп 1: направить плоскость изображения вверх 0xFF: направить плоскость изображения вниз. |
| 3 | bTiltSpeed | 1 | Число | Скорость наклонного движения. |
Поведение поддерживаемых типов запросов следующее:>
| Компенсировать | 0 | 1 | 2 | 3 | Описание |
|---|---|---|---|---|---|
GET_MIN | Зависит от камеры | ||||
GET_MAX | Зависит от камеры | ||||
GET_RES | Зависит от камеры | ||||
GET_LEN | 0x04 | 0x00 | 0x0004 | ||
GET_INFO | 0x0B | Автообновление/запись/чтение | |||
GET_DEF | 0x00 | 0x00 | 0x00 | 0x00 |
похожие темы
- Драйвер Linux USB Video Class (UVC)
- Набор документов Video Class v1.5
- Спецификация USB 2.0
- Справочный центр оборудования Google Meet
- Раздел «Оборудование Google Meet» Справочного центра администратора Google Workspace
- Сценарий тестирования API-интерфейсов USB Video Class Extension Unit оборудования Google Meet
Примечания к выпуску
Эти примечания к выпуску отражают улучшения и новые функции в каждой версии этого документа.
15 ноября 2023 г.
Обновлен тестовый сценарий для проверки и интерпретации допустимых режимов кадрирования. Уточнены представления байтов.
21 июля 2023 г.
Добавлен тестовый скрипт для партнеров для проверки реализаций на соответствие этой спецификации.
25 мая 2023 г.
Исправлено примечание GOOGXU_PRESETS относительно количества пресетов. Это должно быть N, а не N-1.
17 апреля 2023 г.
Изначальный выпуск.