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 de classe de vídeo USB (XU) compatíveis usadas pelos sistemas de conferência do Google Meet para ativar os recursos de câmera inteligente. O objetivo da criação desta especificação é influenciar as práticas para ativar esses recursos e permitir uma melhor escalabilidade e testes assíncronos para nossos parceiros.

Para saber mais 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-for-Meetings definidos no modo de desenvolvedor. Ative a gravação no sistema de arquivos. Adicione as linhas abaixo 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, e a conformidade com as especificações da câmera ativa será executada e registrada em /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 em big-endian (e são transmitidos em little-endian).
  • Matrizes de bytes estão no layout de memória little-endian.

Por exemplo, 0x12345678 é igual a [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 esse GUID.

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

Seletores de XU de controle periférico

Estes são os seletores de 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

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.

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 indivíduos em uma sala de reunião e são uma tuple de:

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

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

Estratégia de autoenquadramento

Em todos os modos de enquadramento automático, exceto "Nenhum", a movimentação, inclinação e 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 para essa estratégia de enquadramento, a câmera permanece na posição atual de panorâmica, inclinação e zoom.
Enquadramento contínuo (CAZ) Com base no enquadramento, a câmera rastreia continuamente as pessoas no ambiente.
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, eles são compostos em blocos em um único stream ou são criados streams de vídeo separados para cada visualização.
Visualização dinâmica Uma ou mais câmeras tentam oferecer a melhor visualização do ambiente. Ele pode decidir se vai compor vários feeds em um ou fornecer uma visualização "interessante" do ambiente atual.
O objetivo dessa visualização é oferecer a visão mais equitativa 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 visualização do ambiente. A estratégia de incorporação está sujeita a alterações sem aviso prévio. Por exemplo, se o número de pessoas na sala mudar ou a câmera detectar a diferença entre uma apresentação "Importante" e uma reunião "Colaboração", o sistema vai poder adaptar ou mudar a estratégia de enquadramento conforme achar melhor nesse modo. Nesse modo, a chamada getCur precisa retornar VENDOR_PREFERRED, e não o modo de enquadramento subjacente selecionado pelo sistema.

Viés de enquadramento automático

Recurso Descrição
Apresentador de alto risco (rastreamento de alto-falante) A câmera tenta enquadrar melhor a pessoa que está falando na sala.
Nesse cenário, a câmera deve se inclinar em direção 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 da melhor forma todos os participantes na sala. Nesse cenário, a câmera precisa tratar todos os participantes de maneira igual.

Feeds com enquadramento automático

Recurso Descrição
Stream único A câmera envia um único stream de vídeo para o dispositivo host.

de vários fluxos(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 deste recurso estão pendentes de revisão e não têm suporte até as revisões posteriores deste documento.

Valores de bitmap do modo de enquadramento automático

Exceto o estado padrão de None, 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 viés de enquadramento automático e dos feeds de enquadramento automático.

Feeds com enquadramento automático CAZ Frame dividido Dinâmico Preferido pelo fornecedor Viés de enquadramento automático
Fluxo único D1
D2		 -
D3		 D5
D7		 D9 (alto-falante ou sala) Alto-falante
Sala
Várias transmissões -
-		 -
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 respectivo bitmap. O comando GET_RES retorna uma máscara de bits de 8 bytes com um valor de zero (0) ou um (1) para indicar se o recurso é compatível ou não com o dispositivo. Por exemplo, se uma câmera oferecer suporte a CAZ, Speaker, Single-Stream, Split-Frame, Room, Single-Stream e Dynamic, Room, Multi-Stream, mas não a outros modos, o GET_RES vai retornar 0x000000000000000085 (ou seja, 0b10000101 seguido de sete bytes nulos).

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 de 8 bytes dos modos de câmera compatíveis
GET_LEN 0x0008 Comprimento
GET_INFO 0x0B AutoUpdate / Write / Read
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 Valor padrão
SET_CUR Definir o modo de enquadramento ativo da câmera

Controle: GOOGXU_REFRAME

Esse controle é usado para acionar o enquadramento de uma única foto, também conhecido como OTAZ. Quando o OTAZ é acionado, a visualização da câmera é fixada na melhor vista do ambiente. Depois disso, o cliente recupera a capacidade de controlar os valores de PTZ. Se não houver suporte para o enquadramento de uma única foto, a câmera não vai 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 a solicitação para enquadramento único

Contagem de ocupação

A contagem de presença (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 de OC e as interações com o fluxo de vídeo da câmera e o indicador de 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 precisa 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 Som desativado Desativado 0x01 Desativadas
Desativadas Não está sendo transmitida e não está silenciada 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 um ambiente. Definir um valor de zero (0) desativa esse recurso, e um (1) 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 a função de contagem de ocupação
0x00 Desativa a função
0x01 Ativa 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 AutoUpdate / Write / Read
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 presença 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 tiver suporte, 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 Retorna 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 têm como objetivo incentivar melhores práticas de depuração com 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 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 satélites adicionais conectados à câmera principal que podem afetar o fluxo de câmera 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 eixos ou motores diferentes para bits diferentes.
2 Undef 6 Undef Para 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 satélite conectados a esse sistema de câmera.

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élites 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 autoalimentados 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 Faça uma solicitação de redefinição para o host e as câmeras conectadas.
Retorna 0x01 se a solicitação de redefinição for 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 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 panorâmica, inclinação e zoom (PTZ, na sigla em inglês) da câmera em uma configuração predefinida.

O Preset Action é usado para declarar a ação pretendida do comando. A definição de um valor de um (1) é usada para mapear os valores atuais de panorâmica, inclinação e zoom para um índice predefinido fornecido. A definição de um valor de dois (2) deve fazer a transição do movimento de panorâmica, inclinação e zoom da câmera para os valores mapeados anteriormente para o índice fornecido ou as coordenadas de fábrica padrão (se não forem mapeados anteriormente). A definição de 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 ao ser ativada 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 de predefinição ativa. 0 a 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 presets máximos com suporte
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 Somente gravação
GET_DEF 0x00 0x00

Mapeamento auxiliar de inclinação e movimento

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

Controle: GOOGXU_PAN_TILT_ABSOLUTE (descontinuado)

Os controles de mapeamento auxiliar de inclinação e panorâmica são definidos no capítulo 4: solicitações específicas de classe, seção 4.2.2.1.14 Controle de inclinação e panorâmica (absoluto) da especificação de classe UVC 1.5.

Controle: GOOGXU_PAN_TILT_RELATIVE (descontinuado)

Os controles de mapeamento auxiliar de inclinação e panorâmica são definidos no capítulo 4: solicitações específicas de classe, seção 4.2.2.1.15 Controle de panorâmica e inclinação (relativo) da especificação de 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.

27 de janeiro de 2025

21 de maio de 2024

15 de novembro de 2023

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

21 de julho de 2023

Adicionamos um script de teste para que os parceiros validem as implementações para conformidade com essa especificação.

25 de maio de 2023

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

17 de abril de 2023

Versão inicial.