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 rozszerzenia (XU) klasy wideo USB, które są używane przez systemy konferencyjne Google Meet do włączania inteligentnych funkcji kamery. Celem stworzenia 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 narzędzie testowe na urządzeniach Chromebox wideokonferencje ustawionych w trybie deweloperskim. Włącz zapisywanie w systemie plików. Dodaj te wiersze do pliku /etc/chrome_dev.conf:

--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 sterowania urządzeniami peryferyjnymi

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 specyficzne dla 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 (widok z kamery)
  • Uprzedzenia (osoby mówiącej lub pomieszczenia)
  • Pliki danych (1 lub więcej strumieni)

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

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 włączona, kamera pozostaje w bieżącej pozycji przesuwania, pochylania i powiększania.
Ciągłe kadrowanie (CAZ) Na podstawie preferencji kadrowania kamera stale śledzi osoby w pokoju.
Podzielone ramki 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 jak najbardziej sprawiedliwego widoku uczestników spotkania w pokoju.
Preferowany przez dostawcę System kamer używa 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 pomieszczeniu 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 kadrować wszystkich uczestników w sali. W takiej sytuacji kamera powinna traktować wszystkich uczestników w sposób równy.

Pliki danych z automatycznym kadrowaniem

Funkcja Opis
Single-Stream Kamera wysyła jeden strumień wideo do urządzenia hosta.
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 ramki 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

Element sterujący: GOOGXU_FRAME_STRATEGY

Ten element sterujący służy do pobierania lub ustawiania trybów kadrowania kamery wymienionych w sekcji Wartości mapy bitowej 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 np. 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 po nim 7 zerowych bajtów).

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

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

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

Przesunięcie 0 Opis
GET_CUR Pobieranie 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

Element sterujący: 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 kamery zostanie automatycznie dostosowany do najlepszego widoku pomieszczenia. Następnie klient odzyskuje możliwość kontrolowania wartości PTZ. Jeśli kadrowanie jednorazowe nie jest obsługiwane, kamera nie powinna definiować tego ustawienia.

Selektor ustawień 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 kadrowania jednorazowego

Zliczanie zajętości

Funkcja zliczania osób (OC) służy do szacowania liczby uczestników w sali konferencyjnej pomimo przyciętego widoku 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 rejestrowanie obłożenia jest & strumień wideo z kamery: Wskaźnik LED aparatu powinien GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR sprawdzenia GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR sprawdzenia
Włączone Nie transmituje i nie jest wyciszony 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 Nie transmituje i nie jest wyciszony Wył. 0x00 Wyłączono
Wyłączono Streaming Wł. 0x00 Wyłączono
Wyłączono wyciszony, Wył. 0x00 Wyłączono

Element sterujący: GOOGXU_OCCUPANCY_COUNTING_TOGGLE

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

Selektor ustawień 3
Operacja GET / SET
wLength 1
Przesunięcie Pole Rozmiar Wartość Opis
0 bOccupancy 1 Wartość logiczna Ustawienie funkcji 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 Zwracanie informacji o tym, 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

Element sterujący: GOOGXU_OCCUPANCY_COUNTING_READ

To ustawienie służy do odczytywania liczby uczestników w sali zgłaszanej przez kamerę, gdy włączone jest liczenie osób. 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 ustawień 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 sprzętu do Google 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 hosta, które są udostępniane partnerom w celu debugowania.

Selektor ustawień 5
Operacja GET
wLength 8
Przesunięcie Pole Rozmiar Wartość Opis
0 bNumCameras 1 Liczba Liczba dodatkowych urządzeń podłączonych do kamery głównej, które mogą wpływać na strumień 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

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 ustawień 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. Każde miejsce jest 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

Element sterujący: 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 ustawień 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.

Element sterujący: 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, pochylania i powiększania na podany indeks ustawienia wstępnego. Ustawienie wartości 2 powinno spowodować przejście 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.

Parametr Preset Index służy do określania współrzędnych PTZ przypisanych do indeksu. Wartość Preset index równa zero (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 ustawień 7
Operacja SET
wLength 2
Przesunięcie Pole Rozmiar Wartość Opis
0 bPresetAction 1 Liczba 0x01: Zapisz gotowe ustawienie.
0x02: Przywróć gotowe ustawienie.
0x03: Zresetuj gotowe ustawienie do ustawień domyślnych. (Wartość domyślna powinna być prawidłową, wstępnie ustawioną wartością współrzędnych).
1 bPresetIndex 1 Liczba Indeks aktywnego gotowego ustawienia. 0~N-1
 – 0 to domyślna pozycja początkowa kamery, a N-1 to stała zdefiniowana przez dostawcę 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ługiwana maksymalna liczba ustawień wstępnych
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 cyfrowe funkcje PTZ. W tym przypadku użyj standardowych elementów sterujących V4L2 do przesuwania, pochylania i powiększania.

Sterowanie: GOOGXU_PAN_TILT_ABSOLUTE (wycofano)

Dodatkowe elementy sterujące mapowaniem przesunięcia i pochylenia są zdefiniowane w rozdziale 4: Żądania specyficzne dla klasy, sekcja 4.2.2.1.14 Sterowanie przesunięciem i pochyleniem (bezwzględne) w specyfikacji klasy UVC 1.5.

Sterowanie: GOOGXU_PAN_TILT_RELATIVE (wycofano)

Dodatkowe elementy sterujące mapowaniem przesuwaniem i pochylaniem są zdefiniowane w rozdziale 4: Żądania specyficzne dla klasy, sekcja 4.2.2.1.15 Element sterujący przesuwaniem i pochylaniem (względny) w 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 skrypt testowy, aby sprawdzać i interpretować prawidłowe tryby kadrowania. Wyjaśnione reprezentacje bajtów.

21 lipca 2023 r.

Dodaliśmy skrypt testowy, który umożliwia partnerom weryfikowanie wdrożeń 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.