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

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

DeviceAsWebcam 服務

Android 開放原始碼計畫中的 DeviceAsWebcam 服務包含預覽活動 (DeviceAsWebcamPreview.java)，可讓使用者針對場景建立影格。預覽活動可讓使用者執行下列操作：

  • 在串流開始前，預覽網路攝影機畫面在主機機器上呈現的樣貌。

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

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

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

透過串流方式播送的網路攝影機動態消息

圖 1 透過網路攝影機在主機串流播放時，可控制動態饋給。

架構

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

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

做為網路攝影機架構

圖 2. DeviceAsWebcam 架構。

導入作業

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

核心支援

如果是 Android 14 以上版本，一般核心映像檔 (GKI) 會預設啟用 UVC 小工具驅動程式 (詳情請參閱 Android 開放原始碼計畫修補程式)。

在小工具 HAL 中支援 UVC

自 Android 14 起，GadgetFunction.aidl HAL 介面內含 UVC 函式。對於小工具 HAL，UVC 小工具掛接至 ConfigFS 的方式，與掛接其他 ConfigFS 函式 (例如 MTP 或 ADB) 的方式相同。

如要實作小工具 HAL，請修改以將 UVC 函式掛接至 ConfigFS。以下是支援 UVC 函式的小工具 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 或 DeviceAsWebcam 服務，因此除了將 UVC 函式與 ConfigFS 建立符號連結以外，除了 UVC 特定邏輯之外，您還需要在 小工具 HAL 中操作。

如需實作的進一步指引，請參閱下列 Android 開放原始碼計畫的程式碼範例：

使用 UVC 設定進行 ConfigFS 設定

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

以下範例說明廠商 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 fps 播放的 1080p MJPEG 串流。當 USB 主機查詢支援的解析度和影格速率時，系統會將這些功能傳達給 USB 主機。

下列是設定網路攝影機廣告設定的通用指南：

  • DeviceAsWebcam 服務支援的兩種串流格式為 MJPEG 和未壓縮的 YUYV。
  • USB 2.0 支援 480 Mbps (60 MB) 的資料傳輸方式。也就是說，如果每秒影格數為 30 影格，則每個影格的大小上限為 2 MB；60 fps 的上限為 1 MB。
    • 未壓縮串流 (YUYV)：支援的影格上限為 30 fps，因此支援的影格大小上限為 720p，因為 YUYV 是每像素 2 個位元組。
    • 壓縮的 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) 的範例，請參閱 Android 開放原始碼計畫範例修補程式。

在版本中啟用網路攝影機

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

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

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

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

您也可以使用 ADB，透過 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。如需 Android 開放原始碼計畫的範例，請參閱 DeviceAsWebcamRaven。

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

驗證

如要在裝置上測試 DeviceAsWebcam 服務的實作方式，請使用下列測試：

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

已知問題

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