Ce document décrit les API USB Video Class Extension Unit (XU) compatibles avec les systèmes de conférence Google Meet qui permettent d'activer les fonctionnalités intelligentes de la caméra. L'objectif de cette spécification est d'influencer les pratiques permettant d'activer ces fonctionnalités et de permettre une meilleure évolutivité asynchrone et des tests pour nos partenaires.
Pour aider les partenaires à valider la conformité avec cette spécification, ce script de test analyse votre mise en œuvre et génère des rapports sur celle-ci.
Pour en savoir plus sur les dernières modifications apportées à ce document, consultez la page Notes de version.
Convention Little-endian
L'USB est une norme « petit-endian ». Dans ce document:
- Les nombres à plusieurs octets apparaissent en mode big-endian (et sont transmis en Little-endian).
- Les tableaux d'octets utilisent la mise en page de la mémoire Little-endian.
Par exemple, 0x12345678
est identique à [0x78, 0x56, 0x34, 0x12]
.
GUID d'unité d'extension
Les unités d'extensions compatibles avec cette spécification de contrôle Meet XU doivent utiliser ce GUID.
Unité d'extension | GUID |
---|---|
Périphérique XU de contrôle | {74D7E924-49C9-4A45-98A3-8A9F60061E83} |
Sélecteurs XU de commande de périphérique
Il s'agit des sélecteurs XU de commande de périphériques définis.
Contrôler les sélecteurs | 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 |
Type de requête de contrôle
Les types de requêtes de contrôle sont définis dans le chapitre 4: Requêtes spécifiques de 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 la caméra
Les modes de caméra sont utilisés pour cadrer les personnes dans une salle de réunion et sont un tuple
des suivants:
- Stratégie (vue de la caméra)
- Biais (enceinte ou salle)
- Flux (un ou plusieurs flux)
Chaque dimension peut être associée à des valeurs décrites dans les sections suivantes.
Stratégie de cadrage automatique
Caractéristique | 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 qui se trouvent dans la pièce. Remarque:Le PTZ est désactivé dans ce mode. |
Images fractionnées | La caméra crée autant de vues que nécessaire. L'option cadrage automatique des flux permet de créer des tuiles dans un seul flux ou de créer des flux vidéo distincts pour chaque vue. Remarque:Le PTZ est désactivé dans ce mode. |
Affichage dynamique | Une ou plusieurs caméras tentent de fournir le meilleur champ de vision de la pièce. Elle permet de décider si vous souhaitez regrouper plusieurs flux en un seul ou fournir une vue "intéressante" de la salle actuelle. L'objectif de cette vue est de présenter l'appel de la façon la plus équitable possible à tous les participants en présentiel. Remarques:
|
Préjugé de cadrage automatique
Caractéristique | Description |
---|---|
Présentateur à enjeux élevés (suivi de l'intervenant) | 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 fait une présentation dans une salle de conférence. |
Collaboration (suivi de la salle) |
La caméra tente de cadrer au mieux tous les participants présents dans la salle. Dans ce scénario, la caméra doit traiter chaque participant de manière équitable. La plupart des réunions devraient utiliser cette stratégie. |
Flux de cadrage automatique
Caractéristique | Description |
---|---|
Flux unique | La caméra envoie un seul flux vidéo à l'appareil hôte. |
Multi-flux (en cours) |
La caméra divise le flux et crée plusieurs flux vidéo à envoyer à l'organisateur. Remarque:Les spécifications complètes et le comportement attendu de cette fonctionnalité sont en attente d'examen. Elles ne seront pas disponibles avant les révisions ultérieures de ce document. |
Valeurs bitmap du mode de cadrage automatique
À l'exception de l'état par défaut de None
qui est représenté par un tableau d'octets vide, chaque bit dans le 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.
Index de bits | CAZ | Frame fractionné | Dynamique | - |
---|---|---|---|---|
Haut-parleur | J1 - |
– – |
J5 J6 |
Flux unique Multiflux |
Room | D2 - |
J3 J4 |
J7 J8 |
Flux unique Multiflux |
Modes de frame | Valeur du mode frame (octet le moins significatif) |
---|---|
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 |
Contrôle: GOOGXU_FRAME_STRATEGY
Cette commande permet d'obtenir ou de définir les modes de cadrage de l'appareil photo, comme indiqué dans la section Valeurs bitmap du mode de cadrage automatique. Chaque mode est représenté sous la forme
d'un bit dans leur bitmap respectif. La commande GET_RES
renvoie un masque de bits de 8 octets avec une valeur zéro (0) ou un (1) pour indiquer respectivement si la fonctionnalité n'est pas compatible ou compatible 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 zéros octets).
La commande SET_CUR
permet d'envoyer des bitmaps afin d'indiquer à la caméra quel mode d'appareil photo SINGLE activer.
Sélecteur de contrôle | 1 | |||
---|---|---|---|---|
Opération | GET / SET |
|||
wLength |
8 | |||
Décalage (offset) | Champ | Taille | Valeur | Description |
0 | bActiveMode |
8 | Bitmap | Activer ou désactiver le mode Appareil photo actif |
Remarques:
|
Le comportement des types de requêtes compatibles est le suivant:
Décalage (offset) | 0 | Description |
---|---|---|
GET_CUR |
Activer le mode Appareil photo avec cadre 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 |
0 x 0 M | 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 Appareil photo Active Framing |
Contrôle: GOOGXU_REFRAME
Cette commande permet de déclencher le cadrage One-Shot, également appelé OTAZ. Lorsque le mode OTAZ est déclenché, la vue de la caméra s'aligne sur la meilleure vue de la pièce. Par la suite, le client peut de nouveau contrôler les valeurs PTZ. Si le cadrage unique n'est pas accepté, l'appareil photo ne doit pas définir cette commande.
Sélecteur de contrôle | 2 | |||
---|---|---|---|---|
Opération | SET |
|||
wLength |
1 | |||
Décalage (offset) | Champ | Taille | Valeur | Description |
0 | bReframe |
1 | Nombre | Exécuter une requête de recadrage 0x01 |
Le comportement des types de requêtes compatibles 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 une demande de cadrage One-Shot |
Décompte de l'occupation
La comptabilisation de l'occupation est une fonctionnalité permettant d'estimer le nombre de participants à une salle de réunion, malgré le recadrage de la caméra.
Ce tableau présente le comportement attendu des commandes OC, ainsi que leurs interactions avec le flux vidéo de la caméra et l'indicateur LED de la caméra.
Lorsque la métrique d'occupation est | et 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ée | Aucune diffusion en streaming ni son coupé | On | 0x01 |
Nombre de personnes dans le champ de vision complet de la caméra. |
activée | Streaming | On | 0x01 |
Nombre de personnes dans le champ de vision complet de la caméra. |
activée | Leur son est coupé. | Désactiver | 0x01 |
Désactivées |
Désactivées | Aucune diffusion en streaming ni son coupé | Désactiver | 0x00 |
Désactivées |
Désactivées | Streaming | On | 0x00 |
Désactivées |
Désactivées | Leur son est coupé. | Désactiver | 0x00 |
Désactivées |
Contrôle: GOOGXU_OCCUPANCY_COUNTING_TOGGLE
Cette commande permet d'activer ou de désactiver la fonctionnalité afin de comptabiliser le nombre de personnes dans une chambre. Définir une valeur de zéro (0) désactive cette fonctionnalité et un (1) l'active. Si cette fonctionnalité n'est pas compatible, la caméra ne doit pas définir cette commande.
Sélecteur de contrôle | 3 | |||
---|---|---|---|---|
Opération | GET / SET |
|||
wLength |
1 | |||
Décalage (offset) | Champ | Taille | Valeur | Description |
0 | bOccupancy |
1 | Booléen | Définir la fonction de comptabilisation de l'occupation 0x00 Désactiver la fonction 0x01 Activer la fonction |
Le comportement des types de requêtes compatibles est le suivant:
Décalage (offset) | 0 | Description |
---|---|---|
GET_CUR |
Revenir si la comptabilisation de l'occupation est activée | |
GET_MIN |
0x00 | |
GET_MAX |
0x01 | |
GET_RES |
0x01 | |
GET_LEN |
0x0001 | |
GET_INFO |
0 x 0 M | Mise à jour automatique / Écriture / Lecture |
GET_DEF |
0x00 | |
SET_CUR |
Activer ou désactiver la fonctionnalité de comptabilisation de l'occupation |
Contrôle: GOOGXU_OCCUPANCY_COUNTING_READ
Cette commande permet de lire le nombre de participants dans une salle indiqués par la caméra lorsque la comptabilisation de l'occupation est activée. Si cette fonctionnalité est désactivée, l'appareil photo devrait désactiver cette commande. Si la comptabilisation de l'occupation n'est pas disponible, la caméra ne doit pas définir cette commande.
Sélecteur de contrôle | 4 | |||
---|---|---|---|---|
Opération | GET |
|||
wLength |
2 | |||
Décalage (offset) | Champ | Taille | Valeur | Description |
0 | bNumPeople |
2 | Nombre | Nombre de personnes détectées dans le champ de vision. (Lecture seule) |
Le comportement des types de requêtes compatibles est le suivant:
Décalage (offset) | 0 | Description |
---|---|---|
GET_CUR |
Afficher le nombre de personnes détectées | |
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 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
Cette commande permet d'interroger les informations de la caméra hôte afin de les partager avec les partenaires à des fins de débogage.
Sélecteur de contrôle | 5 | |||
---|---|---|---|---|
Opération | GET |
|||
wLength |
8 | |||
Décalage (offset) | Champ | Taille | Valeur | Description |
0 | bNumCameras |
1 | Nombre | Nombre de caméras supplémentaires connectées à l'appareil principal. |
1 | bIsMoving |
1 | Bitmap | La valeur 0 si la caméra est inactive et non nulle lorsqu'elle est en mouvement. Les fournisseurs sont libres de mapper différents axes ou moteurs à différents bits. |
2 | Undef |
6 | Non défini | À prolonger à l'avenir. |
Le comportement des types de requêtes compatibles 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 | Mise à jour automatique / Lecture | ||
GET_DEF |
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. La définition de la valeur "un" (1) entraîne la réinitialisation de la caméra. La caméra renvoie une valeur nulle (0) si aucune demande de redémarrage n'a été effectuée depuis la dernière réinitialisation et un (1) si la réinitialisation est en cours. Une réinitialisation déclenche le même comportement qu'une reconnexion matérielle. Cela est utile pour les appareils auto-alimentés où il n'est pas utile de forcer un débranchement USB à émuler une prise de chaud.
Sélecteur de contrôle | 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 la requête de réinitialisation a été émise depuis la dernière réinitialisation. Sinon, 0x00. |
Le comportement des types de requêtes compatibles 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. Le fait de définir la valeur un (1) permet de mapper les valeurs actuelles de panoramique, d'inclinaison et de zoom à un index prédéfini fourni. Si vous définissez une 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 une valeur de trois (3), les coordonnées par défaut de l'index sont rétablies.
Preset Index
permet de spécifier les coordonnées PTZ mappées à l'index.
Le Preset index
de zéro (0) est mappé sur les coordonnées de la maison et doit être la position par défaut de la caméra à l'activation lorsque GOOGXU_FRAME_STRATEGY
est défini sur NONE
.
Sélecteur de contrôle | 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. |
Le comportement des types de requêtes compatibles est le suivant:
Décalage (offset) | 0 | 1 | Description |
---|---|---|---|
GET_MIN |
0x00 | 0x00 | |
GET_MAX |
0x03 | N-1 | N préréglages maximum acceptés |
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 possèdent des composants spéciaux, tels que les moteurs des caméras mécaniques, qui nécessitent de mapper les commandes XU sur les commandes V4L2 standards pour que le panoramique et l'inclinaison fonctionnent comme prévu.
Ces commandes imitent les commandes absolues et relatives de panoramique et d'inclinaison dans la documentation de spécification UVC, ce qui offre aux appareils hôtes un moyen standard de mapper correctement ces commandes.
Contrôle: GOOGXU_PAN_TILT_ABSOLUTE
Les commandes de mappage auxiliaires de panoramique et d'inclinaison sont définies dans le chapitre 4: Requêtes spécifiques à une classe, section 4.2.2.1.14 Commande PanTilt (absolu) de la spécification de classe UVC 1.5.
Sélecteur de contrôle | 8 | |||
---|---|---|---|---|
Opération | GET/SET |
|||
wLength |
8 | |||
Décalage (offset) | Champ | Taille | Valeur | Description |
0 | dwPanAbsolute |
4 | Numéro signé | Paramètre de l'attribut de la commande de panoramique (absolu) adressée. |
4 | dwTiltAbsolute |
4 | Numéro signé | Paramètre de l'attribut de la commande d'inclinaison (absolue) adressée. |
Le comportement des types de requêtes compatibles est le suivant:
Décalage (offset) | 0 | 4 | Description |
---|---|---|---|
GET_MIN |
Dépend de la caméra | ||
GET_MAX |
Dépend de la caméra | ||
GET_RES |
Dépend de la caméra | ||
GET_LEN |
0x0008 | ||
GET_INFO |
0 x 0 M | Mise à jour automatique / Écriture / Lecture | |
GET_DEF |
0x00000000 | 0x00000000 |
Contrôle: GOOGXU_PAN_TILT_RELATIVE
Les commandes de mappage auxiliaires de panoramique et d'inclinaison sont définies dans le chapitre 4: Requêtes spécifiques à une classe, section 4.2.2.1.15 Contrôle (relatif) de PanTilt de la spécification de classe UVC 1.5.
Sélecteur de contrôle | 9 | |||
---|---|---|---|---|
Opération | GET/SET |
|||
wLength |
4 | |||
Décalage (offset) | Champ | Taille | Valeur | Description |
0 | bPanRelative |
1 | Numéro signé | Paramètre de l'attribut de la commande "Panoramique (Rel)" adressée: 0: Arrêt 1: déplacement dans le sens des aiguilles d'une montre 0xFF: déplacement dans le sens inverse des aiguilles d'une montre |
1 | bPanSpeed |
1 | Nombre | Vitesse du mouvement du panoramique. |
2 | bTiltRelative |
1 | Numéro signé | Paramètre de l'attribut du contrôle d'inclinaison (relatif) adressé: 0: arrêt 1: faire pointer le plan d'imagerie vers le haut 0xFF: pointer le plan d'imagerie vers le bas |
3 | bTiltSpeed |
1 | Nombre | Vitesse du mouvement d'inclinaison. |
Le comportement des types de requêtes compatibles est le suivant :
Décalage (offset) | 0 | 1 | 2 | 3 | Description |
---|---|---|---|---|---|
GET_MIN |
Dépend de la caméra | ||||
GET_MAX |
Dépend de la caméra | ||||
GET_RES |
Dépend de la caméra | ||||
GET_LEN |
0x04 | 0x00 | 0x0004 | ||
GET_INFO |
0 x 0 M | Mise à jour automatique / Écriture / Lecture | |||
GET_DEF |
0x00 | 0x00 | 0x00 | 0x00 |
Articles associés
- Pilote de classe vidéo USB (UVC) Linux
- Ensemble de documents de classe vidéo v1.5
- Spécifications USB 2.0
- Centre d'aide pour le matériel Google Meet
- Section "Matériel Google Meet" du Centre d'aide pour les administrateurs Google Workspace
- Script de test des API Video Class Extension Unit du matériel Google Meet
Notes de version
Ces notes de version reflètent les améliorations et les nouvelles fonctionnalités apportées à chaque révision de ce document.
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 pour permettre aux partenaires de valider les mises en œuvre afin de vérifier leur conformité avec cette spécification.
25 mai 2023
Correction de la note GOOGXU_PRESETS concernant le nombre de préréglages. Il devrait s'agir de N, et non de N-1.
17 avril 2023
Version initiale.