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

Ten dokument zawiera informacje o obsługiwanych interfejsach API USB Video Class Extension Unit (XU) używanych przez systemy konferencyjne Google Meet do włączania funkcji inteligentnej kamery. Celem stworzenia tej specyfikacji jest wpłynięcie na praktyki w celu umożliwienia korzystania z tych funkcji oraz zapewnienie partnerom lepszej skalowalności asynchronicznej i testów.

Szczegółowe informacje o najnowszych zmianach w tym dokumencie znajdziesz w informacjach o wersji.

Obiekt testowy

Aby pomóc partnerom w weryfikacji zgodności z tą specyfikacją, udostępniamy im urządzenia Chromebox wideokonferencje w trybie dewelopera. Zezwalaj na zapisywanie w systemie plików. Dodaj do pliku /etc/chrome_dev.conf te wiersze:

--enable-logging
--log-level=0

Uruchom ponownie urządzenie, podłącz kamerę i klawiaturę USB, a następnie naciśnij Ctrl-Alt-X. Spełnienie wymagań przez aktywną kamerę zostanie sprawdzone i zapisywane w /home/chronos/user/log/chrome.

Konwencja little-endian

USB to standard little-endian. W tym dokumencie:

  • Wielokrotne bajty są wyświetlane w formacie big-endian (i przesyłane w formacie little-endian).
  • Tablice bajtów są w układzie pamięci little-endian.

Na przykład 0x12345678 jest takie samo jak [0x78, 0x56, 0x34, 0x12].

Identyfikator GUID jednostki rozszerzenia

Jednostki rozszerzeń obsługujące tę specyfikację kontroli XU w Meet muszą używać tego identyfikatora GUID.

Jednostka rozszerzenia GUID
Peripheral Control XU {74D7E924-49C9-4A45-98A3-8A9F60061E83}

Selektory XU sterowania urządzeniami peryferyjnymi

To są zdefiniowane selektory XU sterowania peryferyjnego.

Selektory 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
GOOGXU_SATELLITE_INFO 0x0A

Typ żądania sterowania

Typy żądań sterujących są zdefiniowane w rozdziale 4: „Zależne od klasy żądania” specyfikacji UVC 1.5 Class Specification.

Operacja Sterowanie UVC
GET GET_CUR, GET_MIN, GET_MAX, GET_RES, GET_LEN, GET_INFO, GET_DEF
SET SET_CUR

Tryby aparatu

Tryby aparatu służą do kadrowania osób w sali konferencyjnej i są tuple:

  • Strategia (widok z kamery)
  • Uprzedzenie (głośnik lub pomieszczenie)
  • pliki danych (jeden lub wiele strumieni),

Każdy wymiar może przyjmować wartości opisane w następnych sekcjach.

Strategia automatycznego kadrowania

We wszystkich trybach automatycznego kadrowania oprócz „Brak” ręczne przesuwanie, przechylanie i powiększanie są wyłączone.

Funkcja Opis
Brak Kamera wyłącza wszystkie funkcje inteligentnego kadrowania i pozwala klientowi swobodnie kontrolować wartości PTZ.
Uwaga: gdy ta strategia kadrowania jest włączona, kamera pozostaje w bieżącej pozycji przesunięcia, pochylenia i powiększenia.
Ciągłe kadrowanie (CAZ) Na podstawie kadrowania kamery ciągle śledzi osoby w pokoju.
Split Frames Aparat tworzy tyle widoków filmu, ile jest potrzebnych. Na podstawie opcji Automatyczne kadrowanie źródeł tworzy z nich kafelki w jednym strumieniu lub osobne strumienie wideo dla każdego widoku.
Widok dynamiczny Co najmniej 1 kamera stara się zapewnić najlepszy widok pokoju. Może ona decydować o tym, czy połączyć kilka strumieni w jeden, czy też wyświetlić „ciekawszą” widok bieżącego pokoju.
Ten widok ma na celu zapewnienie uczestnikom spotkania w pokoju jak najbardziej równego widoku.
Preferowany przez dostawcę System kamery korzysta z własnej logiki, aby określić najlepszy widok pokoju. Strategia kadrowa może ulec zmianie bez powiadomienia. Jeśli na przykład liczba osób w pokoju się zmieni lub kamera wykryje różnicę między spotkaniem w trybie „Prezentacja o wysokich stawkach” a spotkaniem w trybie „Współpraca”, system może dostosować lub zmienić strategię kadrowania w zależności od potrzeb. W tym trybie wywołanie getCur powinno zwracać VENDOR_PREFERRED, a nie domyślny tryb kadrowania wybrany przez system.

Błąd automatycznego kadrowania

Funkcja Opis
Prezentujący w sytuacji wysokiej stawki (śledzenie głośnika) Kamera stara się jak najlepiej uchwycić osobę aktywnie uczestniczącą w rozmowie.
W tym przypadku kamera powinna być ustawiona na prowadzącego. Może to być na przykład prezes w salce konferencyjnej podczas prezentacji.
Współpraca
(śledzenie pokoju)		 Kamera stara się jak najlepiej ująć wszystkich uczestników w sali. W tym przypadku kamera powinna traktować wszystkich uczestników w równy sposób.

Pliki danych z automatycznym kadrowaniem

Funkcja Opis
Single-Stream Kamera wysyła jeden strumień wideo do urządzenia hosta.
Multi-Stream
(w trakcie tworzenia)		 Kamera dzieli strumień i tworzy wiele strumieni wideo, które są wysyłane do gospodarza.
Uwaga: pełna specyfikacja i oczekiwane działanie tej funkcji są w trakcie sprawdzania i nie są obsługiwane do czasu późniejszych wersji tego dokumentu.

Wartości bitmapy trybu automatycznego kadrowania

Z wyjątkiem domyślnego stanu None, który jest reprezentowany przez pusty tablicowy tablice bajtów, każdy bit w tablicy bajtów reprezentuje inny tryb kamery, który jest określoną kombinacją strategii automatycznego kadrowania, błędu automatycznego kadrowania i plików danych automatycznego kadrowania.

Pliki danych z automatycznym kadrowaniem CAZ Ramka podzielona Dynamiczna Preferowany przez dostawcę Automatyczne kadrowanie
Single-Stream D1 
D2		 –
 D3		 D5
D7		 D9 (głośnik lub pokój) Głośnik
Pokój
Multi-Stream –
–		 –
 D4		 D6
D8		 - Prezentujący
Sala
Tryby ramek Wartość trybu ramki (najmniej istotny bajt)
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

Element sterujący: GOOGXU_FRAME_STRATEGY

Ten element sterujący służy do uzyskiwania lub ustawiania trybów kadrowania kamery wymienionych w wartościach bitmapy trybu automatycznego kadrowania. Każdy tryb jest reprezentowany przez bit w odpowiedniej bitmapie. Polecenie GET_RES zwraca 8-bajtową maskę bitową o wartości zero (0) lub jeden (1), odpowiednio wskazującą, czy funkcja jest obsługiwana przez urządzenie, czy nie. Jeśli na przykład aparat obsługuje tryby CAZ, Speaker, Single-Stream, Split-Frame, Room, Single-Stream i Dynamic, Room, Multi-Stream, ale nie obsługuje innych trybów, funkcja GET_RES powinna zwrócić 0x000000000000000085 (czyli 0b10000101, a potem 7 bajtów z zerami).

Polecenie SET_CUR służy do wysyłania bitmap, które informują kamerę, który tryb SINGLE ma być włączony.

Selektor elementów sterujących 1
Operacja GET / SET
wLength 8
Przesunięcie Pole Rozmiar Wartość Opis
0 bActiveMode 8 Bitmapa Ustawianie i przywracanie trybu aktywnej kamery
Uwagi:

Obsługiwane typy żądań działają w ten sposób:

Przesunięcie 0 Opis
GET_CUR Aktywny tryb kadrowania kamery
GET_MIN Zależy od aparatu
GET_MAX Zależy od aparatu
GET_RES Zwraca 8-bajtową maskę bitową obsługiwanych trybów kamery.
GET_LEN 0x0008 Długość
GET_INFO 0x0B AutoUpdate / Write / Read
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 Wartość domyślna
SET_CUR Ustawianie trybu kadrowania aktywnej kamery

Element sterujący: GOOGXU_REFRAME

Ten element sterujący służy do wywołania kadrowania jednorazowego, znanego też jako OTAZ. Gdy zostanie uruchomiony OTAZ, widok kamery przełączy się na najlepszy widok pokoju. Następnie klient odzyskuje możliwość kontrolowania wartości PTZ. Jeśli kadrowanie jednym ujęciem nie jest obsługiwane, aparat nie powinien definiować tego ustawienia.

Selektor elementów sterujących 2
Operacja SET
wLength 1
Przesunięcie Pole Rozmiar Wartość Opis
0 bReframe 1 Liczba 0x01 Wykonaj żądanie reframe

Obsługiwane typy żądań działają w ten sposób:

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 żądanie dotyczące kadrowania jednoujęcikowego

Zliczanie zajętości

Liczenie osób (OC) to funkcja służąca do oszacowania liczby uczestników w sali konferencyjnej, pomimo przyciętego widoku kamery.

Ta tabela pokazuje oczekiwane działanie elementów sterujących OC oraz ich interakcje z strumieniem wideo z kamery i wskaźnikiem LED kamery.

Gdy rejestrowanie obłożenia jest & strumień wideo z kamery: Wskaźnik LED aparatu powinien GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR
Włączone Nie jest transmitowane i nie jest wyciszone. Włączono 0x01 Liczba osób w całym polu widzenia kamery.
Włączone Streaming Włączono 0x01 Liczba osób w całym polu widzenia kamery.
Włączone wyciszony, Wyłącz 0x01 Wyłączono
Wyłączono Nie jest transmitowane i nie jest wyciszone. Wyłącz 0x00 Wyłączono
Wyłączono Streaming Włączono 0x00 Wyłączono
Wyłączono wyciszony, Wyłącz 0x00 Wyłączono

Element sterujący: GOOGXU_OCCUPANCY_COUNTING_TOGGLE

Ten element służy do włączania i wyłączania funkcji zliczania osób w pokoju. Ustawienie wartości 0 wyłącza tę funkcję, a wartość 1 ją włączy. Jeśli ta funkcja nie jest obsługiwana, kamera nie powinna definiować tego ustawienia.

Selektor elementów sterujących 3
Operacja GET / SET
wLength 1
Przesunięcie Pole Rozmiar Wartość Opis
0 bOccupancy 1 Wartość logiczna Ustaw funkcję zliczania obłożenia
0x00 Wyłącz funkcję
0x01 Włącz funkcję

Obsługiwane typy żądań działają w ten sposób:

Przesunięcie 0 Opis
GET_CUR Zwrot, jeśli jest włączone rejestrowanie obłożenia
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x0B AutoUpdate / Write / Read
GET_DEF 0x00
SET_CUR Włączanie i wyłączanie funkcji zliczania obłożenia

Element sterujący: GOOGXU_OCCUPANCY_COUNTING_READ

Ten element służy do odczytywania liczby uczestników w pokoju, którą podaje kamera, gdy włączone jest zliczanie osób. Jeśli funkcja zliczania liczby osób jest wyłączona, kamera powinna wyłączyć tę opcję. Jeśli funkcja zliczania osób nie jest obsługiwana, kamera nie powinna definiować tego ustawienia.

Selektor elementów sterujących 4
Operacja GET
wLength 2
Przesunięcie Pole Rozmiar Wartość Opis
0 bNumPeople 2 Liczba Liczba wykrytych osób w polu widzenia. (tylko do odczytu)

Obsługiwane typy żądań działają w ten sposób:

Przesunięcie 0 Opis
GET_CUR Zwraca liczbę wykrytych pasażerów
GET_MIN 0x0000
GET_MAX 0x00FF
GET_RES 0x0001
GET_LEN 0x0002
GET_INFO 0x09 AutoUpdate / Read
GET_DEF 0x0000

Dane telemetryczne i diagnostyka urządzenia

Te opcje mają zachęcać do stosowania lepszych metod debugowania sprzętu Meet i zwykle nie są widoczne dla użytkowników.

Element sterujący: GOOGXU_STATUS_INFO

To ustawienie służy do wysyłania zapytań o informacje z kamery gospodarza, które są udostępniane partnerom na potrzeby debugowania.

Selektor elementów sterujących 5
Operacja GET
wLength 8
Przesunięcie Pole Rozmiar Wartość Opis
0 bNumCameras 1 Liczba Liczba dodatkowych satelitów dołączonych do głównej kamery, które mogą wpływać na strumień kamery zwracany do hosta.
1 bIsMoving 1 Bitmapa 0, gdy kamera jest nieaktywna, i wartość różną od 0, gdy zmieniają się wartości PTZ. Dostawcy mogą dowolnie mapować różne osie lub silniki na różne bity.
2 Undef 6 Undef W przyszłości może zostać rozszerzona.

Obsługiwane typy żądań działają w ten sposób:

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 AutoUpdate / Read
GET_DEF 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00

Element sterujący: GOOGXU_SATELLITE_INFO

To ustawienie służy do wysyłania zapytań do urządzeń satelitarnych połączonych z tym systemem kamer.

Selektor elementów sterujących 0x0A
Operacja GET
wLength 20
Przesunięcie Pole Rozmiar Wartość Opis
0 bSatelliteList 20 Bitmapa Lista typów satelitów dołączonych do systemu. Zawiera 4 osobne 5-bajtowe sloty. Każdy z nich jest opisany w ten sposób:
Przesunięcie Opis
0 Liczba tego typu satelity.
1-2 Identyfikator dostawcy tego typu satelity.
3-4 Identyfikator produktu dla tego typu satelity.

Obsługiwane typy żądań działają w ten sposób:

Przesunięcie 0 Opis
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 bajtów
GET_INFO 0x09 AutoUpdate / Read
GET_DEF 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00

Element sterujący: GOOGXU_STATUS_RESET

Ten element sterujący służy do wysłania do aparatu żądania zresetowania. Ustawienie wartości 1 powoduje zresetowanie kamery. Kamera zwraca wartość 0, jeśli od ostatniego zresetowania nie było prośby o ponowne uruchomienie kamery, oraz 1, jeśli jest ona resetowana. Resetowanie musi powodować ponowne uruchamianie kamery. (jest to konieczne w przypadku urządzeń samoczynnych, w których przypadku wymuszenie odłączenia USB w celu emulacji hotplug nie jest przydatne).

Selektor elementów sterujących 6
Operacja GET / SET
wLength 1
Przesunięcie Pole Rozmiar Wartość Opis
0 bResetRequest 1 Wartość logiczna Prześlij prośbę o zresetowanie do gospodarza i połączonych kamer.
Zwraca wartość 0x01, jeśli od ostatniego zresetowania urządzenia wysłano żądanie resetowania, w przeciwnym razie zwraca wartość 0x00.

Obsługiwane typy żądań działają w ten sposób:

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 kamery PTZ

Służy do konfigurowania i przywracania pola widzenia kamery do wstępnie ustawionej pozycji.

Element sterujący: GOOGXU_PRESETS

Ta opcja służy do ustawiania wartości przesuwania, pochylania i przybliżania (PTZ) kamery zgodnie z zaprogramowaną konfiguracją.

Preset Action służy do określenia oczekiwanego działania polecenia. Ustawienie wartości 1 służy do zmapowania bieżących wartości panoramowania, przechylania i powiększenia do podanego indeksu wstępnie ustawionego. Ustawienie wartości 2 powoduje przejście na wartości panoramowania, przechylania i przybliżania kamery do wcześniej zmapowanych wartości dla podanego indeksu lub do domyślnych współrzędnych fabrycznych (jeśli nie zostały wcześniej zmapowane). Ustawienie wartości 3 powoduje zresetowanie indeksu do domyślnych współrzędnych fabrycznych.

Wartość Preset Index służy do określenia współrzędnych PTZ mapowanych na indeks. Wartość Preset index 0 jest mapowana na współrzędne wyjściowe i powinna być domyślną pozycją kamery po jej włączeniu, gdy parametr GOOGXU_FRAME_STRATEGY ma wartość NONE.

Selektor elementów sterujących 7
Operacja SET
wLength 2
Przesunięcie Pole Rozmiar Wartość Opis
0 bPresetAction 1 Liczba 0x01: zapisz ustawienie
0x02: przywróć ustawienie
0x03: przywróć ustawienie do domyślnego. (wartość domyślna powinna być prawidłową współrzędną wstępną).
1 bPresetIndex 1 Liczba Indeks aktywnych wstępnie ustawionych wartości. 0 do N-1
gdzie 0 to domyślna pozycja początkowa kamery, a N-1 to zdefiniowana przez producenta stała liczba wstępnie ustawionych wartości.

Obsługiwane typy żądań działają w ten sposób:

Przesunięcie 0 1 Opis
GET_MIN 0x00 0x00
GET_MAX 0x03 N-1 N maks. wstępnie określonych ustawień
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 Tylko do zapisu
GET_DEF 0x00 0x00

Przesuwanie i pochylanie mapy pomocniczej

Niektóre kamery mają specjalne komponenty, takie jak silniki w przypadku kamer mechanicznych lub funkcje cyfrowego PTZ. W takim przypadku użyj standardowych elementów sterujących V4L2 do panoramowania, przechylania i powiększania.

Element sterujący: GOOGXU_PAN_TILT_ABSOLUTE (wycofany)

Elementy sterujące mapowania pomocniczego przesunięcia i pochylenia są zdefiniowane w rozdziale 4: Prośby o specyfikację dotyczące klasy UVC 1.5 (rozdział 4.2.2.1.14).

Element sterujący: GOOGXU_PAN_TILT_RELATIVE (wycofany)

Elementy sterujące przesuwaniem i pochylaniem w ramach mapowania pomocniczego są zdefiniowane w rozdziale 4: Prośby o specyfikację dotyczące klasy UVC 1.5 (sekcja 4.2.2.1.15).

Informacje o wersjach

Te informacje o wersji opisują ulepszenia i nowe funkcje wprowadzone w poszczególnych wersjach tego dokumentu.

27 stycznia 2025 r.

21 maja 2024 r.

15 listopada 2023 r.

Zaktualizowano skrypt testowy, aby sprawdzać i interpretować prawidłowe tryby kadrowania. wyjaśnienie reprezentacji bajtów;

21 lipca 2023 r.

Dodaliśmy testowy skrypt dla partnerów, który umożliwia weryfikację implementacji pod kątem zgodności z tą specyfikacją.

25 maja 2023 r.

Poprawiono GOOGXU_PRESETS notatkę dotyczącą liczby wstępnie ustawionych wartości. Powinien to być N, a nie N-1.

17 kwietnia 2023 r.

Pierwsza wersja.