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

Ce document décrit les API d'unité d'extension (XU) de classe vidéo USB compatibles utilisées par les systèmes de visioconférence Google Meet pour activer les fonctionnalités de caméras intelligentes. L'objectif de cette spécification est d'influencer les pratiques pour activer ces fonctionnalités et permettre une meilleure évolutivité et de meilleurs tests asynchrones pour nos partenaires.

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

Centre de test

Pour aider les partenaires à valider la conformité avec cette spécification, nous fournissons un outil 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 exercée et enregistrée dans /var/log/chrome/chrome (ou /home/chronos/user/log/chrome si vous utilisez une image signée).

Convention Little Endian

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 disposition 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 contrôle Meet XU doivent utiliser ce GUID.

Unité d'extension GUID
Peripheral Control XU {74D7E924-49C9-4A45-98A3-8A9F60061E83}

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

Voici les sélecteurs XU de contrôle des périphériques définis.

Sélecteurs de commandes 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 : "Class Specific Requests" (Requêtes spécifiques à la classe) de la spécification de la 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 caméras

Les modes caméra permettent de cadrer les personnes dans une salle de réunion. Ils sont tuple de :

  • Stratégie (vue de 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 cette stratégie de cadrage est définie, 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.
Images fractionnées La caméra crée autant de vues vidéo que nécessaire. En fonction de l'option Flux de recadrage automatique, il les compose en mosaïques 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 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 possible des participants à l'appel dans la salle.
Privilégié 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 faire la différence entre une réunion "Présentation à fort enjeu" et une réunion "Collaboration", le système est libre d'adapter ou de modifier la stratégie de cadrage comme il l'entend dans ce mode. Dans ce mode, l'appel getCur doit renvoyer VENDOR_PREFERRED, et non le mode d'encadrement sous-jacent sélectionné par le système.

Biais de cadrage automatique

Fonctionnalité Description
Présentateur à enjeu élevé (suivi de l'orateur) 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, un PDG qui fait une présentation dans une salle de réunion.
Collaboration
(suivi de salle)		 La caméra tente de cadrer au mieux tous les participants dans la salle. Dans ce cas, la caméra doit traiter chaque participant de manière équitable.

Flux avec cadrage automatique

Fonctionnalité Description
Flux unique La caméra envoie un seul flux vidéo à l'appareil hôte.
Multi-Stream
(Work-In-Progress)		 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 tant que ce document n'aura pas été révisé.

Valeurs bitmap du mode de recadrage automatique

À l'exception de l'état par défaut None, qui est représenté par un tableau d'octets vide, chaque bit du tableau d'octets représente un mode de caméra 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 avec cadrage automatique CAZ Split-Frame Dynamique Privilégié par le fournisseur Biais de cadrage automatique
Flux unique D1 
D2		 - 
D3		 D5
D7		 D9 (enceinte ou salle) Enceinte
Pièce
Multi-Stream -
-		 - 
 D4		 D6 
D8		 - Enceinte
Pièce
Modes de frame Valeur du mode Frame (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 Valeurs bitmap du mode de cadrage automatique. Chaque mode est représenté par un bit dans sa bitmap respective. 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é n'est pas prise en charge ou si elle l'est par l'appareil. Par exemple, si une caméra est compatible avec CAZ, Speaker, Single-Stream, Split-Frame, Room, Single-Stream et Dynamic, Room, Multi-Stream, mais pas avec d'autres modes, GET_RES doit renvoyer 0x000000000000000085 (c'est-à-dire 0b10000101 suivi de sept octets zéro).

La commande SET_CUR permet d'envoyer des bitmaps pour indiquer à la caméra quel mode SINGLE 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 renvoyer le mode Caméra active
Remarques :

Voici le comportement des types de requêtes acceptés :

Décalage (offset) 0 Description
GET_CUR Obtenir le mode 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 de long des modes de caméras compatibles.
GET_LEN 0x0008 Longueur
GET_INFO 0x0B Mise à jour automatique / Écriture / Lecture
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 Valeur par défaut
SET_CUR Définir le mode de caméra "Cadrage actif"

Contrôle : GOOGXU_REFRAME

Cette commande permet de déclencher le cadrage ponctuel, également appelé OTAZ. Lorsque le cadrage automatique est déclenché, la vue de la caméra se fixe sur la meilleure vue de la pièce. Le client peut ensuite à nouveau contrôler les valeurs PTZ. Si le cadrage ponctuel 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 demande de recadrage

Voici le comportement des types de requêtes acceptés :

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 une requête pour le cadrage unique

Comptage des occupations

Le comptage de l'occupation (OC, Occupancy Counting) est une fonctionnalité utilisée pour estimer le nombre de participants dans une salle de réunion, malgré la vue recadrée de la caméra.

Ce tableau indique le comportement attendu des commandes OC et leurs interactions avec le flux vidéo de la caméra et le voyant LED de la caméra.

Lorsque le comptage des occupants 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é La diffusion n'est pas en cours et le son n'est pas coupé 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 La diffusion n'est pas en cours et le son n'est pas coupé 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

Cette commande 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 la définissez sur un (1), elle 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

Voici le comportement des types de requêtes acceptés :

Décalage (offset) 0 Description
GET_CUR Indique si la détection d'occupation est activée.
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x0B Mise à jour automatique / Écriture / Lecture
GET_DEF 0x00
SET_CUR Activer ou désactiver la fonctionnalité de détection d'occupation

Contrôle : GOOGXU_OCCUPANCY_COUNTING_READ

Cette commande permet de lire le nombre de participants dans une salle, tel qu'indiqué par la caméra lorsque le décompte 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 du nombre de personnes 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)

Voici le comportement des types de requêtes acceptés :

Décalage (offset) 0 Description
GET_CUR Renvoyer le nombre d'occupants détectés
GET_MIN 0x0000
GET_MAX 0x00FF
GET_RES 0x0001
GET_LEN 0x0002
GET_INFO 0x09 Mise à jour automatique / Lecture
GET_DEF 0x0000

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

Ces commandes sont destinées à 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 contrôle permet d'interroger les informations de la caméra hôte pour les partager avec les partenaires à des fins de débogage.

Sélecteur de commandes 5
Opération GET
wLength 8
Décalage (offset) Champ Taille Valeur Description
0 bNumCameras 1 Nombre Nombre de caméras satellites supplémentaires connectées à la caméra principale, ce qui peut affecter le flux de caméras renvoyé à l'hôte.
1 bIsMoving 1 Bitmap 0 lorsque la caméra est inactive et une valeur différente de zéro lorsque ses valeurs PTZ changent. Les fournisseurs sont libres de mapper différents axes ou moteurs à différents bits.
2 Undef 6 Undef Sera étendu à l'avenir.

Voici le comportement des types de requêtes acceptés :

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 Mise à jour automatique / Lecture
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. Comprend quatre emplacements de cinq 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 pour ce type de satellite.

Voici le comportement des types de requêtes acceptés :

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 Mise à jour automatique / Lecture
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 demande de réinitialisation à la caméra. Si vous définissez la valeur sur 1, la caméra est réinitialisée. La caméra renvoie zéro (0) si aucune demande de redémarrage n'a été envoyé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. (Cette opération est nécessaire pour les appareils auto-alimentés, pour lesquels il n'est pas utile de forcer la déconnexion USB pour émuler un branchement à chaud.)

Sélecteur de commandes 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é émise depuis la dernière réinitialisation, ou 0x00 dans le cas contraire.

Voici le comportement des types de requêtes acceptés :

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 sur 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 est utilisé pour indiquer l'action prévue de la commande. La valeur 1 permet de mapper les valeurs actuelles de panoramique, d'inclinaison et de zoom à un index de préréglage 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.

Preset Index permet de spécifier les coordonnées PTZ mappées à l'index. La valeur Preset index zéro (0) est associée aux coordonnées de la position initiale et doit correspondre à la position par défaut de la caméra lors de la sortie de veille lorsque GOOGXU_FRAME_STRATEGY est défini sur NONE.

Sélecteur de commandes 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 Index 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.

Voici le comportement des types de requêtes acceptés :

Décalage (offset) 0 1 Description
GET_MIN 0x00 0x00
GET_MAX 0x03 N-1 Nombre maximal de préréglages N pris en charge
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 Écriture seule
GET_DEF 0x00 0x00

Mappage auxiliaire de panoramique et d'inclinaison

Certaines caméras sont dotées de composants spéciaux, comme des moteurs pour les caméras mécaniques ou des fonctionnalités PTZ numériques. Pour ceux-ci, 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 d'inclinaison sont définies dans le chapitre 4 : Requêtes spécifiques à la classe, section 4.2.2.1.14, Contrôle PanTilt (absolu) de la spécification de la classe UVC 1.5.

Contrôle : GOOGXU_PAN_TILT_RELATIVE (obsolète)

Les commandes de mappage auxiliaires de panoramique et d'inclinaison sont définies dans le chapitre 4 : Requêtes spécifiques à la classe, section 4.2.2.1.15, Commande PanTilt (Relative) de la spécification de la 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.

13 août 2025

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. Clarification des représentations d'octets.

21 juillet 2023

Ajout d'un script de test permettant aux partenaires de valider les implémentations pour vérifier leur conformité avec cette spécification.

25 mai 2023

Note corrigée 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.