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

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

DeviceAsWebcam 服務

AOSP 中的 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 小工具驅動程式 (詳情請參閱 AOSP 修補程式)。

在 Gadget HAL 中支援 UVC

從 Android 14 開始，UVC 功能已納入 GadgetFunction.aidl HAL 介面。對於小工具 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 邏輯都位於供應商初始化或 DeviceAsWebcam 服務中，因此除了將 UVC 函式連結至 ConfigFS 之外，Gadget HAL 不需要任何 UVC 專屬邏輯。

如需進一步的導入指南，請參閱 AOSP 中的以下程式碼範例：

• 新增 UVC 功能支援
• USBGadget：新增對 UVC 功能的支援

使用 UVC 設定設定 ConfigFS

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

以下範例說明供應商初始化程序如何設定 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 MBps) 的資料傳輸速度。也就是說，在 30 fps 下，每個影格必須有 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) 的範例，請參閱 AOSP 範例修補程式。

在版本中啟用網路攝影機

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

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

啟用這個系統屬性後，設定應用程式會在 USB 偏好設定下顯示「Webcam」選項，如圖 3 所示。選取這個選項後，Android 裝置會在主機裝置上顯示為 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 服務的已知問題：

• UVC 小工具驅動程式的串流有時會閃爍，並顯示看似損毀的影格。這個問題已修正，並已合併至上游和 GKI。

  • 上游修正：

    • 如果沒有可用的影片緩衝區，請排入空白 ISOC 要求
    • 請勿使用 worker 執行緒來傳送 USB 要求

  • GKI 修補程式

• 由於 Apple 的 UVC 驅動程式有錯誤，因此 Android 裝置在網路攝影機模式下無法在 macOS 主機上使用 USB 3.0 以上版本的傳輸線。