واجهات برمجة التطبيقات لوحدة إضافة فئة الفيديو عبر USB في جهاز Google Meet

يوضّح هذا المستند واجهات برمجة التطبيقات المتوافقة لوحدة إضافة فئة الفيديو عبر USB (XU) التي تستخدمها أنظمة مؤتمرات Google Meet لتفعيل ميزات الكاميرا الذكية. يهدف إنشاء هذه المواصفة إلى التأثير في الممارسات لتفعيل هذه الميزات والسماح بتوسيع نطاق الاختبار غير المتزامن واختباره بشكلٍ أفضل لشريكينا.

للاطّلاع على تفاصيل حول آخر التغييرات التي تم إجراؤها على هذا المستند، يُرجى الانتقال إلى ملاحظات الإصدار.

منشأة الاختبار

لمساعدة الشركاء في التحقّق من الامتثال لهذه المواصفات، نوفّر اختبارًا في أجهزة Chromebox للاجتماعات التي تم ضبطها على وضع المطوّر. فعِّل الكتابة في نظام الملفات. أضِف الأسطر التالية إلىملف /etc/chrome_dev.conf:

--enable-logging
--log-level=0

يُرجى إعادة تشغيل الجهاز وتوصيل الكاميرا ولوحة مفاتيح USB، والضغط على Ctrl-Alt-X، وسيتم تنفيذ الامتثال لمواصفات الكاميرا النشطة وتسجيل الدخول إلى /home/chronos/user/log/chrome.

تنسيق Little-endian

‫USB هو معيار endian صغير. في هذا المستند:

  • تظهر الأرقام المكوّنة من عدة بايت بترتيب endian الكبير (وتتم إرسالها بترتيب endian الصغير).
  • توجد صفائف البايت في تخطيط الذاكرة الصغيرة.

على سبيل المثال، 0x12345678 هو نفسه [0x78, 0x56, 0x34, 0x12].

المعرّف الفريد العام لوحدة الإضافة

يجب أن تستخدم وحدات الإضافات التي تتوافق مع مواصفات عناصر التحكّم في Meet XU هذا المعرّف الموحّد.

وحدة الإضافات GUID
وحدة التحكّم في الأجهزة الملحقة XU {74D7E924-49C9-4A45-98A3-8A9F60061E83}

أدوات اختيار XU للتحكّم في الأجهزة الملحقة

هذه هي أدوات اختيار XU لعناصر التحكّم الملحقة المحدّدة.

أدوات اختيار عناصر التحكّم القيمة
GOOGXU_FRAME_STRATEGY 0x01
GOOGXU_REFRAME 0x02
GOOGXU_OCCUPANCY_COUNTING_TOGGLE 0x03
GOOGXU_OCCUPANCY_COUNTING_READ 0x04
GOOGXU_STATUS_INFO 0x05
GOOGXU_STATUS_RESET 0x06
GOOGXU_PRESETS 0x07
GOOGXU_PAN_TILT_ABSOLUTE 0x08
GOOGXU_PAN_TILT_RELATIVE 0x09

نوع طلب التحكّم

يتم تحديد أنواع طلبات التحكّم في الفصل 4: الطلبات الخاصة بالفئة من مواصفات فئة UVC 1.5.

العملية التحكّم في كاميرا UVC
GET GET_CUR وGET_MIN وGET_MAX وGET_RES وGET_LEN وGET_INFO وGET_DEF
SET SET_CUR

أوضاع الكاميرا

تُستخدَم أوضاع الكاميرا لتصوير الأفراد في غرفة اجتماعات، وهي tuple مما يلي:

  • الاستراتيجية (عرض الكاميرا)
  • الانحياز (المكبّر أو الغرفة)
  • الخلاصات (عمليات بث واحدة أو متعددة)

يمكن أن تأخذ كل سمة القيم الموضّحة في الأقسام التالية.

استراتيجية التعديل التلقائي لإطار الفيديو

الميزة الوصف
لا ينطبق تعمل الكاميرا على إيقاف جميع ميزات وضع الإطار الذكي وتسمح للعميل بالتحكم بحرية في قيم PTZ.
ملاحظة: عند ضبط استراتيجية ضبط الإطار هذه، ستظلّ الكاميرا في وضع التحريك والإمالة والتكبير/التصغير الحالي.
استخدام الإطارات المتواصل (CAZ) استنادًا إلى انحياز الإطارات، تتتبّع الكاميرا باستمرار الأشخاص في الغرفة.
ملاحظة: لا يمكن استخدام كاميرا PTZ في هذا الوضع.
تقسيم الإطارات تنشئ الكاميرا عدد مشاهدات الفيديوهات الذي تحتاجه. استنادًا إلى خيار استخدام الإطارات التلقائية للخلاصات، يمكن أن يتم إنشاء هذه الخلاصات في أقسام في بث واحد أو إنشاء أحداث بث فيديو منفصلة لكل مرة مشاهدة.
ملاحظة: يتم إيقاف PTZ في هذا الوضع.
العرض الديناميكي تحاول كاميرا واحدة أو أكثر تقديم أفضل عرض للغرفة. ويمكنه تحديد ما إذا كان سيتم دمج خلاصات متعددة في خلاصة واحدة أو تقديم عرض "مثير للاهتمام" للغرفة الحالية.
الغرض من هذا العرض هو توفير رؤية أكثر إنصافًا للمشاركين داخل الغرفة في المكالمة.
ملاحظات:
  • من المفترض أن تستخدِم معظم الاجتماعات هذه الاستراتيجية.
  • تكون ميزة PTZ غير مفعّلة في هذا الوضع.

الانحياز في ميزة "التعديل التلقائي لإطار الفيديو"

الميزة الوصف
ميزة "مقدّم المحتوى المهم" (تتبُّع المتحدّث) تحاول الكاميرا تصوير الشخص الذي يتحدث بشكل نشط في الغرفة بأفضل شكل ممكن.
في هذا السيناريو، يجب أن تركّز الكاميرا على مقدّم المحتوى. على سبيل المثال، الرئيس التنفيذي في غرفة مجلس الإدارة يقدّم عرضًا تقديميًا.
التعاون
(تتبُّع الغرف)		 تحاول الكاميرا تصوير جميع المشاركين في الغرفة على أفضل نحو. في هذا السيناريو، يجب أن تتعامل الكاميرا مع كل مشارك بشكلٍ متساوٍ. من المفترض أن تستخدِم معظم الاجتماعات هذه الاستراتيجية.

خلاصات التعديل التلقائي لإطار الفيديو

الميزة الوصف
بث واحد ترسل الكاميرا بث فيديو واحدًا إلى الجهاز المضيف.
البث المتعدد
(قيد العمل)		 تقسّم الكاميرا البث المباشر وتنشئ مجموعات بث فيديو متعددة لإرسالها إلى المضيف.
ملاحظة: إنّ المواصفات الكاملة للسلوك المتوقّع لهذه الميزة في انتظار المراجعة، ولا يمكن استخدامها إلى أن يتم إجراء مراجعات لاحقة لهذا المستند.

قيم ملفات الأشكال المبعثرة لميزة "استخدام اللقطات التلقائية"

باستثناء الحالة التلقائية None التي يتم تمثيلها من خلال صفيف ملف شخصي فارغ، يمثّل كل بت في صفيف الملف الشخصي وضع كاميرا مختلفًا وهو تركيبة محدّدة من استراتيجية وضع "التصغير/التكبير التلقائي" والميل إلى وضع "التصغير/التكبير التلقائي" وخلاصات وضع "التصغير/التكبير التلقائي".

فهرس البت CAZ إطار مجزّأ ديناميكية -
مكبّرات الصوت D1
-		 -
-		 D5
D6		 بث واحد
بث متعدد
الغرفة D2
-		 D3
D4		 D7
D8		 بث واحد
بث متعدد
أوضاع اللقطات قيمة وضع اللقطة (أصغر بايت)
None 0x00
CAZ, Speaker, Single-Stream 0x01
CAZ, Room, Single-Stream 0x02
Split-Frame, Room, Single-Stream 0×04
Split-Frame, Room, Multi-Stream 0x08
Dynamic, Speaker, Single-Stream 0x10
Dynamic, Speaker, Multi-Stream 0x20
Dynamic, Room, Single-Stream 0x40
Dynamic, Room, Multi-Stream 0x80

المجموعة الضابطة: GOOGXU_FRAME_STRATEGY

يُستخدَم عنصر التحكّم هذا للحصول على أو ضبط أوضاع وضع الإطارات للكاميرا كما هو موضّح في قيم ملفات الأشكال الممسوحة ضوئيًا لميزة "وضع وضع الإطارات تلقائيًا". يتم تمثيل كل وضع على أنّه بت في الصورة المركّزة الخاصة به. يعرض الأمر GET_RES قناع بت طوله 8 بايت بقيمة صفر (0) أو واحد (1) على التوالي للإشارة إلى ما إذا كانت الميزة غير متوافقة أو متوافقة مع الجهاز. على سبيل المثال، إذا كانت الكاميرا تتوافق مع CAZ, Speaker, Single-Stream وSplit-Frame, Room, Single-Stream و Dynamic, Room, Multi-Stream ولكن ليس مع أي أوضاع أخرى، من المفترض أن يعرض GET_RES 0x000000000000000085 (أي 0b10000101 متبوعًا بسبعة بايتات صفرية).

يُستخدَم الأمر SET_CUR لإرسال صور نقطية لتحديد وضع الكاميرا SINGLE الذي يجب تفعيله.

أداة اختيار عناصر التحكّم 1
العملية GET / SET
wLength 8
إزاحة الحقل الحجم القيمة الوصف
0 bActiveMode 8 صورة نقطية ضبط "وضع الكاميرا النشطة" أو الرجوع إليه
ملاحظات:

في ما يلي سلوك أنواع الطلبات المتوافقة:

إزاحة 0 الوصف
GET_CUR الحصول على وضع "الإبقاء داخل الإطار" في الكاميرا
GET_MIN يعتمد على الكاميرا
GET_MAX تعتمد على الكاميرا
GET_RES لعرض قناع بتات بطول 8 بايت لوضعيات الكاميرا المتوافقة
GET_LEN 0x0008 الطول
GET_INFO 0x0B التحديث التلقائي / الكتابة / القراءة
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 القيمة التلقائية
SET_CUR ضبط وضع "استخدام إطارات نشطة" في الكاميرا

المجموعة الضابطة: GOOGXU_REFRAME

يُستخدَم هذا العنصر للتفعيل "وضع وضع الصورة الواحدة"، المعروف أيضًا باسم OTAZ. عند تفعيل ميزة OTAZ ، يتم التقاط عرض الكاميرا لأفضل عرض للغرفة. بعد ذلك، يستعيد العميل إمكانية التحكّم في قيم PTZ. إذا لم يكن وضع "استخدام لقطة واحدة" متاحًا، يجب ألا تحدّد الكاميرا عنصر التحكّم هذا.

أداة اختيار عناصر التحكّم 2
العملية SET
wLength 1
إزاحة الحقل الحجم القيمة الوصف
0 bReframe 1 العدد 0x01 تنفيذ طلب تغيير الإطار

في ما يلي سلوك أنواع الطلبات المتوافقة:

إزاحة 0 الوصف
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x02 للكتابة فقط
GET_DEF 0×00
SET_CUR ضبط طلب وضع "لقطة واحدة"

احتساب عدد النزلاء

احتساب عدد الأشخاص (OC) هي ميزة تُستخدَم لتقدير عدد المشاركين في غرفة اجتماعات، على الرغم من العرض المقتطع للكاميرا.

يعرض هذا الجدول السلوك المتوقّع لأداة التحكّم في الكاميرا وتفاعلاتها مع بث الفيديو من الكاميرا ومؤشر LED للكاميرا.

حالات احتساب معدل الإشغال ويجب أن يكون بث الفيديو من الكاميرا: يجب أن يكون مؤشر LED للكاميرا يجب أن يكون GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR يجب أن يكون GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR
مفعّل لا يتم البث ولا يتم كتم الصوت مفعّل 0x01 عدد الأشخاص في مجال رؤية الكاميرا بالكامل
مفعّل البث مفعّل 0x01 عدد الأشخاص في مجال رؤية الكاميرا بالكامل
مفعّل كتم الصوت إيقاف 0x01 غير مفعّل
غير مفعّل لا يتم بثها أو كتم صوتها إيقاف 0x00 غير مفعّل
غير مفعّل البث مفعّل 0x00 غير مفعّل
غير مفعّل كتم الصوت إيقاف 0x00 غير مفعّل

مجموعة التحكّم: GOOGXU_OCCUPANCY_COUNTING_TOGGLE

يُستخدَم عنصر التحكّم هذا لتفعيل ميزة احتساب عدد الأشخاص في غرفة أو إيقافها. يؤدي ضبط القيمة صفر (0) إلى إيقاف هذه الميزة، ويؤدي ضبط القيمة واحد (1) إلى تفعيل هذه الميزة. وإذا لم تكن هذه الميزة متاحة، يجب ألا تحدّد الكاميرا عنصر التحكم هذا.

أداة اختيار عناصر التحكّم 3
العملية GET / SET
wLength 1
إزاحة الحقل الحجم القيمة الوصف
0 bOccupancy 1 منطقي ضبط وظيفة احتساب معدّل الإشغال
0x00 إيقاف الوظيفة
0x01 تفعيل الوظيفة

في ما يلي سلوك أنواع الطلبات المتوافقة:

إزاحة 0 الوصف
GET_CUR عرض القيمة إذا كان احتساب معدّل الإشغال مفعّلاً
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x0B التحديث التلقائي / كتابة / قراءة
GET_DEF 0x00
SET_CUR تفعيل ميزة احتساب معدل الإشغال أو إيقافها

مجموعة التحكّم: GOOGXU_OCCUPANCY_COUNTING_READ

يُستخدَم هذا التحكّم لقراءة عدد المشاركين في غرفة تم الإبلاغ عنها من قِبل الكاميرا عند تفعيل ميزة احتساب عدد الأشخاص. عند إيقاف ميزة احتساب عدد الأشخاص، من المفترض أن توقف الكاميرا عنصر التحكّم هذا. إذا لم يكن احتساب عدد الأشخاص متاحًا، يجب ألا تحدّد الكاميرا هذا التحكّم.

أداة اختيار عناصر التحكّم 4
العملية GET
wLength 2
إزاحة الحقل الحجم القيمة الوصف
0 bNumPeople 2 العدد عدد الأشخاص الذين تم رصدهم في العرض (للقراءة فقط)

في ما يلي سلوك أنواع الطلبات المتوافقة:

إزاحة 0 الوصف
GET_CUR عرض عدد الأشخاص الذين تم رصدهم
GET_MIN 0x0000
GET_MAX 0x00FF
GET_RES 0×0001
GET_LEN 0x0002
GET_INFO 0x09 التحديث التلقائي / القراءة
GET_DEF 0×0000

بيانات التشخيص وقياس الجهاز عن بُعد

تهدف عناصر التحكّم هذه إلى تشجيع ممارسات تصحيح أخطاء أفضل باستخدام أجهزة Meet، وهي عادةً لا تكون موجّهة للمستخدمين.

المجموعة الضابطة: GOOGXU_STATUS_INFO

يُستخدَم عنصر التحكّم هذا لاسترداد المعلومات من كاميرا المضيف لمشاركتها مع الشركاء بغرض تصحيح الأخطاء.

أداة اختيار عناصر التحكّم 5
العملية GET
wLength 8
إزاحة الحقل الحجم القيمة الوصف
0 bNumCameras 1 العدد عدد الأقمار الصناعية الإضافية المرتبطة بالكاميرا الرئيسية والتي قد تؤثر في بث الكاميرا المُرسَل إلى المضيف
1 bIsMoving 1 صورة نقطية 0 عندما تكون الكاميرا في وضع السكون، وقيمة غير صفرية عندما تتغيّر قيم PTZ يُتاح للمورّدين ربط محاور أو محركات مختلفة بوحدات مختلفة.
2 Undef 6 Undef سيتم تمديدها في المستقبل.

في ما يلي سلوك أنواع الطلبات المتوافقة:

إزاحة 0 1 2 الوصف
GET_MIN 0x00 0×00 0x00 0x00 0x00
0x00 0x00 0x00
GET_MAX 0xFF 0xFF 0xFF 0xFF 0xFF
0xFF 0xFF 0xFF
GET_RES 0x01 0x01 0x01 0x00 0x00
0x00 0x00 0x00
GET_LEN 0x08 0x00 0x0008
GET_INFO 0x09 AutoUpdate / Read
GET_DEF 0x00 0×00 0x00 0x00 0x00
0x00 0x00 0x00

مجموعة التحكّم: GOOGXU_STATUS_RESET

يُستخدَم عنصر التحكّم هذا لإصدار طلب إعادة ضبط للكاميرا. يؤدي ضبط القيمة على واحد (1) إلى طلب إعادة ضبط الكاميرا. وتعود الكاميرا إلى الصفر (0) إذا لم يكن هناك طلب لإعادة تشغيل الكاميرا منذ آخر إعادة الضبط، وعرض واحد (1) في حال إعادة الضبط. من المفترض أن تؤدي عملية إعادة الضبط إلى إعادة تشغيل الكاميرا. (هذا الإجراء مطلوب ل الأجهزة المزوّدة بمصدر طاقة ذاتي حيث لا يكون مرغوبًا فيه فرض فصل USB لمحاكاة عملية توصيل/فصل الأجهزة).

أداة اختيار عناصر التحكّم 6
العملية GET / SET
wLength 1
إزاحة الحقل الحجم القيمة الوصف
0 bResetRequest 1 منطقي أرسِل طلب إعادة ضبط إلى المضيف والكاميرات المتصلة.
يعرض القيمة 0x01 إذا تم تقديم طلب إعادة ضبط منذ آخر عملية إعادة ضبط، وإلا يعرض القيمة 0x00.

في ما يلي سلوك أنواع الطلبات المتوافقة:

إزاحة 0 الوصف
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x03 الكتابة / القراءة
GET_DEF 0x00

الإعدادات المُسبَقة للكاميرا المتحركة

يتم استخدامه لضبط مجال رؤية الكاميرا واستعادته إلى موضع محدَّد مسبقًا.

المجموعة الضابطة: GOOGXU_PRESETS

يُستخدَم عنصر التحكّم هذا لضبط قيم العرض الشامل والإمالة والتكبير/التصغير (PTZ) للكاميرا على إعدادات pre-set (مُعدّة مسبقًا).

يتم استخدام Preset Action لتوضيح الإجراء المقصود من الأمر. يتم استخدام القيمة واحد (1) لربط قيم التمرير والتمايل والتكبير/التصغير الحالية بأحد الفهرسات المُعدّة مسبقًا المقدَّمة. من المفترض أن يؤدي ضبط القيمة اثنين (2) إلى نقل وظائف التمرير والتثبيت والتكبير/التصغير للكاميرا إلى القيم التي تم ربطها سابقًا بالفهرس الذي تم تقديمه، أو إلى الإحداثيات التلقائية للمصنع (إذا لم يتم ربطها سابقًا). يؤدي ضبط قيمة ثلاثة (3) إلى إعادة ضبط الفهرس على الإحداثيات التلقائية الأصلية.

يُستخدَم الرمز Preset Index لتحديد إحداثيات PTZ المرتبطة بالفهرس. يتم ربط القيمة Preset index التي تبلغ صفر (0) بإحداثيات المنزل ويجب أن يكون الموضع التلقائي للكاميرا عند تنشيطها عند ضبط GOOGXU_FRAME_STRATEGY على NONE.

أداة اختيار عناصر التحكّم 7
العملية SET
wLength 2
إزاحة الحقل الحجم القيمة الوصف
0 bPresetAction 1 العدد ‫0x01: حفظ الإعداد المُسبَق
0x02: استعادة الإعداد المُسبَق
0x03: إعادة ضبط الإعداد المُسبَق على الإعدادات التلقائية (يجب أن يكون الإعداد التلقائي إحداثيًا مُعدًّا مسبقًا وصالحًا).
1 bPresetIndex 1 العدد فهرس الإعداد المسبق النشط. ‫0~N-1
حيث يُعدّ 0 هو موضع البدء التلقائي للكاميرا وN-1 هو ثابت يحدّده المورّد لعدد الإعدادات المُسبَقة.

في ما يلي سلوك أنواع الطلبات المتوافقة:

إزاحة 0 1 الوصف
GET_MIN 0x00 0x00
GET_MAX 0x03 N-1 عدد الإعدادات المُسبَقة المسموح به
GET_RES 0x01 0x01
GET_LEN 0x02 0×00 0x0002
GET_INFO 0x02 للكتابة فقط
GET_DEF 0x00 0x00

التنقّل في الخريطة وإمالتها

تحتوي بعض الكاميرات على مكوّنات خاصة، مثل محركات الكاميرات الميكانيكية أو إمكانات كاميرا PTZ الرقمية. لاستخدام هذه الوظائف، استخدِم عناصر التحكّم العادية في V4L2 لنقل الصورة و إمالتها وتكبيرها أو تصغيرها.

مجموعة التحكّم: GOOGXU_PAN_TILT_ABSOLUTE (متوقّف نهائيًا)

يتم تعريف عناصر التحكّم في الربط الإضافي للتحريك والإمالة في الفصل 4: الطلبات الخاصة بالفئة الفقرة 4.2.2.1.14 التحكّم في مواصفات فئة UVC 1.5.

العنصر التحكّمي: GOOGXU_PAN_TILT_RELATIVE (متوقّف نهائيًا)

يتم تحديد عناصر التحكّم في الربط المساعِدة للعرض الشامل والإمالة في الفصل 4: طلبات متعلقة بالفئة القسم 4.2.2.1.15 التحكّم في العرض الشامل والإمالة (النسبي) في مواصفات UVC 1.5 Class.

ملاحظات الإصدار

تعرض ملاحظات الإصدار هذه التحسينات والميزات الجديدة في كل نسخة من هذا المستند.

‫21 مايو 2024

15 تشرين الثاني (نوفمبر) 2023

تم تعديل نص الاختبار للتحقّق من أوضاع وضع الإطارات الصالحة وتفسيرها. تم توضيح تمثيلات البت.

21 تموز (يوليو) 2023

تمت إضافة نص برمجي تجريبي للشركاء للتحقّق من عمليات التنفيذ للتأكّد من امتثالها لهذه المواصفة.

25 أيار (مايو) 2023

تم تصحيح ملاحظة GOOGXU_PRESETS بشأن عدد الإعدادات المسبقة. يجب أن يكون N-1 وليس N-1.

‏17 نيسان (أبريل) 2023

الإصدار الأولي