API USB Video Class Extension Unit du matériel Google Meet

Ce document décrit les API USB Video Class Extension Unit (XU) compatibles utilisées par les systèmes de conférence Google Meet pour activer les fonctionnalités d'appareil photo intelligentes. L'objectif de cette spécification est d'influencer les pratiques pour activer ces fonctionnalités et de permettre une meilleure évolutivité et des tests asynchrones pour nos partenaires.

Pour en savoir plus sur les dernières modifications apportées à ce document, consultez les notes de version.

Installation de test

Pour aider les partenaires à valider la conformité avec cette spécification, nous mettons à leur disposition une plate-forme de test sur les appareils Chromebox pour la visioconférence configurés en mode développeur. Activez l'écriture dans le système de fichiers. Ajoutez les lignes suivantes à /etc/chrome_dev.conf:

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

Redémarrez l'appareil, connectez la caméra et un clavier USB, appuyez sur Ctrl-Alt-X, et la conformité aux spécifications de la caméra active sera testée et enregistrée dans /home/chronos/user/log/chrome.

Convention Little-endian

L'USB est une norme little-endian. Dans ce document:

  • Les nombres multi-octets apparaissent en big-endian (et sont transmis en little-endian).
  • Les tableaux d'octets sont dans la mise en page de mémoire little-endian.

Par exemple, 0x12345678 est identique à [0x78, 0x56, 0x34, 0x12].

GUID de l'unité d'extension

Les unités d'extension compatibles avec cette spécification de commande Meet XU doivent utiliser ce GUID.

Unité d'extension GUID
XU de contrôle des périphériques {74D7E924-49C9-4A45-98A3-8A9F60061E83}

Sélecteurs XU de contrôle des périphériques

Il s'agit des sélecteurs XU de contrôle des périphériques définis.

Sélecteurs de commande Valeur
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

Type de demande de contrôle

Les types de requêtes de contrôle sont définis dans le chapitre 4 : "Requêtes spécifiques à la classe" de la spécification de classe UVC 1.5.

Opération Contrôle UVC
GET GET_CUR, GET_MIN, GET_MAX, GET_RES, GET_LEN, GET_INFO, GET_DEF
SET SET_CUR

Modes de l'appareil photo

Les modes d'appareil photo permettent de cadrer des personnes dans une salle de réunion. Ils sont tuple:

  • Stratégie (vue de la caméra)
  • Biais (enceinte ou pièce)
  • Flux (un ou plusieurs flux)

Chaque dimension peut prendre les valeurs décrites dans les sections suivantes.

Stratégie de cadrage automatique

Dans tous les modes de cadrage automatique, à l'exception de "Aucun", le panoramique, l'inclinaison et le zoom manuels sont désactivés.

Fonctionnalité Description
Aucun La caméra désactive toutes les fonctionnalités de cadrage intelligent et permet au client de contrôler librement les valeurs PTZ.
Remarque:Lorsque vous utilisez cette stratégie de cadrage, la caméra reste dans sa position actuelle de panoramique, d'inclinaison et de zoom.
Cadrage continu (CAZ) En fonction du biais de cadrage, la caméra suit en permanence les personnes présentes dans la pièce.
Cadres fractionnés La caméra crée autant de vues vidéo que nécessaire. En fonction de l'option Flux de cadrage automatique, il les compose en tuiles dans un seul flux ou crée des flux vidéo distincts pour chaque vue.
Vue dynamique Une ou plusieurs caméras tentent de fournir la meilleure vue possible de la pièce. Il peut décider de combiner plusieurs flux en un seul ou de fournir une vue "intéressante" de la pièce actuelle.
L'objectif de cette vue est de fournir la vue la plus équitable des participants à l'appel dans la pièce.
Préféré par le fournisseur Le système de caméras utilise sa propre logique pour déterminer la meilleure vue de la pièce. La stratégie de cadrage sous-jacente est susceptible d'être modifiée sans préavis. Par exemple, si le nombre de personnes dans la pièce change ou si la caméra peut détecter la différence entre une réunion "Présentateur important" et une réunion "Collaboration", le système est libre d'adapter ou de modifier la stratégie de cadrage comme il le souhaite dans ce mode. Dans ce mode, l'appel de getCur doit renvoyer VENDOR_PREFERRED, et non le mode de cadrage sous-jacent sélectionné par le système.

Biais de cadrage automatique

Fonctionnalité Description
Présentateur important (suivi des intervenants) La caméra tente de cadrer au mieux la personne qui parle dans la pièce.
Dans ce scénario, la caméra doit être orientée vers le présentateur. Par exemple, le PDG qui fait une présentation dans une salle de conférence.
Collaboration
(suivi des salles)		 La caméra tente de cadrer au mieux tous les participants dans la salle. Dans ce scénario, la caméra doit traiter tous les participants de manière équitable.

Flux de cadrage automatique

Fonctionnalité Description
Flux unique La caméra envoie un seul flux vidéo à l'appareil hôte.

multiflux(en cours de développement)		 La caméra divise le flux et crée plusieurs flux vidéo à envoyer à l'hôte.
Remarque:La spécification complète et le comportement attendu de cette fonctionnalité sont en cours d'examen et ne sont pas pris en charge jusqu'aux versions ultérieures de ce document.

Valeurs bitmap du mode de cadrage automatique

À l'exception de l'état par défaut de None représenté par un tableau d'octets vide, chaque bit du tableau d'octets représente un mode d'appareil photo différent, qui est une combinaison spécifique de la stratégie de cadrage automatique, du biais de cadrage automatique et des flux de cadrage automatique.

Flux de cadrage automatique CAZ Split-Frame Dynamique Préféré par le fournisseur Biais de cadrage automatique
Single-Stream D1
D2		 -
 D3		 D5 
 D7		 D9 (enceinte ou salon) Enceinte
Pièce
Multi-flux -
-		 -
D4		 D6 
 D8		 - Enceinte
Pièce
Modes de frame Valeur du mode de trame (octet le moins significatif)
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

Contrôle: GOOGXU_FRAME_STRATEGY

Cette commande permet d'obtenir ou de définir les modes de cadrage de la caméra, comme indiqué dans la section Valeurs bitmap du mode de cadrage automatique. Chaque mode est représenté par un bit dans son bitmap respectif. La commande GET_RES renvoie un masque de bits de 8 octets avec une valeur de zéro (0) ou un (1) pour indiquer respectivement si la fonctionnalité est compatible ou non avec l'appareil. Par exemple, si une caméra prend en charge CAZ, Speaker, Single-Stream, Split-Frame, Room, Single-Stream et Dynamic, Room, Multi-Stream, mais aucun autre mode, GET_RES doit renvoyer 0x000000000000000085 (c'est-à-dire 0b10000101 suivi de sept octets de zéro).

La commande SET_CUR permet d'envoyer des bitmaps pour indiquer à l'appareil photo le mode SINGLE (SIMPLE) à activer.

Sélecteur de commandes 1
Opération GET / SET
wLength 8
Décalage (offset) Champ Taille Valeur Description
0 bActiveMode 8 Bitmap Définir ou rétablir le mode Caméra active
Remarques

Le comportement des types de requêtes acceptés est le suivant:

Décalage (offset) 0 Description
GET_CUR Obtenir le mode de caméra avec cadrage actif
GET_MIN Dépend de la caméra
GET_MAX Dépend de la caméra
GET_RES Renvoie un masque de bits de 8 octets des modes d'appareil photo compatibles.
GET_LEN 0x0008 Longueur
GET_INFO 0x0B AutoUpdate / Write / Read
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 Valeur par défaut
SET_CUR Définir le mode de cadrage actif de la caméra

Contrôle: GOOGXU_REFRAME

Ce contrôle permet de déclencher le cadrage à un seul coup, également appelé OTAZ. Lorsque l'OTAZ est déclenché, la vue de la caméra se fige sur la meilleure vue de la pièce. Le client peut ensuite à nouveau contrôler les valeurs PTZ. Si le cadrage en une seule prise de vue n'est pas pris en charge, la caméra ne doit pas définir cette commande.

Sélecteur de commandes 2
Opération SET
wLength 1
Décalage (offset) Champ Taille Valeur Description
0 bReframe 1 Nombre 0x01 Exécuter la requête de recadrage

Le comportement des types de requêtes acceptés est le suivant:

Décalage (offset) 0 Description
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x02 Écriture seule
GET_DEF 0x00
SET_CUR Définir la requête pour le cadrage unique

Comptage de l'occupation

Le comptage de l'occupation est une fonctionnalité qui permet d'estimer le nombre de participants dans une salle de réunion, malgré le recadrage de la caméra.

Ce tableau présente le comportement attendu des commandes OC et leurs interactions avec le flux vidéo de la caméra et l'indicateur LED de la caméra.

Lorsque le comptage d'occupation est Le flux vidéo de la caméra est: Le voyant LED de la caméra doit être GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR doit être GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR doit être
Activé Pas de diffusion et son activé Activé 0x01 Nombre de personnes dans le champ de vision complet de la caméra.
Activé Streaming Activé 0x01 Nombre de personnes dans le champ de vision complet de la caméra.
Activé Leur son est coupé. Désactivé 0x01 Désactivées
Désactivées Pas de diffusion et pas de mise en sourdine Désactivé 0x00 Désactivées
Désactivées Streaming Activé 0x00 Désactivées
Désactivées Leur son est coupé. Désactivé 0x00 Désactivées

Contrôle: GOOGXU_OCCUPANCY_COUNTING_TOGGLE

Ce bouton bascule permet d'activer ou de désactiver la fonctionnalité de comptage des occupants dans une pièce. Si vous définissez la valeur sur zéro (0), cette fonctionnalité est désactivée. Si vous définissez la valeur sur un (1), cette fonctionnalité est activée. Si cette fonctionnalité n'est pas prise en charge, la caméra ne doit pas définir cette commande.

Sélecteur de commandes 3
Opération GET / SET
wLength 1
Décalage (offset) Champ Taille Valeur Description
0 bOccupancy 1 Booléen Définir la fonction de comptage de l'occupation
0x00 Désactiver la fonction
0x01 Activer la fonction

Le comportement des types de requêtes acceptés est le suivant:

Décalage (offset) 0 Description
GET_CUR Renvoie si la détection d'occupation est activée
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x0B AutoUpdate / Write / Read
GET_DEF 0x00
SET_CUR Activer ou désactiver la fonctionnalité de comptage de l'occupation

Contrôle: GOOGXU_OCCUPANCY_COUNTING_READ

Ce paramètre permet de lire le nombre de participants dans une salle indiqué par la caméra lorsque le comptage de l'occupation est activé. Lorsque la détection d'occupation est désactivée, la caméra doit désactiver cette commande. Si le comptage de l'occupation n'est pas pris en charge, la caméra ne doit pas définir cette commande.

Sélecteur de commandes 4
Opération GET
wLength 2
Décalage (offset) Champ Taille Valeur Description
0 bNumPeople 2 Nombre Nombre d'occupants détectés dans le champ de vision. (Lecture seule)

Le comportement des types de requêtes acceptés est le suivant:

Décalage (offset) 0 Description
GET_CUR Renvoie le nombre d'occupants détectés
GET_MIN 0x0000
GET_MAX 0x00FF
GET_RES 0x0001
GET_LEN 0x0002
GET_INFO 0x09 AutoUpdate / Read
GET_DEF 0x0000

Télémétrie et diagnostics de l'appareil

Ces commandes visent à encourager de meilleures pratiques de débogage avec le matériel Meet et ne sont généralement pas destinées aux utilisateurs.

Contrôle: GOOGXU_STATUS_INFO

Ce paramètre permet d'interroger les informations de la caméra hôte à partager avec les partenaires à des fins de débogage.

Sélecteur de commande 5
Opération GET
wLength 8
Décalage (offset) Champ Taille Valeur Description
0 bNumCameras 1 Nombre Nombre de satellites supplémentaires associés à la caméra principale pouvant affecter le flux de la caméra renvoyé à l'hôte.
1 bIsMoving 1 Bitmap 0 lorsque la caméra est inactive et une valeur non nulle lorsque ses valeurs PTZ changent. Les fournisseurs sont libres de mapper différents axes ou moteurs sur différents bits.
2 Undef 6 Undef À étendre à l'avenir.

Le comportement des types de requêtes acceptés est le suivant:

Décalage (offset) 0 1 2 Description
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

Contrôle: GOOGXU_SATELLITE_INFO

Cette commande permet d'interroger les appareils satellites connectés à ce système de caméras.

Sélecteur de commandes 0x0A
Opération GET
wLength 20
Décalage (offset) Champ Taille Valeur Description
0 bSatelliteList 20 Bitmap Liste des types de satellites associés au système. Inclut quatre emplacements de 5 octets distincts. Chacun des emplacements est décrit comme suit:
Décalage (offset) Description
0 Quantité pour ce type de satellite.
1-2 ID du fournisseur de ce type de satellite.
3-4 ID produit de ce type de satellite.

Le comportement des types de requêtes acceptés est le suivant:

Décalage (offset) 0 Description
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 octets
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

Contrôle: GOOGXU_STATUS_RESET

Cette commande permet d'envoyer une requête de réinitialisation à la caméra. Si vous définissez la valeur sur un (1), la caméra est réinitialisée. La caméra renvoie zéro (0) si aucune demande de redémarrage de la caméra n'a été effectuée depuis la dernière réinitialisation et un (1) si elle est en cours de réinitialisation. La réinitialisation doit déclencher le redémarrage de la caméra. (Cela est nécessaire pour les appareils autoalimentés où forcer une déconnexion USB pour émuler un hotplug n'est pas utile.)

Sélecteur de commande 6
Opération GET / SET
wLength 1
Décalage (offset) Champ Taille Valeur Description
0 bResetRequest 1 Booléen Envoyez une demande de réinitialisation à l'hôte et aux caméras connectées.
Renvoie 0x01 si une demande de réinitialisation a été envoyée depuis la dernière réinitialisation, sinon 0x00.

Le comportement des types de requêtes acceptés est le suivant:

Décalage (offset) 0 Description
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x03 Écriture / Lecture
GET_DEF 0x00

Préréglages PTZ

Permet de configurer et de restaurer le champ de vision de la caméra à une position prédéfinie.

Contrôle: GOOGXU_PRESETS

Cette commande permet de définir les valeurs de panoramique, d'inclinaison et de zoom (PTZ) de la caméra sur une configuration prédéfinie.

Preset Action permet d'indiquer l'action prévue de la commande. Définir une valeur de un (1) permet de mapper les valeurs de panoramique, d'inclinaison et de zoom actuelles à un index prédéfini fourni. Si vous définissez la valeur sur deux (2), le panoramique, l'inclinaison et le zoom de la caméra doivent passer aux valeurs précédemment mappées pour l'index fourni ou aux coordonnées d'usine par défaut (si elles n'ont pas été mappées précédemment). Si vous définissez la valeur sur trois (3), l'index est réinitialisé sur les coordonnées par défaut d'usine.

Preset Index permet de spécifier les coordonnées PTZ mappées sur l'index. La valeur Preset index de zéro (0) est mappée sur les coordonnées de la position initiale et doit être la position par défaut de la caméra au réveil lorsque GOOGXU_FRAME_STRATEGY est défini sur NONE.

Sélecteur de commande 7
Opération SET
wLength 2
Décalage (offset) Champ Taille Valeur Description
0 bPresetAction 1 Nombre 0x01: Enregistrer le préréglage
0x02: Restaurer le préréglage
0x03: Rétablir le préréglage par défaut (La valeur par défaut doit être une coordonnée prédéfinie valide.)
1 bPresetIndex 1 Nombre Indice du préréglage actif. 0~N-1
, où 0 est considéré comme la position de départ par défaut de la caméra et N-1 est une constante définie par le fournisseur pour le nombre de préréglages.

Le comportement des types de requêtes acceptés est le suivant:

Décalage (offset) 0 1 Description
GET_MIN 0x00 0x00
GET_MAX 0x03 N-1 N préréglages maximaux compatibles
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 Écriture seule
GET_DEF 0x00 0x00

Déplacer et incliner la carte auxiliaire

Certaines caméras disposent de composants spéciaux, comme les moteurs pour les caméras mécaniques ou les fonctionnalités PTZ numériques. Pour ce faire, utilisez les commandes V4L2 standards pour le panoramique, l'inclinaison et le zoom.

Contrôle: GOOGXU_PAN_TILT_ABSOLUTE (obsolète)

Les commandes de mappage auxiliaires de panoramique et de basculement sont définies dans le chapitre 4 : "Demandes spécifiques à la classe", section 4.2.2.1.14 "Commande PanTilt (absolue)" de la spécification de classe UVC 1.5.

Contrôle: GOOGXU_PAN_TILT_RELATIVE (obsolète)

Les commandes de mappage auxiliaires de panoramique et de basculement sont définies dans le chapitre 4 : "Demandes spécifiques à la classe", section 4.2.2.1.15 "Commande (relative) de panoramique et de basculement" de la spécification de classe UVC 1.5.

Notes de version

Ces notes de version décrivent les améliorations et les nouvelles fonctionnalités apportées à chaque révision de ce document.

27 janvier 2025

21 mai 2024

15 novembre 2023

Mise à jour du script de test pour vérifier et interpréter les modes de cadrage valides. Clarifications apportées aux représentations d'octets.

21 juillet 2023

Ajout d'un script de test permettant aux partenaires de valider la conformité des implémentations avec cette spécification.

25 mai 2023

Correction de la note GOOGXU_PRESETS concernant le nombre de préréglages. Il doit s'agir de N, et non de N-1.

17 avril 2023

Version initiale.