API de la unidad de extensión de clase de video USB del hardware de Google Meet

En este documento, se describen las APIs de la unidad de extensión de clase de video USB (XU) compatibles que usan los sistemas de conferencias de Google Meet para habilitar funciones de cámara inteligente. El propósito de crear esta especificación es influir en las prácticas para habilitar estas funciones y permitir una mejor escalabilidad y pruebas asíncronas para nuestros socios.

Para obtener detalles sobre los cambios más recientes de este documento, consulta las Notas de la versión.

Instalación de prueba

Para ayudar a los socios a validar el cumplimiento de esta especificación, proporcionamos una función de prueba en los dispositivos Chromebox para reuniones configurados en el modo de desarrollador. Habilita la escritura en el sistema de archivos. Agrega las siguientes líneas a /etc/chrome_dev.conf:

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

Reinicia el dispositivo, conecta la cámara y un teclado USB, presiona Ctrl-Alt-X y se verificará el cumplimiento de las especificaciones de la cámara activa y se registrará en /home/chronos/user/log/chrome.

Convención little-endian

USB es un estándar de orden de bytes little endian. En este documento, se incluye lo siguiente:

  • Los números de varios bytes aparecen en formato big-endian (y se transmiten en formato little-endian).
  • Los arrays de bytes están en el diseño de memoria de orden inferior.

Por ejemplo, 0x12345678 es igual que [0x78, 0x56, 0x34, 0x12].

GUID de la unidad de extensión

Las unidades de extensión que admiten esta especificación de control de XU de Meet deben usar este GUID.

Unidad de extensión GUID
XU de control de periféricos {74D7E924-49C9-4A45-98A3-8A9F60061E83}

Selectores de XU de control de periféricos

Estos son los selectores de XU de control de periféricos definidos.

Selectores de control Valor
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

Tipo de solicitud de control

Los tipos de solicitudes de control se definen en el Capítulo 4: Solicitudes específicas de clase de la Especificación de clase UVC 1.5.

Operación Control de UVC
GET GET_CUR, GET_MIN, GET_MAX, GET_RES, GET_LEN, GET_INFO, GET_DEF
SET SET_CUR

Modos de cámara

Los modos de cámara se usan para encuadrar a las personas en una sala de reuniones y son un tuple de lo siguiente:

  • Estrategia (vista de la cámara)
  • Sesgo (bocina o habitación)
  • Feeds (uno o varios flujos)

Cada dimensión puede tener los valores que se describen en las siguientes secciones.

Estrategia de encuadre automático

En todos los modos de encuadre automático, excepto en “Ninguno”, se inhabilitan el desplazamiento lateral, la inclinación y el zoom manuales.

Función Descripción
Ninguno La cámara inhabilita todas las funciones de enmarcado inteligente y permite que el cliente controle libremente los valores de PTZ.
Nota: Cuando se configura esta estrategia de encuadre, la cámara permanece en su posición actual de desplazamiento lateral, inclinación y zoom.
Enmarcado continuo (CAZ) En función del sesgo de enmarcado, la cámara realiza un seguimiento continuo de las personas que están en la habitación.
Marcos divididos La cámara crea tantas vistas de video como sea necesario. Según la opción Feeds de enmarcado automático, los compone en tarjetas en una sola transmisión o crea transmisiones de video independientes para cada vista.
Vista dinámica Una o más cámaras intentan proporcionar la mejor vista de la habitación. Puede decidir si combinar varios feeds en uno o proporcionar una vista "interesante" de la sala actual.
El propósito de esta vista es proporcionar la vista más equitativa de los participantes en la sala a la llamada.
Preferido por el proveedor El sistema de cámaras usa su propia lógica para determinar la mejor vista de la habitación. La estrategia de enmarcado subyacente está sujeta a cambios sin previo aviso. Por ejemplo, si cambia la cantidad de personas en la sala o la cámara puede detectar la diferencia entre una reunión de "Presentador con mucho en juego" y una de "Colaboración", el sistema puede adaptar o cambiar la estrategia de encuadre según lo considere adecuado en este modo. Cuando se usa este modo, llamar a getCur debería mostrar VENDOR_PREFERRED, y no el modo de enmarcado subyacente que seleccionó el sistema.

Sesgo de encuadre automático

Función Descripción
Presentador de alto riesgo (seguimiento de oradores) La cámara intenta encuadrar mejor a la persona que habla de forma activa en la sala.
En este caso, la cámara debe enfocarse en el presentador. Por ejemplo, el director general en una sala de juntas dando una presentación.
Colaboración
(seguimiento de salas)		 La cámara intenta encuadrar mejor a todos los participantes de la sala. En esta situación, la cámara debe tratar a todos los participantes de manera equitativa.

Feeds con encuadre automático

Función Descripción
Transmisión única La cámara envía una sola transmisión de video al dispositivo host.
Multiflujo
(en proceso)		 La cámara divide la transmisión y crea varias transmisiones de video para enviarlas al host.
Nota: La especificación completa y el comportamiento esperado de esta función están pendientes de revisión y no se admiten hasta que se realicen revisiones posteriores de este documento.

Valores de mapa de bits del modo de enmarcado automático

Excepto por el estado predeterminado de None, que está representado por un array de bytes vacío, cada bit del array de bytes representa un modo de cámara diferente, que es una combinación específica de la estrategia de enmarcado automático, el sesgo de enmarcado automático y los feeds de enmarcado automático.

Feeds con encuadre automático CAZ Marco dividido Dinámico Preferido por el proveedor Sesgo de encuadre automático
Transmisión única D1
D2		 -
D3		 D5
D7		 D9 (bocina o sala) Bocina
Habitación
Multitransmisión -
-		 -
D4		 D6
D8		 - Bocina
Habitación
Modos de marco Valor del modo de fotogramas (byte menos significativo)
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

Este control se usa para obtener o configurar los modos de encuadre de la cámara, como se indica en Valores de mapa de bits del modo de encuadre automático. Cada modo se representa como un bit en su respectivo mapa de bits. El comando GET_RES muestra una máscara de bits de 8 bytes con un valor de cero (0) o uno (1) para indicar, respectivamente, si la función es compatible o no con el dispositivo. Por ejemplo, si una cámara admite CAZ, Speaker, Single-Stream, Split-Frame, Room, Single-Stream y Dynamic, Room, Multi-Stream, pero no otros modos, GET_RES debería mostrar 0x000000000000000085 (es decir, 0b10000101 seguido de siete bytes cero).

El comando SET_CUR se usa para enviar mapas de bits para indicarle a la cámara qué modo de cámara SINGLE habilitar.

Selector de control 1
Operación GET / SET
wLength 8
Desplazamiento Campo Tamaño Valor Descripción
0 bActiveMode 8 Mapa de bits Cómo configurar o restablecer el modo de cámara activa
Notas:

El comportamiento de los tipos de solicitud admitidos es el siguiente:

Desplazamiento 0 Descripción
GET_CUR Obtén el modo de cámara de enmarcado activo
GET_MIN Depende de la cámara
GET_MAX Depende de la cámara
GET_RES Muestra una máscara de bits de 8 bytes de los modos de cámara compatibles.
GET_LEN 0x0008 Longitud
GET_INFO 0x0B AutoUpdate / Write / Read
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 Valor predeterminado
SET_CUR Cómo configurar el modo de cámara de enmarcado activo

Control: GOOGXU_REFRAME

Este control se usa para activar el enmarcado único, también conocido como OTAZ. Cuando se activa la OTAZ, la vista de la cámara se ajusta a la mejor vista de la habitación. Luego, el cliente recupera la capacidad de controlar los valores de PTZ. Si no se admite el enmarcado único, la cámara no debe definir este control.

Selector de control 2
Operación SET
wLength 1
Desplazamiento Campo Tamaño Valor Descripción
0 bReframe 1 Número 0x01 Ejecuta la solicitud de cambio de formato

El comportamiento de los tipos de solicitud admitidos es el siguiente:

Desplazamiento 0 Descripción
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x02 Solo escritura
GET_DEF 0x00
SET_CUR Cómo configurar la solicitud para el enmarcado único

Recuento de ocupación

El recuento de ocupación (OC) es una función que se usa para estimar la cantidad de participantes en una sala de reuniones, a pesar de la vista recortada de la cámara.

En esta tabla, se muestra el comportamiento esperado de los controles de OC y sus interacciones con la transmisión de video de la cámara y el indicador LED de la cámara.

Cuándo se realiza el recuento de ocupación y la transmisión de video de la cámara es la siguiente: El indicador LED de la cámara debe estar GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR debe ser GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR debe ser
Activada No se está transmitiendo y no está silenciado Activado 0x01 Es el recuento de personas en el campo visual completo de la cámara.
Activada Transmisión Activado 0x01 Es el recuento de personas en el campo visual completo de la cámara.
Activada Silenciado Desactivado 0x01 Desactivadas
Desactivadas No se está transmitiendo y no está silenciado Desactivado 0x00 Desactivadas
Desactivadas Transmisión Activado 0x00 Desactivadas
Desactivadas Silenciado Desactivado 0x00 Desactivadas

Control: GOOGXU_OCCUPANCY_COUNTING_TOGGLE

Este control se usa para habilitar o inhabilitar la función de contar ocupantes en una habitación. Si estableces un valor de cero (0), se inhabilita esta función, y si estableces uno (1), se habilita. Si esta función no es compatible, la cámara no debería definir este control.

Selector de control 3
Operación GET / SET
wLength 1
Desplazamiento Campo Tamaño Valor Descripción
0 bOccupancy 1 Booleano Configura la función de recuento de ocupación
0x00 Desactiva la función
0x01 Activa la función

El comportamiento de los tipos de solicitud admitidos es el siguiente:

Desplazamiento 0 Descripción
GET_CUR Muestra si el recuento de ocupación está activado.
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x0B AutoUpdate / Write / Read
GET_DEF 0x00
SET_CUR Habilita o inhabilita la función de recuento de ocupación

Control: GOOGXU_OCCUPANCY_COUNTING_READ

Este control se usa para leer la cantidad de participantes en una sala que informa la cámara cuando el recuento de ocupación está habilitado. Cuando el recuento de ocupación está inhabilitado, la cámara debe inhabilitar este control. Si no se admite el recuento de ocupación, la cámara no debe definir este control.

Selector de control 4
Operación GET
wLength 2
Desplazamiento Campo Tamaño Valor Descripción
0 bNumPeople 2 Número Es la cantidad de ocupantes detectados en la vista. (Solo lectura)

El comportamiento de los tipos de solicitud admitidos es el siguiente:

Desplazamiento 0 Descripción
GET_CUR Muestra la cantidad de ocupantes detectados
GET_MIN 0x0000
GET_MAX 0x00FF
GET_RES 0x0001
GET_LEN 0x0002
GET_INFO 0x09 AutoUpdate / Read
GET_DEF 0x0000

Telemetría y diagnóstico del dispositivo

Estos controles están diseñados para fomentar mejores prácticas de depuración con el hardware de Meet y, por lo general, no están orientados al usuario.

Control: GOOGXU_STATUS_INFO

Este control se usa para consultar información de la cámara host y compartirla con los socios para la depuración.

Selector de control 5
Operación GET
wLength 8
Desplazamiento Campo Tamaño Valor Descripción
0 bNumCameras 1 Número Es la cantidad de satélites adicionales conectados a la cámara principal que pueden afectar la transmisión de la cámara que se muestra al host.
1 bIsMoving 1 Mapa de bits Es 0 cuando la cámara está inactiva y distinto de cero cuando cambian sus valores de PTZ. Los proveedores pueden asignar diferentes ejes o motores a diferentes bits.
2 Undef 6 Undef Se extenderá en el futuro.

El comportamiento de los tipos de solicitud admitidos es el siguiente:

Desplazamiento 0 1 2 Descripción
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 AutoUpdate / Read
GET_DEF 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00

Control: GOOGXU_SATELLITE_INFO

Este control se usa para consultar los dispositivos satelitales que están conectados a este sistema de cámaras.

Selector de control 0x0A
Operación GET
wLength 20
Desplazamiento Campo Tamaño Valor Descripción
0 bSatelliteList 20 Mapa de bits Es la lista de tipos de satélites conectados al sistema. Incluye cuatro ranuras separadas de 5 bytes. Cada uno de los espacios se describe de la siguiente manera:
Desplazamiento Descripción
0 Cantidad de este tipo de satélite.
1-2 Es el ID del proveedor de este tipo de satélite.
3-4 Es el ID del producto para este tipo de satélite.

El comportamiento de los tipos de solicitud admitidos es el siguiente:

Desplazamiento 0 Descripción
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 bytes
GET_INFO 0x09 AutoUpdate / Read
GET_DEF 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00

Control: GOOGXU_STATUS_RESET

Este control se usa para enviar una solicitud de restablecimiento a la cámara. Si estableces un valor de uno (1), se solicita que se restablezca la cámara. La cámara muestra cero (0) si no se recibió ninguna solicitud de reinicio desde el último restablecimiento y uno (1) si se está restableciendo. El restablecimiento debe activar el reinicio de la cámara. (Esto es necesario para los dispositivos con alimentación propia en los que no es útil forzar una desconexión USB para emular un dispositivo con conexión en caliente).

Selector de control 6
Operación GET / SET
wLength 1
Desplazamiento Campo Tamaño Valor Descripción
0 bResetRequest 1 Booleano Envía una solicitud de restablecimiento al host y a las cámaras conectadas.
Muestra 0x01 si se emitió una solicitud de restablecimiento desde el último restablecimiento; de lo contrario, muestra 0x00.

El comportamiento de los tipos de solicitud admitidos es el siguiente:

Desplazamiento 0 Descripción
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x03 Escritura / lectura
GET_DEF 0x00

Ajustes predeterminados de PTZ

Se usa para configurar y restablecer el campo de visión de la cámara en una posición predeterminada.

Control: GOOGXU_PRESETS

Este control se usa para establecer los valores de panorámica, inclinación y zoom (PTZ) de la cámara en una configuración predeterminada.

Preset Action se usa para indicar la acción prevista del comando. Establecer un valor de uno (1) se usa para asignar los valores actuales de paneo, inclinación y zoom a un índice predeterminado proporcionado. Si estableces un valor de dos (2), se debe realizar la transición del paneo, la inclinación y el zoom de la cámara a los valores asignados anteriormente para el índice proporcionado o las coordenadas de fábrica predeterminadas (si no se asignaron anteriormente). Si estableces un valor de tres (3), se restablece el índice a las coordenadas predeterminadas de fábrica.

Preset Index se usa para especificar las coordenadas de PTZ asignadas al índice. El Preset index de cero (0) se asigna a las coordenadas de inicio y debe ser la posición predeterminada de la cámara cuando se activa GOOGXU_FRAME_STRATEGY en NONE.

Selector de control 7
Operación SET
wLength 2
Desplazamiento Campo Tamaño Valor Descripción
0 bPresetAction 1 Número 0x01: Guarda el parámetro de configuración predeterminado
. 0x02: Restablece el parámetro de configuración predeterminado
. 0x03: Restablece el parámetro de configuración predeterminado. (El valor predeterminado debe ser una coordenada predeterminada válida).
1 bPresetIndex 1 Número Es el índice de configuración predeterminada activa. 0~N-1
En el que 0 se considera la posición de inicio predeterminada de la cámara y N-1 es una constante definida por el proveedor para la cantidad de ajustes predeterminados.

El comportamiento de los tipos de solicitud admitidos es el siguiente:

Desplazamiento 0 1 Descripción
GET_MIN 0x00 0x00
GET_MAX 0x03 N-1 Se admiten N ajustes predeterminados máximos
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 Solo escritura
GET_DEF 0x00 0x00

Mapeo auxiliar de desplazamiento y giro

Algunas cámaras tienen componentes especiales, como los motores para cámaras mecánicas o las capacidades de PTZ digitales. Para ello, usa los controles estándar de V4L2 para el paneo, la inclinación y el zoom.

Control: GOOGXU_PAN_TILT_ABSOLUTE (obsoleto)

Los controles de asignación auxiliares de paneo y giro se definen en el Capítulo 4: Solicitudes específicas de clase, Sección 4.2.2.1.14 Control PanTilt (absoluto) de la Especificación de la clase UVC 1.5.

Control: GOOGXU_PAN_TILT_RELATIVE (obsoleto)

Los controles de asignación auxiliares de paneo y giro se definen en el Capítulo 4: Solicitudes específicas de clase, Sección 4.2.2.1.15 Control PanTilt (relativo) de la Especificación de la clase UVC 1.5.

Notas de la versión

Estas notas de la versión reflejan las mejoras y las funciones nuevas en cada revisión de este documento.

27 de enero de 2025

21 de mayo de 2024

15 de noviembre de 2023

Se actualizó la secuencia de comandos de prueba para verificar e interpretar los modos de enmarcado válidos. Se aclararon las representaciones de bytes.

21 de julio de 2023

Se agregó una secuencia de comandos de prueba para que los socios validen las implementaciones para garantizar el cumplimiento de esta especificación.

25 de mayo de 2023

Se corrigió la nota de GOOGXU_PRESETS sobre la cantidad de ajustes predeterminados. Debe ser N, no N-1.

17 de abril de 2023

Versión inicial