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 (XU) de la clase de video USB compatibles que utilizan los sistemas de conferencia de Google Meet para habilitar funciones inteligentes de la cámara. El objetivo 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 en 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 herramienta de prueba en los dispositivos Chromebox para Reuniones configurados en 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 registrará el cumplimiento de las especificaciones de la cámara activa en /var/log/chrome/chrome (si usas una imagen firmada, se registrará en /home/chronos/user/log/chrome).

Convención little-endian

USB es un estándar little-endian. En este documento, se incluye la siguiente información:

  • Los números multibyte aparecen en formato big-endian (y se transmiten en formato little-endian).
  • Los arrays de bytes se encuentran en el diseño de memoria little-endian.

Por ejemplo, 0x12345678 es lo mismo 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
Unidad periférica de control XU {74D7E924-49C9-4A45-98A3-8A9F60061E83}

Selectores de XU de control periférico

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

Selectores de controles 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 la clase de la Especificación de la 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 tuple de lo siguiente:

  • Estrategia (vista de cámara)
  • Sesgo (bocina o habitación)
  • Feeds (una o varias transmisiones)

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

Estrategia de encuadre automático

En todos los modos de encuadre automático, excepto “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 encuadre inteligente y permite que el cliente controle libremente los valores de la cámara 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) Según el sesgo de encuadre, la cámara rastrea continuamente a las personas en la sala.
Dividir fotogramas La cámara crea tantas vistas de video como sean necesarias. Según la opción Feeds de encuadre automático, los compone en mosaicos en una sola transmisión o crea transmisiones de video separadas para cada vista.
Vista dinámica Una o más cámaras intentan proporcionar la mejor vista de la habitación. Puede decidir si componer varios feeds en uno o proporcionar una vista "interesante" de la habitación 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 la cámara usa su propia lógica para determinar la mejor vista de la habitación. La estrategia de encuadre 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 de alto nivel" 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 encuentra en este modo, llamar a getCur debería devolver VENDOR_PREFERRED, y no el modo de encuadre subyacente que seleccionó el sistema.

Sesgo de encuadre automático

Función Descripción
Presentador de alto riesgo (seguimiento del orador) La cámara intenta encuadrar de la mejor manera a la persona que está hablando en la sala.
En este caso, la cámara debe enfocarse en el presentador. Por ejemplo, el CEO en una sala de reuniones dando una presentación.
Colaboración
(seguimiento de sala)		 La cámara intenta encuadrar de la mejor manera posible a todos los participantes de la sala. En este caso, la cámara debe tratar a cada participante de manera equitativa.

Feeds con encuadre automático

Función Descripción
Single-Stream La cámara envía una sola transmisión de video al dispositivo host.
Multi-Stream
(en desarrollo)		 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 revisiones posteriores de este documento.

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

A excepción del estado predeterminado de None, que se representa con 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 encuadre automático, la tendencia del encuadre automático y los feeds de encuadre automático.

Feeds con encuadre automático CAZ Split-Frame Dinámico Preferido por el proveedor Sesgo de encuadre automático
Single-Stream D1
D2		 -
D3		 D5
D7		 D9 (bocina o habitación) Bocina
Habitación
Multi-Stream -
-		 -
D4		 D6
D8		 - Bocina
Habitación
Modos de fotogramas Valor del modo de fotograma (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 establecer 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 mapa de bits respectivo. El comando GET_RES devuelve una máscara de bits de 8 bytes con un valor de cero (0) o uno (1) para indicar, respectivamente, si el dispositivo no admite la función o si la admite. 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 devolver 0x000000000000000085 (es decir, 0b10000101 seguido de siete bytes cero).

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

Selector de controles 1
Operación GET / SET
wLength 8
Desplazamiento Campo Tamaño Valor Descripción
0 bActiveMode 8 Mapa de bits Establece o devuelve el modo de cámara activa
Notas:

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

Desplazamiento 0 Descripción
GET_CUR Obtén el modo de cámara de Encuadre activo
GET_MIN Depende de la cámara
GET_MAX Depende de la cámara
GET_RES Devuelve una máscara de bits de 8 bytes de largo 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 encuadre activo

Control: GOOGXU_REFRAME

Este control se usa para activar el encuadre de un solo disparo, también conocido como OTAZ. Cuando se activa la función de OTAZ, la vista de la cámara se ajusta a la mejor vista de la habitación. Después, el cliente recupera la capacidad de controlar los valores de PTZ. Si no se admite el encuadre de un solo disparo, la cámara no debe definir este control.

Selector de controles 2
Operación SET
wLength 1
Desplazamiento Campo Tamaño Valor Descripción
0 bReframe 1 Número 0x01 Ejecutar solicitud de Reframe

El comportamiento de los tipos de solicitudes 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 Configura la solicitud para el encuadre de una sola toma

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 la cámara y sus interacciones con la transmisión de video por Internet de la cámara y el indicador LED de la cámara.

Cuándo se activa 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 debería 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 que cuenta a los ocupantes de una habitación. Si se establece un valor de cero (0), se inhabilita esta función, y si se establece un valor de uno (1), se habilita. Si esta función no es compatible, la cámara no debe definir este control.

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

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

Desplazamiento 0 Descripción
GET_CUR Devuelve 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 Cómo habilitar o inhabilitar 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 se habilita el recuento de ocupación. 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 controles 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 solicitudes admitidos es el siguiente:

Desplazamiento 0 Descripción
GET_CUR Devuelve 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 tienen como objetivo fomentar mejores prácticas de depuración con el hardware de Meet y, por lo general, no están disponibles para los usuarios.

Control: GOOGXU_STATUS_INFO

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

Selector de controles 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 devuelve 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 Indefinido Se extenderá en el futuro.

El comportamiento de los tipos de solicitudes 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 controles 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 una de las posiciones se describe de la siguiente manera:
Desplazamiento Descripción
0 Cantidad para 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 solicitudes 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 se establece un valor de uno (1), se solicita que se restablezca la cámara. La cámara devuelve cero (0) si no se solicitó reiniciar la cámara 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 autoalimentados en los que no es útil forzar una desconexión USB para emular una conexión en caliente).

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

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

Desplazamiento 0 Descripción
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x03 Lectura y escritura
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.

El Preset Action se usa para indicar la acción prevista del comando. Se usa un valor de uno (1) para asignar los valores actuales de panoramización, inclinación y zoom a un índice de ajustes predeterminados proporcionado. Si se establece un valor de dos (2), se debería 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 a las coordenadas predeterminadas de fábrica (si no se asignaron anteriormente). Si se establece un valor de tres (3), se restablece el índice a las coordenadas predeterminadas de fábrica.

El parámetro 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 la casa y debe ser la posición predeterminada de la cámara cuando se activa si el GOOGXU_FRAME_STRATEGY está configurado como NONE.

Selector de controles 7
Operación SET
wLength 2
Desplazamiento Campo Tamaño Valor Descripción
0 bPresetAction 1 Número 0x01: Guarda el ajuste predeterminado
. 0x02: Restablece el ajuste predeterminado
. 0x03: Restablece el ajuste predeterminado a la configuración predeterminada. (El valor predeterminado debe ser una coordenada preestablecida válida).
1 bPresetIndex 1 Número Índice del ajuste predeterminado activo. 0~N-1
, donde 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 solicitudes admitidos es el siguiente:

Desplazamiento 0 1 Descripción
GET_MIN 0x00 0x00
GET_MAX 0x03 N-1 Cantidad máxima de ajustes predeterminados admitidos
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 Solo escritura
GET_DEF 0x00 0x00

Mapeo auxiliar de paneo e inclinación

Algunas cámaras tienen componentes especiales, como los motores de las cámaras mecánicas o las capacidades de PTZ digitales. Para estos, 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 e inclinación se definen en el capítulo 4: Solicitudes específicas de la clase, sección 4.2.2.1.14 Control de paneo e inclinación (absoluto) de la Especificación de la clase UVC 1.5.

Control: GOOGXU_PAN_TILT_RELATIVE (obsoleto)

Los controles auxiliares de asignación de paneo y tilt se definen en el Capítulo 4: Solicitudes específicas de la clase, Sección 4.2.2.1.15 Control de paneo y tilt (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 nuevas funciones de cada revisión de este documento.

13 de agosto de 2025

27 de enero de 2025

21 de mayo de 2024

15 de noviembre de 2023

Se actualizó el script de prueba para verificar e interpretar los modos de encuadre 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 en relación con el cumplimiento de esta especificación.

25 de mayo de 2023

Nota corregida sobre la cantidad de ajustes predeterminados.GOOGXU_PRESETS Debería ser N, no N-1.

17 de abril de 2023

Versión inicial