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 der Erstellung dieser Spezifikation sollen die Praktiken zur Aktivierung dieser Funktionen sowie für eine bessere asynchrone Skalierbarkeit und Tests für unsere Partner beeinflusst werden.

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, schließen Sie die Kamera an eine USB-Tastatur an und drücken Sie Ctrl-Alt-X. Die Spezifikationskonformität der aktiven Kamera wird ausgeführt 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-Steuerspezifikation 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-Selektoren für Peripheriegeräte.

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

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

Funktion Beschreibung
Keine Die Kamera deaktiviert alle intelligenten Framing-Funktionen und ermöglicht es dem Kunden, 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) Basierend auf der Voreingenommenheit beim Bildausschnitt verfolgt die Kamera kontinuierlich Personen im Raum.
Hinweis:PTZ ist in diesem Modus deaktiviert.
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.
Hinweis:PTZ ist in diesem Modus deaktiviert.
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.
Hinweise:
  • Diese Strategie sollte bei den meisten Besprechungen angewendet werden.
  • PTZ ist in diesem Modus deaktiviert.

Voreingenommenheit durch den automatischen Bildausschnitt

Funktion Beschreibung
Redner mit hoher Bedeutung (Sprecher-Tracking) Die Kamera versucht, die Person, die im Raum aktiv spricht, optimal zu fokussieren.
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 zu fokussieren. In diesem Szenario sollte die Kamera alle Teilnehmer gleich behandeln. Diese Strategie sollte in den meisten Meetings verwendet werden.

Feeds mit automatischer Bildausrichtung

Funktion Beschreibung
Einzelner Stream Die Kamera sendet einen einzelnen Videostream an das Hostgerät.
Multistream
(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 derzeit überprüft und werden erst in späteren Versionen dieses Dokuments unterstützt.

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

Bit index CAZ Split-Frame Dynamisch -
Lautsprecher D1
–		 –
–		 D5 
D6		 Einzelstream
Multistream
Raum D2
–		 D3
D4		 D7
D8		 Einzelstream
Multistream
Frame-Modi Frame-Modus-Wert (niedrigstwertiges Byte)
None 0x00
CAZ, Speaker, Single-Stream 0x01
CAZ, Room, Single-Stream 0x02
Split-Frame, Room, Single-Stream 0x04
Split-Frame, Room, Multi-Stream 0x08
Dynamic, Speaker, Single-Stream 0x10
Dynamic, Speaker, Multi-Stream 0x20
Dynamic, Room, Single-Stream 0x40
Dynamic, Room, Multi-Stream 0x80

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 den Wert 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 einstellen 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 0 x 0 Mrd. AutoUpdate / Write / Read
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 Standardwert
SET_CUR Kameramodus für den automatischen Bildausschnitt festlegen

Kontrollgruppe: GOOGXU_REFRAME

Mit dieser Einstellung wird der One-Shot-Bildausschnitt (One-Shot-Anzeige, OTAZ) ausgelöst. Wenn OTAZ ausgelöst wird, wechselt die Kameraansicht zur besten Ansicht des Raums. Danach kann der Client die PTZ-Werte wieder steuern. Wenn die automatische Bildkomposition 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 Anwesenheitszählung ist eine Funktion, mit der die Anzahl der Teilnehmer in einem Konferenzraum trotz des zugeschnittenen Sichtfelds der Kamera geschätzt wird.

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 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 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 Kein Streaming 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 Zurückkehren, wenn die Belegungszählung 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 Belegung gezählt wird. Wenn die Personenzählung deaktiviert ist, sollte die Kamera diese Einstellung deaktivieren. Wenn die Belegungszählung nicht unterstützt wird, sollte die Kamera dieses Steuerelement nicht definieren.

Auswahl für Steuerelemente 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_STATUS_RESET

Mit diesem Steuerelement wird eine Anfrage zum Zurücksetzen 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 kein Neustart angefordert wurde, und „1“, wenn sie zurückgesetzt wird. Durch das Zurücksetzen muss die Kamera neu gestartet werden. (Dies ist für selbstversorgte Geräte erforderlich, bei denen das Erzwingen einer USB-Trennung zur Emulation eines Hotplugs nicht sinnvoll ist.)

Auswahl für Steuerelemente 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 einen Wert von 2 (2) festlegen, werden Schwenken, Neigung und Zoom der Kamera auf die zuvor zugeordneten Werte für den angegebenen Index oder auf die standardmäßigen Werkkoordinaten (falls noch nicht zugeordnet) umgestellt. 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 (Die Standardeinstellung 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 Presets.

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 von 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.

Kontrolle: GOOGXU_PAN_TILT_ABSOLUTE (eingestellt)

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

Kontrolle: 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-/Neigesteuerung (relativ)) der UVC 1.5-Klassenspezifikation definiert.

Versionshinweise

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

21. Mai 2024

15. November 2023

Das Testskript 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