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, mit denen Google Meet-Konferenzsysteme intelligente Kamerafunktionen aktivieren können. Der Zweck der Erstellung dieser Spezifikation besteht darin, die Praktiken zur Aktivierung dieser Features zu beeinflussen und eine bessere asynchrone Skalierbarkeit und Tests für unsere Partner zu ermöglichen.

In diesem Testskript wird Ihre Implementierung analysiert und dokumentiert, um Partnern bei der Prüfung der Einhaltung dieser Spezifikation zu helfen.

Details zu den neuesten Änderungen an diesem Dokument finden Sie unter Versionshinweise.

Little-Endian-Konvention

USB ist ein Little-Endian-Standard. Inhalt dieses Dokuments:

  • Multibyte-Zahlen erscheinen als Big-Endian-Zahlen (und werden übertragen Little-Endian).
  • Byte-Arrays befinden sich im Little-Endian-Speicherlayout.

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

Erweiterungseinheits-GUID

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

Erweiterungseinheit GUID
Peripheriegerätesteuerung XU {74D7E924-49C9-4A45-98A3-8A9F60061E83}

XU-Auswahl für Peripheriegeräte

Dies sind die XU-Selektoren für die Peripheriesteuerung.

Auswahlsteuerelemente steuern 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

Anfragetyp steuern

Die Typen von Kontrollanfragen sind in Kapitel 4: Klassenspezifische Anfragen der Klassenspezifikation UVC 1.5 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 zeigen. Sie sind eine tuple von:

  • Strategie (Kameraansicht)
  • Verzerrung (Lautsprecher oder Raum)
  • Feeds (ein oder mehrere Streams)

Jede Dimension kann Werte annehmen, die in den folgenden Abschnitten beschrieben werden.

Strategie für den automatischen Bildausschnitt

Funktion Beschreibung
Keine Die Kamera deaktiviert alle intelligenten Framing-Funktionen und ermöglicht dem Kunden, die PTZ-Werte frei zu steuern.
Hinweis:Wenn Sie diese Framing-Strategie auswählen, bleibt die Kamera in ihrer aktuellen Schwenk-, Neigungs- und Zoomposition.
CAZ (Continuous Framing) Basierend auf der Framing-Biasung verfolgt die Kamera kontinuierlich die Personen im Raum.
Hinweis:Die PTZ ist in diesem Modus deaktiviert.
Geteilte Frames Die Kamera erstellt so viele Videoaufrufe wie nötig. Basierend auf der Option Feeds mit automatischem Framing werden sie entweder in Kacheln in einem einzelnen Stream zusammengefasst oder es werden separate Videostreams für jede Ansicht erstellt.
Hinweis:Die PTZ ist in diesem Modus deaktiviert.
Dynamische Ansicht Mindestens eine Kamera versucht, die beste Sicht im Raum zu bieten. Sie kann entscheiden, ob mehrere Feeds zu einem Feed zusammengeführt werden sollen oder ob ein „interessantes“ Bild des aktuellen Raums angezeigt werden soll.
Damit soll eine möglichst genaue Ansicht der Teilnehmer im Konferenzraum gewährleistet werden.
Hinweise:
  • Diese Strategie sollte für die meisten Besprechungen verwendet werden.
  • Die PTZ ist in diesem Modus deaktiviert.

Gewichtung durch automatisches Framing

Funktion Beschreibung
High-Stakes-Vortragende (Sprecherverfolgung) Die Kamera versucht, die aktiv sprechende Person im Raum bestmöglich zu erfassen.
In diesem Szenario sollte die Kamera auf die präsentierende Person ausgerichtet sein. Beispiel: Der CEO eines Geschäftsvorstands hält eine Präsentation.
Zusammenarbeit
(Raumverfolgung)		 Die Kamera versucht, alle Teilnehmer im Raum bestmöglich zu erfassen. In diesem Szenario sollte die Kamera alle Teilnehmenden gleich behandeln. Diese Strategie sollte für die meisten Besprechungen verwendet werden.

Feeds mit automatischem Framing

Funktion Beschreibung
Einzelner Stream Die Kamera sendet einen einzelnen Videostream an das Hostgerät.
Multi-Stream
(In Arbeit)		 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 muss noch überprüft werden. Sie wird erst bei späteren Überarbeitungen dieses Dokuments unterstützt.

Bitmapwerte für den Modus „Automatischer Bildausschnitt“

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. Dieser ist eine spezifische Kombination aus der Strategie für das automatische Framing, der Verzerrung durch den automatischen Bildausschnitt und den Feeds mit automatischem Framing.

Bit-Index CAZ Split-Frame Dynamisch -
Lautsprecher T1
–		 –
–		 D5
D6		 Single-Stream
Multi-Stream
Raum T2
–		 D3
D4		 D7
D8		 Single-Stream
Multi-Stream
Frame-Modi Framemoduswert (niedrigstes 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

Steuerung: GOOGXU_FRAME_STRATEGY

Mit diesem Steuerelement können Sie die Framing-Modi der Kamera abrufen oder festlegen, wie unter Bitmapwerte für den Modus „Automatischer Framing“ aufgeführt. Jeder Modus wird in der jeweiligen Bitmap als Bit dargestellt. Der Befehl GET_RES gibt eine 8 Byte lange Bitmaske mit einem Wert von null (0) oder eins (1) zurück, um anzugeben, ob das Feature vom Gerät nicht unterstützt wird oder 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 zurückgeben (d.h. 0b10000101 gefolgt von sieben Nullbyte).

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

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

Das Verhalten der unterstützten Anfragetypen sieht so aus:

Offset 0 Beschreibung
GET_CUR Active Framing-Kameramodus
GET_MIN Kameraabhängig
GET_MAX Kameraabhängig
GET_RES Gibt eine lange 8-Byte-Bitmaske der unterstützten Kameramodi zurück
GET_LEN 0x0008 Länge
GET_INFO 0 x 0 Mrd. AutoUpdate / Schreiben / Lesen
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 Standardwert
SET_CUR Active Framing-Kameramodus festlegen

Steuerung: GOOGXU_REFRAME

Mit diesem Steuerelement wird der One-Shot-Framing ausgelöst, auch als OTAZ bezeichnet. Wenn OTAZ ausgelöst wird, wechselt die Kameraansicht zur besten Ansicht des Raums. Danach kann der Client die PTZ-Werte wieder steuern. Wenn das Framing mit nur einer Aufnahme nicht unterstützt wird, sollte die Kamera dieses Steuerelement nicht definieren.

Steuerungsauswahl 2
Vorgang SET
wLength 1
Offset Feld Größe Wert Beschreibung
0 bReframe 1 Zahl 0x01 Anfrage zur Ausführung des neuen Frames

Das Verhalten der unterstützten Anfragetypen sieht so aus:

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 einstellen

Anwesenheitszählung

Die Anwesenheitserkennung ist eine Funktion, mit der die Anzahl der Teilnehmer in einem Konferenzraum trotz des Bildausschnitts der Kamera geschätzt wird.

In dieser Tabelle sehen Sie das erwartete Verhalten der Steuerelemente für das beste Temperatursystem und ihre Interaktionen mit dem Kamera-Videostream und der Kamera-LED-Anzeige.

Wenn die Anwesenheitszählung und der Kamera-Videostream ist: Die LED-Anzeige der Kamera sollte GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR sollte sein GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR sollte sein
Aktiviert Kein Streaming und nicht stummgeschaltet An 0x01 Die Anzahl der Personen im gesamten Sichtfeld der Kamera.
Aktiviert Livestreams 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 Livestreams An 0x00 Deaktiviert
Deaktiviert stummgeschaltet, Aus 0x00 Deaktiviert

Steuerung: GOOGXU_OCCUPANCY_COUNTING_TOGGLE

Mit diesem Steuerelement wird die Funktion zum Zählen der Personen in einem Raum aktiviert oder deaktiviert. Wenn Sie den Wert null (0) festlegen, wird diese Funktion deaktiviert und durch eins (1) wird sie aktiviert. Wenn diese Funktion nicht unterstützt wird, sollte die Kamera dieses Steuerelement nicht definieren.

Steuerungsauswahl 3
Vorgang GET / SET
wLength 1
Offset Feld Größe Wert Beschreibung
0 bOccupancy 1 Boolesch Anwesenheitszählfunktion festlegen
0x00 Funktion deaktivieren
0x01 Funktion aktivieren

Das Verhalten der unterstützten Anfragetypen sieht so aus:

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 0 x 0 Mrd. AutoUpdate / Schreiben / Lesen
GET_DEF 0x00
SET_CUR Funktion zur Belegungszähler aktivieren oder deaktivieren

Steuerung: GOOGXU_OCCUPANCY_COUNTING_READ

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

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

Das Verhalten der unterstützten Anfragetypen sieht so aus:

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 / Lesen
GET_DEF 0x0000

Telemetrie und Diagnose des Geräts

Diese Einstellungen sollen die Fehlerbehebung mit Meet-Hardware verbessern und sind in der Regel nicht für Nutzer sichtbar.

Steuerung: GOOGXU_STATUS_INFO

Mit diesem Steuerelement werden Informationen von der Hostkamera abgefragt, die zur Fehlerbehebung an Partner weitergegeben werden.

Steuerungsauswahl 5
Vorgang GET
wLength 8
Offset Feld Größe Wert Beschreibung
0 bNumCameras 1 Zahl Die Anzahl zusätzlicher Kameras, die mit dem Hauptgerät verbunden sind.
1 bIsMoving 1 Bitmap 0, wenn die Kamera inaktiv ist, und nicht null, wenn sie bewegt wird. Es steht den Anbietern kostenlos, verschiedene Achsen oder Motoren verschiedenen Bits zuzuordnen.
2 Undef 6 Keine Definition Wird demnächst verlängert.

Das Verhalten der unterstützten Anfragetypen sieht so aus:

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

Steuerung: GOOGXU_STATUS_RESET

Über dieses Steuerelement wird eine Anfrage zum Zurücksetzen an die Kamera gesendet. Wenn Sie den Wert eins (1) festlegen, wird die Kamera zurückgesetzt. Die Kamera gibt null (0) zurück, wenn seit dem letzten Zurücksetzen keine Aufforderung zum Neustart der Kamera eingegangen ist, und eins (1), wenn sie zurückgesetzt wird. Das Zurücksetzen löst dasselbe Verhalten aus wie die Wiederherstellung der Hardware. Dies ist für Geräte mit Selbstbetrieb nützlich, bei denen das Erzwingen der USB-Verbindung zur Emulation eines Hotplugs nicht sinnvoll ist.

Steuerungsauswahl 6
Vorgang GET / SET
wLength 1
Offset Feld Größe Wert Beschreibung
0 bResetRequest 1 Boolesch Senden Sie eine Anfrage zum Zurücksetzen an den Host und die verbundenen Kameras.
Gibt 0x01 zurück, wenn die Anfrage zum Zurücksetzen seit dem letzten Zurücksetzen gestellt wurde. Andernfalls wird 0x00 zurückgegeben.

Das Verhalten der unterstützten Anfragetypen sieht so aus:

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

Wird verwendet, um das Sichtfeld der Kamera auf eine voreingestellte Position zu konfigurieren und wiederherzustellen.

Steuerung: GOOGXU_PRESETS

Mit diesem Steuerelement werden die PTZ-Werte (Schwenken, Neigen und Zoomen) der Kamera auf eine voreingestellte Konfiguration gesetzt.

Mit Preset Action wird die beabsichtigte Aktion des Befehls angegeben. Wenn Sie den Wert eins (1) festlegen, werden die aktuellen Werte für Schwenken, Neigen und Zoomen einem bereitgestellten voreingestellten Index zugeordnet. Wenn Sie einen Wert von zwei (2) festlegen, sollten Schwenken, Neigen und Zoomen der Kamera auf die zuvor zugeordneten Werte für den angegebenen Index bzw. auf die standardmäßigen Werkskoordinaten (falls noch nicht zugeordnet) übergehen. Durch Festlegen eines Werts von drei (3) wird der Index auf die werkseitigen Standardkoordinaten zurückgesetzt.

Mit Preset Index werden die PTZ-Koordinaten angegeben, die dem Index zugeordnet sind. Der Preset index von null (0) wird den Heimatkoordinaten zugeordnet und sollte die Standardposition der Kamera sein, wenn der Ruhemodus beendet wird, wenn GOOGXU_FRAME_STRATEGY auf NONE eingestellt ist.

Steuerungsauswahl 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 muss eine gültige voreingestellte Koordinate sein.
1 bPresetIndex 1 Zahl Der Index der aktiven Voreinstellung. 0~N-1
Dabei gilt 0 als Standardstartposition der Kamera und N-1 als anbieterdefinierte Konstante für die Anzahl der Voreinstellungen.

Das Verhalten der unterstützten Anfragetypen sieht so aus:

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

Hilfszuordnung zum Schwenken und Neigen

Einige Kameras haben spezielle Komponenten, z. B. die Motoren für mechanische Kameras, für die XU-Befehle den standardmäßigen V4L2-Steuerelementen zugeordnet werden müssen, damit Schwenken und Neigen wie vorgesehen funktionieren.

Diese Steuerelemente ahmen die absoluten und relativen Steuerelemente für Schwenken und Neigen in der Dokumentation der UVC-Spezifikation nach und bieten eine Standardmethode für Hostgeräte, diese Steuerelemente korrekt zuzuordnen.

Steuerung: GOOGXU_PAN_TILT_ABSOLUTE

Die zusätzlichen Steuerelemente zum Schwenken und Neigen sind in Kapitel 4: Klassenspezifische Anfragen, Abschnitt 4.2.2.1.14 „Panneigung (Absolute)“-Steuerung der UVC 1.5-Klassenspezifikation definiert.

Steuerungsauswahl 8
Vorgang GET/SET
wLength 8
Offset Feld Größe Wert Beschreibung
0 dwPanAbsolute 4 Signierte Nummer Die Einstellung für das Attribut des angesprochenen Schwenk- bzw. absoluten Steuerelements.
4 dwTiltAbsolute 4 Signierte Nummer Die Einstellung für das Attribut des angepassten Neigungssteuerelements (Absolutes)

Das Verhalten der unterstützten Anfragetypen sieht so aus:

Offset 0 4 Beschreibung
GET_MIN Kameraabhängig
GET_MAX Kameraabhängig
GET_RES Kameraabhängig
GET_LEN 0x0008
GET_INFO 0 x 0 Mrd. AutoUpdate / Schreiben / Lesen
GET_DEF 0x00000000 0x00000000

Steuerung: GOOGXU_PAN_TILT_RELATIVE

Die zusätzlichen Steuerelemente zum Schwenken und Neigen sind in Kapitel 4: Klassenspezifische Anfragen, Abschnitt 4.2.2.1.15 Steuerung der relativen Panneigung der UVC 1.5-Klassenspezifikation definiert.

Steuerungsauswahl 9
Vorgang GET/SET
wLength 4
Offset Feld Größe Wert Beschreibung
0 bPanRelative 1 Signierte Nummer Die Einstellung für das Attribut des adressierten Steuerelements „Schwenken (relativ)“:
0: Stopp
1: Bewegung im Uhrzeigersinn
0xFF: Bewegung gegen den Uhrzeigersinn
1 bPanSpeed 1 Zahl Geschwindigkeit der Schwenkbewegung.
2 bTiltRelative 1 Signierte Nummer Einstellung für das Attribut der adressierten Neigungssteuerung (relativ):
0: Stopp
1: Bildebene nach oben zeigen
0xFF: Bildebene nach unten zeigen
3 bTiltSpeed 1 Zahl Geschwindigkeit der Neigungsbewegung.

Das Verhalten der unterstützten Anfragetypen sieht so aus:>

Offset 0 1 2 3 Beschreibung
GET_MIN Kameraabhängig
GET_MAX Kameraabhängig
GET_RES Kameraabhängig
GET_LEN 0x04 0x00 0x0004
GET_INFO 0 x 0 Mrd. AutoUpdate / Schreiben / Lesen
GET_DEF 0x00 0x00 0x00 0x00

Versionshinweise

Diese Versionshinweise beziehen sich auf Verbesserungen und neue Funktionen für jede Version dieses Dokuments.

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

Es wurde ein Testskript für Partner hinzugefügt, mit dem sich Implementierungen auf Einhaltung dieser Spezifikation überprüfen lassen.

25. Mai 2023

GOOGXU_PRESETS Hinweis bezüglich der Anzahl der Voreinstellungen wurde korrigiert. Es sollte N sein, nicht N-1.

17. April 2023

Erste Version