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

Ten dokument zawiera opis obsługiwanych interfejsów API jednostki rozszerzeń (XU) klasy wideo USB, które są używane przez systemy konferencyjne Google Meet do włączania inteligentnych funkcji kamery. Celem utworzenia tej specyfikacji jest wpłynięcie na praktyki, które umożliwią korzystanie z tych funkcji, a także zapewnienie naszym partnerom lepszej skalowalności asynchronicznej i możliwości testowania.

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

Obiekt testowy

Aby pomóc partnerom w sprawdzaniu zgodności z tą specyfikacją, udostępniamy środowisko testowe na urządzeniach Chromebox wideokonferencje ustawionych w trybie deweloperskim. Włącz 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, naciśnij Ctrl-Alt-X, a zgodność specyfikacji aktywnej kamery zostanie sprawdzona i zarejestrowana w /var/log/chrome/chrome (jeśli używasz podpisanego obrazu, to w /home/chronos/user/log/chrome).

Konwencja little-endian

USB to standard little-endian. W tym dokumencie:

  • Liczby wielobajtowe są wyświetlane w formacie big-endian (a przesyłane w formacie little-endian).
  • Tablice bajtów są ułożone w pamięci w formacie little-endian.

Na przykład 0x12345678 to to samo co [0x78, 0x56, 0x34, 0x12].

Identyfikator GUID jednostki rozszerzenia

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

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

Selektory XU kontroli urządzeń peryferyjnych

Są to zdefiniowane selektory XU kontroli urządzeń peryferyjnych.

Selektory elementów sterujących 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 prośby o kontrolę

Typy żądań sterujących są zdefiniowane w rozdziale 4: Żądania dotyczące klasy w specyfikacji klasy UVC 1.5.

Operacja Sterowanie 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ą tuple:

  • Strategia (obraz z kamery)
  • Uprzedzenia (głośnik lub pomieszczenie)
  • Pliki danych (jeden lub wiele strumieni)

Każdy wymiar może przyjmować wartości opisane w kolejnych sekcjach.

Strategia automatycznego kadrowania

We wszystkich trybach automatycznego kadrowania z wyjątkiem trybu „Brak” ręczne przesuwanie, przechylanie i powiększanie są wyłączone.

Funkcja Opis
Brak Kamera wyłącza wszystkie inteligentne funkcje kadrowania i umożliwia klientowi swobodne sterowanie wartościami PTZ.
Uwaga: gdy ta strategia kadrowania jest ustawiona, kamera pozostaje w bieżącej pozycji przesuwania, pochylania i powiększania.
Ciągłe kadrowanie (CAZ) Na podstawie tego ustawienia kamera stale śledzi osoby w pomieszczeniu.
Dzielenie klatek Kamera tworzy tyle widoków wideo, ile jest potrzebnych. W zależności od opcji Automatyczne kadrowanie łączy je w kafelki w jednym strumieniu lub tworzy osobne strumienie wideo dla każdego widoku.
Widok dynamiczny Co najmniej jedna kamera próbuje zapewnić najlepszy widok pomieszczenia. Może zdecydować, czy połączyć wiele strumieni w jeden, czy też zapewnić „ciekawy” widok bieżącego pomieszczenia.
 Celem tego widoku jest zapewnienie najbardziej sprawiedliwego widoku uczestników spotkania w pokoju.
Preferowany przez dostawcę System kamer korzysta z własnej logiki, aby określić najlepszy widok pomieszczenia. Podstawowa strategia kadrowania może ulec zmianie bez powiadomienia. Jeśli np. zmieni się liczba osób w pokoju lub kamera wykryje różnicę między spotkaniem „Prezentacja o wysokiej stawce” a spotkaniem „Współpraca”, system może dostosować lub zmienić strategię kadrowania w tym trybie. W tym trybie wywołanie getCur powinno zwracać VENDOR_PREFERRED, a nie wybrany przez system podstawowy tryb kadrowania.

Błąd automatycznego kadrowania

Funkcja Opis
Prezentacja o dużym znaczeniu (śledzenie mówcy) Kamera próbuje jak najlepiej wykadrować osobę, która aktywnie mówi w pomieszczeniu.
W tym przypadku kamera powinna być skierowana na prezentera. Na przykład dyrektor generalny w sali konferencyjnej prowadzący prezentację.
Współpraca
(śledzenie pomieszczeń)		 Kamera próbuje jak najlepiej wykadrować wszystkich uczestników w sali. W takiej sytuacji kamera powinna traktować wszystkich uczestników w równy sposób.

Pliki danych z automatycznym kadrowaniem

Funkcja Opis
Single-Stream Kamera przesyła do urządzenia hosta jeden strumień wideo.
Multi-Stream
(w trakcie prac)		 Kamera dzieli strumień i tworzy wiele strumieni wideo, które wysyła do hosta.
Uwaga: pełna specyfikacja i oczekiwane działanie tej funkcji są w trakcie weryfikacji i nie są obsługiwane do czasu wprowadzenia późniejszych zmian w tym dokumencie.

Wartości mapy bitowej trybu automatycznego kadrowania

Z wyjątkiem stanu domyślnego None, który jest reprezentowany 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 źródeł automatycznego kadrowania.

Pliki danych z automatycznym kadrowaniem CAZ Split-Frame Dynamiczne Preferowany przez dostawcę Błąd automatycznego kadrowania
Single-Stream D1
D2		 – 
D3		 D5
D7		 D9 (głośnik lub pokój) Głośnik
Pomieszczenie
Multi-Stream -
-		 -
D4		 D6
D8		 - Głośnik
Pomieszczenie
Tryby klatek Wartość trybu ramki (najmniej znaczący 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

Sterowanie: GOOGXU_FRAME_STRATEGY

To ustawienie służy do pobierania lub ustawiania trybów kadrowania kamery wymienionych w sekcji Wartości bitmapy trybu automatycznego kadrowania. Każdy tryb jest reprezentowany jako bit w odpowiedniej mapie bitowej. Polecenie GET_RES zwraca 8-bajtową maskę bitową o wartości zero (0) lub jeden (1), która wskazuje, czy funkcja jest obsługiwana przez urządzenie. 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, wartość GET_RES powinna wynosić 0x000000000000000085 (czyli 0b10000101, a następnie 7 zerowych bajtów).

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

Selektor sterowania 1
Operacja GET / SET
wLength 8
Przesunięcie Pole Rozmiar Wartość Opis
0 bActiveMode 8 Bitmapa Ustawianie lub przywracanie aktywnego trybu kamery
Uwagi:

Działanie obsługiwanych typów żądań jest następujące:

Przesunięcie 0 Opis
GET_CUR Włączanie trybu aktywnego kadrowania
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 Automatyczna aktualizacja / zapis / odczyt
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 Wartość domyślna
SET_CUR Ustawianie trybu aktywnego kadrowania

Sterowanie: GOOGXU_REFRAME

Ten element sterujący służy do wywoływania kadrowania jednorazowego, znanego też jako OTAZ. Gdy zostanie wywołana funkcja OTAZ, widok z kamery zostanie automatycznie dostosowany do najlepszego widoku pomieszczenia. Następnie klient odzyskuje możliwość kontrolowania wartości PTZ. Jeśli jednorazowe kadrowanie 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 Liczba 0x01 Wykonaj żądanie zmiany kadru

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 Ustawianie żądania dotyczące kadrowania One-Shot

Zliczanie zajętości

Funkcja zliczania osób (OC) służy do szacowania liczby uczestników w sali konferencyjnej pomimo przyciętego widoku z kamery.

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

Gdy funkcja liczenia zajętości jest & strumień wideo z kamery: Wskaźnik LED aparatu powinien być GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR powinno być GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR powinno być
Włączone Brak transmisji i brak wyciszenia Wł. 0x01 Liczba osób w pełnym polu widzenia kamery.
Włączone Streaming Wł. 0x01 Liczba osób w pełnym polu widzenia kamery.
Włączone wyciszony, Wył. 0x01 Wyłączono
Wyłączono Brak transmisji i brak wyciszenia Wył. 0x00 Wyłączono
Wyłączono Streaming Wł. 0x00 Wyłączono
Wyłączono wyciszony, Wył. 0x00 Wyłączono

Sterowanie: GOOGXU_OCCUPANCY_COUNTING_TOGGLE

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

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

Działanie obsługiwanych typów żądań jest następujące:

Przesunięcie 0 Opis
GET_CUR Sprawdzanie, czy rejestrowanie obłożenia jest włączone
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x0B Automatyczna aktualizacja / zapis / odczyt
GET_DEF 0x00
SET_CUR Włączanie i wyłączanie funkcji rejestrowania obłożenia

Sterowanie: GOOGXU_OCCUPANCY_COUNTING_READ

Ten element sterujący służy do odczytywania liczby uczestników w pomieszczeniu zgłaszanej przez kamerę, gdy włączone jest liczenie obłożenia. Gdy liczenie osób jest wyłączone, kamera powinna wyłączyć tę funkcję. 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 Liczba Liczba wykrytych osób w polu widzenia. (tylko do odczytu)

Działanie obsługiwanych typów żądań jest następujące:

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

Dane telemetryczne i diagnostyczne urządzenia

Te ustawienia mają zachęcać do lepszych praktyk debugowania urządzeń Google Meet i zwykle nie są widoczne dla użytkowników.

Sterowanie: GOOGXU_STATUS_INFO

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

Selektor sterowania 5
Operacja GET
wLength 8
Przesunięcie Pole Rozmiar Wartość Opis
0 bNumCameras 1 Liczba Liczba dodatkowych satelitów podłączonych do kamery głównej, które mogą wpływać na strumień z kamery zwracany do hosta.
1 bIsMoving 1 Bitmapa 0, gdy kamera jest w stanie bezczynności, i wartość różna od zera, gdy zmieniają się wartości PTZ. Dostawcy mogą przypisywać różne osie lub silniki do różnych bitów.
2 Undef 6 Nieokreślony W przyszłości planujemy rozszerzyć tę listę.

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

Sterowanie: GOOGXU_SATELLITE_INFO

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

Selektor sterowania 0x0A
Operacja GET
wLength 20
Przesunięcie Pole Rozmiar Wartość Opis
0 bSatelliteList 20 Bitmapa Lista typów satelitów podłączonych do systemu. Zawiera 4 osobne 5-bajtowe miejsca. Poszczególne miejsca są opisane w ten sposób:
Przesunięcie Opis
0 Liczba satelitów tego typu.
1-2 Identyfikator dostawcy tego typu satelity.
3-4 Identyfikator produktu dla tego typu satelity.

Działanie obsługiwanych typów żądań jest następujące:

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

Sterowanie: GOOGXU_STATUS_RESET

Ten element sterujący służy do wysyłania do kamery żądania zresetowania. Ustawienie wartości 1 powoduje zresetowanie kamery. Kamera zwraca wartość zero (0), jeśli od ostatniego resetu nie było prośby o ponowne uruchomienie kamery, a wartość jeden (1), jeśli jest ona resetowana. Resetowanie musi spowodować ponowne uruchomienie kamery. (Jest to potrzebne w przypadku urządzeń zasilanych samodzielnie, w których wymuszenie odłączenia USB w celu emulowania podłączenia na gorąco nie jest przydatne).

Selektor sterowania 6
Operacja GET / SET
wLength 1
Przesunięcie Pole Rozmiar Wartość Opis
0 bResetRequest 1 Wartość logiczna Wysyłanie prośby o zresetowanie do gospodarza i połączonych kamer.
 Zwraca wartość 0x01, jeśli od ostatniego resetowania wysłano żądanie resetowania, w przeciwnym razie zwraca wartość 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 ustawionej pozycji.

Sterowanie: GOOGXU_PRESETS

Ten element sterujący służy do ustawiania wartości przesuwania, pochylania i powiększania kamery w konfiguracji wstępnej.

Symbol Preset Action służy do określania zamierzonego działania polecenia. Ustawienie wartości 1 służy do mapowania bieżących wartości panoramowania, pochylenia i powiększenia na podany indeks ustawienia wstępnego. Ustawienie wartości 2 powinno spowodować przejście kamery do wcześniej zmapowanych wartości panoramowania, pochylenia i powiększenia 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.

Pole Preset Index służy do określania współrzędnych PTZ przypisanych do indeksu. Wartość Preset index 0 jest przypisana do współrzędnych pozycji wyjściowej i powinna być domyślną pozycją kamery po wybudzeniu, gdy wartość GOOGXU_FRAME_STRATEGY jest ustawiona na NONE.

Selektor sterowania 7
Operacja SET
wLength 2
Przesunięcie Pole Rozmiar Wartość Opis
0 bPresetAction 1 Liczba 0x01: Zapisz gotowe ustawienia.
0x02: Przywróć gotowe ustawienia.
0x03: Przywróć domyślne gotowe ustawienia. (Wartość domyślna powinna być prawidłową współrzędną gotowych ustawień).
1 bPresetIndex 1 Liczba Indeks aktywnego gotowego ustawienia. 0~N-1
 – 0 to domyślna pozycja początkowa kamery, a N-1 to zdefiniowana przez dostawcę stała liczba ustawień wstępnych.

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ługiwanych jest maksymalnie N gotowych ustawień
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 Tylko do zapisu
GET_DEF 0x00 0x00

Przesuwanie i pochylanie mapy dodatkowej

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

Grupa kontrolna: GOOGXU_PAN_TILT_ABSOLUTE (wycofano)

Pomocnicze elementy sterujące mapowaniem przesunięcia i pochylenia są zdefiniowane w rozdziale 4: Żądania specyficzne dla klasy, sekcja 4.2.2.1.14 Przesunięcie/pochylenie (bezwzględne) w specyfikacji klasy UVC 1.5.

Grupa kontrolna: GOOGXU_PAN_TILT_RELATIVE (wycofano)

Pomocnicze elementy sterujące mapowaniem panoramowania i pochylania są zdefiniowane w rozdziale 4: Żądania specyficzne dla klasy, sekcja 4.2.2.1.15 Sterowanie panoramowaniem i pochylaniem (względne) specyfikacji klasy UVC 1.5.

Informacje o wersjach

Znajdziesz tu informacje o ulepszeniach i nowych funkcjach każdej wersji tego dokumentu.

13 sierpnia 2025 r.

27 stycznia 2025 r.

21 maja 2024 r.

15 listopada 2023 r.

Zaktualizowano scenariusz testowania, aby sprawdzać i interpretować prawidłowe tryby kadrowania. Wyjaśnione reprezentacje bajtów.

21 lipca 2023 r.

Dodaliśmy scenariusz testowania, który umożliwia partnerom weryfikowanie implementacji pod kątem zgodności z tą specyfikacją.

25 maja 2023 r.

Poprawiona GOOGXU_PRESETS uwaga dotycząca liczby ustawień wstępnych. Powinno to być N, a nie N-1.

17 kwietnia 2023 r.

Pierwsza wersja.