Utiliser un appareil comme webcam

Pour les appareils équipés d'Android 14-QPR1 ou version ultérieure, Android permet d'utiliser l'appareil comme webcam USB. Les appareils Android compatibles avec cette fonctionnalité sont annoncés en tant que appareil UVC, ce qui permet à un large éventail d'hôtes USB avec différents systèmes d'exploitation (Linux, macOS, Windows et ChromeOS, par exemple) d'utiliser la caméra de l'appareil comme webcam. Le service DeviceAsWebcam est compatible avec cette fonctionnalité pour utiliser l'appareil comme webcam.

Service DeviceAsWebcam

Le service DeviceAsWebcam dans AOSP inclut une activité d'aperçu (DeviceAsWebcamPreview.java) qui permet aux utilisateurs de cadrer la scène. L'activité d'aperçu permet à l'utilisateur d'effectuer les opérations suivantes:

  • Aperçu de l'apparence du flux de la webcam sur la machine hôte avant le début de la diffusion

  • Personnalisez le flux de webcam envoyé à l'hôte de la manière suivante:

    • Sélection de la caméra à diffuser, avant ou arrière.
    • Sélectionner le niveau de zoom à l'aide d'un curseur ou de boutons
    • Appuyer sur une région spécifique de l'aperçu pour mettre au point ou supprimer la mise au point sur une région.

L'activité d'aperçu fonctionne avec les fonctionnalités d'accessibilité générales sur Android, telles que TalkBack, Switch Access et Voice Access.

Flux de webcam diffusé sur l'hôte

Figure 1 : Flux de webcam diffusé vers un hôte avec un aperçu qui contrôle le flux.

Architecture

L'architecture permettant d'utiliser un appareil en tant que webcam est illustrée dans la figure 2. Ce qui suit décrit le flux d'interaction du service DeviceAsWebcam avec le reste du framework Android:

  1. L'utilisateur sélectionne l'option de webcam USB dans l'application Paramètres.
  2. L'application Paramètres envoie un appel de liaison à system_server via la classe UsbManager pour l'informer que FUNCTION_UVC est sélectionné.
  3. Le serveur système effectue les opérations suivantes :
    1. Informe le HAL du gadget USB de récupérer la fonction du gadget UVC via un appel d'interface HAL setUsbFunctions.
    2. Informe le HAL du gadget USB de configurer le pilote du gadget UVC à l'aide de ConfigFs.
  4. À la réception d'un rappel de la HAL du gadget, system_server envoie une diffusion au framework pour être récupérée par le service DeviceAsWebcam.
  5. Le pilote du gadget USB démarre le flux de la webcam lorsqu'il reçoit des commandes de configuration de l'hôte via des nœuds V4L2 à /dev/video*.

Architecture de l'appareil en tant que webcam

Figure 2. Architecture DeviceAsWebcam.

Implémentation

Cette section explique comment utiliser un appareil Android comme webcam.

Prise en charge du noyau

Pour Android 14 ou version ultérieure, l'image du noyau générique (GKI) active le pilote de gadget UVC par défaut (voir les détails dans le correctif AOSP).

Prise en charge de l'UVC dans le HAL Gadget

À partir d'Android 14, la fonction UVC est incluse dans l'interface HAL GadgetFunction.aidl. Pour le HAL Gadget, le gadget UVC est installé sur ConfigFS de la même manière que les autres fonctions ConfigFS telles que MTP ou ADB.

Pour implémenter le HAL Gadget, apportez des modifications pour monter la fonction UVC sur ConfigFS. Voici un exemple d'extrait d'implémentation de HAL Gadget compatible avec la fonction UVC:

UsbGadget::setCurrentUsbFunctions(long functions) {
   ...
   // Existing functions
   if ((functions & GadgetFunction::MTP) != 0) {
       ...
       linkFunction("ffs.mtp"); // Mount to ConfigFS
       ...
   }
   ...
   // UVC function follows the same pattern!
   if ((functions & GadgetFunction::UVC) != 0) {
       ...
       linkFunction("uvc.0"); // Mount to ConfigFS
       ...
   }
   ...
}

Lorsque l'appareil joue le rôle de webcam, assurez-vous que le HAL du gadget USB annonce les combinaisons VID/PID appropriées.

Étant donné que toute la logique UVC se trouve dans l'initialisation du fournisseur ou dans le service DeviceAsWebcam, aucune logique spécifique à l'UVC, à l'exception d'un lien symbolique de la fonction UVC vers ConfigFS, n'est requise dans le HAL du gadget.

Pour obtenir des conseils sur l'implémentation, consultez l'exemple de code suivant dans AOSP:

Configurer ConfigFS avec des configurations UVC

Pour indiquer au pilote du gadget UVC les formats, tailles et fréquences d'images compatibles avec la webcam Android, configurez ConfigFS avec des configurations UVC. Pour en savoir plus, consultez la documentation Linux en amont sur l'ABI du gadget UVC ConfigFS.

Vous trouverez ci-dessous un exemple de configuration du pilote de gadget UVC par l'init du fournisseur (extrait de code dans AOSP):

# uvc function
   mkdir /configfs_path/functions/uvc.0
   write /configfs_path/functions/uvc.0/function_name "Android Webcam"
   write /configfs_path/functions/uvc.0/streaming_maxpacket 3072
   # setup control params
   mkdir /configfs_path/functions/uvc.0/control/header/h
   symlink /configfs_path/functions/uvc.0/control/header/h \
                /configfs_path/functions/uvc.0/control/class/fs/h
   symlink /configfs_path/functions/uvc.0/control/header/h \
                /configfs_path/functions/uvc.0/control/class/ss/h
   # advertise 1080p resolution for webcam encoded as mjpeg
   mkdir /configfs_path/functions/uvc.0/streaming/mjpeg/m/1080p
   write /configfs_path/functions/uvc.0/streaming/mjpeg/m/1080p/wHeight 1080
   write /configfs_path/functions/uvc.0/streaming/mjpeg/m/1080p/wWidth 1920
   write /configfs_path/functions/uvc.0/streaming/mjpeg/m/1080p/dwMaxVideoFrameBufferSize 4147200
   # advertise 30 fps support for 1080p.
   write /configfs_path/functions/uvc.0/streaming/mjpeg/m/1080p/dwDefaultFrameInterval 333333
   write /configfs_path/functions/uvc.0/streaming/mjpeg/m/1080p/dwFrameInterval "333333"
   # setup streaming params
   mkdir /configfs_path/functions/uvc.0/streaming/header/h
   symlink /configfs_path/functions/uvc.0/streaming/mjpeg/m \
                /configfs_path/functions/uvc.0/streaming/header/h/m
   symlink /configfs_path/functions/uvc.0/streaming/header/h \
                /configfs_path/functions/uvc.0/streaming/class/fs/h
   symlink /configfs_path/functions/uvc.0/streaming/header/h \
                /configfs_path/functions/uvc.0/streaming/class/hs/h
   symlink /configfs_path/functions/uvc.0/streaming/header/h \
                /config/usb_gadget/g1/functions/uvc.0/streaming/class/ss/h
   # ...

Cet extrait configure le pilote du gadget UVC pour annoncer un flux MJPEG 1080p à 30 FPS. Ces fonctionnalités sont communiquées à l'hôte USB lorsqu'il interroge les résolutions et les fréquences d'images compatibles.

Voici quelques consignes générales pour sélectionner les configurations que la webcam annonce:

  • Les deux formats de flux compatibles avec le service DeviceAsWebcam sont MJPEG et YUYV non compressé.
  • L'USB 2.0 accepte le transfert de données à 480 Mbit/s (60 Mo/s). Cela signifie qu'à 30 ips, chaque frame doit avoir une taille maximale de 2 Mo et à 60 ips, une taille maximale de 1 Mo.
    • Flux non compressés (YUYV): à 30 images par seconde, la taille de frame maximale prise en charge est de 720p, car YUYV est de 2 octets par pixel.
    • Flux MJPEG compressés: en supposant un taux de compression de 1:10 à partir de YUV, USB 2.0 est compatible avec la 4K (1,18 Mo par frame).
  • Les appareils photo avant et arrière principaux doivent être compatibles avec toutes les tailles de cadre annoncées. En effet, l'utilisateur peut basculer entre les ID de caméra à l'aide de l'UI d'aperçu. Pour les flux MJPEG, nous recommandons aux fournisseurs de diffuser les tailles de frame 480p (640 x 480), 720p (1 280 x 820) et 1080p (1 920 x 1 080), car elles sont couramment utilisées par les applications hôtes.
  • Les appareils photo avant et arrière principaux doivent être compatibles avec toutes les fréquences d'images annoncées. Nous recommandons vivement aux fournisseurs de prendre en charge les 30 FPS.

Pour obtenir un exemple d'ajout de configurations de flux de webcam (ConfigFS), consultez l'exemple de correctif AOSP.

Activer la webcam dans le build

Pour activer le service DeviceAsWebcam, vous devez définir la propriété système ro.usb.uvc.enabled sur true dans le fichier device.mk.

# Enable UVC support
PRODUCT_VENDOR_PROPERTIES += \
    ro.usb.uvc.enabled=true

Lorsque cette propriété système est activée, une option Webcam s'affiche dans l'application Paramètres sous "Préférences USB", comme illustré dans la figure 3. Lorsque cette option est sélectionnée, l'appareil Android apparaît comme une webcam USB pour l'appareil hôte.

Figure 3. Préférences USB dans l'application Paramètres.

Vous pouvez également définir la fonction de webcam USB sur l'appareil via ADB à l'aide de la commande suivante:

adb shell svc usb setFunctions uvc

Tenir compte des problèmes d'alimentation et de température

Les opérations de webcam signifient que la caméra d'un appareil peut être allumée plusieurs heures par jour. Nous vous recommandons donc de prendre des mesures pour vous assurer que la consommation d'énergie et la température de l'appareil restent dans certaines limites. Vous trouverez ci-dessous des solutions recommandées pour limiter la consommation d'énergie:

  • Pour de meilleures performances énergétiques de la couche HAL de l'appareil photo, activez STREAM_USE_CASE_VIDEO_CALL dans le service DeviceAsWebcam.

  • Si l'alimentation pose problème même lorsque STREAM_USE_CASE_VIDEO_CALL est activé, le service DeviceAsWebcam offre une option permettant de réduire davantage la consommation d'énergie en utilisant des flux physiques. Vous pouvez utiliser des superpositions de ressources d'exécution (RRO) pour spécifier la caméra physique à utiliser. Les flux physiques réduisent considérablement la qualité vidéo et entraînent une expérience utilisateur confuse. N'utilisez cette solution qu'en dernier recours. L'optimisation de STREAM_USE_CASE_VIDEO_CALL est la solution privilégiée pour les problèmes d'alimentation. Pour en savoir plus sur les RRO compatibles avec le service DeviceAsWebcam, consultez readme.md.

    Vous trouverez ci-dessous un exemple de RRO configuré pour utiliser l'ID de caméra physique 3 au lieu de l'ID de caméra logique 0. Pour obtenir un exemple dans AOSP, consultez DeviceAsWebcamRaven.

    // For logical camera id 0 - use physical camera id 3
{"0": {"3" : "UW"}}

Validation

Pour tester votre implémentation du service DeviceAsWebcam sur votre appareil, utilisez les tests suivants:

  • Test de vérification CTS de la webcam: vérifiez que les formats, les tailles et les fréquences d'images sont compatibles avec l'appareil.
  • Tests manuels: vérifiez que la fonctionnalité de webcam fonctionne avec différentes applications hôtes sur différents systèmes d'exploitation hôtes.

Problèmes connus

Voici les problèmes connus du service DeviceAsWebcam: