APIs de unidade de extensão de vídeo USB do hardware do Google Meet

Neste documento, descrevemos as APIs Video Class Extension Unit (XU) USB compatíveis usadas pelos sistemas de videoconferência do Google Meet para ativar recursos de câmera inteligentes. O objetivo da criação dessa especificação é influenciar as práticas para ativar esses recursos e permitir uma melhor escalonabilidade e testes assíncronos para nossos parceiros.

Para ajudar os parceiros a validar a conformidade com essa especificação, este script de teste analisa e gera relatórios sobre sua implementação.

Para detalhes sobre as mudanças mais recentes neste documento, acesse as Notas da versão.

Convenção Little-endian

USB é um padrão few-endian. Neste documento:

  • Números de vários bytes parecem big-endian (e são transmitidos few-endian).
  • As matrizes de bytes estão no layout de memória few-endian.

Por exemplo, 0x12345678 é igual a [0x78, 0x56, 0x34, 0x12].

GUID da unidade de extensão

As unidades de extensão compatíveis com a especificação de controle do Meet XU precisam usar esse GUID.

Unidade de extensão GUID
Controle periférico XU {74D7E924-49C9-4A45-98A3-8A9F60061E83}

Seletores XU de controle periférico

Estes são os seletores XU dos controles de periféricos definidos.

Seletores de controle 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

Controlar o tipo de solicitação

Os tipos de solicitação de controle são definidos no Capítulo 4, solicitações específicas de classe da especificação de classe UVC 1.5 (link em inglês).

Operação Controle de UVC
GET GET_CUR, GET_MIN, GET_MAX, GET_RES, GET_LEN, GET_INFO, GET_DEF
SET SET_CUR

Modos da câmera

Os modos de câmera são usados para enquadrar pessoas em uma sala de conferências e são tuple de:

  • Estratégia (visualização da câmera)
  • Viés (alto-falante ou sala)
  • Feeds (únicos ou vários streams)

Cada dimensão pode ter valores descritos nas seções a seguir.

Estratégia de enquadramento automático

Recurso Descrição
Nenhum A câmera desativa todos os recursos de enquadramento inteligente e permite que o cliente controle livremente os valores PTZ.
Observação:quando definida para essa estratégia de enquadramento, a câmera permanece na posição de movimentação, inclinação e zoom atuais.
Enquadramento contínuo (CAZ, na sigla em inglês) Com base no viés de enquadramento, a câmera rastreia continuamente as pessoas na sala.
Observação:o modo PTZ está desativado nesse modo.
Quadros separados A câmera cria quantas exibições de vídeo forem necessárias. Com base na opção Enquadramento automático de feeds, os feeds são compostos por blocos em um único stream ou criados streams de vídeo separados para cada visualização.
Observação:o modo PTZ está desativado nesse modo.
Visualização dinâmica Uma ou mais câmeras tentam fornecer a melhor visão do ambiente. Ela decide se vai ou não combinar vários feeds em um ou fornecer uma visão "interessante" da sala atual.
O objetivo dessa visualização é mostrar de maneira equitativa os participantes da sala na chamada.
Observações:
  • A maioria das reuniões deve usar essa estratégia.
  • A opção PTZ está desativada nesse modo.

Viés de enquadramento automático

Recurso Descrição
Apresentador de alto risco (acompanhamento de palestrantes) A câmera tenta enquadrar melhor a pessoa que está falando ativamente na sala.
Neste cenário, a câmera precisa estar voltada para o apresentador. Por exemplo, o CEO em uma sala de reuniões fazendo uma apresentação.
Colaboração
(rastreamento de sala)		 A câmera tenta enquadrar melhor todos os participantes na sala. Neste cenário, a câmera precisa tratar todos os participantes de maneira equitativa. A maioria das reuniões deve usar essa estratégia.

Enquadramento automático de feeds

Recurso Descrição
Fluxo único A câmera envia um único stream de vídeo para o dispositivo host.
Multistream
(em andamento)		 A câmera divide o stream e cria vários streams de vídeo para enviar ao host.
Observação:a especificação completa e o comportamento esperado para esse recurso estão com revisão pendente e estão disponíveis apenas após as próximas revisões deste documento.

Valores de bitmap do modo de enquadramento automático

Exceto pelo estado padrão de None, que é representado por uma matriz de bytes vazia, cada bit na matriz de bytes representa um modo de câmera diferente, que é uma combinação específica da estratégia de enquadramento automático, viés de enquadramento automático e Feeds de enquadramento automático.

Índice de bits CAZ Frame dividido Dynamic -
Apresentador Dia 1
–		 –
–		 D5
D6		 Stream único
Multistream
Room Dia 2
–		 D3
D4		 D7
D8		 Stream único
Multistream
Modos de frame Valor do modo de frame (byte menos significativo)
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

Controle: GOOGXU_FRAME_STRATEGY

Esse controle é usado para conferir ou definir os modos de enquadramento da câmera, conforme listado em Valores de bitmap do modo de enquadramento automático. Cada modo é representado como um bit nos respectivos bitmaps. O comando GET_RES retorna uma bitmask de 8 bytes com um valor zero (0) ou um (1) para indicar, respectivamente, se o recurso não tem suporte ou tem suporte do dispositivo. Por exemplo, se uma câmera for compatível com CAZ, Speaker, Single-Stream, Split-Frame, Room, Single-Stream e Dynamic, Room, Multi-Stream, mas nenhum outro modo, GET_RES retornará 0x000000000000000085 (ou seja, 0b10000101 seguido por sete zero bytes).

O comando SET_CUR é usado para enviar bitmaps e informar à câmera qual modo SINGLE precisa ser ativado.

Seletor de controle 1
Operação GET / SET
wLength 8
Deslocamento Campo Tamanho Valor Descrição
0 bActiveMode 8 Bitmap Definir ou retornar o modo de câmera ativa
Observações:

O comportamento dos tipos de solicitação compatíveis é o seguinte:

Deslocamento 0 Descrição
GET_CUR Acessar modo de câmera enquadramento ativo
GET_MIN Dependente da câmera
GET_MAX Dependente da câmera
GET_RES Retorna uma bitmask de 8 bytes dos modos de câmera com suporte
GET_LEN 0x0008 Comprimento
GET_INFO 0 x 0 bi Atualização automática / gravação / leitura
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 Valor padrão
SET_CUR Definir o modo da câmera de enquadramento ativo

Controle: GOOGXU_REFRAME

Esse controle é usado para acionar o enquadramento único, também conhecido como OTAZ. Quando a OTAZ é acionada, a visualização da câmera se ajusta à melhor visualização do cômodo. Depois, o cliente recupera a capacidade de controlar os valores de PTZ. Se o enquadramento único não for compatível, a câmera não definirá esse controle.

Seletor de controle 2
Operação SET
wLength 1
Deslocamento Campo Tamanho Valor Descrição
0 bReframe 1 Número 0x01 Executar solicitação de reenquadramento

O comportamento dos tipos de solicitação compatíveis é o seguinte:

Deslocamento 0 Descrição
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x02 Somente gravação
GET_DEF 0x00
SET_CUR Definir solicitação de enquadramento único

Contagem de ocupação

A contagem de ocupação (OC, na sigla em inglês) é um recurso usado para estimar o número de participantes em uma sala de reunião, apesar da visualização cortada da câmera.

Esta tabela mostra o comportamento esperado dos controles da OC e as interações deles com o stream de vídeo e o indicador LED da câmera.

Quando a contagem de ocupação é e o stream de vídeo da câmera é: O indicador LED da câmera deve estar GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR precisa ser GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR precisa ser
Ativado Não está sendo transmitida e não está silenciada Ativado 0x01 A contagem de pessoas no campo de visão completo da câmera.
Ativado Streaming Ativado 0x01 A contagem de pessoas no campo de visão completo da câmera.
Ativado silenciado; Desativado 0x01 Desativadas
Desativadas Não está sendo transmitida e não está silenciada Desativado 0x00 Desativadas
Desativadas Streaming Ativado 0x00 Desativadas
Desativadas silenciado; Desativado 0x00 Desativadas

Controle: GOOGXU_OCCUPANCY_COUNTING_TOGGLE

Esse controle é usado para ativar ou desativar o recurso de contagem de ocupantes em um ambiente. Definir um valor como zero (0) desativa esse recurso e 1 (um) ativa ele. Se esse recurso não tiver suporte, a câmera não vai definir esse controle.

Seletor de controle 3
Operação GET / SET
wLength 1
Deslocamento Campo Tamanho Valor Descrição
0 bOccupancy 1 Booleano Definir função de contagem de ocupação
0x00 Desativar função
0x01 Ativar função

O comportamento dos tipos de solicitação compatíveis é o seguinte:

Deslocamento 0 Descrição
GET_CUR Devolver se a contagem de ocupação estiver ativada
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0 x 0 bi Atualização automática / gravação / leitura
GET_DEF 0x00
SET_CUR Ativar ou desativar o recurso de contagem de ocupação

Controle: GOOGXU_OCCUPANCY_COUNTING_READ

Esse controle é usado para ler o número de participantes de uma sala informado pela câmera quando a contagem de ocupação está ativada. Se esse recurso estiver desativado, a câmera precisará desativar o controle. Se a contagem de ocupação não estiver disponível, a câmera não vai definir esse controle.

Seletor de controle 4
Operação GET
wLength 2
Deslocamento Campo Tamanho Valor Descrição
0 bNumPeople 2 Número O número de ocupantes detectados na visualização. (Somente leitura)

O comportamento dos tipos de solicitação compatíveis é o seguinte:

Deslocamento 0 Descrição
GET_CUR Número de retorno dos ocupantes detectados
GET_MIN 0x0000
GET_MAX 0x00FF
GET_RES 0x0001
GET_LEN 0x0002
GET_INFO 0x09 Atualização automática / leitura
GET_DEF 0x0000

Telemetria e diagnósticos do dispositivo

Esses controles visam incentivar práticas de depuração melhores com o hardware do Google Meet e geralmente não são voltados para o usuário.

Controle: GOOGXU_STATUS_INFO

Esse controle é usado para consultar informações da câmera do host e compartilhar com parceiros para depuração.

Seletor de controle 5
Operação GET
wLength 8
Deslocamento Campo Tamanho Valor Descrição
0 bNumCameras 1 Número O número de câmeras adicionais conectadas ao dispositivo principal.
1 bIsMoving 1 Bitmap 0 quando a câmera está inativa e diferente de zero quando ela está em movimento. Os fornecedores são livres para mapear diferentes eixos ou motores para diferentes bits.
2 Undef 6 Cancelar definição A ser estendido no futuro.

O comportamento dos tipos de solicitação compatíveis é o seguinte:

Deslocamento 0 1 2 Descrição
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 Atualização automática / leitura
GET_DEF 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00

Controle: GOOGXU_STATUS_RESET

Esse controle é usado para solicitar a redefinição da câmera. A definição do valor 1 (um) solicita que a câmera seja redefinida. A câmera vai retornar zero (0) se não houver solicitação para reiniciá-la desde a última redefinição, e um (1) se ela estiver sendo redefinida. Uma redefinição aciona o mesmo comportamento que uma reconexão de hardware. Isso é útil para dispositivos autoalimentados em que não é útil forçar um desconexão USB para emular um hotplug.

Seletor de controle 6
Operação GET / SET
wLength 1
Deslocamento Campo Tamanho Valor Descrição
0 bResetRequest 1 Booleano Enviar uma solicitação de redefinição ao host e às câmeras conectadas.
retorna 0x01 se a solicitação de redefinição foi emitida desde a última redefinição. Caso contrário, retorna 0x00.

O comportamento dos tipos de solicitação compatíveis é o seguinte:

Deslocamento 0 Descrição
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x03 Gravação / leitura
GET_DEF 0x00

Predefinições PTZ

Usado para configurar e restaurar o campo de visão da câmera em uma posição predefinida.

Controle: GOOGXU_PRESETS

Esse controle é usado para definir os valores de movimentação, inclinação e zoom (PTZ, na sigla em inglês) da câmera para uma configuração predefinida.

O Preset Action é usado para declarar a ação pretendida do comando. A definição de um valor de 1 (um) é usada para mapear os valores atuais de movimentação, inclinação e zoom para um índice predefinido fornecido. A definição de um valor de dois (2) precisa fazer a transição da movimentação, inclinação e zoom da câmera para os valores mapeados anteriormente para o índice fornecido ou as coordenadas padrão de fábrica (se não tiverem sido mapeadas anteriormente). Definir um valor de três (3) redefine o índice para as coordenadas padrão de fábrica.

O Preset Index é usado para especificar as coordenadas PTZ mapeadas para o índice. O Preset index de zero (0) é mapeado para as coordenadas da casa e precisa ser a posição padrão da câmera na ativação, quando GOOGXU_FRAME_STRATEGY está definido como NONE.

Seletor de controle 7
Operação SET
wLength 2
Deslocamento Campo Tamanho Valor Descrição
0 bPresetAction 1 Número 0x01: salvar predefinição
0x02: restaurar predefinição
0x03: redefinir predefinição para o padrão O padrão deve ser uma coordenada predefinida válida.
1 bPresetIndex 1 Número O índice de predefinição ativa. 0~N-1
, em que 0 é considerado a posição inicial padrão da câmera e N-1 é uma constante definida pelo fornecedor para o número de predefinições.

O comportamento dos tipos de solicitação compatíveis é o seguinte:

Deslocamento 0 1 Descrição
GET_MIN 0x00 0x00
GET_MAX 0x03 N-1 Número máximo de predefinições compatíveis
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 Somente gravação
GET_DEF 0x00 0x00

Mapeamento auxiliar de movimentação e inclinação

Algumas câmeras têm componentes especiais, como os motores para câmeras mecânicas, que exigem o mapeamento de comandos XU em controles V4L2 padrão para que os recursos de movimentação e inclinação funcionem conforme o esperado.

Esses controles imitam os controles absolutos e relativos de movimentação e inclinação na documentação de especificação UVC, fornecendo uma maneira padrão para os dispositivos host mapearem corretamente esses controles.

Controle: GOOGXU_PAN_TILT_ABSOLUTE

Os controles de mapeamento auxiliar de movimentação e inclinação são definidos no Capítulo 4: solicitações específicas de classe, Seção 4.2.2.1.14 Controle "Panorâmica (absoluto)" da especificação de classe UVC 1.5 (link em inglês).

Seletor de controle 8
Operação GET/SET
wLength 8
Deslocamento Campo Tamanho Valor Descrição
0 dwPanAbsolute 4 Número assinado A configuração do atributo do controle de panorâmica (absoluto) endereçado.
4 dwTiltAbsolute 4 Número assinado A configuração do atributo do controle de inclinação (absoluto) endereçado.

O comportamento dos tipos de solicitação compatíveis é o seguinte:

Deslocamento 0 4 Descrição
GET_MIN Dependente da câmera
GET_MAX Dependente da câmera
GET_RES Dependente da câmera
GET_LEN 0x0008
GET_INFO 0 x 0 bi Atualização automática / gravação / leitura
GET_DEF 0x00000000 0x00000000

Controle: GOOGXU_PAN_TILT_RELATIVE

Os controles de mapeamento auxiliar de movimentação e inclinação são definidos no Capítulo 4: solicitações específicas de classe, Seção 4.2.2.1.15 Controle do PanIntil (relativo) da especificação de classe UVC 1.5 (link em inglês).

Seletor de controle 9
Operação GET/SET
wLength 4
Deslocamento Campo Tamanho Valor Descrição
0 bPanRelative 1 Número assinado A configuração do atributo do controle de movimentação (relativa) endereçada:
0: Parada
1: movendo-se para a direção no sentido horário
0xFF: movendo-se para o sentido anti-horário
1 bPanSpeed 1 Número Velocidade do movimento da movimentação.
2 bTiltRelative 1 Número assinado A configuração do atributo do controle de inclinação (relativo) endereçado:
0: parar
1: apontar o plano de imagem para cima
0xFF: apontar o plano de imagem para baixo
3 bTiltSpeed 1 Número Velocidade do movimento de inclinação.

O comportamento dos tipos de solicitação compatíveis é o seguinte:>

Deslocamento 0 1 2 3 Descrição
GET_MIN Dependente da câmera
GET_MAX Dependente da câmera
GET_RES Dependente da câmera
GET_LEN 0x04 0x00 0x0004
GET_INFO 0 x 0 bi Atualização automática / gravação / leitura
GET_DEF 0x00 0x00 0x00 0x00

Notas da versão

As notas da versão refletem as melhorias e os novos recursos em cada revisão deste documento.

15 de novembro de 2023

O script de teste foi atualizado para verificar e interpretar os modos de enquadramento válidos. Esclarecimento das representações de bytes.

21 de julho de 2023

Adicionamos um script de teste para que os parceiros validem implementações para obedecer a essa especificação.

25 de maio de 2023

Correção da observação GOOGXU_PRESETS sobre o número de predefinições. Deve ser N, não N-1.

17 de abril de 2023

Versão inicial.