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

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:
  • La maggior parte delle riunioni dovrebbe usare questa strategia.
  • La PTZ è disattivata in questa modalità.

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

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.