استخدام الجهاز ككاميرا ويب

بالنسبة إلى الأجهزة التي تعمل بالإصدار 14-QPR1 من Android أو إصدار أحدث، يتيح Android استخدام الجهاز ككاميرا ويب USB. يتم الإعلان عن أجهزة Android المتوافقة مع هذه الميزة كـ جهاز UVC، ما يتيح لمجموعة كبيرة من مضيفي USB الذين يستخدمون أنظمة تشغيل مختلفة (مثل Linux وmacOS وWindows وChromeOS) استخدام كاميرا الجهاز كاميرا ويب. تتيح خدمة DeviceAsWebcam استخدام هذه الميزة لاستخدام الجهاز ككاميرا ويب.

خدمة DeviceAsWebcam

تتضمّن خدمة DeviceAsWebcam في AOSP نشاط معاينة (DeviceAsWebcamPreview.java) يتيح للمستخدمين وضع إطار للمشهد. يتيح نشاط المعاينة للمستخدم إجراء ما يلي:

• يمكنك معاينة الشكل الذي ستظهر به خلاصة كاميرا الويب على الجهاز المضيف قبل بدء البث.

• يمكنك تخصيص خلاصة كاميرا الويب المُرسَلة إلى المضيف بالطُرق التالية:

  • اختيار الكاميرا التي تريد بث المحتوى منها، سواء كانت الكاميرا الأمامية أو الخلفية
  • اختيار مستوى التكبير/التصغير باستخدام شريط تمرير أو أزرار
  • النقر على منطقة معيّنة من المعاينة للتركيز عليها أو إزالة التركيز على منطقة

يعمل نشاط المعاينة مع ميزات تسهيل الاستخدام العامة على Android، مثل TalkBack والوصول عبر مفتاح التحويل و الاستخدام عبر الصوت.

الشكل 1: يتم بث خلاصة كاميرا الويب إلى مضيف مع معاينة تتحكّم في الخلاصة.

هندسة معمارية

توضِّح المخطّط 2 البنية الأساسية لاستخدام جهاز ككاميرا ويب. في ما يلي وصف لتدفق التفاعل بين DeviceAsWebcam الخدمة وبقية إطار عمل Android:

1. يختار المستخدم خيار كاميرا الويب USB في تطبيق "الإعدادات".
2. يُرسِل تطبيق "الإعدادات" طلب ربط إلى system_server من خلال فئة UsbManager لإعلامها بأنّه تم اختيار FUNCTION_UVC.
3. ينفِّذ خادم النظام ما يلي:
   1. إبلاغ HAL لأجهزة USB لاسترداد وظيفة جهاز UVC من خلال واجهة setUsbFunctions HAL
   2. إبلاغ HAL لأجهزة USB بضبط برنامج تشغيل جهاز UVC باستخدام ConfigFs
4. عند تلقّي مكالمة صادرة من HAL للأجهزة، يُرسِل system_server بثًا إلى إطار العمل ليتم استرجاعه من خلال خدمة DeviceAsWebcam.
5. يشغِّل برنامج تشغيل جهاز USB بث كاميرا الويب عند تلقّي رسائل برمجية لضبط الإعدادات من المضيف من خلال عقد V4L2 في /dev/video*.

الشكل 2: بنية DeviceAsWebcam

التنفيذ

يوضِّح هذا القسم كيفية إتاحة استخدام جهاز Android ككاميرا ويب.

دعم النواة

في نظام التشغيل Android 14 أو الإصدارات الأحدث، تفعِّل صورة Kernel Generic (GKI) برنامج تشغيل أدوات UVC تلقائيًا (اطّلِع على التفاصيل في تصحيح AOSP).

تحذير: حدثت بعض المشاكل الخطيرة في ثبات برنامج تشغيل أداة UVC في شباط (فبراير) 2024. تم نقل الإصلاحات (AOSP Gerrit) إلى الإصدار العلني وهي متوفرة في جميع فروع تطوير GKI. إذا لم يكن الإصدار المحدّد يحتوي على الإصلاحات، اطلب إعادة إرسال الإصدار مع التغييرات التي تم اختيارها بعناية.

إتاحة واجهة برمجة التطبيقات UVC في HAL للأجهزة

بدءًا من الإصدار Android 14، تم تضمين وظيفة UVC في واجهة GadgetFunction.aidl HAL. بالنسبة إلى HAL الخاص بالأجهزة، يتم تثبيت كاميرا UVC الذكية على ConfigFS بالطريقة نفسها التي يتم بها تثبيت وظائف ConfigFS الأخرى، مثل MTP أو ADB.

لتنفيذ HAL الخاص بالأجهزة، عليك إجراء تعديلات لتركيب وظيفة UVC في ملف ‎ ConfigFS. في ما يلي مثال على مقتطف لواجهة 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 متوفّر في ملف vendor init أو في DeviceAsWebcam service، لا يلزم توفير أي منطق خاص بـ UVC في HAL الخاص بالأجهزة سوى ربط وظيفة UVC بملف ملف رمز برمجي ثابت (ملف ConfigFS).

للحصول على مزيد من الإرشادات حول التنفيذ، اطّلِع على الرمز البرمجي النموذجي التالي في AOSP:

• إضافة وظائف UVC
• USBGadget: إضافة وظائف UVC

إعداد ConfigFS باستخدام إعدادات UVC

لإعلام برنامج تشغيل أداة UVC بالتنسيقات والأحجام ومعدّلات عرض اللقطات التي تتوافق مع كاميرا الويب في Android، عليك إعداد ConfigFS باستخدام إعدادات UVC. للحصول على مزيد من المعلومات، يُرجى الاطّلاع على مستندات Linux الأساسية حول ABI لجهاز ConfigFS UVC القابل للبرمجة.

في ما يلي مثال على كيفية إعداد برنامج vendor init لبرنامج تشغيل أداة UVC (مقتطف رمز في 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 بدقة 1080p بمعدّل 30 صورة في الثانية. ويتم إرسال هذه الإمكانات إلى مضيف USB عندما يطلب معرفة الدقة وعدد اللقطات في الثانية المتوافقَين.

في ما يلي إرشادات عامة لاختيار الإعدادات التي تعرضها كاميرا الويب:

• تنسيقَا البث المتوافقَين مع خدمة DeviceAsWebcam هما MJPEG و YUYV غير المضغوطة.
• يتوافق USB 2.0 مع نقل البيانات بسرعة 480 ميغابت في الثانية (60 ميغابايت في الثانية). ويعني ذلك أنّه عند عرض 30 لقطة في الثانية، يجب ألا يزيد حجم كل لقطة عن 2 ميغابايت، وعند عرض 60 لقطة في الثانية، يجب ألا يزيد حجم كل لقطة عن 1 ميغابايت.
  • أحداث البث غير المضغوطة (YUYV): عند 30 صورة في الثانية، يكون الحد الأقصى لحجم اللقطة هو 720p لأنّ تنسيق YUYV يضم بايتين لكل بكسل.
  • أحداث MJPEG المضغوطة: بافتراض نسبة ضغط 1:10 من YUV، يمكن لبروتوكول USB 2.0 إتاحة دقة 4K (1.18 MB لكل إطار).
• يجب أن تتيح كاميرا الجهاز الأمامية والخلفية الأساسية جميع أحجام اللقطات المُعلَن عنها. ويرجع ذلك إلى أنّه يمكن للمستخدم التبديل بين أرقام تعريف الكاميرات باستخدام واجهة مستخدم المعاينة. بالنسبة إلى أحداث البث بتنسيق MJPEG، ننصح المورّدين بعرض أحجام اللقطات بدقة 480p (640 x 480) و720p (1280 x 820) و1080p (1920 x 1080) لأنّها الأحجام التي تستخدمها التطبيقات المستضيفة بشكل شائع.
• يجب أن تتوافق الكاميرا الأمامية والخلفية الأساسية مع جميع معدّلات اللقطات في الثانية المُعلَن عنها. ننصحك بشدة بأن يتيح المورّدون سرعة 30 صورة في الثانية.

للحصول على مثال على إضافة إعدادات لبث كاميرا الويب (ConfigFS)، يُرجى الاطّلاع على نموذج تصحيح AOSP.

تفعيل كاميرا الويب في الإصدار

لتفعيل خدمة DeviceAsWebcam، يجب ضبط ro.usb.uvc.enabled سمة النظام على true في ملف device.mk.

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

عند تفعيل سمة النظام هذه، يظهر خيار كاميرا الويب في تطبيق "الإعدادات" ضمن الإعدادات المفضّلة لـ USB كما هو موضّح في الشكل 3. عند تحديد الخيار، يظهر جهاز Android للجهاز المضيف ككاميرا ويب USB.

الشكل 3: الإعدادات المفضّلة لـ USB في تطبيق "الإعدادات"

يمكنك أيضًا ضبط الجهاز على وظيفة كاميرا الويب USB من خلال ADB باستخدام الأمر التالي:

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 هو الحلّ المفضّل لحلّ مشكلات الطاقة. لمزيد من المعلومات عن عمليات إعادة البيع التي تتيحها DeviceAsWebcam الخدمة، يُرجى الاطّلاع على readme.md.

  في ما يلي مثال على ملف RRO تم إعداده لاستخدام معرّف الكاميرا المادي 3 بدلاً من معرّف الكاميرا المنطقي 0. للحصول على مثال في AOSP، يُرجى الاطّلاع على DeviceAsWebcamRaven.

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

التحقق

لاختبار عملية تنفيذ خدمة DeviceAsWebcam على جهازك، استخدِم الاختبارات التالية:

• اختبار أداة التحقّق من توافق الأجهزة مع معيار CTS لـ كاميرا الويب: عليك اختبار تنسيقات الملفات وأحجامها ومعدلات عرض اللقطات للتأكّد من توافقها مع الجهاز.
• الاختبارات اليدوية: يمكنك اختبار عمل ميزة كاميرا الويب مع مجموعة متنوعة من التطبيقات المستضافة على مجموعة متنوعة من أنظمة التشغيل المستضافة.

المشاكل المعروفة

في ما يلي المشاكل المعروفة لخدمة DeviceAsWebcam:

• في بعض الأحيان، ينطفئ بث برنامج تشغيل أداة UVC ويظهر فيه ما يبدو أنّه لقطات متضرّرة. تم حلّ هذه المشكلة وتم دمجها في الإصدار العلني وفي GKI.

  • إصلاحات "التحميل":

    • إضافة طلبات ISOC فارغة إلى "قائمة الانتظار" في حال عدم توفّر ذاكرة تخزين مؤقت للفيديو
    • عدم استخدام سلسلة مهام العمل لضخ طلبات USB

  • تصحيح GKI

• لا تعمل أجهزة Android في وضع كاميرا الويب مع كابلات USB 3.0 والإصدارات الأحدث على مضيفي macOS بسبب خطأ في برنامج تشغيل UVC من Apple.