APIs für die USB Video Class Extension Unit der Google Meet-Hardware

In diesem Dokument werden die unterstützten USB Video Class Extension Unit (XU)-APIs beschrieben, die von Google Meet-Konferenzsystemen verwendet werden, um intelligente Kamerafunktionen zu ermöglichen. Mit dieser Spezifikation sollen Praktiken beeinflusst werden, um diese Funktionen zu ermöglichen und unseren Partnern eine bessere asynchrone Skalierbarkeit und Tests zu ermöglichen.

Details zu den letzten Änderungen an diesem Dokument finden Sie in den Versionshinweisen.

Testeinrichtung

Um Partnern zu helfen, die Einhaltung dieser Spezifikation zu prüfen, bieten wir eine Testeinrichtung auf Chromebox for Meetings-Geräten, die im Entwicklermodus eingerichtet sind. Aktivieren Sie das Schreiben in das Dateisystem. Fügen Sie /etc/chrome_dev.conf die folgenden Zeilen hinzu:

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

Starte das Gerät neu, schließe die Kamera und eine USB-Tastatur an, drücke Ctrl-Alt-X. Die Spezifikationskonformität der aktiven Kamera wird geprüft und in /var/log/chrome/chrome protokolliert (bei Verwendung eines signierten Images in /home/chronos/user/log/chrome).

Little-Endian-Konvention

USB ist ein Little-Endian-Standard. In diesem Dokument gilt Folgendes:

  • Mehrbyte-Zahlen werden im Big-Endian-Format angezeigt (und im Little-Endian-Format übertragen).
  • Byte-Arrays haben das Little-Endian-Speicherlayout.

0x12345678 entspricht beispielsweise [0x78, 0x56, 0x34, 0x12].

GUID der Erweiterungseinheit

Erweiterungseinheiten, die diese Meet-XU-Steuerungsspezifikation unterstützen, müssen diese GUID verwenden.

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

XU-Selektoren für die Steuerung von Peripheriegeräten

Dies sind die definierten XU-Selektoren für die Peripheriegeräte-Steuerung.

Steuerelementauswahl Wert
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

Art des Kontrollantrags

Steueranfragetypen sind in Kapitel 4: Class Specific Requests der UVC 1.5 Class Specification definiert.

Vorgang UVC-Steuerung
GET GET_CUR, GET_MIN, GET_MAX, GET_RES, GET_LEN, GET_INFO, GET_DEF
SET SET_CUR

Kameramodi

Kameramodi werden verwendet, um Personen in einem Konferenzraum zu erfassen. Sie sind eine tuplevon:

  • Strategie (Kameraansicht)
  • Bias (Redner oder Raum)
  • Feeds (einzelne oder mehrere Streams)

Jede Dimension kann die in den folgenden Abschnitten beschriebenen Werte annehmen.

Strategie für den automatischen Bildausschnitt

In allen automatischen Framing-Modi außer „Keine“ sind das manuelle Schwenken, Neigen und Zoomen deaktiviert.

Funktion Beschreibung
Keine Die Kamera deaktiviert alle intelligenten Framing-Funktionen und ermöglicht dem Client, die PTZ-Werte frei zu steuern.
Hinweis:Wenn diese Framing-Strategie festgelegt ist, bleibt die Kamera in ihrer aktuellen Schwenk-, Neigungs- und Zoomposition.
Automatischer Bildausschnitt (CAZ) Anhand des Framing-Bias verfolgt die Kamera Personen im Raum kontinuierlich.
Geteilte Frames Die Kamera erstellt so viele Videoansichten wie nötig. Je nach der Option Auto-Framing-Feeds werden sie entweder in Kacheln in einem einzelnen Stream zusammengestellt oder es werden separate Videostreams für jede Ansicht erstellt.
Dynamische Ansicht Eine oder mehrere Kameras versuchen, die beste Ansicht des Raums zu liefern. Es kann entscheiden, ob mehrere Feeds in einem zusammengefasst werden sollen oder ob eine „interessante“ Ansicht des aktuellen Raums bereitgestellt werden soll.
 Diese Ansicht soll eine möglichst faire Darstellung der Teilnehmer im Raum ermöglichen.
Vom Anbieter bevorzugt Das Kamerasystem verwendet eine eigene Logik, um die beste Ansicht des Raums zu ermitteln. Die zugrunde liegende Framing-Strategie kann ohne Vorankündigung geändert werden. Wenn sich beispielsweise die Anzahl der Personen im Raum ändert oder die Kamera den Unterschied zwischen einer Präsentation und einer Besprechung mit mehreren Teilnehmern erkennen kann, kann das System die Framing-Strategie in diesem Modus nach Bedarf anpassen oder ändern. In diesem Modus sollte beim Aufrufen von getCur VENDOR_PREFERRED zurückgegeben werden und nicht der zugrunde liegende Framing-Modus, der vom System ausgewählt wurde.

Bias durch automatische Auswahl des Bildausschnitts

Funktion Beschreibung
Wichtiger Referent (Sprecher-Tracking) Die Kamera versucht, die Person, die gerade spricht, bestmöglich zu erfassen.
 In diesem Szenario sollte die Kamera auf den Vortragenden ausgerichtet sein. Zum Beispiel der CEO, der in einem Konferenzraum eine Präsentation hält.
Zusammenarbeit 
(Raum-Tracking)		 Die Kamera versucht, alle Teilnehmer im Raum bestmöglich ins Bild zu setzen. In diesem Szenario sollte die Kamera alle Teilnehmer gleich behandeln.

Feeds mit automatischem Bildausschnitt

Funktion Beschreibung
Single-Stream Die Kamera sendet einen einzelnen Videostream an das Hostgerät.
Multi-Stream 
(Work-In-Progress)		 Die Kamera teilt den Stream auf und erstellt mehrere Videostreams, die an den Host gesendet werden.
Hinweis:Die vollständige Spezifikation und das erwartete Verhalten dieser Funktion werden noch überprüft und werden erst in späteren Überarbeitungen dieses Dokuments unterstützt.

Bitmap-Werte für den automatischen Framing-Modus

Mit Ausnahme des Standardstatus von None, der durch ein leeres Byte-Array dargestellt wird, steht jedes Bit im Byte-Array für einen anderen Kameramodus, der eine bestimmte Kombination aus Strategie für die automatische Bildausschnittanpassung, Bias für die automatische Bildausschnittanpassung und Feeds für die automatische Bildausschnittanpassung ist.

Feeds mit automatischem Bildausschnitt CAZ Split-Frame Dynamisch Vom Anbieter bevorzugt Bias durch automatische Auswahl des Bildausschnitts
Single-Stream D1 
D2		 – 
D3		 D5 
D7		 D9 (Lautsprecher oder Raum) Lautsprecher
Raum
Multi-Stream –
–		 –
D4		 D6 
D8		 - Lautsprecher
Raum
Frame-Modi Wert für den Frame-Modus (niedrigstwertiges Byte)
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

Steuerung: GOOGXU_FRAME_STRATEGY

Mit diesem Steuerelement können die Framing-Modi der Kamera abgerufen oder festgelegt werden, die unter Bitmap-Werte für den automatischen Framing-Modus aufgeführt sind. Jeder Modus wird als Bit im jeweiligen Bitmap dargestellt. Der Befehl GET_RES gibt eine 8 Byte lange Bitmaske mit dem Wert 0 oder 1 zurück, um anzugeben, ob die Funktion vom Gerät unterstützt wird. Wenn eine Kamera beispielsweise CAZ, Speaker, Single-Stream, Split-Frame, Room, Single-Stream und Dynamic, Room, Multi-Stream, aber keine anderen Modi unterstützt, sollte GET_RES 0x000000000000000085 (d.h. 0b10000101 gefolgt von sieben Null-Bytes) zurückgeben.

Mit dem Befehl SET_CUR werden Bitmaps gesendet, um der Kamera mitzuteilen, welcher SINGLE-Kameramodus aktiviert werden soll.

Steuerelementauswahl 1
Vorgang GET / SET
wLength 8
Offset Feld Größe Wert Beschreibung
0 bActiveMode 8 Bitmap Aktivkameramodus festlegen oder zurückgeben
Hinweise

So verhalten sich die unterstützten Anfragetypen:

Offset 0 Beschreibung
GET_CUR Kameramodus „Aktives Framing“ verwenden
GET_MIN Kameraabhängig
GET_MAX Kameraabhängig
GET_RES Gibt eine 8 Byte lange Bitmaske der unterstützten Kameramodi zurück.
GET_LEN 0x0008 Länge
GET_INFO 0x0B AutoUpdate / Write / Read
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 Standardwert
SET_CUR Kameramodus „Aktives Framing“ einstellen

Steuerung: GOOGXU_REFRAME

Mit diesem Steuerelement wird One-Shot Framing ausgelöst, auch bekannt als OTAZ. Wenn OTAZ ausgelöst wird, wird die Kameraansicht auf die beste Ansicht des Raums ausgerichtet. Danach kann der Client die PTZ-Werte wieder steuern. Wenn die Einzelfoto-Kadrierung nicht unterstützt wird, sollte die Kamera dieses Steuerelement nicht definieren.

Steuerelementauswahl 2
Vorgang SET
wLength 1
Offset Feld Größe Wert Beschreibung
0 bReframe 1 Zahl 0x01 Reframe-Anfrage ausführen

So verhalten sich die unterstützten Anfragetypen:

Offset 0 Beschreibung
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x02 Nur Schreibzugriff
GET_DEF 0x00
SET_CUR Anfrage für One-Shot Framing festlegen

Anwesenheitszähler

Die Funktion „Personenzählung“ (Occupancy Counting, OC) schätzt die Anzahl der Teilnehmer in einem Konferenzraum, obwohl das Kamerabild zugeschnitten ist.

In dieser Tabelle wird das erwartete Verhalten der OC-Steuerelemente und ihre Interaktionen mit dem Kameravideostream und der LED-Anzeige der Kamera beschrieben.

Wann die Anwesenheitszählung & der Videostream der Kamera ist: Die LED-Anzeige der Kamera sollte GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR sollte GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR sollte
Aktiviert Weder Streaming noch stummgeschaltet An 0x01 Die Anzahl der Personen im gesamten Sichtfeld der Kamera.
Aktiviert Streaming An 0x01 Die Anzahl der Personen im gesamten Sichtfeld der Kamera.
Aktiviert Stummgeschaltet Aus 0x01 Deaktiviert
Deaktiviert Weder Streaming noch stummgeschaltet Aus 0x00 Deaktiviert
Deaktiviert Streaming An 0x00 Deaktiviert
Deaktiviert Stummgeschaltet Aus 0x00 Deaktiviert

Steuerung: GOOGXU_OCCUPANCY_COUNTING_TOGGLE

Mit dieser Einstellung wird die Funktion zum Zählen von Personen in einem Raum aktiviert oder deaktiviert. Wenn Sie den Wert auf „0“ setzen, wird diese Funktion deaktiviert. Wenn Sie den Wert auf „1“ setzen, wird diese Funktion aktiviert. Wenn diese Funktion nicht unterstützt wird, sollte die Kamera dieses Steuerelement nicht definieren.

Steuerelementauswahl 3
Vorgang GET / SET
wLength 1
Offset Feld Größe Wert Beschreibung
0 bOccupancy 1 Boolesch Funktion zum Zählen der Belegung festlegen 
0x00 Funktion deaktivieren 
0x01 Funktion aktivieren

So verhalten sich die unterstützten Anfragetypen:

Offset 0 Beschreibung
GET_CUR Zurückgeben, ob die Ermittlung der Belegung aktiviert ist
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x0B AutoUpdate / Write / Read
GET_DEF 0x00
SET_CUR Funktion zur Ermittlung der Belegung aktivieren oder deaktivieren

Steuerung: GOOGXU_OCCUPANCY_COUNTING_READ

Mit diesem Steuerelement wird die von der Kamera gemeldete Anzahl der Teilnehmer in einem Raum gelesen, wenn die Belegungserfassung aktiviert ist. Wenn die Belegungserkennung deaktiviert ist, sollte die Kamera diese Funktion deaktivieren. Wenn die Personenzählung nicht unterstützt wird, sollte die Kamera dieses Steuerelement nicht definieren.

Steuerelementauswahl 4
Vorgang GET
wLength 2
Offset Feld Größe Wert Beschreibung
0 bNumPeople 2 Zahl Die Anzahl der erkannten Personen im Sichtfeld. (schreibgeschützt)

So verhalten sich die unterstützten Anfragetypen:

Offset 0 Beschreibung
GET_CUR Anzahl der erkannten Personen zurückgeben
GET_MIN 0x0000
GET_MAX 0x00FF
GET_RES 0x0001
GET_LEN 0x0002
GET_INFO 0x09 AutoUpdate / Read
GET_DEF 0x0000

Gerätetelemetrie und ‑diagnose

Diese Einstellungen sollen bessere Debugging-Methoden mit Meet-Hardware fördern und sind in der Regel nicht für Nutzer sichtbar.

Steuerung: GOOGXU_STATUS_INFO

Mit dieser Steuerung werden Informationen von der Hostkamera abgefragt, die zu Debugging-Zwecken an Partner weitergegeben werden.

Steuerelementauswahl 5
Vorgang GET
wLength 8
Offset Feld Größe Wert Beschreibung
0 bNumCameras 1 Zahl Die Anzahl der zusätzlichen Satelliten, die an die Hauptkamera angeschlossen sind und sich auf den an den Host zurückgegebenen Kamerastream auswirken können.
1 bIsMoving 1 Bitmap 0, wenn die Kamera im Leerlauf ist, und ein Wert ungleich null, wenn sich die PTZ-Werte ändern. Anbieter können verschiedene Achsen oder Motoren unterschiedlichen Bits zuordnen.
2 Undef 6 Undef Wird in Zukunft erweitert.

So verhalten sich die unterstützten Anfragetypen:

Offset 0 1 2 Beschreibung
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

Steuerung: GOOGXU_SATELLITE_INFO

Mit diesem Steuerelement werden die Satellitengeräte abgefragt, die mit diesem Kamerasystem verbunden sind.

Steuerelementauswahl 0x0A
Vorgang GET
wLength 20
Offset Feld Größe Wert Beschreibung
0 bSatelliteList 20 Bitmap Die Liste der Satellitentypen, die mit dem System verbunden sind. Enthält vier separate 5‑Byte-Slots. Die einzelnen Slots werden so beschrieben:
Offset Beschreibung
0 Menge für diesen Satellitentyp.
1-2 Anbieter-ID dieses Satellitentyps.
3-4 Produkt-ID für diesen Satellitentyp.

So verhalten sich die unterstützten Anfragetypen:

Offset 0 Beschreibung
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 Byte
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

Steuerung: GOOGXU_STATUS_RESET

Mit diesem Steuerelement wird eine Zurücksetzung der Kamera angefordert. Wenn Sie den Wert auf 1 setzen, wird die Kamera zurückgesetzt. Die Kamera gibt null (0) zurück, wenn seit dem letzten Zurücksetzen keine Anfrage zum Neustarten der Kamera eingegangen ist, und eins (1), wenn sie zurückgesetzt wird. Durch das Zurücksetzen muss ein Neustart der Kamera ausgelöst werden. Dies ist für Geräte mit eigener Stromversorgung erforderlich, bei denen das Erzwingen einer USB-Trennung zur Emulation eines Hotplug nicht sinnvoll ist.

Steuerelementauswahl 6
Vorgang GET / SET
wLength 1
Offset Feld Größe Wert Beschreibung
0 bResetRequest 1 Boolesch Senden Sie eine Zurücksetzungsanfrage an den Host und die verbundenen Kameras.
 Gibt 0x01 zurück, wenn seit dem letzten Zurücksetzen eine Zurücksetzungsanfrage gesendet wurde, andernfalls 0x00.

So verhalten sich die unterstützten Anfragetypen:

Offset 0 Beschreibung
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x03 Schreiben / Lesen
GET_DEF 0x00

PTZ-Voreinstellungen

Damit wird das Sichtfeld der Kamera konfiguriert und in eine voreingestellte Position zurückgesetzt.

Steuerung: GOOGXU_PRESETS

Mit diesem Steuerelement werden die Schwenk-, Neigungs- und Zoomwerte (PTZ) der Kamera auf eine voreingestellte Konfiguration festgelegt.

Mit Preset Action wird die beabsichtigte Aktion des Befehls angegeben. Wenn Sie den Wert 1 festlegen, werden die aktuellen Schwenk-, Neigungs- und Zoomwerte einem bereitgestellten Preset-Index zugeordnet. Wenn Sie den Wert „2“ festlegen, sollten die Schwenk-, Neigungs- und Zoomwerte der Kamera auf die zuvor zugeordneten Werte für den angegebenen Index oder auf die Standardkoordinaten (falls nicht zuvor zugeordnet) umgestellt werden. Wenn Sie den Wert auf „3“ setzen, wird der Index auf die Koordinaten der Werkseinstellungen zurückgesetzt.

Mit Preset Index werden die PTZ-Koordinaten angegeben, die dem Index zugeordnet sind. Der Preset index-Wert 0 wird den Koordinaten der Startposition zugeordnet und sollte die Standardposition der Kamera beim Aufwachen sein, wenn GOOGXU_FRAME_STRATEGY auf NONE eingestellt ist.

Steuerelementauswahl 7
Vorgang SET
wLength 2
Offset Feld Größe Wert Beschreibung
0 bPresetAction 1 Zahl 0x01: Voreinstellung 
speichern 0x02: Voreinstellung 
wiederherstellen 0x03: Voreinstellung auf Standard zurücksetzen Der Standardwert sollte eine gültige voreingestellte Koordinate sein.
1 bPresetIndex 1 Zahl Der Index der aktiven Voreinstellung. 0~N-1
 Dabei ist 0 die Standard-Startposition der Kamera und N-1 eine anbieterdefinierte Konstante für die Anzahl der Voreinstellungen.

So verhalten sich die unterstützten Anfragetypen:

Offset 0 1 Beschreibung
GET_MIN 0x00 0x00
GET_MAX 0x03 N-1 Maximale Anzahl unterstützter Voreinstellungen
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 Nur Schreibzugriff
GET_DEF 0x00 0x00

Hilfskarte schwenken und neigen

Einige Kameras haben spezielle Komponenten wie die Motoren für mechanische Kameras oder digitale PTZ-Funktionen. Verwenden Sie für diese die standardmäßigen V4L2-Steuerelemente für Schwenken, Neigen und Zoomen.

Steuerung: GOOGXU_PAN_TILT_ABSOLUTE (eingestellt)

Die Hilfssteuerelemente für Schwenken und Neigen sind in Kapitel 4: Klassenspezifische Anfragen, Abschnitt 4.2.2.1.14 „PanTilt (Absolute) Control“ der UVC 1.5 Class Specification definiert.

Steuerung: GOOGXU_PAN_TILT_RELATIVE (eingestellt)

Die Hilfszuordnungssteuerelemente für Schwenken und Neigen sind in Kapitel 4: Klassenspezifische Anfragen, Abschnitt 4.2.2.1.15 „PanTilt (Relative) Control“ der UVC 1.5 Class Specification definiert.

Versionshinweise

Diese Versionshinweise enthalten die Verbesserungen und neuen Funktionen der einzelnen Überarbeitungen dieses Dokuments.

13. Aug. 2025

27. Januar 2025

21. Mai 2024

15. November 2023

Das Testskript wurde aktualisiert, um gültige Framing-Modi zu prüfen und zu interpretieren. Die Darstellung von Byte wurde klarer formuliert.

21. Juli 2023

Es wurde ein Testskript für Partner hinzugefügt, mit dem Implementierungen auf Einhaltung dieser Spezifikation geprüft werden können.

25. Mai 2023

GOOGXU_PRESETS – Korrigierte Anmerkung zur Anzahl der Voreinstellungen. Es sollte N und nicht N–1 sein.

17. April 2023

Erste Version