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 unidades de extensión de clase de video (XU) USB compatibles que usan los sistemas de conferencias de Google Meet para habilitar funciones de cámara inteligentes. 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 ayudar a los socios a validar el cumplimiento de esta especificación, esta secuencia de comandos de prueba analiza la implementación y genera informes sobre ella.

Para obtener información sobre los cambios más recientes que se realizaron en este documento, consulta Notas de la versión.

Convención de Little-endian

El USB es un estándar Little-endian. En este documento se incluye lo siguiente:

  • Los números de varios bytes aparecen con formato big-endian (y se transmiten en formato Little-endian).
  • Los arrays de bytes están 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
Control de periféricos XU {74D7E924-49C9-4A45-98A3-8A9F60061E83}

Selectores XU de control de periféricos

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

Controlar selectores Valor
GOOGXU_FRAME_STRATEGY 0x01
GOOGXU_REFRAME 0x02
GOOGXU_OCCUPANCY_COUNTING_TOGGLE 0x03
GOOGXU_OCCUPANCY_COUNTING_READ 0x04
GOOGXU_STATUS_INFO 0 × 05
GOOGXU_STATUS_RESET 6 x 0
GOOGXU_PRESETS 0x07
GOOGXU_PAN_TILT_ABSOLUTE 0 × 08
GOOGXU_PAN_TILT_RELATIVE 0x09

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 de 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 personas en una sala de reuniones y son un tuple de lo siguiente:

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

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

Estrategia de encuadre automático

Función Descripción
Ninguna La cámara inhabilita todas las funciones inteligentes de encuadre y le permite al cliente controlar libremente los valores PTZ.
Nota: Cuando se establece esta estrategia de encuadre, la cámara permanece en la posición de desplazamiento lateral, inclinación y zoom actuales.
Enmarcado continuo (CAZ) Según el sesgo del encuadre, la cámara sigue continuamente a las personas que están en la habitación.
Nota: La PTZ se inhabilita en este modo.
Marcos divididos La cámara crea todas las vistas de video necesarias. Según la opción Encuadre automático de feeds, los feeds se redactan en mosaicos en una sola transmisión o se crean transmisiones de video por Internet separadas para cada vista.
Nota: La PTZ se inhabilita en este modo.
Vista dinámica Una o más cámaras intentan ofrecer la mejor vista de la habitación. Puede decidir si componer o no varios feeds en uno o proporcionar una vista "interesante" de la habitación actual.
El propósito de esta vista es ofrecer la visión más equitativa de los participantes en la sala para la llamada.
Notas:
  • La mayoría de las reuniones deberían usar esta estrategia.
  • La PTZ está inhabilitada en este modo.

Sesgo de encuadre automático

Función Descripción
Presentador de alto nivel (seguimiento del orador) La cámara intenta encuadrar mejor a la persona que habla activamente en la sala.
En este escenario, la cámara debe orientar al presentador. Por ejemplo, el director general en una sala de juntas dando una presentación.
Colaboración
(seguimiento de Room)		 La cámara intenta encuadrar mejor a todos los participantes de la sala. En este escenario, la cámara debe tratar a todos los participantes de manera equitativa. La mayoría de las reuniones deberían usar esta estrategia.

Feeds de encuadre automático

Función Descripción
Transmisión única La cámara envía una sola transmisión de video por Internet al dispositivo host.
Varias transmisiones
(trabajo en curso)		 La cámara divide la transmisión y crea varias transmisiones de video por Internet 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 las revisiones posteriores de este documento.

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

Excepto por el 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, el sesgo de encuadre automático y los feeds de encuadre automático.

Índice de bits CAZ Marco dividido Dinámico -
Bocina D1
-		 -
-		 D5
D6		 Transmisión única
Transmisión múltiple
Room D2
-		 D3
D4		 D7
D8		 Transmisión única
Transmisión múltiple
Modos de encuadre Valor de modo de trama (byte menos significativo)
None 0 × 00
CAZ, Speaker, Single-Stream 0x01
CAZ, Room, Single-Stream 0x02
Split-Frame, Room, Single-Stream 0x04
Split-Frame, Room, Multi-Stream 0 × 08
Dynamic, Speaker, Single-Stream 0 × 10
Dynamic, Speaker, Multi-Stream 0 × 20
Dynamic, Room, Single-Stream 0 × 40
Dynamic, Room, Multi-Stream 0 × 80

Control: GOOGXU_FRAME_STRATEGY

Este control se usa para obtener o establecer los modos de encuadre de la cámara como se enumeran en los 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 el dispositivo no admite o no la función. 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 cero bytes).

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

Selector de control 1
Operación GET / SET
wLength 8
Desplazamiento Campo Tamaño Valor Descripción
0 bActiveMode 8 Mapa de bits Establecer o regresar el Modo de cámara activa
Notas:

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

Desplazamiento 0 Descripción
GET_CUR Obtener el modo de cámara de enmarcado activo
GET_MIN Funciones que dependen de la cámara
GET_MAX Funciones que dependen 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 0 x 0 mil millones Actualización automática / escritura / lectura
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 Valor predeterminado
SET_CUR Establecer el modo de cámara de encuadre activo

Control: GOOGXU_REFRAME

Este control se usa para activar el Enmarcado único, también conocido como OTAZ. Cuando se activa el modo 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 encuadre único, la cámara no debería 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 Ejecutar solicitud de replanteamiento

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

Desplazamiento 0 Descripción
GET_MIN 0 × 00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x02 Solo escritura
GET_DEF 0 × 00
SET_CUR Establece la solicitud para el enmarcado de un solo ejemplo

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 por Internet de la cámara y su indicador LED.

Cuando el recuento de ocupación es y la transmisión de video de la cámara es: El indicador LED de la cámara debería estar El valor de GET_CUR de GOOGXU_OCCUPANCY_COUNTING_TOGGLE debe ser El valor de GET_CUR de GOOGXU_OCCUPANCY_COUNTING_READ debe ser
Activada No está transmitiendo y no silenciado Activo 0x01 La cantidad de personas en el campo visual completo de la cámara.
Activada Transmisión Activo 0x01 La cantidad de personas en el campo visual completo de la cámara.
Activada Se silenció Desactivado 0x01 Desactivadas
Desactivadas No está transmitiendo y no silenciado Desactivado 0x00 Desactivadas
Desactivadas Transmisión Activo 0x00 Desactivadas
Desactivadas Se silenció Desactivado 0x00 Desactivadas

Control: GOOGXU_OCCUPANCY_COUNTING_TOGGLE

Este control se usa para habilitar o inhabilitar la función a fin de contar a los ocupantes de una habitación. Si se establece un valor de cero (0), se inhabilita esta función y uno (1), se habilita. Si no se admite esta función, 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 Configurar la función de recuento de ocupación
0x00 Desactivar función
0x01 Activar función

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

Desplazamiento 0 Descripción
GET_CUR Mostrar si el recuento de ocupación está activado
GET_MIN 0 × 00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0 x 0 mil millones Actualización automática / escritura / lectura
GET_DEF 0 × 00
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 está habilitado el recuento de ocupación. Si se inhabilita esta función, la cámara debe desactivar este control. Si no se admite el recuento de ocupación, la cámara no debería definir este control.

Selector de control 4
Operación GET
wLength 2
Desplazamiento Campo Tamaño Valor Descripción
0 bNumPeople 2 Número 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 Número de retorno de ocupantes detectados
GET_MIN 0x0000
GET_MAX 0x00FF
GET_RES 0x0001
GET_LEN 0x0002
GET_INFO 0x09 Actualización automática / lectura
GET_DEF 0x0000

Telemetría y diagnóstico del dispositivo

Estos controles tienen como objetivo fomentar mejores prácticas de depuración con hardware de Meet y, por lo general, no están para los usuarios.

Control: GOOGXU_STATUS_INFO

Este control se usa para consultar información de la cámara host y compartirla con 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 La cantidad de cámaras adicionales conectadas al dispositivo principal.
1 bIsMoving 1 Mapa de bits 0 cuando la cámara está inactiva y un valor distinto de cero cuando está en movimiento. Los proveedores tienen la libertad de asignar diferentes ejes o motores a diferentes bits.
2 Undef 6 Dejar de definir Se extenderá en el futuro.

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

Desplazamiento 0 1 2 Descripción
GET_MIN 0 × 00 0 × 00 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 0 × 08 0 × 00 0x0008
GET_INFO 0x09 Actualización automática / lectura
GET_DEF 0 × 00 0 × 00 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 solicitará que se restablezca la cámara. La cámara muestra cero (0) si no se solicitó reiniciar la cámara desde el último restablecimiento y un (1) si se está restableciendo. Un restablecimiento activa el mismo comportamiento que una reconexión de hardware. Esta opción es útil para dispositivos autogenerados en los que no resulta útil forzar una desconexión por USB para emular una 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 la solicitud de restablecimiento se emitió desde el último restablecimiento, de lo contrario, 0x00.

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

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

Ajustes predeterminados de PTZ

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

Control: GOOGXU_PRESETS

Este control se usa para establecer los valores de desplazamiento lateral, 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. Si se establece un valor de uno (1), se usan para asignar los valores actuales de desplazamiento lateral, inclinación y zoom a un índice predeterminado proporcionado. Si se establece un valor de dos (2), se debería cambiar el desplazamiento lateral, 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 previamente). Si se establece un valor de tres (3), se restablecerá el índice a las coordenadas predeterminadas de fábrica.

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

Selector de control 7
Operación SET
wLength 2
Desplazamiento Campo Tamaño Valor Descripción
0 bPresetAction 1 Número 0x01: Guardar ajuste predeterminado
0x02: Restablecer ajuste predeterminado
0x03: Restablecer ajuste predeterminado al valor predeterminado (El valor predeterminado debe ser una coordenada predeterminada válida).
1 bPresetIndex 1 Número El índice de Active Preset. 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 el número de ajustes predeterminados.

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

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

Asignación auxiliar de inclinación y desplazamiento lateral

Algunas cámaras tienen componentes especiales, como los motores de las cámaras mecánicas, que requieren la asignación de comandos XU a los controles estándar de V4L2 para que el desplazamiento lateral y la inclinación funcionen correctamente.

Estos controles imitan los controles absolutos y relativos de desplazamiento lateral e inclinación en la documentación de la especificación de UVC, lo que proporciona una forma estándar para que los dispositivos host asignen estos controles de forma correcta.

Control: GOOGXU_PAN_TILT_ABSOLUTE

Los controles de asignación auxiliar de desplazamiento lateral e inclinación se definen en el Capítulo 4: Sección 4.2.2.1.14 Solicitudes de inclinación (absoluta) de la Especificación de clases UVC 1.5.

Selector de control 8
Operación GET/SET
wLength 8
Desplazamiento Campo Tamaño Valor Descripción
0 dwPanAbsolute 4 Número firmado Es el parámetro de configuración del atributo del control de desplazamiento (absoluto) abordado.
4 dwTiltAbsolute 4 Número firmado Es el parámetro de configuración del atributo del control de inclinación (absoluto) indicado.

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

Desplazamiento 0 4 Descripción
GET_MIN Funciones que dependen de la cámara
GET_MAX Funciones que dependen de la cámara
GET_RES Funciones que dependen de la cámara
GET_LEN 0x0008
GET_INFO 0 x 0 mil millones Actualización automática / escritura / lectura
GET_DEF 0x00000000 0x00000000

Control: GOOGXU_PAN_TILT_RELATIVE

Los controles de asignación auxiliar de inclinación y desplazamiento se definen en el Capítulo 4: Sección 4.2.2.1.15 Solicitudes de desplazamiento lateral (relativo) en la sección Solicitudes específicas para clases de la Especificación de clases UVC 1.5.

Selector de control 9
Operación GET/SET
wLength 4
Desplazamiento Campo Tamaño Valor Descripción
0 bPanRelative 1 Número firmado Configuración del atributo del control de desplazamiento (relativo) asignado:
0: Parada
1: desplazamiento en el sentido de las manecillas del reloj
0xFF: movimiento en sentido contrario a las manecillas del reloj
1 bPanSpeed 1 Número Velocidad del movimiento de desplazamiento lateral.
2 bTiltRelative 1 Número firmado Configuración del atributo del control de inclinación (relativo) asignado:
0: Detener
1: Apuntar el plano de imagen hacia arriba
0xFF: Apuntar el plano de imagen hacia abajo
3 bTiltSpeed 1 Número Velocidad del movimiento de inclinación.

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

Desplazamiento 0 1 2 3 Descripción
GET_MIN Funciones que dependen de la cámara
GET_MAX Funciones que dependen de la cámara
GET_RES Funciones que dependen de la cámara
GET_LEN 0x04 0 × 00 0x0004
GET_INFO 0 x 0 mil millones Actualización automática / escritura / lectura
GET_DEF 0 × 00 0 × 00 0 × 00 0 × 00

Notas de la versión

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

15 de noviembre de 2023

Se actualizó la secuencia de comandos de prueba para verificar y también 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 a fin de cumplir con esta especificación.

25 de mayo de 2023

Se corrigió la nota de GOOGXU_PRESETS con respecto a la cantidad de ajustes predeterminados. Debería ser N, no N-1.

17 de abril de 2023

Versión inicial