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 möchten wir die Praktiken beeinflussen, um diese Funktionen zu ermöglichen und eine bessere asynchrone Skalierbarkeit und Tests für unsere Partner zu ermöglichen.

Details zu den neuesten Änderungen an diesem Dokument finden Sie in den Release-Notes.

Testeinrichtung

Um Partnern die Einhaltung dieser Spezifikation zu erleichtern, stellen wir auf Chromebox for Meetings-Geräten, die im Entwicklermodus laufen, eine Testfunktion zur Verfügung. Aktivieren Sie das Schreiben in das Dateisystem. Fügen Sie /etc/chrome_dev.conf die folgenden Zeilen hinzu:

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

Starten Sie das Gerät neu, verbinden Sie die Kamera mit einer USB-Tastatur und drücken Sie Ctrl-Alt-X. Die Einhaltung der Spezifikationen der aktiven Kamera wird geprüft und in /home/chronos/user/log/chrome protokolliert.

Little-Endian-Konvention

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

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

Beispiel: 0x12345678 ist mit [0x78, 0x56, 0x34, 0x12] identisch.

GUID der Erweiterungseinheit

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

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

XU-Auswahlschalter für die Peripheriesteuerung

Dies sind die definierten XU-Auswahlen für die Peripheriesteuerung.

Steuerelemente 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

Typ der Steueranfrage

Die Typen von Steueranfragen sind in Kapitel 4: Klassenspezifische Anfragen der UVC 1.5-Klassenspezifikation definiert.

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

Kameramodi

Mit Kameramodi können Sie Personen in einem Konferenzraum tuple einrahmen:

  • Strategie (Kameraansicht)
  • Voreingenommenheit (Lautsprecher oder Raum)
  • Feeds (einzelne oder mehrere Streams)

Für jede Dimension sind die in den folgenden Abschnitten beschriebenen Werte zulässig.

Strategie für den automatischen Bildausschnitt

In allen Modi für automatisches Framing außer „Kein“ sind manuelles Schwenken, Neigen und Zoomen deaktiviert.

Funktion Beschreibung
Keine Die Kamera deaktiviert alle Funktionen für die intelligente Bildkomposition und ermöglicht es dem Kunden, die PTZ-Werte frei zu steuern.
Hinweis:Wenn diese Bildausschnittstrategie festgelegt ist, bleibt die Kamera in ihrer aktuellen Schwenk-, Neige- und Zoomposition.
Automatischer Bildausschnitt (CAZ) Basierend auf der Voreingenommenheit beim Bildausschnitt verfolgt die Kamera kontinuierlich Personen im Raum.
Frames teilen Die Kamera erstellt so viele Videoaufrufe wie erforderlich. Je nach Einstellung für Feeds mit automatischer Bildausrichtung werden sie entweder in einem einzigen Stream zu Kacheln zusammengesetzt oder es werden separate Videostreams für jede Ansicht erstellt.
Dynamische Ansicht Eine oder mehrere Kameras versuchen, den besten Blick auf den Raum zu bieten. Sie kann entscheiden, ob mehrere Feeds zu einem zusammengeführt werden sollen oder ob eine „interessante“ Ansicht des aktuellen Raums angezeigt werden soll.
 Diese Ansicht soll den Teilnehmern im Konferenzraum einen möglichst ausgewogenen Blick auf den Anruf bieten.
Vom Anbieter bevorzugt Das Kamerasystem verwendet eine eigene Logik, um den besten Blick auf den Raum zu ermitteln. Die zugrunde liegende Framing-Strategie kann jederzeit ohne vorherige Ankündigung geändert werden. Wenn sich beispielsweise die Anzahl der Personen im Raum ändert oder die Kamera den Unterschied zwischen einer Präsentation mit hohem Risiko und einer Gruppenarbeit erkennen kann, kann das System die Bildkomposition in diesem Modus nach Bedarf anpassen oder ändern. In diesem Modus sollte der Aufruf von getCur VENDOR_PREFERRED zurückgeben und nicht den zugrunde liegenden Framing-Modus, der vom System ausgewählt wurde.

Voreingenommenheit durch den automatischen Bildausschnitt

Funktion Beschreibung
Redner mit hohem Risiko (Sprecher-Tracking) Die Kamera versucht, die Person im Raum, die gerade spricht, optimal im Bild zu zeigen.
In diesem Szenario sollte die Kamera auf den Vortragenden ausgerichtet sein. Beispiel: Der CEO hält in einem Konferenzraum eine Präsentation.
Gruppenarbeit 
(Raum-Tracking)		 Die Kamera versucht, alle Teilnehmer im Raum optimal einzurahmen. In diesem Szenario sollte die Kamera alle Teilnehmer gleich behandeln.

Feeds mit automatischer Bildausrichtung

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

Bitmap-Werte für den Modus „Automatische Bildausrichtung“

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 der Strategie für die automatische Bildausrichtung, der Voreinstellung für die automatische Bildausrichtung und den Feeds für die automatische Bildausrichtung ist.

Feeds mit automatischer Bildausrichtung CAZ Split-Frame Dynamisch Vom Anbieter bevorzugt Voreingenommenheit durch den automatischen Bildausschnitt
Einzelstream D1 
D2		 –
 D3		 D5 
D7		 D9 (Lautsprecher oder Raum) Lautsprecher
Raum
Multistream –
–		 –
 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

Kontrollgruppe: GOOGXU_FRAME_STRATEGY

Mit diesem Steuerelement können Sie die Bildfeldmodi der Kamera abrufen oder festlegen, die in den Bitmaskenwerten für den automatischen Bildfeldmodus aufgeführt sind. Jeder Modus wird in der jeweiligen Bitmap als Bit 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 oder nicht. 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 zurückgeben (d.h. 0b10000101 gefolgt von sieben Null-Byte).

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

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

Die unterstützten Anfragetypen verhalten sich so:

Offset 0 Beschreibung
GET_CUR Kameramodus „Aktives Framing“
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 für aktives Framing festlegen

Kontrollgruppe: GOOGXU_REFRAME

Mit dieser Einstellung wird der One-Shot-Bildausschnitt (One-Shot-Anzeige, OTAZ) ausgelöst. Wenn OTAZ ausgelöst wird, wird die Kameraansicht auf die beste Ansicht des Raums ausgerichtet. Danach kann der Kunde die PTZ-Werte wieder steuern. Wenn die Funktion „Einstellung in einem Schritt“ 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 Anfrage zum Neuausrichten ausführen

Die unterstützten Anfragetypen verhalten sich so:

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 einmaliges Framing festlegen

Anwesenheitszähler

Die Belegungszählerfunktion (Occupancy Counting, OC) wird verwendet, um die Anzahl der Teilnehmer in einem Konferenzraum trotz des zugeschnittenen Kamerabilds zu schätzen.

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

Wenn die Anwesenheitszählung und der Kamera-Videostream: Die LED-Anzeige der Kamera sollte GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR sollte GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR sollte
Aktiviert Nicht gestreamt und nicht 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 Nicht gestreamt und nicht stummgeschaltet Aus 0x00 Deaktiviert
Deaktiviert Streaming An 0x00 Deaktiviert
Deaktiviert Stummgeschaltet Aus 0x00 Deaktiviert

Kontrollgruppe: GOOGXU_OCCUPANCY_COUNTING_TOGGLE

Mit dieser Einstellung können Sie die Funktion zum Zählen der Personen in einem Raum aktivieren oder deaktivieren. Wenn Sie den Wert auf „0“ (null) setzen, wird diese Funktion deaktiviert. Bei „1“ (eins) ist sie 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 Belegungszählerfunktion festlegen
0x00 Funktion deaktivieren
0x01 Funktion aktivieren

Die unterstützten Anfragetypen verhalten sich so:

Offset 0 Beschreibung
GET_CUR Gibt zurück, 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

Kontrollgruppe: GOOGXU_OCCUPANCY_COUNTING_READ

Mit diesem Steuerelement wird die von der Kamera gemeldete Anzahl der Teilnehmer in einem Raum gelesen, wenn die Personenzählung aktiviert ist. Wenn die Personenzählung deaktiviert ist, sollte die Kamera diese Einstellung 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 Bild. (schreibgeschützt)

Die unterstützten Anfragetypen verhalten sich so:

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 Steuerelemente sollen bessere Debugging-Methoden für Meet-Hardware fördern und sind in der Regel nicht für Nutzer sichtbar.

Kontrollgruppe: GOOGXU_STATUS_INFO

Mit dieser Einstellung werden Informationen von der Hostkamera abgefragt, die für das Debugging 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 der Hauptkamera angeschlossen sind und sich auf den an den Host zurückgegebenen Kamerastream auswirken können.
1 bIsMoving 1 Bitmap „0“, wenn die Kamera inaktiv ist, und ein anderer Wert, wenn sich die PTZ-Werte ändern. Anbieter können verschiedene Achsen oder Motoren verschiedenen Bits zuordnen.
2 Undef 6 Undef Wird in Zukunft erweitert.

Die unterstützten Anfragetypen verhalten sich so:

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

Kontrollgruppe: 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 wie folgt beschrieben:
Offset Beschreibung
0 Die Stückzahl für diesen Satellitentyp.
1-2 Anbieter-ID dieses Satellitentyps.
3-4 Produkt-ID für diesen Satellitentyp.

Die unterstützten Anfragetypen verhalten sich so:

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

Kontrollgruppe: GOOGXU_STATUS_RESET

Mit dieser Steuerung wird eine Rücksetzungsanfrage an die Kamera gesendet. Wenn Sie den Wert „1“ festlegen, wird die Kamera zurückgesetzt. Die Kamera gibt „0“ zurück, wenn seit dem letzten Zurücksetzen keine Neustartsanfrage erfolgt ist, und „1“, wenn die Kamera zurückgesetzt wird. Das Zurücksetzen muss einen Neustart der Kamera auslösen. (Dies ist für selbstversorgte Geräte erforderlich, bei denen das Erzwingen einer USB-Trennung zur Emulation eines Hotplugs nicht sinnvoll ist.)

Steuerelementauswahl 6
Vorgang GET / SET
wLength 1
Offset Feld Größe Wert Beschreibung
0 bResetRequest 1 Boolesch Senden Sie eine Rü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.

Die unterstützten Anfragetypen verhalten sich so:

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

Hiermit können Sie das Sichtfeld der Kamera konfigurieren und in eine voreingestellte Position zurückversetzen.

Kontrollgruppe: GOOGXU_PRESETS

Mit diesem Steuerelement können Sie die PTZ-Werte (Schwenken, Neigen und Zoomen) der Kamera auf eine vordefinierte Konfiguration festlegen.

Mit Preset Action wird die beabsichtigte Aktion des Befehls angegeben. Wenn Sie den Wert „1“ festlegen, werden die aktuellen Schwenk-, Neige- und Zoomwerte einem bereitgestellten Voreinstellungsindex zugeordnet. Wenn Sie den Wert „2“ festlegen, sollten Schwenken, Neigen und Zoomen der Kamera zu den zuvor für den angegebenen Index zugeordneten Werten oder den Standardkoordinaten der Fabrik (falls nicht zuvor zugeordnet) wechseln. Wenn Sie den Wert auf „3“ festlegen, wird der Index auf die Werksstandardkoordinaten zurückgesetzt.

Mit Preset Index werden die PTZ-Koordinaten angegeben, die dem Index zugeordnet sind. Die Preset index 0 (Null) wird den Startkoordinaten zugeordnet und sollte die Standardposition der Kamera beim Aufwachen sein, wenn die 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 Standardeinstellungen zurücksetzen (Der Standardwert sollte eine gültige voreingestellte Koordinate sein.)
1 bPresetIndex 1 Zahl Der Index der aktiven Voreinstellung. 0 bis N-1
Dabei gilt 0 als Standardstartposition der Kamera und N-1 ist eine vom Hersteller definierte Konstante für die Anzahl der Voreinstellungen.

Die unterstützten Anfragetypen verhalten sich so:

Offset 0 1 Beschreibung
GET_MIN 0x00 0x00
GET_MAX 0x03 N-1 N max-Voreinstellungen werden unterstützt
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 Nur Schreibzugriff
GET_DEF 0x00 0x00

Schwenken und neigen für Hilfskarten

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

Kontrollgruppe: GOOGXU_PAN_TILT_ABSOLUTE (eingestellt)

Die Steuerelemente für die zusätzliche Schwenk- und Neigungssteuerung sind in Kapitel 4: Klassenspezifische Anfragen, Abschnitt 4.2.2.1.14 „PanTilt (Absolute) Control“ der UVC 1.5-Klassenspezifikation definiert.

Kontrollgruppe: GOOGXU_PAN_TILT_RELATIVE (eingestellt)

Die Steuerelemente für die zusätzliche Ausrichtung von Schwenk- und Neigekopf sind in Kapitel 4: Klassenspezifische Anfragen, Abschnitt 4.2.2.1.15 „PanTilt (Relative) Control“ (Schwenk-/Neigekopfsteuerung (relativ)) der UVC 1.5-Klassenspezifikation definiert.

Versionshinweise

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

27. Januar 2025

21. Mai 2024

15. November 2023

Das Testscript wurde aktualisiert, um gültige Framing-Modi zu prüfen und zu interpretieren. Bytedarstellungen wurden klarer formuliert.

21. Juli 2023

Testscript für Partner hinzugefügt, um die Einhaltung dieser Spezifikation zu überprüfen.

25. Mai 2023

Korrigierter Hinweis zur Anzahl der GOOGXU_PRESETS Voreinstellungen. Es sollte N und nicht N-1 sein.

17. April 2023

Erste Version