APIهای واحد برنامه افزودنی کلاس ویدیوی USB سخت افزار Google Meet

این سند به تشریح APIهای پشتیبانی شده USB Class Video Class Extension Unit (XU) می‌پردازد که توسط سیستم‌های کنفرانس Google Meet برای فعال کردن ویژگی‌های دوربین هوشمند استفاده می‌شود. هدف از ایجاد این مشخصات، تأثیرگذاری بر روش‌های فعال کردن این ویژگی‌ها و امکان مقیاس‌پذیری و آزمایش ناهمزمان بهتر برای شرکای ما است.

برای کمک به شرکا در تأیید انطباق با این مشخصات، این اسکریپت آزمایشی پیاده‌سازی شما را تحلیل و گزارش می‌کند.

برای جزئیات درباره آخرین تغییرات این سند، به یادداشت‌های انتشار بروید.

کنوانسیون اندین کوچک

USB یک استاندارد کمی است. در این سند:

  • اعداد چند بایتی به شکل بزرگ اندین به نظر می رسند (و به اندین کوچک منتقل می شوند).
  • آرایه‌های بایت در طرح‌بندی حافظه‌های کوچک اندین قرار دارند.

برای مثال، 0x12345678 همان [0x78, 0x56, 0x34, 0x12] است.

GUID واحد افزونه

واحدهای برنامه افزودنی که از این مشخصات کنترل Meet XU پشتیبانی می کنند باید از این GUID استفاده کنند.

واحد توسعه 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 در این حالت غیرفعال است.
فریم های تقسیم شده دوربین به تعداد مورد نیاز نمایش ویدیو ایجاد می کند. بر اساس گزینه Auto-framing feeds ، یا آنها را به کاشی‌ها در یک استریم ترکیب می‌کند یا جریان‌های ویدیویی جداگانه برای هر نما ایجاد می‌کند.
توجه: 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 0x04
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 باید 0x0000000000000000085 (یعنی 0b10000101 و به دنبال آن 0b101000) را برگرداند. بایت).

دستور 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 حالت Active Framing Camera را تنظیم کنید

کنترل: GOOGXU_REFRAME

این کنترل برای فعال کردن کادربندی تک شات که به نام OTAZ نیز شناخته می شود استفاده می شود. هنگامی که OTAZ فعال می شود، نمای دوربین به بهترین نمای اتاق می رسد. پس از آن، مشتری توانایی کنترل مقادیر PTZ را دوباره به دست می آورد. اگر کادربندی تک شات پشتیبانی نمی‌شود، دوربین نباید این کنترل را تعریف کند.

انتخابگر کنترل 2
عمل SET
wLength 1
انحراف رشته اندازه ارزش شرح
0 bReframe 1 عدد 0x01 درخواست Reframe را اجرا کنید

رفتار انواع درخواست های پشتیبانی شده به شرح زیر است:

انحراف 0 شرح
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x02 فقط بنویس
GET_DEF 0x00
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 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 0x0001
GET_LEN 0x0002
GET_INFO 0x09 به روز رسانی خودکار / خواندن
GET_DEF 0x0000

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

این کنترل‌ها برای تشویق شیوه‌های اشکال‌زدایی بهتر با سخت‌افزار Meet هستند و معمولاً با کاربر مواجه نمی‌شوند.

کنترل: GOOGXU_STATUS_INFO

این کنترل برای جستجوی اطلاعات از دوربین میزبان برای اشتراک گذاری با شرکا برای اشکال زدایی استفاده می شود.

انتخابگر کنترل 5
عمل GET
wLength 8
انحراف رشته اندازه ارزش شرح
0 bNumCameras 1 عدد تعداد دوربین های اضافی متصل به دستگاه اصلی.
1 bIsMoving 1 بیت مپ 0 وقتی دوربین بیکار است و غیر صفر وقتی در حال حرکت است. فروشندگان آزادند تا محورها یا موتورهای مختلف را به بیت های مختلف نقشه برداری کنند.
2 Undef 6 Undef در آینده تمدید می شود.

رفتار انواع درخواست های پشتیبانی شده به شرح زیر است:

انحراف 0 1 2 شرح
GET_MIN 0x00 0x00 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 به روز رسانی خودکار / خواندن
GET_DEF 0x00 0x00 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

پیش تنظیم PTZ

برای پیکربندی و بازیابی میدان دید دوربین در موقعیت از پیش تعیین شده استفاده می شود.

کنترل: GOOGXU_PRESETS

این کنترل برای تنظیم مقادیر حرکت، شیب و بزرگنمایی دوربین (PTZ) روی یک پیکربندی از پیش تعیین شده استفاده می شود.

از Preset Action برای بیان عملکرد مورد نظر دستور استفاده می شود. تنظیم مقدار یک (1) برای نگاشت مقادیر حرکت، شیب و بزرگنمایی فعلی به یک شاخص از پیش تعیین شده ارائه شده استفاده می شود. تنظیم مقدار دو (2) باید حرکت، شیب و بزرگنمایی دوربین را به مقادیر قبلاً نقشه‌برداری شده برای شاخص ارائه شده یا مختصات کارخانه پیش‌فرض (اگر قبلاً نقشه‌برداری نشده است) تغییر دهد. تنظیم مقدار سه (3) ایندکس را به مختصات پیش فرض کارخانه بازنشانی می کند.

Preset Index برای تعیین مختصات PTZ نگاشت شده به شاخص استفاده می شود. زمانی که GOOGXU_FRAME_STRATEGY روی NONE تنظیم شده است Preset index شده صفر (0) به مختصات اصلی نگاشت می شود و باید موقعیت پیش فرض دوربین در حالت بیداری باشد.

انتخابگر کنترل 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 از پیش تنظیم حداکثر N پشتیبانی می شود
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 فقط بنویس
GET_DEF 0x00 0x00

نقشه برداری کمکی حرکت و شیب

برخی از دوربین‌ها دارای اجزای ویژه‌ای هستند، مانند موتورهای دوربین‌های مکانیکی، که نیاز به نقشه‌برداری دستورات XU بر روی کنترل‌های استاندارد V4L2 برای حرکت و شیب دارند تا مطابق مورد نظر عمل کنند.

این کنترل‌ها از کنترل‌های مطلق و نسبی حرکت و شیب در مستندات مشخصات UVC تقلید می‌کنند و یک راه استاندارد برای دستگاه‌های میزبان برای نقشه‌برداری صحیح این کنترل‌ها فراهم می‌کنند.

کنترل: GOOGXU_PAN_TILT_ABSOLUTE

کنترل‌های نگاشت کمکی پان و شیب در فصل 4 تعریف شده‌اند: درخواست‌های ویژه کلاس بخش 4.2.2.1.14 کنترل PanTilt (مطلق) مشخصات کلاس UVC 1.5 .

انتخابگر کنترل 8
عمل GET/SET
wLength 8
انحراف رشته اندازه ارزش شرح
0 dwPanAbsolute 4 شماره امضا شده تنظیم ویژگی کنترل Pan (مطلق) آدرس‌دهی شده.
4 dwTiltAbsolute 4 شماره امضا شده تنظیم ویژگی کنترل Tilt (مطلق) آدرس‌دهی شده.

رفتار انواع درخواست های پشتیبانی شده به شرح زیر است:

انحراف 0 4 شرح
GET_MIN وابسته به دوربین
GET_MAX وابسته به دوربین
GET_RES وابسته به دوربین
GET_LEN 0x0008
GET_INFO 0x0B به روز رسانی خودکار / نوشتن / خواندن
GET_DEF 0x00000000 0x00000000

کنترل: GOOGXU_PAN_TILT_RELATIVE

کنترل‌های نگاشت کمکی پان و شیب در فصل 4 تعریف شده‌اند: درخواست‌های ویژه کلاس بخش 4.2.2.1.15 کنترل PanTilt (نسبی) مشخصات کلاس UVC 1.5 .

انتخابگر کنترل 9
عمل GET/SET
wLength 4
انحراف رشته اندازه ارزش شرح
0 bPanRelative 1 شماره امضا شده تنظیم ویژگی کنترل Pan (نسبی) آدرس‌دهی شده:
0: توقف کنید
1: حرکت در جهت عقربه های ساعت
0xFF: حرکت به سمت خلاف جهت عقربه های ساعت
1 bPanSpeed 1 عدد سرعت حرکت تابه.
2 bTiltRelative 1 شماره امضا شده تنظیم ویژگی کنترل Tilt (نسبی) آدرس‌دهی شده:
0: توقف کنید
1: صفحه تصویربرداری را به سمت بالا بگیرید
0xFF: صفحه تصویر را به سمت پایین بگیرید
3 bTiltSpeed 1 عدد سرعت حرکت شیب.

رفتار انواع درخواست های پشتیبانی شده به شرح زیر است:>

انحراف 0 1 2 3 شرح
GET_MIN وابسته به دوربین
GET_MAX وابسته به دوربین
GET_RES وابسته به دوربین
GET_LEN 0x04 0x00 0x0004
GET_INFO 0x0B به روز رسانی خودکار / نوشتن / خواندن
GET_DEF 0x00 0x00 0x00 0x00

یادداشت های انتشار

این یادداشت‌های انتشار نشان‌دهنده پیشرفت‌ها و ویژگی‌های جدید در هر بازبینی این سند است.

15 نوامبر 2023

اسکریپت آزمایشی به روز شده برای بررسی و تفسیر حالت های کادربندی معتبر. نمایش های بایت روشن شده است.

21 جولای 2023

اسکریپت آزمایشی برای شرکا اضافه شد تا اجراها را برای انطباق با این مشخصات تأیید کند.

25 مه 2023

یادداشت GOOGXU_PRESETS در مورد تعداد از پیش تنظیم‌ها تصحیح شد. باید N باشد نه N-1.

17 آوریل 2023

انتشار اولیه.