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

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:
  • La plupart des réunions devraient utiliser cette stratégie.
  • Le PTZ est désactivé dans ce mode.

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

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.