API unità di estensione della classe video USB per l'hardware Google Meet

Questo documento descrive le API USB Video Class Extension Unit (XU) supportate utilizzate dai sistemi di conferenza Google Meet per attivare le funzionalità intelligenti della videocamera. Lo scopo della creazione di questa specifica è influenzare le pratiche per abilitare queste funzionalità e consentire una migliore scalabilità e test asincroni per i nostri partner.

Per informazioni dettagliate sulle ultime modifiche apportate a questo documento, consulta le note di rilascio.

Struttura di test

Per aiutare i partner a convalidare la conformità a questa specifica, forniamo un impianto di test nei dispositivi Chromebox for meetings impostati in modalità sviluppatore. Attiva la scrittura nel file system. Aggiungi le seguenti righe a /etc/chrome_dev.conf:

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

Riavvia il dispositivo, collega la videocamera e una tastiera USB, premi Ctrl-Alt-X e la conformità alle specifiche della videocamera attiva verrà esercitata e registrata in /var/log/chrome/chrome (se utilizzi un'immagine firmata, in /home/chronos/user/log/chrome).

Convenzione little-endian

USB è uno standard little-endian. All'interno di questo documento:

  • I numeri multi-byte vengono visualizzati in formato big-endian (e vengono trasmessi in formato little-endian).
  • Gli array di byte sono nel layout di memoria little-endian.

Ad esempio, 0x12345678 è uguale a [0x78, 0x56, 0x34, 0x12].

GUID unità di estensione

Le unità di estensione che supportano questa specifica di controllo Meet XU devono utilizzare questo GUID.

Unità di estensione GUID
Peripheral Control XU {74D7E924-49C9-4A45-98A3-8A9F60061E83}

Selettori XU di controllo delle periferiche

Questi sono i selettori XU di controllo delle periferiche definiti.

Selettori di controllo Valore
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 di richiesta di controllo

I tipi di richieste di controllo sono definiti nel capitolo 4: Richieste specifiche della classe della specifica della classe UVC 1.5.

Operazione Controllo UVC
GET GET_CUR, GET_MIN, GET_MAX, GET_RES, GET_LEN, GET_INFO, GET_DEF
SET SET_CUR

Modalità fotocamera

Le modalità fotocamera vengono utilizzate per inquadrare le persone in una sala riunioni e sono un tuple di:

  • Strategia (vista della videocamera)
  • Bias (speaker o stanza)
  • Feed (uno o più stream)

Ogni dimensione può assumere i valori descritti nelle sezioni seguenti.

Strategia di inquadratura automatica

In tutte le modalità di inquadratura automatica, tranne "Nessuna", la panoramica, l'inclinazione e lo zoom manuali sono disattivati.

Funzionalità Descrizione
Nessuno La videocamera disattiva tutte le funzionalità di inquadratura intelligente e consente al client di controllare liberamente i valori PTZ.
Nota:se impostata su questa strategia di inquadratura, la videocamera rimane nella sua attuale posizione di panoramica, inclinazione e zoom.
Inquadratura continua (CAZ) In base alla preferenza di inquadratura, la videocamera traccia continuamente le persone nella stanza.
Frame divisi La videocamera crea tutte le visualizzazioni video necessarie. In base all'opzione Feed con inquadratura automatica, li compone in riquadri in un unico stream o crea stream video separati per ogni visualizzazione.
Visualizzazione dinamica Una o più videocamere tentano di fornire la migliore visualizzazione della stanza. Può decidere se comporre più feed in uno solo o fornire una visualizzazione "interessante" della stanza corrente.
Lo scopo di questa visualizzazione è fornire una visione più equa dei partecipanti alla chiamata presenti nella stanza.
Preferito dal fornitore Il sistema di videocamere utilizza una propria logica per determinare la migliore visuale della stanza. La strategia di inquadratura sottostante è soggetta a modifiche senza preavviso. Ad esempio, se il numero di persone nella stanza cambia o la videocamera è in grado di rilevare la differenza tra una riunione "Presentatore di alto livello" e una riunione "Collaborazione", il sistema è libero di adattare o modificare la strategia di inquadratura come meglio crede in questa modalità. In questa modalità, la chiamata getCur dovrebbe restituire VENDOR_PREFERRED e non la modalità di inquadratura sottostante selezionata dal sistema.

Bias di inquadratura automatica

Funzionalità Descrizione
Presentatore di eventi importanti (tracciamento dell'oratore) La videocamera tenta di inquadrare al meglio la persona che sta parlando attivamente nella stanza.
In questo scenario, la videocamera dovrebbe dare la priorità al relatore. Ad esempio, l'amministratore delegato in una sala riunioni che fa una presentazione.
Collaborazione
(monitoraggio della stanza)		 La videocamera tenta di inquadrare al meglio tutti i partecipanti nella stanza. In questo scenario, la videocamera deve trattare tutti i partecipanti in modo equo.

Feed con inquadratura automatica

Funzionalità Descrizione
Single-Stream La videocamera invia un singolo video stream al dispositivo host.
Multi-Stream
(in corso di elaborazione)		 La videocamera divide lo stream e crea più video stream da inviare all'host.
Nota:la specifica completa e il comportamento previsto di questa funzionalità sono in attesa di revisione e non sono supportati fino alle revisioni successive di questo documento.

Valori bitmap della modalità di inquadratura automatica

Ad eccezione dello stato predefinito di None, rappresentato da un array di byte vuoto, ogni bit nell'array di byte rappresenta una modalità della videocamera diversa, ovvero una combinazione specifica della strategia di inquadratura automatica, della distorsione dell'inquadratura automatica e dei feed dell'inquadratura automatica.

Feed con inquadratura automatica CAZ Split-Frame Dinamico Preferito dal fornitore Bias di inquadratura automatica
Single-Stream D1
D2		 -
D3		 D5
D7		 D9 (speaker o stanza) Speaker
Stanza
Multi-Stream -
-		 -
D4		 D6
D8		 - Speaker
Stanza
Modalità frame Valore della modalità Frame (byte meno 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

Controllo: GOOGXU_FRAME_STRATEGY

Questo controllo viene utilizzato per ottenere o impostare le modalità di inquadratura della videocamera elencate in Valori bitmap della modalità di inquadratura automatica. Ogni modalità è rappresentata da un bit nella rispettiva bitmap. Il comando GET_RES restituisce una maschera di bit lunga 8 byte con un valore pari a zero (0) o uno (1) per indicare rispettivamente se la funzionalità non è supportata o è supportata dal dispositivo. Ad esempio, se una videocamera supporta CAZ, Speaker, Single-Stream, Split-Frame, Room, Single-Stream e Dynamic, Room, Multi-Stream, ma non altre modalità, GET_RES deve restituire 0x000000000000000085 (ovvero 0b10000101 seguito da sette byte zero).

Il comando SET_CUR viene utilizzato per inviare bitmap per indicare alla videocamera quale modalità videocamera SINGLE attivare.

Selettore di controllo 1
Operazione GET / SET
wLength 8
Offset Campo Dimensioni Valore Descrizione
0 bActiveMode 8 Bitmap Impostare o ripristinare la modalità Fotocamera attiva
Note:

Il comportamento dei tipi di richieste supportati è il seguente:

Offset 0 Descrizione
GET_CUR Ottenere la modalità fotocamera Inquadratura attiva
GET_MIN Dipendente dalla videocamera
GET_MAX Dipendente dalla videocamera
GET_RES Restituisce una maschera di bit lunga 8 byte delle modalità della videocamera supportate
GET_LEN 0x0008 Lunghezza
GET_INFO 0x0B Aggiornamento automatico / Scrittura / Lettura
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 Valore predefinito
SET_CUR Impostare la modalità della videocamera con inquadratura attiva

Controllo: GOOGXU_REFRAME

Questo controllo viene utilizzato per attivare l'inquadratura one-shot, nota anche come OTAZ. Quando viene attivata la funzionalità OTAZ, la visualizzazione della videocamera si sposta sulla migliore visualizzazione della stanza. Successivamente, il client riacquisisce la possibilità di controllare i valori PTZ. Se l'inquadratura one-shot non è supportata, la videocamera non deve definire questo controllo.

Selettore di controllo 2
Operazione SET
wLength 1
Offset Campo Dimensioni Valore Descrizione
0 bReframe 1 Numero 0x01 Execute Reframe Request

Il comportamento dei tipi di richieste supportati è il seguente:

Offset 0 Descrizione
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x02 Solo scrittura
GET_DEF 0x00
SET_CUR Imposta la richiesta di inquadratura one-shot

Conteggio presenze

Il conteggio delle persone (OC) è una funzionalità utilizzata per stimare il numero di partecipanti in una sala riunioni, nonostante la visuale ritagliata della videocamera.

Questa tabella mostra il comportamento previsto dei controlli OC e le loro interazioni con il video stream della videocamera e l'indicatore LED della videocamera.

Quando il conteggio presenze è e lo stream video della videocamera è: L'indicatore LED della videocamera dovrebbe essere GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR deve essere GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR deve essere
Attivato Non in streaming e audio non disattivato On 0x01 Il conteggio delle persone nel campo visivo completo della videocamera.
Attivato Streaming On 0x01 Il conteggio delle persone nel campo visivo completo della videocamera.
Attivato Audio disattivato Off 0x01 Disattivate
Disattivate Non in streaming e audio non disattivato Off 0x00 Disattivate
Disattivate Streaming On 0x00 Disattivate
Disattivate Audio disattivato Off 0x00 Disattivate

Controllo: GOOGXU_OCCUPANCY_COUNTING_TOGGLE

Questo controllo viene utilizzato per attivare o disattivare la funzionalità di conteggio degli occupanti in una stanza. Se imposti il valore su zero (0), questa funzionalità viene disattivata, mentre se lo imposti su uno (1), viene attivata. Se questa funzionalità non è supportata, la videocamera non deve definire questo controllo.

Selettore di controllo 3
Operazione GET / SET
wLength 1
Offset Campo Dimensioni Valore Descrizione
0 bOccupancy 1 Booleano Imposta la funzione di conteggio del numero di partecipanti
0x00 Disattiva la funzione
0x01 Attiva la funzione

Il comportamento dei tipi di richieste supportati è il seguente:

Offset 0 Descrizione
GET_CUR Restituisce un valore se il conteggio del numero di partecipanti è attivo
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x0B Aggiornamento automatico / Scrittura / Lettura
GET_DEF 0x00
SET_CUR Attivare o disattivare la funzionalità di conteggio del numero di partecipanti

Controllo: GOOGXU_OCCUPANCY_COUNTING_READ

Questo controllo viene utilizzato per leggere il numero di partecipanti in una stanza segnalato dalla videocamera quando il conteggio dell'occupazione è abilitato. Quando il conteggio dell'occupazione è disattivato, la videocamera deve disattivare questo controllo. Se il conteggio dell'occupazione non è supportato, la videocamera non deve definire questo controllo.

Selettore di controllo 4
Operazione GET
wLength 2
Offset Campo Dimensioni Valore Descrizione
0 bNumPeople 2 Numero Il numero di occupanti rilevati nella visualizzazione. (Sola lettura)

Il comportamento dei tipi di richieste supportati è il seguente:

Offset 0 Descrizione
GET_CUR Restituisce il numero di occupanti rilevati
GET_MIN 0x0000
GET_MAX 0x00FF
GET_RES 0x0001
GET_LEN 0x0002
GET_INFO 0x09 AutoUpdate / Read
GET_DEF 0x0000

Telemetria e diagnostica del dispositivo

Questi controlli hanno lo scopo di incoraggiare migliori pratiche di debug con l'hardware Meet e di solito non sono rivolti agli utenti.

Controllo: GOOGXU_STATUS_INFO

Questo controllo viene utilizzato per eseguire query sulle informazioni della videocamera host da condividere con i partner per il debug.

Selettore di controllo 5
Operazione GET
wLength 8
Offset Campo Dimensioni Valore Descrizione
0 bNumCameras 1 Numero Il numero di satelliti aggiuntivi collegati alla videocamera principale che potrebbero influire sullo stream della videocamera restituito all'host.
1 bIsMoving 1 Bitmap 0 quando la videocamera è inattiva e diverso da zero quando i valori PTZ cambiano. I fornitori sono liberi di mappare assi o motori diversi su bit diversi.
2 Undef 6 Undef Verrà esteso in futuro.

Il comportamento dei tipi di richieste supportati è il seguente:

Offset 0 1 2 Descrizione
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

Controllo: GOOGXU_SATELLITE_INFO

Questo controllo viene utilizzato per eseguire query sui dispositivi satellite connessi a questo sistema di telecamere.

Selettore di controllo 0x0A
Operazione GET
wLength 20
Offset Campo Dimensioni Valore Descrizione
0 bSatelliteList 20 Bitmap L'elenco dei tipi di satelliti collegati al sistema. Include quattro slot separati da 5 byte. Ciascuno slot è descritto come segue:
Offset Descrizione
0 Quantità per questo tipo di satellite.
1-2 L'ID fornitore di questo tipo di satellite.
3-4 ID prodotto per questo tipo di satellite.

Il comportamento dei tipi di richieste supportati è il seguente:

Offset 0 Descrizione
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 byte
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

Controllo: GOOGXU_STATUS_RESET

Questo controllo viene utilizzato per inviare una richiesta di ripristino alla videocamera. L'impostazione del valore su uno (1) richiede il ripristino della videocamera. La videocamera restituisce zero (0) se non è stata richiesta la riattivazione della videocamera dall'ultimo ripristino e uno (1) se è in fase di ripristino. Il ripristino deve attivare il riavvio della videocamera. (Questo è necessario per i dispositivi autoalimentati in cui forzare una disconnessione USB per emulare un hotplug non è utile.)

Selettore di controllo 6
Operazione GET / SET
wLength 1
Offset Campo Dimensioni Valore Descrizione
0 bResetRequest 1 Booleano Invia una richiesta di ripristino all'hub e alle videocamere connesse.
Restituisce 0x01 se la richiesta di ripristino è stata emessa dall'ultimo ripristino, altrimenti 0x00.

Il comportamento dei tipi di richieste supportati è il seguente:

Offset 0 Descrizione
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x03 Scrittura / lettura
GET_DEF 0x00

Preset PTZ

Utilizzato per configurare e ripristinare il campo visivo della videocamera in una posizione preimpostata.

Controllo: GOOGXU_PRESETS

Questo controllo viene utilizzato per impostare i valori di panoramica, inclinazione e zoom (PTZ) della videocamera su una configurazione preimpostata.

Preset Action viene utilizzato per indicare l'azione prevista del comando. L'impostazione di un valore pari a uno (1) viene utilizzata per mappare i valori correnti di panoramica, inclinazione e zoom a un indice preimpostato fornito. L'impostazione di un valore pari a due (2) deve spostare la panoramica, l'inclinazione e lo zoom della videocamera sui valori mappati in precedenza per l'indice fornito o sulle coordinate predefinite di fabbrica (se non mappate in precedenza). L'impostazione di un valore di tre (3) ripristina l'indice alle coordinate predefinite di fabbrica.

Preset Index viene utilizzato per specificare le coordinate PTZ mappate all'indice. Il valore Preset index pari a zero (0) è mappato alle coordinate della posizione originale e deve essere la posizione predefinita della videocamera al risveglio quando GOOGXU_FRAME_STRATEGY è impostato su NONE.

Selettore di controllo 7
Operazione SET
wLength 2
Offset Campo Dimensioni Valore Descrizione
0 bPresetAction 1 Numero 0x01: Salva preimpostazione
0x02: Ripristina preimpostazione
0x03: Ripristina preimpostazione predefinita. (Il valore predefinito deve essere una coordinata preimpostata valida.)
1 bPresetIndex 1 Numero Indice dei preset attivi. 0~N-1
Dove 0 è considerato la posizione iniziale predefinita della videocamera e N-1 è una costante definita dal fornitore per il numero di preset.

Il comportamento dei tipi di richieste supportati è il seguente:

Offset 0 1 Descrizione
GET_MIN 0x00 0x00
GET_MAX 0x03 N-1 Numero massimo di preset supportati
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 Solo scrittura
GET_DEF 0x00 0x00

Mappatura ausiliaria di panoramica e inclinazione

Alcune videocamere hanno componenti speciali, come i motori per le videocamere meccaniche o funzionalità PTZ digitali. Per queste, utilizza i controlli V4L2 standard per la panoramica, l'inclinazione e lo zoom.

Controllo: GOOGXU_PAN_TILT_ABSOLUTE (deprecato)

I controlli di mappatura ausiliari di panoramica e inclinazione sono definiti nel capitolo 4: Richieste specifiche della classe, sezione 4.2.2.1.14 Controllo panoramica/inclinazione (assoluto) della specifica della classe UVC 1.5.

Controllo: GOOGXU_PAN_TILT_RELATIVE (deprecato)

I controlli di mappatura ausiliari di panoramica e inclinazione sono definiti nel capitolo 4: Richieste specifiche della classe, sezione 4.2.2.1.15 Controllo panoramica/inclinazione (relativo) della specifica della classe UVC 1.5.

Note di rilascio

Queste note di rilascio riflettono i miglioramenti e le nuove funzionalità in ogni revisione di questo documento.

13 agosto 2025

27 gen 2025

21 maggio 2024

15 novembre 2023

Aggiornamento dello script di test per controllare e interpretare le modalità di inquadratura valide. Rappresentazioni di byte chiarite.

21 luglio 2023

È stato aggiunto uno script di test per consentire ai partner di convalidare le implementazioni per la conformità a questa specifica.

25 maggio 2023

Correzione GOOGXU_PRESETS nota relativa al numero di preset. Deve essere N, non N-1.

17 aprile 2023

Release iniziale.