Menggunakan perangkat sebagai webcam

Untuk perangkat yang menjalankan Android 14-QPR1 atau yang lebih tinggi, Android mendukung penggunaan perangkat sebagai webcam USB. Perangkat Android yang mendukung fitur ini diiklankan sebagai perangkat UVC, yang memungkinkan berbagai host USB dengan sistem operasi yang berbeda (misalnya, Linux, macOS, Windows, dan ChromeOS) menggunakan kamera perangkat sebagai webcam. Layanan DeviceAsWebcam mendukung fitur ini untuk menggunakan perangkat sebagai webcam.

Layanan DeviceAsWebcam

Layanan DeviceAsWebcam di AOSP mencakup aktivitas pratinjau (DeviceAsWebcamPreview.java) yang memungkinkan pengguna membingkai adegan. Aktivitas pratinjau memungkinkan pengguna melakukan hal berikut:

  • Pratinjau tampilan feed webcam di mesin host sebelum streaming dimulai.

  • Sesuaikan feed webcam yang dikirim ke host dengan cara berikut:

    • Memilih kamera yang akan melakukan streaming, depan atau belakang.
    • Memilih tingkat zoom menggunakan penggeser atau tombol.
    • Mengetuk wilayah tertentu pada pratinjau untuk memfokuskan atau menghapus fokus pada suatu wilayah.

Aktivitas pratinjau berfungsi dengan fitur aksesibilitas umum di Android seperti TalkBack, Tombol Akses, dan Voice Access.

feed webcam yang di-streaming ke host

Gambar 1. Feed webcam yang di-streaming ke host dengan pratinjau yang mengontrol feed.

Arsitektur

Arsitektur untuk mendukung penggunaan perangkat sebagai webcam diilustrasikan dalam Gambar 2. Berikut ini menjelaskan alur interaksi layanan DeviceAsWebcam dengan framework Android lainnya:

  1. Pengguna memilih opsi webcam USB di aplikasi Setelan.
  2. Aplikasi Setelan mengirimkan panggilan binder ke system_server melalui class UsbManager yang memberi tahu bahwa FUNCTION_UVC dipilih.
  3. Server sistem melakukan hal berikut:
    1. Memberi tahu HAL gadget USB untuk mengambil fungsi gadget UVC melalui panggilan antarmuka HAL setUsbFunctions.
    2. Memberi tahu HAL gadget USB untuk mengonfigurasi driver gadget UVC menggunakan ConfigFs.
  4. Setelah menerima callback dari gadget HAL, system_server mengirim siaran ke framework untuk diambil oleh layanan DeviceAsWebcam.
  5. Driver gadget USB memulai streaming webcam setelah menerima perintah konfigurasi dari host melalui node V4L2 di /dev/video*.

arsitektur perangkat sebagai webcam

Gambar 2. Arsitektur DeviceAsWebcam.

Implementasi

Bagian ini menjelaskan cara mendukung penggunaan perangkat Android sebagai webcam.

Dukungan kernel

Untuk Android 14 atau yang lebih tinggi, Generic Kernel Image (GKI) mengaktifkan driver gadget UVC secara default (lihat detailnya di patch AOSP).

Mendukung UVC di Gadget HAL

Mulai Android 14, fungsi UVC disertakan dalam antarmuka HAL GadgetFunction.aidl. Untuk Gadget HAL, gadget UVC dipasang ke ConfigFS dengan cara yang sama seperti fungsi ConfigFS lainnya seperti MTP atau ADB.

Untuk menerapkan Gadget HAL, lakukan modifikasi untuk memasang fungsi UVC ke ConfigFS. Berikut adalah contoh cuplikan penerapan HAL Gadget yang mendukung fungsi 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
       ...
   }
   ...
}

Saat perangkat berfungsi sebagai webcam, pastikan HAL gadget USB mengiklankan kombinasi VID/PID yang tepat.

Karena semua logika UVC ada di vendor init atau di layanan DeviceAsWebcam, tidak ada logika khusus UVC, selain membuat link simbolik fungsi UVC ke ConfigFS, yang diperlukan di Gadget HAL.

Untuk panduan lebih lanjut tentang penerapan, lihat contoh kode berikut di AOSP:

Menyiapkan ConfigFS dengan konfigurasi UVC

Untuk memberi tahu driver gadget UVC format, ukuran, dan kecepatan frame yang didukung oleh webcam Android, siapkan ConfigFS dengan konfigurasi UVC. Untuk mengetahui informasi selengkapnya, lihat dokumentasi Linux upstream tentang ABI gadget UVC ConfigFS.

Berikut adalah contoh cara vendor init dapat menyiapkan driver gadget UVC (cuplikan kode di 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
   # ...

Cuplikan ini menyiapkan driver gadget UVC untuk mengiklankan streaming MJPEG 1080p pada 30 fps. Kemampuan ini dikomunikasikan ke host USB saat host tersebut mengkueri resolusi dan kecepatan frame yang didukung.

Berikut adalah panduan umum untuk memilih konfigurasi yang diiklankan webcam:

  • Dua format streaming yang didukung oleh layanan DeviceAsWebcam adalah MJPEG dan YUYV yang tidak dikompresi.
  • USB 2.0 mendukung transfer data 480 Mbps (60 MBps). Artinya, pada 30 fps, setiap frame harus memiliki ukuran maksimum 2 MB; dan pada 60 fps, ukuran maksimum 1 MB.
    • Streaming yang tidak dikompresi (YUYV): Pada 30 fps, ukuran frame maksimum yang didukung adalah 720p karena YUYV adalah 2 byte per piksel.
    • Streaming MJPEG yang dikompresi: Dengan asumsi rasio kompresi 1:10 dari YUV, USB 2.0 dapat mendukung 4K (1,18 MB per frame).
  • Perangkat kamera depan dan belakang utama harus mendukung semua ukuran frame yang diiklankan. Hal ini karena pengguna dapat beralih di antara ID kamera menggunakan UI pratinjau. Untuk streaming MJPEG, sebaiknya vendor mengiklankan ukuran frame 480p (640 x 480), 720p (1280 x 820), dan 1080p (1920 x 1080) karena ukuran ini umumnya digunakan oleh aplikasi host.
  • Perangkat kamera depan dan belakang utama harus mendukung semua kecepatan frame yang diiklankan. Sebaiknya vendor mendukung 30 fps.

Untuk contoh penambahan konfigurasi streaming webcam (ConfigFS), lihat patch contoh AOSP.

Mengaktifkan webcam di build

Untuk mengaktifkan layanan DeviceAsWebcam, Anda harus menyetel properti sistem ro.usb.uvc.enabled ke true dalam file device.mk.

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

Jika properti sistem ini diaktifkan, opsi Webcam akan muncul di aplikasi Setelan di bagian preferensi USB seperti yang ditunjukkan pada Gambar 3. Jika opsi ini dipilih, perangkat Android akan muncul sebagai webcam USB di perangkat host.

Preferensi USB di aplikasi Setelan

Gambar 3. Preferensi USB di aplikasi Setelan.

Anda juga dapat menyetel perangkat ke fungsi webcam USB melalui ADB menggunakan perintah ini:

adb shell svc usb setFunctions uvc

Pertimbangkan daya dan masalah termal

Pengoperasian webcam berarti kamera perangkat mungkin aktif selama beberapa jam sehari, jadi sebaiknya ambil tindakan untuk memastikan konsumsi daya dan suhu perangkat tetap berada di bawah batas tertentu. Berikut adalah solusi yang direkomendasikan untuk menjaga konsumsi daya di bawah batas:

  • Untuk performa daya yang lebih baik dari HAL kamera, aktifkan STREAM_USE_CASE_VIDEO_CALL di layanan DeviceAsWebcam.

  • Jika daya menjadi masalah meskipun STREAM_USE_CASE_VIDEO_CALL diaktifkan, layanan DeviceAsWebcam menyediakan opsi untuk lebih mengurangi konsumsi daya dengan menggunakan aliran fisik. Anda dapat menggunakan overlay resource runtime (RRO) untuk menentukan kamera fisik yang akan digunakan. Aliran fisik menurunkan kualitas video secara signifikan dan menyebabkan UX yang membingungkan, jadi gunakan solusi ini hanya sebagai upaya terakhir. Mengoptimalkan STREAM_USE_CASE_VIDEO_CALL adalah solusi yang lebih disukai untuk mengatasi masalah daya. Untuk mengetahui informasi selengkapnya tentang RRO yang didukung oleh layanan DeviceAsWebcam, lihat readme.md.

    Berikut adalah contoh RRO yang disiapkan untuk menggunakan ID kamera fisik 3, bukan ID kamera logis 0. Untuk contoh di AOSP, lihat DeviceAsWebcamRaven.

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

Verifikasi

Untuk menguji penerapan layanan DeviceAsWebcam di perangkat Anda, gunakan pengujian berikut:

  • Pengujian verifikasi CTS webcam: Menguji apakah format, ukuran, dan kecepatan frame didukung oleh perangkat.
  • Pengujian manual: Uji bahwa fitur webcam berfungsi dengan berbagai aplikasi host di berbagai sistem operasi host.

Masalah umum

Berikut adalah masalah umum untuk layanan DeviceAsWebcam: