Questo documento descrive le API XU (USB Video Class Extension Unit) supportate utilizzate dai sistemi per conferenze di Google Meet per abilitare le funzionalità delle videocamere intelligenti. Lo scopo della creazione di questa specifica è influenzare le pratiche per abilitare queste funzionalità e consentire una migliore scalabilità asincrone e test per i nostri partner.
Per aiutare i partner a convalidare la conformità a questa specifica, questo script di test analizza e genera report sull'implementazione.
Per maggiori dettagli sulle ultime modifiche a questo documento, vai a Note di rilascio.
Convenzione delle Little-endian
Lo standard USB è uno standard small-endian. All'interno di questo documento:
- I numeri multibyte appaiono big-endian (e sono trasmessi small-endian).
- Gli array di byte si trovano 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 XU di Meet devono utilizzare questo GUID.
Unità di estensione | GUID |
---|---|
XU di controllo delle periferiche | {74D7E924-49C9-4A45-98A3-8A9F60061E83} |
Selettori XU per il controllo delle periferiche
Questi sono i selettori XU di controllo periferici 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 |
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 VUC 1.5.
Operazione | Controllo UVC |
---|---|
GET |
GET_CUR , GET_MIN , GET_MAX , GET_RES , GET_LEN , GET_INFO e GET_DEF |
SET |
SET_CUR |
Modalità fotocamera
Le modalità Fotocamera vengono utilizzate per inquadrare le persone in una sala riunioni e sono tuple
di:
- Strategia (vista videocamera)
- Pregiudizi (altoparlante o stanza)
- Feed (stream singoli o multipli)
Ogni dimensione può assumere valori descritti nelle sezioni seguenti.
Strategia di inquadratura automatica
Funzionalità | Descrizione |
---|---|
Nessuno | La videocamera disattiva tutte le funzionalità di inquadratura intelligenti e consente al client di controllare liberamente i valori PTZ. Nota: se è impostata questa strategia di inquadratura, la videocamera rimane nella posizione corrente di panoramica, inclinazione e zoom. |
Inquadratura continua (CAZ) | In base all'inquadratura, la videocamera segue continuamente le persone nella stanza. Nota: la PTZ è disattivata in questa modalità. |
Frame divisi | La videocamera crea tutte le visualizzazioni video necessarie. In base all'opzione Inquadratura automatica dei feed, li compone in riquadri in un unico stream oppure crea stream video separati per ogni visualizzazione. Nota: la PTZ è disattivata in questa modalità. |
Visualizzazione dinamica | Una o più videocamere cercano di offrire la visuale migliore della stanza. Può decidere se comporre o meno più feed in un unico feed o fornire una vista "interessante" della stanza corrente. Lo scopo di questa visualizzazione è fornire la visione più equa dei partecipanti in sala alla chiamata. Note:
|
Bias inquadratura automatica
Funzionalità | Descrizione |
---|---|
Presentatore ad alte prestazioni (rilevamento dello speaker) | La videocamera cerca di inquadrare al meglio la persona che parla attivamente nella stanza. In questo scenario, la videocamera deve essere orientata verso il presentatore. Ad esempio, il CEO in una sala riunioni durante una presentazione. |
Collaborazione (monitoraggio delle stanze virtuali) |
La videocamera cerca di inquadrare al meglio tutti i partecipanti nella stanza virtuale. In questo scenario, la videocamera deve trattare equamente tutti i partecipanti. La maggior parte delle riunioni dovrebbe usare questa strategia. |
Feed incorniciato automaticamente
Funzionalità | Descrizione |
---|---|
Stream singolo | La videocamera invia un singolo stream video al dispositivo host. |
Multi-stream (Lavoro in corso) |
La videocamera suddivide lo stream e crea più stream video da inviare all'organizzatore. Nota: la specifica completa e il comportamento previsto di questa funzionalità sono in attesa di revisione e non sono supportati fino a 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 dell'inquadratura automatica e dei feed di inquadratura automatica.
Indice di bit | CAZ | Frame diviso | Dinamico | - |
---|---|---|---|---|
Altoparlante | D1 - |
- - |
D5 D6 |
Stream singolo Multistream |
Stanza | D2 - |
D3 D4 |
G7 G8 |
Stream singolo Multistream |
Modalità frame | Valore della modalità frame (byte meno 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 |
Controllo: GOOGXU_FRAME_STRATEGY
Questo controllo viene utilizzato per ottenere o impostare le modalità di inquadratura della fotocamera elencate in Valori bitmap della modalità Inquadratura automatica. Ogni modalità è rappresentata come
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 fotocamera
supporta CAZ, Speaker, Single-Stream
, Split-Frame, Room, Single-Stream
e
Dynamic, Room, Multi-Stream
ma nessun'altra modalità, GET_RES
deve restituire
0x000000000000000085 (ovvero 0b10000101
seguito da sette zero byte).
Il comando SET_CUR
viene utilizzato per inviare bitmap e indicare alla fotocamera in quale modalità fotocamera SINGOLA attivare.
Selettore del 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 |
Attiva la modalità fotocamera inquadratura attiva | |
GET_MIN |
In base alla fotocamera | |
GET_MAX |
In base alla fotocamera | |
GET_RES |
Restituisce una maschera di bit lunga 8 byte delle modalità 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 |
Imposta modalità inquadratura attiva |
Controllo: GOOGXU_REFRAME
Questo controllo viene utilizzato per attivare l'inquadratura one-shot, nota anche come OTAZ. Quando si attiva OTAZ, l'inquadratura della videocamera si aggancia alla visuale migliore della stanza. In seguito, il client riacquista la capacità di controllare i valori PTZ. Se l'inquadratura one-shot non è supportata, la videocamera non deve definire questo controllo.
Selettore del controllo | 2 | |||
---|---|---|---|---|
Operazione | SET |
|||
wLength |
1 | |||
Offset | Campo | Dimensioni | Valore | Descrizione |
0 | bReframe |
1 | Numero | Esecuzione richiesta di nuovo frame 0x01 |
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 richiesta per inquadratura one-shot |
Conteggio del numero di persone
Il conteggio delle presenze (OC) è una funzionalità utilizzata per stimare il numero di partecipanti in una sala riunioni, nonostante la visualizzazione ritagliata della videocamera.
Questa tabella mostra il comportamento previsto dei controlli della concorrenza ottimizzata e le loro interazioni con lo stream video della videocamera e con l'indicatore LED della videocamera.
Quando il conteggio del numero di persone è | 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 |
---|---|---|---|---|
Attivata | Lo streaming e l'audio non sono attivi | On | 0x01 |
Il numero di persone nell'intero campo visivo della videocamera. |
Attivata | live streaming | On | 0x01 |
Il numero di persone nell'intero campo visivo della videocamera. |
Attivata | Audio disattivato | Off | 0x01 |
Disattivata |
Disattivata | Lo streaming e l'audio non sono attivi | Off | 0x00 |
Disattivata |
Disattivata | live streaming | On | 0x00 |
Disattivata |
Disattivata | Audio disattivato | Off | 0x00 |
Disattivata |
Controllo: GOOGXU_OCCUPANCY_COUNTING_TOGGLE
Questo controllo viene utilizzato per attivare o disattivare la funzionalità per conteggiare gli occupanti in una stanza. L'impostazione di un valore pari a zero (0) disattiva questa funzionalità e uno (1) abilita questa funzionalità. Se questa funzionalità non è supportata, la videocamera non deve definire questo controllo.
Selettore del controllo | 3 | |||
---|---|---|---|---|
Operazione | GET / SET |
|||
wLength |
1 | |||
Offset | Campo | Dimensioni | Valore | Descrizione |
0 | bOccupancy |
1 | Booleano | Imposta la funzione di conteggio del numero di persone 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 persone è 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 |
Abilita o disabilita la funzionalità di conteggio del numero di persone |
Controllo: GOOGXU_OCCUPANCY_COUNTING_READ
Questo controllo viene utilizzato per leggere il numero di partecipanti in una stanza segnalato dalla videocamera quando è abilitato il conteggio del numero di persone. Se viene disattivata, la videocamera deve disattivare questo controllo. Se il conteggio del numero di persone non è supportato, la videocamera non deve definire questo controllo.
Selettore del controllo | 4 | |||
---|---|---|---|---|
Operazione | GET |
|||
wLength |
2 | |||
Offset | Campo | Dimensioni | Valore | Descrizione |
0 | bNumPeople |
2 | Numero | Il numero di persone rilevate e visibili. (Sola lettura) |
Il comportamento dei tipi di richieste supportati è il seguente:
Offset | 0 | Descrizione |
---|---|---|
GET_CUR |
Numero restituito 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 sono pensati per incoraggiare best practice 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 sulla videocamera host da condividere con i partner per il debug.
Selettore del controllo | 5 | |||
---|---|---|---|---|
Operazione | GET |
|||
wLength |
8 | |||
Offset | Campo | Dimensioni | Valore | Descrizione |
0 | bNumCameras |
1 | Numero | Il numero di videocamere aggiuntive collegate al dispositivo principale. |
1 | bIsMoving |
1 | Bitmap | 0 quando la videocamera è inattiva e diverso da zero quando è in movimento. I fornitori sono liberi di mappare assi o motori diversi a bit diversi. |
2 | Undef |
6 | Definita | Da estendere 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 | Aggiornamento automatico / lettura | ||
GET_DEF |
0x00 | 0x00 | 0x00 0x00 0x00 0x00 0x00 0x00 |
Controllo: GOOGXU_STATUS_RESET
Questo controllo viene utilizzato per inviare una richiesta di reimpostazione della videocamera. L'impostazione del valore di uno (1) richiede il ripristino della videocamera. La videocamera restituisce zero (0) se non è stata richiesta alcuna richiesta di riavvio dall'ultimo ripristino e una (1) se in fase di reimpostazione. Il ripristino attiva lo stesso comportamento di una riconnessione dell'hardware. Ciò è utile per i dispositivi autoalimentati in cui forzare una disconnessione USB per emulare un hotplug non è utile.
Selettore del controllo | 6 | |||
---|---|---|---|---|
Operazione | GET / SET |
|||
wLength |
1 | |||
Offset | Campo | Dimensioni | Valore | Descrizione |
0 | bResetRequest |
1 | Booleano | Invia una richiesta di reimpostazione dell'host e delle videocamere connesse. Restituisce 0x01 se la richiesta di reimpostazione è stata inviata 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 |
Preimpostazioni 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 dichiarare l'azione prevista del comando. L'impostazione del valore 1 (1) viene utilizzata per mappare i valori correnti di panoramica, inclinazione e zoom a un indice predefinito fornito. L'impostazione di un valore pari a due (2) dovrebbe comportare la transizione di panoramica, inclinazione e zoom della videocamera ai valori mappati in precedenza per l'indice fornito o alle coordinate di fabbrica predefinite (se non mappate 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 corrispondere
alla posizione predefinita della videocamera quando si attiva quando GOOGXU_FRAME_STRATEGY
è impostato su
NONE
.
Selettore del controllo | 7 | |||
---|---|---|---|---|
Operazione | SET |
|||
wLength |
2 | |||
Offset | Campo | Dimensioni | Valore | Descrizione |
0 | bPresetAction |
1 | Numero | 0x01: salva il preset 0x02: ripristina il preset 0x03: ripristina il valore predefinito. Il valore predefinito deve essere una coordinata preimpostata valida. |
1 | bPresetIndex |
1 | Numero | L'indice delle preimpostazioni attive. 0~N-1 , dove 0 è considerato la posizione di inizio predefinita della fotocamera e N-1 è una costante definita dal fornitore per il numero di preimpostazioni. |
Il comportamento dei tipi di richieste supportati è il seguente:
Offset | 0 | 1 | Descrizione |
---|---|---|---|
GET_MIN |
0x00 | 0x00 | |
GET_MAX |
0x03 | N-1 | N max preset supportati |
GET_RES |
0x01 | 0x01 | |
GET_LEN |
0x02 | 0x00 | 0x0002 |
GET_INFO |
0x02 | Solo scrittura | |
GET_DEF |
0x00 | 0x00 |
Mappatura ausiliaria panoramica e inclinazione
Alcune videocamere hanno componenti speciali, come i motori delle videocamere meccaniche, che richiedono la mappatura dei comandi XU rispetto ai controlli V4L2 standard affinché panoramica e inclinazione funzionino come previsto.
Questi controlli imitano i controlli assoluti e relativi di panoramica e inclinazione nella documentazione relativa alle specifiche UDC, fornendo ai dispositivi host un modo standard per mappare correttamente questi controlli.
Controllo: GOOGXU_PAN_TILT_ABSOLUTE
I controlli di mappatura ausiliari Pan e Tilt sono definiti nel Capitolo 4: Richieste specifiche di classe, Sezione 4.2.2.1.14 Controllo PanTilt (assoluto) della Specifica di classe VUC 1.5.
Selettore del controllo | 8 | |||
---|---|---|---|---|
Operazione | GET/SET |
|||
wLength |
8 | |||
Offset | Campo | Dimensioni | Valore | Descrizione |
0 | dwPanAbsolute |
4 | Numero firmato | L'impostazione dell'attributo del controllo Pan (assoluto) indirizzato. |
4 | dwTiltAbsolute |
4 | Numero firmato | L'impostazione dell'attributo del controllo inclinazione (assoluto) indirizzato. |
Il comportamento dei tipi di richieste supportati è il seguente:
Offset | 0 | 4 | Descrizione |
---|---|---|---|
GET_MIN |
In base alla fotocamera | ||
GET_MAX |
In base alla fotocamera | ||
GET_RES |
In base alla fotocamera | ||
GET_LEN |
0x0008 | ||
GET_INFO |
0x0B | Aggiornamento automatico / scrittura / lettura | |
GET_DEF |
0x00000000 | 0x00000000 |
Controllo: GOOGXU_PAN_TILT_RELATIVE
I controlli di mappatura ausiliari Pan e Tilt sono definiti nel Capitolo 4: Richieste specifiche di classe, Sezione 4.2.2.1.15 Controllo PanTilt (relativo) della Specifica di classe VUC 1.5.
Selettore del controllo | 9 | |||
---|---|---|---|---|
Operazione | GET/SET |
|||
wLength |
4 | |||
Offset | Campo | Dimensioni | Valore | Descrizione |
0 | bPanRelative |
1 | Numero firmato | L'impostazione dell'attributo del controllo Pan (relativo) indirizzato: 0: Arresto 1: spostamento in senso orario 0xFF: spostamento in direzione antiorario |
1 | bPanSpeed |
1 | Numero | Velocità del movimento della panoramica. |
2 | bTiltRelative |
1 | Numero firmato | L'impostazione dell'attributo del controllo di inclinazione (relativo) indirizzato: 0: Arresto 1: punta il piano di immagine verso l'alto 0xFF: punta il piano di immagine verso il basso |
3 | bTiltSpeed |
1 | Numero | Velocità del movimento di inclinazione. |
Il comportamento dei tipi di richieste supportati è il seguente:>
Offset | 0 | 1 | 2 | 3 | Descrizione |
---|---|---|---|---|---|
GET_MIN |
In base alla fotocamera | ||||
GET_MAX |
In base alla fotocamera | ||||
GET_RES |
In base alla fotocamera | ||||
GET_LEN |
0x04 | 0x00 | 0x0004 | ||
GET_INFO |
0x0B | Aggiornamento automatico / scrittura / lettura | |||
GET_DEF |
0x00 | 0x00 | 0x00 | 0x00 |
Argomenti correlati
- Driver Linux USB Video Class (UVC)
- Set di documenti classe video v1.5
- Specifiche USB 2.0
- Centro assistenza per l'hardware Google Meet
- Sezione Hardware Google Meet del Centro assistenza per amministratori di Google Workspace
- Script per il test delle API dell'unità di estensione della classe video USB dell'hardware Google Meet
Note di rilascio
Queste note di rilascio riflettono i miglioramenti e le nuove funzionalità di ogni revisione di questo documento.
15 novembre 2023
È stato aggiornato lo script di test per controllare e interpretare modalità di inquadratura valide. Rappresentazioni in byte chiare.
21 luglio 2023
È stato aggiunto uno script di test per consentire ai partner di convalidare le implementazioni relative alla conformità a questa specifica.
25 maggio 2023
Nota GOOGXU_PRESETS corretta per il numero di preimpostazioni. Deve essere N, non N-1.
17 aprile 2023
Versione iniziale.