W tym dokumencie opisujemy obsługiwane interfejsy API USB Video Class Extension Unit (XU), które są używane przez systemy konferencyjne Google Meet do włączania inteligentnych funkcji kamer. Opracowaliśmy tę specyfikację, aby wpłynąć na praktyki w celu włączenia tych funkcji oraz umożliwić naszym partnerom lepszą asynchroniczną skalowalność i testowanie.
Aby ułatwić partnerom sprawdzenie zgodności z tą specyfikacją, ten skrypt testowy analizuje i raportuje Twoją implementację.
Szczegółowe informacje o najnowszych zmianach w tym dokumencie znajdziesz w sekcji Informacje o wersji.
Konferencja taneczna
USB to raczej standard. W tym dokumencie:
- Liczby wielobajtowe mają postać big-endian (i są przesyłane little-endian).
- Tablice bajtów są w układzie pamięci małego producenta.
np. 0x12345678
i [0x78, 0x56, 0x34, 0x12]
są takie same.
Identyfikator GUID jednostki rozszerzenia
Jednostki rozszerzeń obsługujące tę specyfikację sterowania Meet XU muszą używać tego identyfikatora GUID.
Jednostka rozszerzenia | GUID |
---|---|
Sterowanie peryferyjne XU | {74D7E924-49C9-4A45-98A3-8A9F60061E83} |
Selektory XU sterowania peryferyjnego
To są zdefiniowane selektory XU elementów peryferyjnych.
Selektory sterowania | Wartość |
---|---|
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 |
Kontroluj typ żądania
Typy żądań kontrolnych zostały zdefiniowane w rozdziale 4: Żądania specyficzne dla klasy w specyfikacji klasy UVC 1.5.
Operacja | kontrola UVC |
---|---|
GET |
GET_CUR , GET_MIN , GET_MAX , GET_RES , GET_LEN , GET_INFO , GET_DEF |
SET |
SET_CUR |
Tryby aparatu
Tryby kamery służą do kadrowania osób w sali konferencyjnej i są jednymi z tuple
:
- Strategia (widok z kamery)
- Odchylenie (głośnik lub sala)
- Kanały (pojedynczy lub wiele strumieni)
Każdy wymiar może przyjmować wartości opisane w sekcjach poniżej.
Strategia automatycznego kadrowania
Funkcja | Opis |
---|---|
Brak | Kamera wyłączy wszystkie inteligentne funkcje kadrowania i umożliwi klientowi swobodne sterowanie wartościami PTZ. Uwaga: po włączeniu tej strategii kadrowania kamera pozostaje w obecnej pozycji przesunięcia, przechylenia i powiększenia. |
Ciągłe kadrowanie (CAZ) | Na podstawie odchylenia w kadrze kamera stale śledzi osoby w pomieszczeniu. Uwaga: w tym trybie kamera PTZ jest wyłączona. |
Podzielone klatki | Kamera może wygenerować odpowiednią liczbę wyświetleń filmu. W zależności od opcji Automatyczne kadrowanie kanałów tworzy ona kafelki w ramach jednego strumienia lub tworzy osobne strumienie wideo dla każdego wyświetlenia. Uwaga: w tym trybie kamera PTZ jest wyłączona. |
Widok dynamiczny | Co najmniej 1 kamera stara się zapewnić jak najlepszy obraz pomieszczenia. Pozwala ona zdecydować, czy połączyć kilka kanałów w jeden, czy stworzyć „ciekawy” widok bieżącego pokoju. Ten widok ma zapewnić najbardziej sprawiedliwy widok uczestników rozmowy w pokoju. Uwagi:
|
Wpływ automatycznego kadrowania
Funkcja | Opis |
---|---|
Osoba prowadząca z wysoką stawką (monitorowanie prelegenta) | Kamera próbuje jak najlepiej wykadrować osobę mówiącą w pomieszczeniu. W tym scenariuszu kamera powinna kierować się w stronę prowadzącego. Na przykład podczas prezentacji prezes zarządu w sali konferencyjnej. |
Współpraca (śledzenie sal) |
Kamera próbuje jak najlepiej wykadrować wszystkich uczestników spotkania. W takim przypadku kamera powinna traktować wszystkich uczestników równomiernie. Tej strategii należy używać na większości spotkań. |
Pliki danych z automatycznym kadrowaniem
Funkcja | Opis |
---|---|
Jeden strumień | Kamera wysyła pojedynczy strumień wideo do urządzenia. |
Wiele strumieni (praca w toku) |
Kamera dzieli strumień i tworzy kilka strumieni wideo, które można wysłać do hosta. Uwaga: pełna specyfikacja i oczekiwane działanie tej funkcji oczekują na sprawdzenie i nie jest obsługiwane w kolejnych wersjach tego dokumentu. |
Wartości bitmapy w trybie automatycznego kadrowania
Oprócz domyślnego stanu None
reprezentowanego przez pustą tablicę bajtów każdy bit w tablicy bajtów reprezentuje inny tryb kamery, który jest konkretną kombinacją strategii automatycznego kadrowania, odchylenia automatycznego kadrowania i kanałów automatycznego kadrowania.
Indeks bitowy | CAZ | Podzielona ramka | Dynamiczna | - |
---|---|---|---|---|
Głośnik | D1 – |
– – |
D5 D6 |
Pojedyncza transmisja Wiele strumieni |
Sala | D2 – |
D3 D4 |
D7 D8 |
Pojedyncza transmisja Wiele strumieni |
Tryby kadrowania | Wartość trybu klatki (najmniej istotny bajt) |
---|---|
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 |
Grupa kontrolna: GOOGXU_FRAME_STRATEGY
To ustawienie służy do pobierania lub ustawiania trybów kadrowania kamery zgodnie z opisem w artykule Wartości bitmapy w trybie automatycznego kadrowania. Każdy tryb jest reprezentowany
jako bit w odpowiedniej bitmapie. Polecenie GET_RES
zwraca 8-bajtową maskę bitową z wartością 0 (0) lub 1 (1), wskazując, czy funkcja jest nieobsługiwana lub obsługiwana przez urządzenie. Jeśli np. kamera obsługuje CAZ, Speaker, Single-Stream
, Split-Frame, Room, Single-Stream
i Dynamic, Room, Multi-Stream
, ale nie obsługuje żadnych innych trybów, GET_RES
powinien zwrócić 0x000000000000000085 (czyli 0b10000101
, a po nim 7 zerowych bajtów).
Polecenie SET_CUR
umożliwia wysyłanie map bitowych, aby informować kamerę, który tryb aparatu ma być włączony (JEDNOL).
Selektor sterowania | 1 | |||
---|---|---|---|---|
Operacja | GET / SET |
|||
wLength |
8 | |||
Przesunięcie | Pole | Rozmiar | Wartość | Opis |
0 | bActiveMode |
8 | Bitmapa | Ustawianie i powracanie trybu aktywnego aparatu |
Uwagi:
|
Działanie obsługiwanych typów żądań jest następujące:
Przesunięcie | 0 | Opis |
---|---|---|
GET_CUR |
Pobierz tryb aktywnego kadrowania kamery | |
GET_MIN |
Zależne od kamery | |
GET_MAX |
Zależne od kamery | |
GET_RES |
Zwraca 8-bajtową maskę bitową obsługiwanych trybów aparatu | |
GET_LEN |
0x0008 | Długość |
GET_INFO |
0x0B | Autoaktualizacja / zapis / odczyt |
GET_DEF |
0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 |
Wartość domyślna |
SET_CUR |
Ustaw tryb aktywnego kadrowania na kamerze |
Grupa kontrolna: GOOGXU_REFRAME
To ustawienie służy do uruchamiania kadrowania One-Shot, znanego też jako OTAZ. Po uruchomieniu funkcji OTAZ obraz z kamery zostanie dopasowany do najlepszego ujęcia w pomieszczeniu. Potem klient odzyskuje możliwość sterowania wartościami PTZ. Jeśli kadrowanie w ramach jednego ujęcia nie jest obsługiwane, kamera nie powinna definiować tego ustawienia.
Selektor sterowania | 2 | |||
---|---|---|---|---|
Operacja | SET |
|||
wLength |
1 | |||
Przesunięcie | Pole | Rozmiar | Wartość | Opis |
0 | bReframe |
1 | Liczby | 0x01 Wykonaj żądanie ponownego kadrowania |
Działanie obsługiwanych typów żądań jest następujące:
Przesunięcie | 0 | Opis |
---|---|---|
GET_MIN |
0x00 | |
GET_MAX |
0x01 | |
GET_RES |
0x01 | |
GET_LEN |
0x0001 | |
GET_INFO |
0x02 | Tylko do zapisu |
GET_DEF |
0x00 | |
SET_CUR |
Ustaw prośbę o kadrowanie One-Shot |
Zliczanie obłożenia
Zliczanie obłożenia to funkcja używana do szacowania liczby uczestników w sali konferencyjnej pomimo przyciętego widoku kamery.
Ta tabela przedstawia oczekiwane działanie elementów sterujących OC oraz ich interakcje ze strumieniem wideo z kamery i wskaźnikiem LED kamery.
Gdy liczenie obłożenia to | a strumień wideo z kamery to: | Dioda LED kamery powinna być | Wartość w kolumnie „GET_CUR ” w przypadku GOOGXU_OCCUPANCY_COUNTING_TOGGLE |
Wartość w kolumnie „GET_CUR ” w przypadku GOOGXU_OCCUPANCY_COUNTING_READ |
---|---|---|---|---|
Włączone | Nie odtwarzam ani nie jest wyciszony | Włączono | 0x01 |
Liczba osób znajdujących się w pełnym polu widzenia kamery. |
Włączone | transmisje | Włączono | 0x01 |
Liczba osób znajdujących się w pełnym polu widzenia kamery. |
Włączone | wyciszone, | Wyłącz | 0x01 |
Wyłączono |
Wyłączono | Nie odtwarzam ani nie jest wyciszony | Wyłącz | 0x00 |
Wyłączono |
Wyłączono | transmisje | Włączono | 0x00 |
Wyłączono |
Wyłączono | wyciszone, | Wyłącz | 0x00 |
Wyłączono |
Grupa kontrolna: GOOGXU_OCCUPANCY_COUNTING_TOGGLE
Ta opcja służy do włączania i wyłączania funkcji zliczania osób w pokoju. Ustawienie wartości 0 (0) wyłącza tę funkcję, a 1 (1) ją włącza. Jeśli ta funkcja nie jest obsługiwana, kamera nie powinna definiować tych ustawień.
Selektor sterowania | 3 | |||
---|---|---|---|---|
Operacja | GET / SET |
|||
wLength |
1 | |||
Przesunięcie | Pole | Rozmiar | Wartość | Opis |
0 | bOccupancy |
1 | Wartość logiczna | Ustaw funkcję zliczania obłożenia 0 x 00 Wyłącz funkcję 0x01 Włącz funkcję |
Działanie obsługiwanych typów żądań jest następujące:
Przesunięcie | 0 | Opis |
---|---|---|
GET_CUR |
Wróć, jeśli zliczanie obłożenia jest włączone | |
GET_MIN |
0x00 | |
GET_MAX |
0x01 | |
GET_RES |
0x01 | |
GET_LEN |
0x0001 | |
GET_INFO |
0x0B | Autoaktualizacja / zapis / odczyt |
GET_DEF |
0x00 | |
SET_CUR |
Włączanie i wyłączanie funkcji zliczania obłożenia |
Grupa kontrolna: GOOGXU_OCCUPANCY_COUNTING_READ
To ustawienie służy do odczytywania liczby uczestników w sali zgłoszonej przez kamerę, gdy włączone jest zliczanie obłożenia. Jeśli ta funkcja jest wyłączona, kamera powinna ją wyłączyć. Jeśli liczenie obłożenia nie jest obsługiwane, kamera nie powinna definiować tego ustawienia.
Selektor sterowania | 4 | |||
---|---|---|---|---|
Operacja | GET |
|||
wLength |
2 | |||
Przesunięcie | Pole | Rozmiar | Wartość | Opis |
0 | bNumPeople |
2 | Liczby | Liczba wykrytych osób w widocznym miejscu. (tylko do odczytu) |
Działanie obsługiwanych typów żądań jest następujące:
Przesunięcie | 0 | Opis |
---|---|---|
GET_CUR |
Zwróć liczbę wykrytych osób | |
GET_MIN |
0x0000 | |
GET_MAX |
0x00FF | |
GET_RES |
0x0001 | |
GET_LEN |
0x0002 | |
GET_INFO |
0x09 | Automatyczna aktualizacja / odczyt |
GET_DEF |
0x0000 |
Dane telemetryczne i diagnostyczne urządzenia
Te ustawienia mają zachęcać do lepszych metod debugowania na sprzęcie do Google Meet i zwykle nie są widoczne dla użytkowników.
Grupa kontrolna: GOOGXU_STATUS_INFO
To ustawienie służy do wysyłania zapytań o informacje z kamery hostującej i udostępniania ich partnerom na potrzeby debugowania.
Selektor sterowania | 5 | |||
---|---|---|---|---|
Operacja | GET |
|||
wLength |
8 | |||
Przesunięcie | Pole | Rozmiar | Wartość | Opis |
0 | bNumCameras |
1 | Liczby | Liczba dodatkowych kamer podłączonych do urządzenia głównego. |
1 | bIsMoving |
1 | Bitmapa | Wartość 0, gdy kamera jest nieaktywna, i wartość inna niż 0, gdy się porusza. Dostawcy mogą mapować różne osie lub silniki na różne części. |
2 | Undef |
6 | Nie zdefiniowano | Zostanie ona przedłużona w przyszłości. |
Działanie obsługiwanych typów żądań jest następujące:
Przesunięcie | 0 | 1 | 2 | Opis |
---|---|---|---|---|
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 | Automatyczna aktualizacja / odczyt | ||
GET_DEF |
0x00 | 0x00 | 0x00 0x00 0x00 0x00 0x00 0x00 |
Grupa kontrolna: GOOGXU_STATUS_RESET
To ustawienie służy do wysyłania prośby o zresetowanie kamery. Ustawienie wartości 1 (1) wymaga zresetowania kamery. Kamera zwraca zero (0), jeśli od ostatniego resetowania nie wysłano prośby o ponowne uruchomienie, oraz jedną (1), jeśli się resetuje. Reset uruchamia to samo co ponowne połączenie sprzętu. Jest to przydatne w przypadku urządzeń z własnym zasilaniem, gdy wymuszanie odłączenia USB w celu emulacji podłączonej wtyczki nie jest przydatne.
Selektor sterowania | 6 | |||
---|---|---|---|---|
Operacja | GET / SET |
|||
wLength |
1 | |||
Przesunięcie | Pole | Rozmiar | Wartość | Opis |
0 | bResetRequest |
1 | Wartość logiczna | Wyślij prośbę o zresetowanie do hosta i połączonych kamer. zwraca wartość 0x01, jeśli żądanie resetowania zostało wysłane od ostatniego resetu, a w przeciwnym razie – 0x00. |
Działanie obsługiwanych typów żądań jest następujące:
Przesunięcie | 0 | Opis |
---|---|---|
GET_MIN |
0x00 | |
GET_MAX |
0x01 | |
GET_RES |
0x01 | |
GET_LEN |
0x0001 | |
GET_INFO |
0x03 | Zapis / odczyt |
GET_DEF |
0x00 |
Gotowe ustawienia PTZ
Służy do konfigurowania i przywracania pola widzenia kamery do wstępnie ustawionego położenia.
Grupa kontrolna: GOOGXU_PRESETS
Ten element sterujący umożliwia ustawienie wartości przesuwania, pochylenia i powiększenia (PTZ) kamery do gotowej konfiguracji.
Parametr Preset Action
wskazuje zamierzone działanie polecenia. Ustawienie wartości 1 (1) umożliwia mapowanie bieżących wartości przesunięcia, pochylenia i powiększenia na udostępniony indeks. Ustawienie wartości 2 (2) powinno spowodować przeniesienie, przesuwanie, pochylanie i powiększanie kamery do wcześniej zmapowanych wartości dla podanego indeksu lub domyślnych współrzędnych fabrycznych (jeśli nie były wcześniej mapowane). Ustawienie wartości 3 (3) powoduje zresetowanie indeksu do domyślnych współrzędnych fabrycznych.
Preset Index
służy do określania współrzędnych PTZ zmapowanych na indeks.
Wartość Preset index
o wartości 0 (0) jest zmapowana na współrzędne domu i powinna być domyślną pozycją kamery po wybudzeniu, gdy parametr GOOGXU_FRAME_STRATEGY
jest ustawiony na NONE
.
Selektor sterowania | 7 | |||
---|---|---|---|---|
Operacja | SET |
|||
wLength |
2 | |||
Przesunięcie | Pole | Rozmiar | Wartość | Opis |
0 | bPresetAction |
1 | Liczby | 0x01: zapisz gotowe ustawienia 0x02: przywróć gotowe ustawienia 0x03: przywróć gotowe ustawienia do wartości domyślnych. (Wartość domyślna powinna być prawidłową gotową współrzędną). |
1 | bPresetIndex |
1 | Liczby | Indeks aktywnych gotowych ustawień. 0~N-1 gdzie 0 jest uznawane za domyślną pozycję początkową kamery, a N-1 to zdefiniowana przez dostawcę stała liczba gotowych ustawień. |
Działanie obsługiwanych typów żądań jest następujące:
Przesunięcie | 0 | 1 | Opis |
---|---|---|---|
GET_MIN |
0x00 | 0x00 | |
GET_MAX |
0x03 | N-1 | Obsługiwane są maksimum N gotowych ustawień |
GET_RES |
0x01 | 0x01 | |
GET_LEN |
0x02 | 0x00 | 0x0002 |
GET_INFO |
0x02 | Tylko do zapisu | |
GET_DEF |
0x00 | 0x00 |
Dodatkowe mapowanie do przesuwania i pochylania
Niektóre kamery mają specjalne komponenty, np. silniki kamer mechanicznych, które wymagają mapowania poleceń XU na standardowe elementy sterujące V4L2, aby umożliwić prawidłowe przesuwanie i przechylanie.
Te elementy sterujące naśladują bezwzględne i względne elementy sterujące przesuwaniem i przechyleniem podane w dokumentacji specyfikacji UVC, zapewniając standardowy sposób prawidłowego mapowania tych elementów przez urządzenia hostujące.
Grupa kontrolna: GOOGXU_PAN_TILT_ABSOLUTE
Dodatkowe elementy sterujące przesuwaniem i przechylaniem zostały zdefiniowane w rozdziale 4. Żądania specyficzne dla danej klasy – sekcja 4.2.2.1.14 Sterowanie przechylaniem (bezwzględnym) w specyfikacji klasy UVC 1.5.
Selektor sterowania | 8 | |||
---|---|---|---|---|
Operacja | GET/SET |
|||
wLength |
8 | |||
Przesunięcie | Pole | Rozmiar | Wartość | Opis |
0 | dwPanAbsolute |
4 | Podpisany numer | Ustawienie atrybutu adresowanej kontroli przesuwania (bezwzględnej). |
4 | dwTiltAbsolute |
4 | Podpisany numer | Ustawienie atrybutu adresowanej kontroli przechylania (bezwzględnej). |
Działanie obsługiwanych typów żądań jest następujące:
Przesunięcie | 0 | 4 | Opis |
---|---|---|---|
GET_MIN |
Zależne od kamery | ||
GET_MAX |
Zależne od kamery | ||
GET_RES |
Zależne od kamery | ||
GET_LEN |
0x0008 | ||
GET_INFO |
0x0B | Autoaktualizacja / zapis / odczyt | |
GET_DEF |
0x00000000 | 0x00000000 |
Grupa kontrolna: GOOGXU_PAN_TILT_RELATIVE
Dodatkowe elementy sterujące przesuwaniem i przechylaniem są zdefiniowane w rozdziale 4. Zgłoszenia specyficzne dla danej klasy – sekcja 4.2.2.1.15 Sterowanie przesuwaniem (względne) specyfikacji klasy UVC 1.5.
Selektor sterowania | 9 | |||
---|---|---|---|---|
Operacja | GET/SET |
|||
wLength |
4 | |||
Przesunięcie | Pole | Rozmiar | Wartość | Opis |
0 | bPanRelative |
1 | Podpisany numer | Ustawienie atrybutu obsługiwanego elementu sterującego przesuwaniem (względnego): 0: zatrzymaj 1: przejście w prawo 0xFF: przesunięcie w lewo |
1 | bPanSpeed |
1 | Liczby | Prędkość ruchu przesuwania. |
2 | bTiltRelative |
1 | Podpisany numer | Ustawienie atrybutu adresu ustawienia przechylenia (względnego): 0: zatrzymanie 1: skieruj płaszczyznę obrazową w górę 0xFF: skieruj płaszczyznę obrazową w dół |
3 | bTiltSpeed |
1 | Liczby | Prędkość ruchu pochylenia. |
Działanie obsługiwanych typów żądań jest następujące:
Przesunięcie | 0 | 1 | 2 | 3 | Opis |
---|---|---|---|---|---|
GET_MIN |
Zależne od kamery | ||||
GET_MAX |
Zależne od kamery | ||||
GET_RES |
Zależne od kamery | ||||
GET_LEN |
0x04 | 0x00 | 0x0004 | ||
GET_INFO |
0x0B | Autoaktualizacja / zapis / odczyt | |||
GET_DEF |
0x00 | 0x00 | 0x00 | 0x00 |
Powiązane artykuły
- Sterownik UVC USB na urządzenia z systemem Linux
- Zestaw dokumentów klasy Video v1.5
- Specyfikacja USB 2.0
- Centrum pomocy sprzętu do Google Meet
- Sekcja „Sprzęt do Google Meet” w Centrum pomocy dla administratorów Google Workspace
- Skrypt testowy interfejsów API jednostki rozszerzeń wideo USB do sprzętu do Google Meet
Informacje o wersjach
Te informacje o wersji opisują ulepszenia i nowe funkcje zawarte w każdej wersji tego dokumentu.
15 listopada 2023 r.
Zaktualizowaliśmy skrypt testowy, aby umożliwić sprawdzanie i interpretowanie prawidłowych trybów kadrowania. Wyjaśnione reprezentacje bajtów.
21 lipca 2023 r.
Dodaliśmy skrypt testowy dla partnerów, aby sprawdzać zgodność implementacji z tą specyfikacją.
25 maja 2023 r.
Poprawiono uwagę o GOOGXU_PRESETS dotyczącej liczby gotowych ustawień. Powinno to być N, a nie N-1.
17 kwietnia 2023 r.
Pierwsza wersja.