Interfejsy API przedłużenia do klasy wideo przez USB sprzętu do Google Meet

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:
  • Tej strategii należy używać na większości spotkań.
  • W tym trybie PTZ jest wyłączona.

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

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.