استفاده از دستگاه به‌عنوان وب‌کم

در دستگاه‌های دارای Android 14 QPR1 یا بالاتر، Android از استفاده از دستگاه به‌عنوان وب‌بین USB پشتیبانی می‌کند. دستگاه‌های Android که از این ویژگی پشتیبانی می‌کنند به‌عنوان دستگاه UVC تبلیغ می‌شوند که به طیف وسیعی از میزبان‌های USB با سیستم‌عامل‌های مختلف (برای مثال، Linux،‏ macOS،‏ Windows، و ChromeOS) اجازه می‌دهد از دوربین دستگاه به‌عنوان وب‌کم استفاده کنند. خدمات DeviceAsWebcam از این ویژگی برای استفاده از دستگاه به‌عنوان وب‌کم پشتیبانی می‌کند.

سرویس DeviceAsWebcam

سرویس DeviceAsWebcam در AOSP شامل فعالیت پیش‌نمایشی (DeviceAsWebcamPreview.java) است که به کاربران امکان می‌دهد صحنه را قاب‌بندی کنند. فعالیت پیش‌نمایش به کاربر امکان می‌دهد کارهای زیر را انجام دهد:

  • پیش‌نمایش فید وب‌کم را در دستگاه میزبان قبل‌از شروع جاری‌سازی ببینید.

  • فید وب‌کم ارسالی به میزبان را به روش‌های زیر سفارشی‌سازی کنید:

    • انتخاب دوربین برای جاری‌سازی، جلو یا پشت.
    • انتخاب سطح بزرگ‌نمایی بااستفاده از لغزنده یا دکمه‌ها.
    • تک‌ضرب زدن روی ناحیه خاصی از پیش‌نمایش برای کانونی کردن یا برداشتن کانون از روی ناحیه.

فعالیت پیش‌نمایش با ویژگی‌های دسترس‌پذیری عمومی در Android مانند TalkBack، دسترسی با کلید، و دسترسی با صدا کار می‌کند.

فید وب‌کم برای میزبان جاری‌سازی شد

شکل ۱. فید وب‌بین به میزبان جاری‌سازی می‌شود و پیش‌نمایش فید را کنترل می‌کند.

معماری

معماری پشتیبانی از استفاده از دستگاه به‌عنوان وب‌بین در شکل ۲ نشان داده شده است. در زیر جریان تعامل سرویس DeviceAsWebcam با بقیه چارچوب Android شرح داده شده است:

  1. کاربر گزینه وب‌کم USB را در برنامه «تنظیمات» انتخاب می‌کند.
  2. برنامه «تنظیمات» ازطریق کلاس UsbManager با system_server تماس گیره ارسال می‌کند و به آن اطلاع می‌دهد که FUNCTION_UVC انتخاب شده است.
  3. کار سرور سیستم این است:
    1. به HAL ابزار USB اطلاع می‌دهد که عملکرد ابزار UVC را ازطریق فراخوانی میانای HAL setUsbFunctions بازیابی کند.
    2. به HAL ابزارک USB اطلاع می‌دهد که درایور ابزارک UVC را بااستفاده از ConfigFs پیکربندی کند.
  4. پس‌از دریافت تماس برگشتی از HAL ابزارک، system_server یک همه‌فرستی به چارچوب ارسال می‌کند تا توسط سرویس DeviceAsWebcam دریافت شود.
  5. درایور ابزارک USB با دریافت دستورات پیکربندی از میزبان ازطریق گره‌های V4L2 در /dev/video*، جاری‌سازی وب‌کم را شروع می‌کند.

معماری دستگاه به‌عنوان وب‌بین

شکل ۲. معماری «دستگاه به‌عنوان وب‌کم».

پیاده‌سازی

این بخش نحوه پشتیبانی از استفاده از دستگاه Android به‌عنوان وب‌کم را توضیح می‌دهد.

پشتیبانی هسته

برای Android 14 یا بالاتر، «تصویر هسته عمومی» (GKI) به‌طور پیش‌فرض درایور ابزارک UVC را فعال می‌کند (جزئیات را در وصله AOSP ببینید).

پشتیبانی از UVC در Gadget HAL

از Android 14، تابع UVC در رابط GadgetFunction.aidl HAL گنجانده شده است. برای Gadget HAL، ابزارک UVC به‌همان روش سایر عملکردهای ConfigFS مانند MTP یا ADB به ConfigFS پیوست می‌شود.

برای پیاده‌سازی Gadget HAL، تغییراتی برای نصب تابع UVC در ConfigFS ایجاد کنید. در زیر نمونه‌ای از تکه‌کد پیاده‌سازی Gadget HAL که از عملکرد 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
       ...
   }
   ...
}

وقتی دستگاه به‌عنوان وب‌بین عمل می‌کند، مطمئن شوید که HAL ابزارک USB ترکیب‌های VID/PID مناسب را تبلیغ می‌کند.

ازآنجایی‌که همه منطق UVC یا در مقداردهی اولیه فروشنده یا در DeviceAsWebcam سرویس است، هیچ منطق خاص UVC، به‌جز پیوند نمادین تابع UVC به ConfigFS، در Gadget HAL لازم نیست.

برای راهنمایی بیشتر درباره پیاده‌سازی، کد نمونه زیر را در AOSP ببینید:

راه‌اندازی ConfigFS با پیکربندی‌های UVC

برای اینکه به درایور ابزارک UVC اطلاع دهید که وب‌کم Android از کدام قالب‌ها، اندازه‌ها، و نرخ‌های فریم پشتیبانی می‌کند، ‫ConfigFS را با پیکربندی‌های UVC راه‌اندازی کنید. برای اطلاعات بیشتر، به اسناد Linux بالادستی درباره ConfigFS UVC gadget ABI مراجعه کنید.

در زیر نمونه‌ای از نحوه راه‌اندازی درایور ابزارک UVC توسط vendor init آمده است (تکه کد در 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
   # ...

این تکه‌کد درایور ابزارک UVC را تنظیم می‌کند تا یک جاری‌سازی MJPEG با وضوح ۱۰۸۰ پیکسل در ۳۰ فریم در ثانیه تبلیغ کند. این قابلیت‌ها زمانی که میزبان USB درباره وضوح و نرخ‌های فریم پشتیبانی‌شده پرس‌وجو می‌کند به آن اعلام می‌شود.

در زیر دستورالعمل‌های کلی برای انتخاب پیکربندی‌هایی که وب‌بین تبلیغ می‌کند آورده شده است:

  • دو قالب جاری‌سازی پشتیبانی‌شده توسط سرویس DeviceAsWebcam عبارت‌اند از MJPEG و فشرده‌نشده YUYV.
  • ‫USB 2.0 از انتقال داده با سرعت ۴۸۰ مگابیت در ثانیه (۶۰ مگابایت در ثانیه) پشتیبانی می‌کند. این یعنی در ۳۰ فریم در ثانیه، هر فریم باید حداکثر ۲ مگابایت باشد؛ و در ۶۰ فریم در ثانیه، حداکثر ۱ مگابایت باشد.
    • جاری‌سازی‌های فشرده‌نشده (YUYV): در ۳۰ فریم در ثانیه، حداکثر اندازه فریم پشتیبانی‌شده ۷۲۰ پیکسل است زیرا YUYV برای هر پیکسل ۲ بایت است.
    • جاری‌سازی‌های MJPEG فشرده: با فرض نسبت فشرده‌سازی ۱:۱۰ از YUV، USB 2.0 می‌تواند از 4K (۱٫۱۸ مگابایت در هر قاب) پشتیبانی کند.
  • دستگاه‌های دوربین جلو و پشت اصلی باید از همه اندازه‌های قاب که تبلیغ می‌شود پشتیبانی کنند. به این دلیل که کاربر می‌تواند بااستفاده از میانای کاربر پیش‌نمایش بین شناسه‌های دوربین جابه‌جا شود. برای جاری‌سازی‌های MJPEG، توصیه می‌کنیم فروشندگان اندازه‌های قاب 480p (640 x 480)، 720p (1280 x 820)، و 1080p (1920 x 1080) را تبلیغ کنند زیرا این اندازه‌ها اندازه‌هایی هستند که معمولاً توسط برنامه‌های میزبان استفاده می‌شوند.
  • دستگاه‌های دوربین جلو و پشت اصلی باید از همه نرخ‌های فریم تبلیغ‌شده پشتیبانی کنند. به‌شدت توصیه می‌کنیم که فروشندگان از ۳۰ فریم در ثانیه پشتیبانی کنند.

برای نمونه‌ای از افزودن پیکربندی‌های جاری‌سازی وب‌کم (ConfigFS)، به وصله نمونه AOSP مراجعه کنید.

فعال کردن وب‌کم در ساخت

برای فعال کردن سرویس DeviceAsWebcam، باید ویژگی سیستم ro.usb.uvc.enabled را در فایل device.mk روی true تنظیم کنید.

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

وقتی این دارایی سیستم فعال باشد، گزینه وب‌کم در برنامه «تنظیمات» در بخش اولویت‌های USB ظاهر می‌شود، همان‌طور که در «شکل ۳» نشان داده شده است. وقتی این گزینه انتخاب شود، دستگاه Android به‌عنوان وب‌کم USB برای دستگاه میزبان نمایش داده می‌شود.

اولویت‌های USB در برنامه «تنظیمات»

شکل ۳. اولویت‌های USB در برنامه «تنظیمات».

همچنین می‌توانید دستگاه را ازطریق ADB بااستفاده از این فرمان روی عملکرد وب‌بین USB تنظیم کنید:

adb shell svc usb setFunctions uvc

نگرانی‌های مربوط به توان و گرما را درنظر بگیرید

عملکرد وب‌کم به این معنی است که دوربین دستگاه ممکن است چندین ساعت در روز روشن باشد، بنابراین توصیه می‌کنیم اقداماتی انجام دهید تا مطمئن شوید مصرف برق و حرارت دستگاه در محدوده معینی باقی می‌ماند. راه‌حل‌های توصیه‌شده زیر برای حفظ مصرف انرژی در محدوده مجاز ارائه شده است:

  • برای عملکرد بهتر دوربین HAL، STREAM_USE_CASE_VIDEO_CALL را در سرویس DeviceAsWebcam فعال کنید.

  • اگر حتی با فعال بودن STREAM_USE_CASE_VIDEO_CALL، باز هم نگران مصرف انرژی هستید، سرویس DeviceAsWebcam گزینه‌ای برای کاهش بیشتر مصرف انرژی بااستفاده از جاری‌سازی‌های فیزیکی ارائه می‌دهد. می‌توانید از رونهادهای منبع زمان اجرا (RRO) برای مشخص کردن دوربین فیزیکی موردنظر برای استفاده استفاده کنید. جاری‌سازی فیزیکی کیفیت ویدیو را به‌طور قابل‌توجهی کاهش می‌دهد و منجر به تجربه کاربری گیج‌کننده می‌شود، بنابراین از این راه‌حل فقط به‌عنوان آخرین گزینه استفاده کنید. بهینه‌سازی STREAM_USE_CASE_VIDEO_CALL راه‌حل ترجیحی برای نگرانی‌های مربوط به مصرف برق است. برای کسب اطلاعات بیشتر درباره RROهای پشتیبانی‌شده توسط DeviceAsWebcam خدمات، readme.md را ببینید.

    در زیر نمونه‌ای از راه‌اندازی «هم‌پوشانی منبع زمان اجرا» برای استفاده از شناسه دوربین فیزیکی ۳ به‌جای شناسه دوربین منطقی ۰ ارائه شده است. برای نمونه در AOSP، به DeviceAsWebcamRaven مراجعه کنید.

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

درستی‌سنجی

برای آزمایش پیاده‌سازی سرویس DeviceAsWebcam در دستگاهتان، از آزمایش‌های زیر استفاده کنید:

  • آزمایش درستی‌سنج CTS وب‌کم: آزمایش اینکه قالب‌ها، اندازه‌ها، و نرخ‌های فریم توسط دستگاه پشتیبانی می‌شوند.
  • آزمایش‌های دستی: آزمایش کنید که ویژگی وب‌بین با انواع برنامه‌های میزبان در انواع سیستم‌عامل‌های میزبان کار می‌کند.

مشکلات شناخته‌شده

موارد زیر مشکلات شناخته‌شده سرویس DeviceAsWebcam هستند: