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 dispositivi UVC, il che consente a una vasta 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 l'utilizzo del 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'host nei seguenti modi:

    • Selezionare la fotocamera da cui trasmettere in streaming, anteriore o posteriore.
    • Selezionare il livello di zoom utilizzando un cursore o i pulsanti.
    • Toccare una determinata regione dell'anteprima per mettere a fuoco o rimuovere l'attenzione su una regione.

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

Feed della webcam trasmesso in streaming all'host

Figura 1. Il feed della webcam viene trasmesso 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 della webcam USB nell'app Impostazioni.
  2. L'app Impostazioni invia una chiamata al binder a system_server tramite la classe UsbManager per informarlo che FUNCTION_UVC è selezionato.
  3. Il server di sistema esegue le seguenti operazioni:
    1. Informa l'HAL del gadget USB di recuperare la funzione del gadget UVC tramite una chiamata all'interfaccia HAL setUsbFunctions.
    2. Informa l'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 un broadcast al framework per essere rilevato dal servizio DeviceAsWebcam.
  5. Il driver del gadget USB avvia lo stream della webcam quando riceve comandi di configurazione dall'host tramite i nodi V4L2 in /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, l'immagine del kernel generico (GKI) attiva il driver del gadget UVC per impostazione predefinita (vedi i dettagli nella patch AOSP).

Supporto UVC in HAL Gadget

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

Per implementare l'HAL Gadget, apporta modifiche per montare la funzione UVC su ConfigFS. Di seguito è riportato uno snippet di esempio di un'implementazione HAL di Gadget supportante 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 appropriate.

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

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

Configura ConfigFS con le configurazioni UVC

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

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 stream 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 f/s ogni fotogramma deve avere una dimensione massima di 2 MB e a 60 f/s una dimensione massima di 1 MB.
    • Stream non compressi (YUYV): a 30 fps, la dimensione massima supportata del frame è 720p perché YUYV è di 2 byte per pixel.
    • Stream MJPEG compressi: se si assume un rapporto di compressione di 1:10 da YUV, USB 2.0 può supportare 4K (1,18 MB per frame).
  • Le fotocamere anteriori e posteriori 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é sono le dimensioni comunemente utilizzate dalle app host.
  • I dispositivi con fotocamera anteriore e posteriore principali devono supportare tutte le frequenze frame pubblicizzate. Consigliamo vivamente ai fornitori di supportare 30 fps.

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

Attivare la webcam nella compilazione

Per attivare 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 viene visualizzata l'opzione Webcam in Preferenze USB, come mostrato in Figura 3. Se l'opzione è selezionata, il dispositivo Android viene visualizzato come webcam USB sul dispositivo host.

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

Valutare i problemi di potenza e termici

Le operazioni con la webcam comportano che la fotocamera di un dispositivo possa essere accesa per più ore al giorno, pertanto ti consigliamo di adottare misure per assicurarti che il consumo di energia e la temperatura del dispositivo rimangano entro determinati limiti. Di seguito sono riportate le soluzioni consigliate per mantenere il consumo di energia entro i limiti:

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

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

    Di seguito è riportato un esempio di RRO configurato per utilizzare l'ID videocamera fisica 3 instead of l'ID videocamera logico 0. Per un esempio in AOSP, consulta 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 del verifier CTS webcam: verifica che i formati, le dimensioni e le frequenze frame siano supportati dal dispositivo.
  • Test manuali: verifica che la funzionalità della webcam funzioni con una serie di app host su diversi sistemi operativi host.

Problemi noti

Di seguito sono riportati i problemi noti relativi al servizio DeviceAsWebcam: