Utilizzare un dispositivo come webcam

Per i dispositivi con Android 14-QPR1 o versioni successive, Android supporta l'utilizzo del dispositivo come webcam USB. I dispositivi Android che supportano questa funzionalità vengono pubblicizzati come dispositivo UVC, il che consente a un'ampia gamma di host USB con diversi sistemi operativi (ad esempio Linux, macOS, Windows e ChromeOS) di utilizzare la fotocamera del dispositivo come webcam. Il servizio DeviceAsWebcam supporta questa funzionalità per utilizzare il dispositivo come webcam.

Servizio DeviceAsWebcam

Il servizio DeviceAsWebcam in AOSP include un'attività di anteprima (DeviceAsWebcamPreview.java) che consente agli utenti di inquadrare la scena. L'attività di anteprima consente all'utente di:

  • Visualizza l'anteprima dell'aspetto del feed della webcam sulla macchina host prima dell'inizio dello streaming.

  • Personalizza il feed della webcam inviato all'organizzatore nei seguenti modi:

    • Selezionando la videocamera per lo streaming, anteriore o posteriore.
    • Selezionando il livello di zoom utilizzando un cursore o i pulsanti.
    • Toccando una regione specifica dell'anteprima per mettere a fuoco o rimuovere la messa a fuoco su una regione.

L'attività di anteprima funziona con le funzionalità di accessibilità generali su Android, ad esempio TalkBack, Switch Access e Voice Access.

feed della webcam trasmesso in streaming all'host

Figura 1. Feed della webcam in streaming a un host con l'anteprima che controlla il feed.

Architettura

L'architettura per supportare l'utilizzo di un dispositivo come webcam è illustrata nella Figura 2. Di seguito viene descritto il flusso di interazione del servizio DeviceAsWebcam con il resto del framework Android:

  1. L'utente seleziona l'opzione Webcam USB nell'app Impostazioni.
  2. L'app Impostazioni invia una chiamata binder a system_server tramite la classe UsbManager comunicando che FUNCTION_UVC è selezionato.
  3. Il server di sistema esegue le seguenti operazioni:
    1. Comunica all'HAL del gadget USB di recuperare la funzione del gadget UVC tramite una chiamata all'interfaccia HAL setUsbFunctions.
    2. Comunica all'HAL del gadget USB di configurare il driver del gadget UVC utilizzando ConfigFS.
  4. Dopo aver ricevuto un callback dall'HAL del gadget, system_server invia una trasmissione al framework da recuperare dal servizio DeviceAsWebcam.
  5. Il driver del gadget USB avvia lo stream della webcam dopo aver ricevuto i comandi di configurazione dall'host tramite i nodi V4L2 all'indirizzo /dev/video*.

architettura del dispositivo come webcam

Figura 2. Architettura DeviceAsWebcam.

Implementazione

Questa sezione descrive come supportare l'utilizzo di un dispositivo Android come webcam.

Supporto del kernel

Per Android 14 o versioni successive, la Generic Kernel Image (GKI) attiva il driver del gadget UVC per impostazione predefinita (vedi i dettagli nella patch AOSP).

Supportare UVC in Gadget HAL

A partire da Android 14, la funzione UVC è inclusa nell'interfaccia HAL GadgetFunction.aidl. Per l'HAL gadget, il gadget UVC viene montato su ConfigFS nello stesso modo delle altre funzioni ConfigFS, come MTP o ADB.

Per implementare l'HAL del gadget, modifica il montaggio della funzione UVC in ConfigFS. Di seguito è riportato un esempio di snippet di un'implementazione di Gadget HAL che supporta la funzione 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
       ...
   }
   ...
}

Quando il dispositivo funge da webcam, assicurati che l'HAL del gadget USB pubblicizzi le combinazioni VID/PID corrette.

Poiché tutta la logica UVC si trova nell'inizializzazione del fornitore o nel servizio DeviceAsWebcam, non è necessaria alcuna logica specifica UVC, ad eccezione del collegamento simbolico della funzione UVC a ConfigFS, nella HAL del gadget.

Per ulteriori indicazioni sull'implementazione, consulta il seguente esempio di codice in AOSP:

Configurare ConfigFS con le configurazioni UVC

Per comunicare al driver del gadget UVC quali formati, dimensioni e frame rate sono supportati dalla webcam Android, configura ConfigFS con le configurazioni UVC. Per maggiori informazioni, consulta la documentazione Linux upstream sull'ABI del gadget ConfigFS UVC.

Di seguito è riportato un esempio di come l'inizializzazione del fornitore può configurare il driver del gadget UVC (snippet di codice in 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
   # ...

Questo snippet configura il driver del gadget UVC per pubblicizzare uno stream MJPEG a 1080p a 30 fps. Queste funzionalità vengono comunicate all'host USB quando esegue query su risoluzioni e frame rate supportati.

Di seguito sono riportate le linee guida generali per la selezione delle configurazioni pubblicizzate dalla webcam:

  • I due formati di streaming supportati dal servizio DeviceAsWebcam sono MJPEG e YUYV non compresso.
  • USB 2.0 supporta il trasferimento di dati a 480 Mbps (60 MBps). Ciò significa che a 30 fps ogni fotogramma deve avere una dimensione massima di 2 MB; e a 60 fps, una dimensione massima di 1 MB.
    • Stream non compressi (YUYV): a 30 fps, la dimensione massima del frame supportata è 720p perché YUYV è 2 byte per pixel.
    • Stream MJPEG compressi: supponendo un rapporto di compressione di 1:10 da YUV, USB 2.0 può supportare 4K (1,18 MB per frame).
  • I dispositivi con fotocamera anteriore e posteriore principali devono supportare tutte le dimensioni dei frame pubblicizzate. Questo perché l'utente può passare da un ID videocamera all'altro utilizzando l'interfaccia utente di anteprima. Per gli stream MJPEG, consigliamo ai fornitori di pubblicizzare dimensioni dei frame di 480p (640 x 480), 720p (1280 x 820) e 1080p (1920 x 1080) perché queste sono dimensioni comunemente utilizzate dalle app host.
  • I dispositivi con fotocamera anteriore e posteriore principale devono supportare tutti i frame rate pubblicizzati. Consigliamo vivamente ai fornitori di supportare 30 fps.

Per un esempio di aggiunta di configurazioni di stream della webcam (ConfigFS), vedi Patch di esempio AOSP.

Attiva la webcam nella build

Per abilitare il servizio DeviceAsWebcam, devi impostare la proprietà di sistema ro.usb.uvc.enabled su true nel file device.mk.

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

Quando questa proprietà di sistema è attivata, nell'app Impostazioni, in Preferenze USB, viene visualizzata l'opzione Webcam, come mostrato nella Figura 3. Quando l'opzione è selezionata, il dispositivo Android viene visualizzato come webcam USB sul dispositivo host.

Preferenze USB nell'app Impostazioni

Figura 3. Preferenze USB nell'app Impostazioni.

Puoi anche impostare il dispositivo sulla funzione webcam USB tramite ADB utilizzando questo comando:

adb shell svc usb setFunctions uvc

Considera i problemi di alimentazione e termici

Le operazioni della webcam comportano l'accensione della videocamera di un dispositivo per diverse ore al giorno, pertanto ti consigliamo di adottare misure per garantire che il consumo energetico e la temperatura del dispositivo rimangano entro determinati limiti. Di seguito sono riportate le soluzioni consigliate per mantenere il consumo energetico entro i limiti:

  • Per prestazioni migliori della fotocamera HAL, attiva STREAM_USE_CASE_VIDEO_CALL nel servizio DeviceAsWebcam.

  • Se il consumo energetico è un problema anche con STREAM_USE_CASE_VIDEO_CALL attivato, il servizio DeviceAsWebcam offre un'opzione per ridurre ulteriormente il consumo energetico utilizzando gli stream fisici. Puoi utilizzare overlay delle risorse di runtime (RRO) per specificare quale videocamera fisica utilizzare. Gli stream fisici riducono significativamente la qualità video e portano a un'esperienza utente confusa, quindi utilizza questa soluzione solo come ultima risorsa. L'ottimizzazione STREAM_USE_CASE_VIDEO_CALL è la soluzione preferita per i problemi di alimentazione. Per ulteriori informazioni sugli overlay di risorse supportati dal servizio DeviceAsWebcam, consulta readme.md.

    Di seguito è riportato un esempio di RRO configurato per utilizzare l'ID fotocamera fisica 3 anziché l'ID fotocamera logica 0. Per un esempio in AOSP, vedi DeviceAsWebcamRaven.

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

Verifica

Per testare l'implementazione del servizio DeviceAsWebcam sul tuo dispositivo, utilizza i seguenti test:

  • Test di verifica CTS webcam: verifica che formati, dimensioni e frame rate siano supportati dal dispositivo.
  • Test manuali: verifica che la funzionalità della webcam funzioni con una serie di app host su una serie di sistemi operativi host.

Problemi noti

Di seguito sono riportati i problemi noti del servizio DeviceAsWebcam: