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à sono pubblicizzati come dispositivi UMC, che consentono a un'ampia gamma di host USB con diversi sistemi operativi (ad es. Linux, macOS, Windows e ChromeOS) di utilizzare la videocamera 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:

• Prima di avviare lo streaming, visualizza l'anteprima del feed della webcam sulla macchina host.

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

  • Selezione della videocamera per lo streaming, anteriore o posteriore.
  • Selezione del livello di zoom utilizzando un dispositivo di scorrimento o i pulsanti.
  • Toccare una particolare area dell'anteprima per impostare lo stato attivo su una regione o rimuoverla.

L'attività di anteprima è compatibile con le funzioni di accessibilità generali su Android, come TalkBack, Switch Access e Voice Access.

Figura 1. Il feed della webcam viene trasmesso a un host con un'anteprima che controlla il feed.

Architettura

L'architettura da supportare per 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 a Raccoglitore a system_server tramite il corso UsbManager per informarlo che è selezionato FUNCTION_UVC.
3. Il server di sistema effettua le seguenti operazioni:
   1. Informa l'HAL del gadget USB per recuperare la funzione del gadget UVC tramite una chiamata all'interfaccia dell'HAL setUsbFunctions.
   2. Informa l'HAL per il gadget USB di configurare il driver del gadget UVC utilizzando ConfigF.
4. Dopo aver ricevuto una richiamata dal gadget HAL, system_server invia una trasmissione al framework per essere prelevata dal servizio DeviceAsWebcam.
5. Il driver del gadget USB avvia il flusso della webcam dopo aver ricevuto i comandi di configurazione dall'host attraverso i nodi V4L2 all'indirizzo /dev/video*.

Figura 2. Architettura di DeviceAsWebcam.

Implementazione

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

Supporto kernel

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

Attenzione: a febbraio 2024, il driver del gadget UVC ha riscontrato alcuni problemi critici di stabilità. Le correzioni (AOSP Gerrit) sono state eseguite upstream e sono disponibili in tutti i rami di sviluppo GKI. Se la tua release specifica non presenta le correzioni, richiedi un respin con le modifiche selezionate.

Supporta UVC in Gadget HAL

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

Per implementare il gadget HAL, apporta modifiche per montare la 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 nel servizio init del fornitore o nel servizio DeviceAsWebcam, nell'HAL del gadget non è richiesta alcuna logica specifica per UVC, a parte il collegamento simbolico della funzione UVC a ConfigFS.

Per ulteriori indicazioni sull'implementazione, vedi il seguente codice campione in AOSP:

• Aggiungi il supporto della funzione UVC
• USBGadget: aggiunta del supporto per la funzione UVC

Imposta ConfigFS con configurazioni UVC

Per comunicare al driver del gadget UVC i formati, le dimensioni e le frequenze fotogrammi supportati dalla webcam Android, configura ConfigFS con configurazioni UVC. Per ulteriori informazioni, consulta la documentazione di Linux upstream nell'ABI del gadget UVC ConfigFS.

Di seguito è riportato un esempio di come init 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 in modo da pubblicizzare uno stream MJPEG a 1080p a 30 f/s. Queste funzionalità vengono comunicate all'host USB quando esegue query su risoluzioni e frequenze fotogrammi supportate.

Di seguito sono riportate le linee guida generali per la scelta 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 frame deve avere una dimensione massima di 2 MB, mentre a 60 f/s, una dimensione massima di 1 MB.
  • Stream non compressi (YUYV): a 30 f/s, la dimensione massima dei fotogrammi supportata è 720p, perché gli errori YUYV sono di 2 byte per pixel.
  • Stream MJPEG compressi: con un rapporto di compressione 1:10 di YUV, USB 2.0 può supportare 4K (1,18 MB per frame).
• Le fotocamere principali e posteriori devono supportare tutte le dimensioni dei fotogrammi annunciate. Questo perché l'utente può passare da un ID fotocamera all'altro utilizzando l'interfaccia utente di anteprima. Per gli stream MJPEG, consigliamo ai fornitori di pubblicizzare le dimensioni 480p (640 x 480), 720p (1280 x 820) e 1080p (1920 x 1080) perché si tratta di dimensioni comunemente utilizzate dalle app host.
• I dispositivi principali delle fotocamere anteriore e posteriore devono supportare tutte le frequenze fotogrammi pubblicizzate. Consigliamo vivamente ai fornitori di supportare la velocità a 30 f/s.

Per un esempio di aggiunta di configurazioni di flussi di webcam (ConfigFS), consulta la patch di esempio AOSP.

Attiva la webcam nella build

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, nella sezione Preferenze USB, come mostrato nella Figura 3. Quando questa opzione è selezionata, il dispositivo Android viene visualizzato come webcam USB per il 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

Considerare i problemi di alimentazione e termica

Quando si utilizza la webcam, la fotocamera di un dispositivo potrebbe essere accesa per più ore al giorno, quindi consigliamo di adottare misure per garantire che il consumo energetico e la temperatura del dispositivo rimangano al di sotto di determinati limiti. Di seguito sono riportate le soluzioni consigliate per mantenere il consumo energetico entro i limiti:

• Per migliorare le prestazioni di alimentazione dell'HAL della videocamera, abilita STREAM_USE_CASE_VIDEO_CALL nel servizio DeviceAsWebcam.

• Se l'alimentazione è un problema anche con STREAM_USE_CASE_VIDEO_CALL abilitato, il servizio DeviceAsWebcam offre un'opzione per ridurre ulteriormente il consumo di energia utilizzando stream fisici. Puoi utilizzare gli overlay delle risorse di runtime per specificare la videocamera fisica da utilizzare. Gli stream fisici riducono notevolmente la qualità video e portano a un'esperienza utente confusa, quindi usa questa soluzione solo come ultima risorsa. L'ottimizzazione di STREAM_USE_CASE_VIDEO_CALL è la soluzione migliore per le preoccupazioni. Per ulteriori informazioni sugli RRO supportati dal servizio DeviceAsWebcam, consulta readme.md.

  Di seguito è riportato un esempio di configurazione RRO che utilizza 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, esegui i seguenti test:

• Test della webcam dello strumento di verifica CTS: verifica che formati, dimensioni e frequenze fotogrammi siano supportati dal dispositivo.
• Test manuali: verifica che la funzionalità della webcam funzioni con varie app host su vari sistemi operativi host.

Problemi noti

Di seguito sono riportati i problemi noti del servizio DeviceAsWebcam:

• Lo stream del driver del gadget UVC a volte sfarfalla e mostra frame danneggiati. Questo problema è stato risolto e unito upstream e in GKI.

  • Correzioni upstream:

    • Mettere in coda richieste ISOC vuote se non è disponibile nessun buffer video
    • Non utilizzare il thread worker per eseguire il pompaggio delle richieste USB

  • Patch GKI

• I dispositivi Android in modalità webcam non funzionano con cavi USB 3.0 o versioni successive su host macOS a causa di un bug con il driver UVC di Apple.