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

Este documento descreve as APIs de unidade de extensão (XU) da classe de vídeo USB compatíveis usadas pelos sistemas de conferência do Google Meet para ativar recursos inteligentes de câmera. O objetivo de criar essa especificação é influenciar as práticas para ativar esses recursos e permitir melhor escalonabilidade e testes assíncronos para nossos parceiros.

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

Instalação de teste

Para ajudar os parceiros a validar a conformidade com essa especificação, oferecemos uma instalação de teste em dispositivos Chromebox para reuniões definidos no modo desenvolvedor. Ative a opção gravar no sistema de arquivos. Adicione as linhas a seguir a /etc/chrome_dev.conf:

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

Reinicie o dispositivo, conecte a câmera e um teclado USB, pressione Ctrl-Alt-X. A conformidade com as especificações da câmera ativa será exercida e registrada em /var/log/chrome/chrome (se você estiver usando uma imagem assinada, /home/chronos/user/log/chrome).

Convenção little-endian

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

  • Números de vários bytes aparecem big-endian (e são transmitidos little-endian).
  • Os arrays de bytes estão no layout de memória little-endian.

Por exemplo, 0x12345678 é o mesmo que [0x78, 0x56, 0x34, 0x12].

GUID da unidade de extensão

As unidades de extensão que oferecem suporte a essa especificação de controle do Meet XU precisam usar este GUID.

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

Seletores de unidade de controle periférico XU

Estes são os seletores XU de controle periférico 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
GOOGXU_SATELLITE_INFO 0x0A

Tipo de solicitação de controle

Os tipos de solicitação de controle são definidos no Capítulo 4: Solicitações específicas da classe da Especificação da classe UVC 1.5.

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

Modos de câmera

Os modos de câmera são usados para enquadrar pessoas em uma sala de reunião e são um tuple de:

  • Estratégia (visualização da câmera)
  • Viés (locutor ou ambiente)
  • Feeds (um ou vários fluxos)

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

Estratégia de autoenquadramento

Em todos os modos de enquadramento automático, exceto "Nenhum", a movimentação, a inclinação e o zoom manuais são desativados.

Recurso Descrição
Nenhum A câmera desativa todos os recursos de enquadramento inteligente e permite que o cliente controle livremente os valores de PTZ.
Observação:quando definida como essa estratégia de enquadramento, a câmera permanece na posição atual de rotação horizontal, vertical e zoom.
Enquadramento constante (CAZ) Com base no viés de enquadramento, a câmera rastreia continuamente as pessoas na sala.
Frames divididos A câmera cria quantas visualizações de vídeo forem necessárias. Com base na opção Feeds de enquadramento automático, ele os organiza em blocos em um único stream ou cria streams de vídeo separados para cada visualização.
Visualização dinâmica Uma ou mais câmeras tentam oferecer a melhor visão do ambiente. Ele pode decidir se vai compor vários feeds em um só ou fornecer uma visualização "interessante" da sala atual.
O objetivo dessa visualização é oferecer a visão mais igualitária dos participantes na sala para a chamada.
Preferido pelo fornecedor O sistema de câmera usa a própria lógica para determinar a melhor visão do ambiente. A estratégia de enquadramento subjacente está sujeita a mudanças sem aviso prévio. Por exemplo, se o número de pessoas na sala mudar ou se a câmera conseguir detectar a diferença entre uma reunião de "Apresentador de alto risco" e uma de "Colaboração", o sistema poderá adaptar ou mudar a estratégia de enquadramento conforme achar adequado nesse modo. Nesse modo, chamar getCur precisa retornar VENDOR_PREFERRED, e não o modo de enquadramento subjacente selecionado pelo sistema.

Viés de autoenquadramento

Recurso Descrição
Apresentador de alto risco (rastreamento de falas) A câmera tenta enquadrar da melhor forma possível a pessoa que está falando na sala.
Nesse cenário, a câmera deve dar preferência ao 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 todos os participantes da sala da melhor forma possível. Nesse cenário, a câmera precisa tratar todos os participantes de forma igualitária.

Feeds de autoenquadramento

Recurso Descrição
Single-Stream A câmera envia um único stream de vídeo para o dispositivo host.
Multi Stream
(em andamento)		 A câmera divide o stream e cria vários streams de vídeo para enviar ao organizador.
Observação:a especificação completa e o comportamento esperado desse recurso estão pendentes de revisão e não são compatíveis até revisões posteriores 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, do ajuste de enquadramento automático e dos feeds de enquadramento automático.

Feeds de autoenquadramento CAZ Split-Frame Dinâmico Preferido pelo fornecedor Viés de autoenquadramento
Fluxo único D1
D2		 -
D3		 D5
D7		 D9 (alto-falante ou sala) Alto-falante
Sala
Multi-Stream -
-		 -
D4		 D6
D8		 - Alto-falante
Sala
Modos de frame Valor do modo de frame (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

Controle: GOOGXU_FRAME_STRATEGY

Esse controle é usado para receber 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 no bitmap respectivo. O comando GET_RES retorna uma máscara de bits de 8 bytes com um valor de zero (0) ou um (1) para indicar, respectivamente, se o recurso não é compatível ou é compatível com o 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 não com outros modos, GET_RES vai retornar 0x000000000000000085 (ou seja, 0b10000101 seguido por sete bytes zero).

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

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 Receber o modo de enquadramento ativo da câmera
GET_MIN Dependente da câmera
GET_MAX Dependente da câmera
GET_RES Retorna uma máscara de bits longa de 8 bytes dos modos de câmera compatíveis.
GET_LEN 0x0008 Comprimento
GET_INFO 0x0B 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 de câmera de enquadramento ativo

Controle: GOOGXU_REFRAME

Esse controle é usado para acionar o One-Shot Framing, também conhecido como OTAZ. Quando o OTAZ é acionado, a visualização da câmera muda para a melhor visualização do ambiente. Depois disso, 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 poderá 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 reframing

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 para enquadramento único

Contagem de ocupação

A contagem de ocupação (OC) é 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 na tela e as interações deles com o stream de vídeo e o indicador LED da câmera.

Quando a contagem de ocupação está & o stream de vídeo da câmera é: O indicador LED da câmera precisa estar GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR precisa ser GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR precisa ser
Ativado Não está transmitindo nem silenciado 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 Som desativado Desativado 0x01 Desativadas
Desativadas Não está transmitindo nem silenciado Desativado 0x00 Desativadas
Desativadas Streaming Ativado 0x00 Desativadas
Desativadas Som desativado Desativado 0x00 Desativadas

Controle: GOOGXU_OCCUPANCY_COUNTING_TOGGLE

Esse controle é usado para ativar ou desativar o recurso de contagem de ocupantes em uma sala. Definir o valor como zero (0) desativa esse recurso, e um (1) o ativa. Se esse recurso não for compatível, a câmera não poderá definir esse controle.

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

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

Deslocamento 0 Descrição
GET_CUR Retorna se a contagem de ocupação está ativada
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x0B 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 em uma sala informado pela câmera quando a contagem de ocupação está ativada. Quando a contagem de ocupação é desativada, a câmera também desativa esse controle. Se a contagem de ocupação não for compatível, a câmera não poderá 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 Retornar o número de ocupantes detectados
GET_MIN 0x0000
GET_MAX 0x00FF
GET_RES 0x0001
GET_LEN 0x0002
GET_INFO 0x09 AutoUpdate / Read
GET_DEF 0x0000

Telemetria e diagnósticos do dispositivo

Esses controles incentivam práticas de depuração melhores com o hardware do Meet e geralmente não são voltados ao usuário.

Controle: GOOGXU_STATUS_INFO

Esse controle é usado para consultar informações da câmera 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 satélites adicionais conectados à câmera principal que podem afetar o stream de vídeo retornado ao host.
1 bIsMoving 1 Bitmap 0 quando a câmera está inativa e diferente de zero quando os valores de PTZ estão mudando. Os fornecedores podem mapear diferentes eixos ou motores para diferentes bits.
2 Undef 6 Indef 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 AutoUpdate / Read
GET_DEF 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00

Controle: GOOGXU_SATELLITE_INFO

Esse controle é usado para consultar os dispositivos de satélite conectados a esse sistema de câmeras.

Seletor de controle 0x0A
Operação GET
wLength 20
Deslocamento Campo Tamanho Valor Descrição
0 bSatelliteList 20 Bitmap A lista de tipos de satélite anexados ao sistema. Inclui quatro slots separados de 5 bytes. Cada um dos slots é descrito da seguinte forma:
Deslocamento Descrição
0 Quantidade para esse tipo de satélite.
1-2 ID do fornecedor desse tipo de satélite.
3-4 ID do produto para esse tipo de satélite.

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

Deslocamento 0 Descrição
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

Controle: GOOGXU_STATUS_RESET

Esse controle é usado para emitir uma solicitação de redefinição para a câmera. Definir um valor de um (1) solicita que a câmera seja redefinida. A câmera retorna zero (0) se não houver uma solicitação para reiniciar a câmera desde a última redefinição e um (1) se ela estiver sendo redefinida. A redefinição precisa acionar uma reinicialização da câmera. Isso é necessário para dispositivos autônomos em que forçar uma desconexão USB para emular um hotplug não é útil.

Seletor de controle 6
Operação GET / SET
wLength 1
Deslocamento Campo Tamanho Valor Descrição
0 bResetRequest 1 Booleano Envie uma solicitação de redefinição para o host e as câmeras conectadas.
Retorna 0x01 se o pedido de redefinição foi emitido desde a última redefinição, caso contrário, 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 de 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 inclinação, panorâmica e zoom (PTZ) da câmera em uma configuração predefinida.

O Preset Action é usado para declarar a ação pretendida do comando. Definir um valor de um (1) é usado para mapear os valores atuais de rotação horizontal, vertical e zoom para um índice predefinido fornecido. Definir um valor de dois (2) deve fazer a transição do movimento panorâmico, da inclinação e do 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 antes). 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 de PTZ mapeadas para o índice. O Preset index zero (0) é mapeado para as coordenadas de início e deve ser a posição padrão da câmera ao despertar quando o GOOGXU_FRAME_STRATEGY é 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 precisa ser uma coordenada predefinida válida.
1 bPresetIndex 1 Número O índice da 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 predefinições máximas compatíveis
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 Somente gravação
GET_DEF 0x00 0x00

Mover e inclinar o mapeamento auxiliar

Algumas câmeras têm componentes especiais, como os motores de câmeras mecânicas ou recursos de PTZ digital. Para eles, use os controles padrão do V4L2 para panorâmica, inclinação e zoom.

Controle: GOOGXU_PAN_TILT_ABSOLUTE (descontinuado)

Os controles auxiliares de mapeamento de panorâmica e inclinação são definidos no Capítulo 4: Solicitações específicas da classe, Seção 4.2.2.1.14 Controle PanTilt (absoluto) da Especificação da classe UVC 1.5.

Controle: GOOGXU_PAN_TILT_RELATIVE (descontinuado)

Os controles auxiliares de mapeamento de panorâmica e inclinação são definidos no Capítulo 4: Solicitações específicas da classe, Seção 4.2.2.1.15 Controle PanTilt (relativo) da Especificação da classe UVC 1.5.

Notas de lançamento

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

13 de agosto de 2025

27 de janeiro de 2025

21 de maio de 2024

15 de novembro de 2023

Script de teste atualizado para verificar e interpretar modos de enquadramento válidos. Representações de bytes esclarecidas.

21 de julho de 2023

Adição de um script de teste para parceiros validarem implementações de acordo com esta especificação.

25 de maio de 2023

Observação corrigida sobre o número de predefinições.GOOGXU_PRESETS Precisa ser N, não N-1.

17 de abril de 2023

Versão inicial.