Gerät als Webcam verwenden

Auf Geräten mit Android 14-QPR1 oder höher unterstützt Android die Verwendung des Geräts als USB-Webcam. Android-Geräte, die diese Funktion unterstützen, werden als UVC-Gerät angezeigt. So können eine Vielzahl von USB-Hosts mit verschiedenen Betriebssystemen (z. B. Linux, macOS, Windows und ChromeOS) die Kamera des Geräts als Webcam verwenden. Der Dienst DeviceAsWebcam unterstützt diese Funktion, um das Gerät als Webcam zu verwenden.

DeviceAsWebcam-Dienst

Der DeviceAsWebcam-Dienst in AOSP enthält eine Vorschauaktivität (DeviceAsWebcamPreview.java), mit der Nutzer die Szene in Frames darstellen können. Mit der Vorschauaktivität können Nutzer Folgendes tun:

  • Sie können sich eine Vorschau des Webcam-Feeds auf dem Hostcomputer ansehen, bevor das Streaming beginnt.

  • Sie können den an den Host gesendeten Webcam-Feed auf folgende Weise anpassen:

    • Die Auswahl der zu streamenden Kamera (Vorder- oder Rückansicht)
    • Auswählen der Zoomstufe mithilfe eines Schiebereglers oder mithilfe von Schaltflächen.
    • Tippen Sie auf einen bestimmten Bereich in der Vorschau, um den Fokus darauf zu verschieben oder ihn zu entfernen.

Die Vorschauaktivität funktioniert mit allgemeinen Bedienungshilfen unter Android wie TalkBack, Schalterzugriff und Voice Access.

Webcam-Feed wird an den Host gestreamt

Abbildung 1. Der Webcam-Feed wird an einen Host gestreamt, dessen Feed von der Vorschau gesteuert wird.

Architektur

Die Architektur zur Unterstützung der Verwendung eines Geräts als Webcam ist in Abbildung 2 dargestellt. Im Folgenden wird der Interaktionsablauf des DeviceAsWebcam-Dienstes mit dem Rest des Android-Frameworks beschrieben:

  1. Der Nutzer wählt in den Einstellungen die Option „USB-Webcam“ aus.
  2. Die Einstellungen-App sendet über die Klasse UsbManager einen Binderaufruf an system_server, um ihn darüber zu informieren, dass FUNCTION_UVC ausgewählt ist.
  3. Der Systemserver führt Folgendes aus:
    1. Informiert die USB-Gadget-HAL, die UVC-Gadget-Funktion über einen setUsbFunctions-HAL-Interface-Aufruf abzurufen.
    2. Informiert den USB-Gadget-HAL, den UVC-Gadget-Treiber mit ConfigFs zu konfigurieren.
  4. Wenn system_server einen Rückruf von der Gadget-HAL erhält, sendet es einen Broadcast an das Framework, der vom DeviceAsWebcam-Dienst abgerufen wird.
  5. Der USB-Gadget-Treiber startet den Webcam-Stream, wenn er Konfigurationsbefehle vom Host über V4L2-Knoten unter /dev/video* empfängt.

Architektur „Gerät als Webcam“

Abbildung 2. DeviceAsWebcam-Architektur

Implementierung

In diesem Abschnitt wird beschrieben, wie Sie die Verwendung eines Android-Geräts als Webcam unterstützen.

Kernel-Unterstützung

Unter Android 14 oder höher aktiviert das generische Kernel-Image (GKI) standardmäßig den UVC-Gadget-Treiber (Details finden Sie im AOSP-Patch).

UVC in Gadget HAL unterstützen

Ab Android 14 ist die UVC-Funktion in der HAL-Schnittstelle GadgetFunction.aidl enthalten. Bei der Gadget-HAL wird das UVC-Gadget auf die gleiche Weise wie andere ConfigFS-Funktionen wie MTP oder ADB auf ConfigFS bereitgestellt.

Um die Gadget HAL zu implementieren, müssen Sie die UVC-Funktion in ConfigFS bereitstellen. Im Folgenden finden Sie ein Beispiel für ein Snippet einer Gadget HAL-Implementierung, die die UVC-Funktion unterstützt:

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
       ...
   }
   ...
}

Wenn das Gerät als Webcam verwendet wird, muss die HAL des USB-Gadgets die richtigen VID/PID-Kombinationen angeben.

Da sich die gesamte UVC-Logik entweder in der Anbieterinitialisierung oder im DeviceAsWebcam-Dienst befindet, ist in der Gadget HAL keine UVC-spezifische Logik erforderlich, mit Ausnahme eines Symlinks zur UVC-Funktion in ConfigFS.

Weitere Anleitungen zur Implementierung finden Sie im folgenden Beispielcode in AOSP:

ConfigFS mit UVC-Konfigurationen einrichten

Richten Sie ConfigFS mit UVC-Konfigurationen ein, um dem UVC-Gadget-Treiber mitzuteilen, welche Formate, Größen und Frameraten von der Android-Webcam unterstützt werden. Weitere Informationen finden Sie in der Upstream-Linux-Dokumentation zum ConfigFS UVC-Gadget ABI.

Im folgenden Beispiel wird gezeigt, wie der UVC-Gadget-Treiber über die Anbieter-Init-Funktion eingerichtet werden kann (Code-Snippet 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
   # ...

In diesem Snippet wird der UVC-Gadget-Treiber so eingerichtet, dass ein 1080p-MJPEG-Stream mit 30 fps beworben wird. Diese Funktionen werden an den USB-Host gesendet, wenn er unterstützte Auflösungen und Frameraten abfragt.

Im Folgenden finden Sie allgemeine Richtlinien für die Auswahl der Konfigurationen, die von der Webcam angeboten werden:

  • Die beiden vom DeviceAsWebcam-Dienst unterstützten Streamformate sind MJPEG und unkomprimiertes YUYV.
  • USB 2.0 unterstützt eine Datenübertragungsgeschwindigkeit von 480 Mbit/s (60 MB/s). Das bedeutet, dass bei 30 fps jeder Frame eine maximale Größe von 2 MB und bei 60 fps eine maximale Größe von 1 MB haben muss.
    • Unkomprimierte Streams (YUYV): Bei 30 fps ist die maximal unterstützte Framegröße 720p, da YUYV 2 Byte pro Pixel hat.
    • Komprimierte MJPEG-Streams: Bei einem Komprimierungsverhältnis von 1:10 von YUV kann USB 2.0 4K (1,18 MB pro Frame) unterstützen.
  • Die primäre Front- und Rückkamera müssen alle beworbenen Frame-Größen unterstützen. Das liegt daran, dass der Nutzer über die Benutzeroberfläche der Vorschau zwischen den Kamera-IDs wechseln kann. Für MJPEG-Streams empfehlen wir Anbietern, die Framegrößen 480p (640 × 480), 720p (1280 × 820) und 1080p (1920 × 1080) anzugeben, da diese Größen häufig von Host-Apps verwendet werden.
  • Die primäre Front- und Rückkamera müssen alle angegebenen Bildraten unterstützen. Wir empfehlen Anbietern dringend, 30 fps zu unterstützen.

Ein Beispiel für das Hinzufügen von Webcam-Streamkonfigurationen (ConfigFS) findest du unter AOSP-Beispielpatch.

Webcam im Build aktivieren

Wenn Sie den DeviceAsWebcam-Dienst aktivieren möchten, müssen Sie in der Datei device.mk die Systemeigenschaft ro.usb.uvc.enabled auf true festlegen.

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

Wenn diese Systemeigenschaft aktiviert ist, wird in der App „Einstellungen“ unter „USB-Einstellungen“ die Option Webcam angezeigt (siehe Abbildung 3). Wenn die Option ausgewählt ist, wird das Android-Gerät für das Hostgerät als USB-Webcam angezeigt.

Abbildung 3: USB-Einstellungen in den Einstellungen

Sie können das Gerät auch über ADB mit diesem Befehl auf die USB-Webcamfunktion umstellen:

adb shell svc usb setFunctions uvc

Leistungs- und Wärmeaspekte berücksichtigen

Wenn die Webcam aktiviert ist, kann die Kamera eines Geräts mehrere Stunden am Tag eingeschaltet sein. Wir empfehlen daher, Maßnahmen zu ergreifen, damit die Stromaufnahme und die Temperatur des Geräts unter bestimmten Grenzwerten bleiben. Im Folgenden finden Sie empfohlene Lösungen, um den Stromverbrauch unter den Grenzwerten zu halten:

  • Aktivieren Sie für eine bessere Energieeffizienz der Kamera-HAL STREAM_USE_CASE_VIDEO_CALL im Dienst DeviceAsWebcam.

  • Wenn der Stromverbrauch auch bei aktiviertem STREAM_USE_CASE_VIDEO_CALL ein Problem darstellt, bietet der DeviceAsWebcam-Dienst die Möglichkeit, den Stromverbrauch durch die Verwendung physischer Streams weiter zu senken. Mit Laufzeit-Ressourcen-Overlays (RROs) können Sie angeben, welche physische Kamera verwendet werden soll. Physische Streams beeinträchtigen die Videoqualität erheblich und führen zu einer verwirrenden Nutzererfahrung. Verwenden Sie diese Lösung daher nur als letzten Ausweg. Die Optimierung von STREAM_USE_CASE_VIDEO_CALL ist die bevorzugte Lösung für Probleme mit der Stromversorgung. Weitere Informationen zu RROs, die vom DeviceAsWebcam-Dienst unterstützt werden, finden Sie in der readme.md.

    Im Folgenden finden Sie ein Beispiel für eine RRO, die so eingerichtet ist, dass die physische Kamera-ID 3 anstelle der logischen Kamera-ID 0 verwendet wird. Ein Beispiel in AOSP finden Sie unter DeviceAsWebcamRaven.

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

Bestätigung

Mit den folgenden Tests kannst du die Implementierung des Dienstes DeviceAsWebcam auf deinem Gerät testen:

  • CTS-Verifier-Test Webcam: Prüfen, ob Formate, Größen und Bildraten vom Gerät unterstützt werden.
  • Manuelle Tests: Testen Sie, ob die Webcam-Funktion mit verschiedenen Host-Apps auf verschiedenen Host-Betriebssystemen funktioniert.

Bekannte Probleme

Die folgenden Probleme sind für den DeviceAsWebcam-Dienst bekannt: