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

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

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

Struttura di test

Per aiutare i partner a convalidare la conformità a questa specifica, forniamo un laboratorio di test nei dispositivi Chromebox per videoconferenze 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à verificata e registrata in /home/chronos/user/log/chrome.

Convenzione little-endian

USB è uno standard little-endian. In questo documento:

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

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

GUID dell'unità di estensione

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

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

Selettori XU per il controllo delle periferiche

Questi sono i selettori XU di controllo periferico 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 per la 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à della fotocamera

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

  • Strategia (vista della videocamera)
  • Bias (altoparlante 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, ad eccezione di "Nessuno", la panoramica, la panoramica verticale e lo zoom manuali sono disabilitati.

Funzionalità Descrizione
Nessuno La videocamera disattiva tutte le funzionalità di inquadratura intelligente e consente al cliente di controllare liberamente i valori PTZ.
Nota: se viene impostata questa strategia di inquadratura, la videocamera rimane nella posizione attuale di panoramica, inclinazione e zoom.
Inquadratura continua (CAZ) In base al bias di inquadratura, la videocamera monitora continuamente le persone nella stanza.
Frame divisi La videocamera crea tutte le visualizzazioni del 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ù fotocamere tentano di fornire la migliore visuale della stanza. Può decidere se combinare o meno più feed in uno o fornire una vista "interessante" della stanza corrente.
Lo scopo di questa visualizzazione è fornire la visualizzazione più equa dei partecipanti in sala alla chiamata.
Preferito dal fornitore Il sistema di videocamere utilizza la propria logica per determinare la visuale migliore 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 riesce a rilevare la differenza tra una riunione "Presentatore con responsabilità elevate" e una riunione "Collaborazione", il sistema è libero di adattare o modificare la strategia di inquadratura in base alle proprie esigenze in questa modalità. In questa modalità, la chiamata a getCur dovrebbe restituire VENDOR_PREFERRED e non la modalità di inquadratura sottostante selezionata dal sistema.

Bias di inquadratura automatica

Funzionalità Descrizione
Presentatore con responsabilità elevate (monitoraggio dello speaker) La videocamera tenta di inquadrare al meglio la persona che parla attivamente nella stanza.
In questo caso, la videocamera deve essere inclinata verso il presentatore. Ad esempio, il CEO che fa una presentazione in una sala riunioni.
Collaborazione
(monitoraggio della stanza)		 La videocamera tenta di inquadrare al meglio tutti i partecipanti nella stanza. In questo caso, la videocamera deve trattare tutti i partecipanti in modo equo.

Feed con inquadratura automatica

Funzionalità Descrizione
Singolo stream La videocamera invia un singolo stream video al dispositivo host.
Multistream
(in fase di sviluppo)		 La videocamera suddivide lo stream e crea più stream video da inviare all'host.
Nota: le specifiche complete 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 None, rappresentato da un array di byte vuoto, ogni bit nell'array di byte rappresenta una modalità della fotocamera diversa, ovvero una combinazione specifica della strategia di inquadratura automatica, del bias di inquadratura automatica e dei feed di inquadratura automatica.

Feed con inquadratura automatica CAZ Frame diviso Dinamico Preferito dal fornitore Bias di inquadratura automatica
Singolo stream D1
D2		 -
D3		 D5
D7		 D9 (altoparlante o stanza) Speaker
Stanza
Multistream -
-		 -
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 fotocamera elencate in Valori bitmap della modalità di inquadratura automatica. Ogni modalità è rappresentata come un bit nella rispettiva bitmap. Il comando GET_RES restituisce una maschera di bit di 8 byte con un valore pari a zero (0) o uno (1) per indicare rispettivamente se la funzionalità è supportata o meno 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à di fotocamera SINGOLA attivare.

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

Il comportamento dei tipi di richiesta supportati è il seguente:

Offset 0 Descrizione
GET_CUR Ottenere la modalità fotocamera con inquadratura attiva
GET_MIN Dipende dalla videocamera
GET_MAX Dipende dalla videocamera
GET_RES Restituisce una maschera di bit di 8 byte delle modalità della fotocamera 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à di fotocamera con inquadratura attiva

Controllo: GOOGXU_REFRAME

Questo controllo viene utilizzato per attivare il framing one-shot, noto anche come OTAZ. Quando viene attivato OTAZ, la visualizzazione della videocamera passa alla visualizzazione migliore della stanza. Successivamente, il cliente recupera la possibilità di controllare i valori PTZ. Se l'inquadratura singola non è supportata, la fotocamera non deve definire questo controllo.

Selettore di controllo 2
Operazione SET
wLength 1
Offset Campo Dimensioni Valore Descrizione
0 bReframe 1 Numero 0x01 Esegui richiesta di ritaglio

Il comportamento dei tipi di richiesta 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 per l'inquadratura One-Shot

Conteggio delle presenze

Il conteggio del numero di persone è 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 relative interazioni con lo stream video della videocamera e l'indicatore LED della videocamera.

Quando il conteggio del numero di partecipanti è e lo stream video della videocamera è: L'indicatore LED della videocamera deve essere GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR deve essere GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR deve essere
Attivato Non in streaming e non con l'audio disattivato On 0x01 Il numero di persone nel campo visivo completo della videocamera.
Attivato Streaming On 0x01 Il numero di persone nel campo visivo completo della videocamera.
Attivato Audio disattivato Off 0x01 Disattivate
Disattivate Non in streaming e non con l'audio 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 delle persone in una stanza. Se imposti un valore pari a zero (0), questa funzionalità viene disattivata, mentre se imposti un valore pari a uno (1), la funzionalità 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 richiesta 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 registrato dalla videocamera quando il conteggio delle persone è attivo. Quando il conteggio delle persone è disattivato, la videocamera dovrebbe disattivare questo controllo. Se il conteggio delle persone 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 persone rilevate nell'inquadratura. (Sola lettura)

Il comportamento dei tipi di richiesta 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 Aggiornamento automatico / Lettura
GET_DEF 0x0000

Telemetria e diagnostica del dispositivo

Questi controlli hanno lo scopo di incoraggiare pratiche di debug migliori con 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 altri satelliti 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 a bit diversi.
2 Undef 6 Undef Da estendere in futuro.

Il comportamento dei tipi di richiesta 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 Aggiornamento automatico / Lettura
GET_DEF 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00

Controllo: GOOGXU_SATELLITE_INFO

Questo controllo viene utilizzato per eseguire query sui dispositivi satellitari collegati a questo sistema di videocamere.

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. Sono inclusi quattro slot separati di 5 byte. Ogni 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 richiesta 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 Aggiornamento automatico / Lettura
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 reimpostazione alla videocamera. L'impostazione di un valore di uno (1) richiede il ripristino dei dati di fabbrica della videocamera. La videocamera restituisce zero (0) se non è stata richiesta alcuna riavvio della videocamera dall'ultimo reset e uno (1) se è in corso il riavvio. Il ripristino dei dati di fabbrica deve attivare il riavvio della videocamera. Questo è necessario per i dispositivi autoalimentati in cui non è utile forzare una disconnessione USB per emulare un hotplug.

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

Il comportamento dei tipi di richiesta 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

Consente di 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 1 viene utilizzata per mappare i valori attuali di panoramica, inclinazione e zoom a un indice preimpostato fornito. L'impostazione di un valore pari a due (2) dovrebbe consentire la transizione della panoramica, dell'inclinazione e dello zoom della videocamera ai valori mappati in precedenza per l'indice fornito o alle coordinate di fabbrica predefinite (se non mappati in precedenza). L'impostazione di un valore di tre (3) reimposta l'indice sulle 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 casa 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 L'indice di preset attivo. 0~N-1
dove 0 è considerata la posizione iniziale predefinita della videocamera e N-1 è una costante definita dal fornitore per il numero di preset.

Il comportamento dei tipi di richiesta supportati è il seguente:

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

Mappatura ausiliaria con panoramica e inclinazione

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

Controllo: GOOGXU_PAN_TILT_ABSOLUTE (deprecato)

I controlli di mappatura ausiliari di panoramica e inclinazione sono definiti nel Capitolo 4: Richieste specifiche per le classi, Sezione 4.2.2.1.14 Controllo panoramica/inclinazione (assoluto) della Classificazione 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 per le classi, 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.

27 gennaio 2025

21 maggio 2024

15 novembre 2023

Script di test aggiornato per controllare e interpretare le modalità di inquadratura valide. Rappresentazioni dei byte chiarite.

21 luglio 2023

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

25 maggio 2023

Nota corretta GOOGXU_PRESETS in merito al numero di preset. Deve essere N, non N-1.

17 aprile 2023

Lancio iniziale.