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

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

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

مرکز آزمایش

برای کمک به شرکا در تأیید انطباق با این مشخصات، یک مرکز آزمایشی در دستگاه‌های Chromebox-for-Meetings که در حالت برنامه‌نویس تنظیم شده‌اند، ارائه می‌کنیم. نوشتن در فایل سیستم را فعال کنید. خطوط زیر را به /etc/chrome_dev.conf اضافه کنید:

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

دستگاه را راه اندازی مجدد کنید، دوربین و یک صفحه کلید USB را وصل کنید، Ctrl-Alt-X را فشار دهید و مطابقت با مشخصات دوربین فعال اعمال می شود و به /home/chronos/user/log/chrome وارد می شود.

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

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 ) را برگرداند. بایت).

دستور 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 و زمانی که مقادیر PTZ آن در حال تغییر است غیر صفر. فروشندگان آزادند تا محورها یا موتورهای مختلف را به بیت های مختلف نقشه برداری کنند.
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

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

برخی از دوربین ها دارای اجزای خاصی هستند، مانند موتورهای دوربین های مکانیکی یا قابلیت های دیجیتال PTZ. برای این موارد، از کنترل‌های استاندارد V4L2 برای حرکت، شیب و زوم استفاده کنید.

کنترل: GOOGXU_PAN_TILT_ABSOLUTE (منسوخ شده)

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

کنترل: GOOGXU_PAN_TILT_RELATIVE (منسوخ شده)

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

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

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

21 مه 2024

15 نوامبر 2023

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

21 جولای 2023

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

25 مه 2023

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

17 آوریل 2023

انتشار اولیه