將裝置當做網路攝影機使用

如果裝置搭載 Android 14-QPR1 以上版本，Android 支援將裝置當做 USB 網路攝影機使用。支援這項功能的 Android 裝置會宣傳為 UVC 裝置，讓各種作業系統 (例如 Linux、macOS、Windows 和 ChromeOS) 的 USB 主機都能將裝置的相機當做網路攝影機使用。DeviceAsWebcam 服務支援這項功能，可將裝置當做網路攝影機使用。

DeviceAsWebcam 服務

AOSP 中的 DeviceAsWebcam 服務包含預覽活動 (DeviceAsWebcamPreview.java)，可讓使用者構圖。使用者可透過預覽活動執行下列操作：

  • 開始串流前，先預覽網路攝影機畫面在主機上的顯示效果。

  • 你可以透過下列方式自訂傳送給主辦人的網路攝影機動態饋給：

    • 選取要串流播放的攝影機 (前置或後置)。
    • 使用滑桿或按鈕選取縮放等級。
    • 輕觸預覽畫面中的特定區域，即可對焦或移除區域焦點。

預覽活動可與 Android 上的一般無障礙功能搭配使用，例如 TalkBack、切換控制功能和語音存取。

網路攝影機畫面串流至主辦人

圖 1. 網路攝影機畫面串流至主辦人，並透過預覽畫面控制畫面。

建築

圖 2 說明瞭支援將裝置當做網路攝影機使用的架構。以下說明 DeviceAsWebcam 服務與 Android 架構其餘部分的互動流程：

  1. 使用者在「設定」應用程式中選取 USB 網路攝影機選項。
  2. 「設定」應用程式會透過 UsbManager 類別將繫結器呼叫傳送至 system_server，通知 FUNCTION_UVC 已選取。
  3. 系統伺服器會執行下列動作：
    1. 通知 USB 裝置 HAL 透過 setUsbFunctions HAL 介面呼叫擷取 UVC 裝置函式。
    2. 通知 USB 小工具 HAL 使用 ConfigFs 設定 UVC 小工具驅動程式。
  4. 收到小工具 HAL 的回呼後，system_server 會將廣播傳送至架構，供 DeviceAsWebcam 服務接收。
  5. USB 小工具驅動程式會在 /dev/video* 透過 V4L2 節點收到主機的設定指令時，啟動網路攝影機串流。

裝置做為網路攝影機的架構

圖 2. DeviceAsWebcam 架構。

實作

本節說明如何支援將 Android 裝置當做網路攝影機使用。

核心支援

如果是 Android 14 以上版本，通用核心映像檔 (GKI) 預設會啟用 UVC 小工具驅動程式 (詳情請參閱 AOSP 修補程式)。

在 Gadget HAL 中支援 UVC

從 Android 14 開始，UVC 函式會納入 GadgetFunction.aidl HAL 介面。對於 Gadget HAL，UVC 小工具會以與其他 ConfigFS 函式 (例如 MTP 或 ADB) 相同的方式，掛接到 ConfigFS。

如要實作 Gadget HAL，請修改掛接 UVC 函式至 ConfigFS 的方式。以下是支援 UVC 函式的 Gadget HAL 實作範例程式碼片段：

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

裝置做為網路攝影機時，請確認 USB 小工具 HAL 正在宣傳正確的 VID/PID 組合。

由於所有 UVC 邏輯都位於供應商 init 或服務中，因此 Gadget HAL 不需要任何 UVC 專屬邏輯，只要將 UVC 函式符號連結至 ConfigFS 即可。DeviceAsWebcam

如需實作方面的進一步指引，請參閱 AOSP 中的下列程式碼範例：

使用 UVC 設定設定 ConfigFS

如要讓 UVC 小工具驅動程式瞭解 Android 網路攝影機支援的格式、大小和影格速率，請使用 UVC 設定設定 ConfigFS。詳情請參閱上游 Linux 說明文件中的 ConfigFS UVC 小工具 ABI。

以下範例說明供應商 init 如何設定 UVC 小工具驅動程式 (Android 開放原始碼計畫中的程式碼片段)：

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

這段程式碼片段會設定 UVC 小工具驅動程式，以每秒 30 格的速率播送 1080p MJPEG 串流。USB 主機查詢支援的解析度和影格速率時，系統會將這些功能傳達給主機。

以下是選取網路攝影機播送設定的一般準則：

  • DeviceAsWebcam 服務支援兩種串流格式：MJPEG 和未壓縮的 YUYV。
  • USB 2.0 支援 480 Mbps (60 MBps) 的資料傳輸速度。也就是說，如果畫面更新率為 30 fps，每個影格的大小上限為 2 MB；如果畫面更新率為 60 fps，每個影格的大小上限為 1 MB。
    • 未壓縮的串流 (YUYV)：由於 YUYV 是每像素 2 個位元組，因此在 30 FPS 時，支援的畫面大小上限為 720p。
    • 壓縮 MJPEG 串流：假設 YUV 的壓縮比為 1:10，USB 2.0 可支援 4K (每影格 1.18 MB)。
  • 主要前後鏡頭裝置必須支援所有宣傳的影格大小。這是因為使用者可以透過預覽 UI 切換攝影機 ID。如果是 MJPEG 串流，建議供應商宣傳 480p (640 x 480)、720p (1280 x 820) 和 1080p (1920 x 1080) 的影格大小，因為這些是主機應用程式常用的影格大小。
  • 主要前後鏡頭裝置必須支援所有宣傳的影格速率。強烈建議供應商支援 30 FPS。

如要查看新增網路攝影機串流設定 (ConfigFS) 的範例，請參閱 AOSP 範例修補程式。

在建構版本中啟用網路攝影機

如要啟用 DeviceAsWebcam 服務，請在 device.mk 檔案中，將 ro.usb.uvc.enabled 系統屬性設為 true。

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

啟用這項系統屬性後，「設定」應用程式的 USB 偏好設定下方會顯示「網路攝影機」選項，如圖 3 所示。選取這個選項後，Android 裝置就會以 USB 網路攝影機的形式顯示在主機裝置上。

「設定」應用程式中的 USB 偏好設定

圖 3. 「設定」應用程式中的 USB 偏好設定。

你也可以透過 ADB 使用下列指令，將裝置設為 USB 網路攝影機：

adb shell svc usb setFunctions uvc

考量電力和熱能問題

網路攝影機運作時，裝置的攝影機可能一天會開啟數小時，因此建議採取措施，確保裝置的耗電量和熱能維持在特定限制內。建議採取下列解決方案，將耗電量控制在限制內：

  • 如要提升相機 HAL 的電源效能，請在 DeviceAsWebcam 服務中啟用 STREAM_USE_CASE_VIDEO_CALL。

  • 如果啟用 STREAM_USE_CASE_VIDEO_CALL 後仍擔心耗電問題，DeviceAsWebcam 服務提供使用實體串流進一步降低耗電量的選項。您可以使用執行階段資源疊加 (RRO) 指定要使用的實體攝影機。實體串流會大幅降低影片品質，並導致使用者體驗混亂，因此請僅在不得已時使用此解決方案。建議採用「最佳化」STREAM_USE_CASE_VIDEO_CALL解決耗電問題。如要進一步瞭解 DeviceAsWebcam 服務支援的 RRO，請參閱 readme.md。

    以下範例說明如何設定 RRO，以便使用實體攝影機 ID 3，而非邏輯攝影機 ID 0。如需 AOSP 中的範例，請參閱「DeviceAsWebcamRaven」。

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

驗證

如要在裝置上測試 DeviceAsWebcam 服務的導入成果，請使用下列測試：

  • CTS 驗證器測試 Webcam：測試裝置是否支援格式、大小和影格速率。
  • 手動測試：測試網路攝影機功能是否能在各種主機作業系統上，搭配各種主機應用程式運作。

已知問題

以下是 DeviceAsWebcam 服務的已知問題：