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

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

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

منشأة اختبار

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

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

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

اصطلاحات قصيرة القامة

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

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

على سبيل المثال، 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 0×04
GOOGXU_STATUS_INFO 0x05
GOOGXU_STATUS_RESET 0×06
GOOGXU_PRESETS 0×07
GOOGXU_PAN_TILT_ABSOLUTE 0×08
GOOGXU_PAN_TILT_RELATIVE 0x09

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

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

العملية التحكم في الأشعة فوق البنفسجية
GET GET_CUR وGET_MIN وGET_MAX وGET_RES وGET_LEN وGET_INFO وGET_DEF
SET SET_CUR

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

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

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

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

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

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

انحياز الإطار التلقائي

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

ضبط الإطار التلقائي للخلاصات

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

قيم الصور النقطية في وضع التعديل التلقائي لإطار الفيديو

باستثناء الحالة التلقائية None التي يتم تمثيلها ببايت فارغ صفيفة، فإن كل بت في صفيفة البايت يمثل وضع كاميرا مختلف وهو تركيبة محدَّدة من استراتيجية ضبط الإطار التلقائي والتعديل التلقائي لإطار الفيديو التحيز، وخلاصات التعديل التلقائي لإطار الفيديو.

فهرس البت CAZ إطار مقسَّم ديناميكية -
مكبّرات الصوت اليوم الأول
-		 -
-		 ي 5
د6		 بث واحد
بث متعدد
الغرفة اليوم الثاني
-		 D3
D4		 اليوم 7
D8		 بث واحد
بث متعدد
أوضاع اللقطات قيمة وضع الإطار (البايت الأقل أهمية)
None 0×00
CAZ, Speaker, Single-Stream 0x01
CAZ, Room, Single-Stream 0x02
Split-Frame, Room, Single-Stream 0×04
Split-Frame, Room, Multi-Stream 0×08
Dynamic, Speaker, Single-Stream 0x10
Dynamic, Speaker, Multi-Stream 0x20
Dynamic, Room, Single-Stream 0x40
Dynamic, Room, Multi-Stream 0×80

مجموعة التحكّم: 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 لإرسال صور نقطية لإخبار الكاميرا وضع الكاميرا الفردي المطلوب تفعيله.

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

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

إزاحة 0 الوصف
GET_CUR تفعيل وضع "استخدام الإطار" النشط في الكاميرا
GET_MIN يعتمد على الكاميرا
GET_MAX يعتمد على الكاميرا
GET_RES تعرض قناع بت طويل بحجم 8 بايت من أوضاع الكاميرا المتوافقة
GET_LEN 0×0008 الطول
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 0×00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0×0001
GET_INFO 0x02 للكتابة فقط
GET_DEF 0×00
SET_CUR ضبط طلب لاستخدام الإطار بلقطة واحدة

احتساب الإشغال

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

يوضح هذا الجدول السلوك المتوقع لعناصر التحكم في 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 0×00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0×0001
GET_INFO 0x0B التحديث التلقائي / كتابة / قراءة
GET_DEF 0×00
SET_CUR تفعيل ميزة احتساب عدد الإشغال أو إيقافها

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

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

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

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

إزاحة 0 الوصف
GET_CUR عدد النزلاء الذين تم رصدهم
GET_MIN 0×0000
GET_MAX 0x00FF
GET_RES 0×0001
GET_LEN 0×0002
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 إلغاء تحديد ليتم التمديد لها في المستقبل.

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

إزاحة 0 1 2 الوصف
GET_MIN 0×00 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 0×08 0×00 0×0008
GET_INFO 0x09 التحديث التلقائي / القراءة
GET_DEF 0×00 0×00 0x00 0x00 0x00
0x00 0x00 0x00

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

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

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

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

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

الإعدادات المسبقة لـ PTZ

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

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

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

يتم استخدام 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 0×00 0×00
GET_MAX 0x03 N-1 لا يمكن ضبط الإعدادات المسبقة لـ N كحد أقصى
GET_RES 0x01 0x01
GET_LEN 0x02 0×00 0×0002
GET_INFO 0x02 للكتابة فقط
GET_DEF 0×00 0×00

تصوير سينمائي و ربط التطبيقات الإضافية للإمالة

تحتوي بعض الكاميرات على مكونات خاصة، مثل محركات الكاميرات الميكانيكية، أو 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 المواصفات:

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

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

‫21 مايو 2024

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

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

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

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

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

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

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

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