ממשקי API של יחידות תוספים לכיתת וידאו ל-Google Meet בציוד ל-Google Meet

במאמר הזה מפורטים ממשקי ה-API של יחידת ההרחבה (XU) של USB Video Class (מחלקה של מכשירי וידאו ב-USB) שנתמכים על ידי מערכות לשיחות ועידה ב-Google Meet, כדי להפעיל תכונות חכמות של המצלמה. המטרה של יצירת המפרט הזה היא להשפיע על שיטות עבודה כדי להפעיל את התכונות האלה, ולאפשר לשותפים שלנו בדיקות והתאמות טובות יותר של קנה מידה אסינכרוני.

לפרטים על השינויים האחרונים במסמך הזה, אפשר לעבור אל הערות על הגרסה.

מתקן בדיקה

כדי לעזור לשותפים לוודא שהם עומדים בדרישות המפרט הזה, אנחנו מספקים מתקן בדיקה במכשירי Chromebox-for-Meetings שהוגדרו במצב פיתוח. מפעילים כתיבה למערכת הקבצים. מוסיפים את השורות הבאות לקובץ /etc/chrome_dev.conf:

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

מפעילים מחדש את המכשיר, מחברים את המצלמה ואת מקלדת ה-USB, לוחצים על Ctrl-Alt-X, ותאימות המפרט של המצלמה הפעילה תופעל ותתועד ב-/var/log/chrome/chrome (אם משתמשים בתמונה חתומה, אז ב-/home/chronos/user/log/chrome).

מוסכמת Little-endian

USB הוא תקן little-endian. במסמך הזה:

  • מספרים מרובי-בייט מופיעים בפורמט big-endian (ומועברים בפורמט little-endian).
  • מערכי הבייטים הם בפריסת הזיכרון little-endian.

לדוגמה, 0x12345678 זהה ל-[0x78, 0x56, 0x34, 0x12].

‫GUID של יחידת ההרחבה

יחידות הרחבה שתומכות במפרט הזה של אמצעי בקרה ב-Meet XU צריכות להשתמש ב-GUID הזה.

יחידת תוסף GUID
Peripheral Control 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
GOOGXU_SATELLITE_INFO 0x0A

סוג בקשת השליטה

סוגי בקשות הבקרה מוגדרים בפרק 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) המצלמה עוקבת אחרי האנשים בחדר באופן רציף על סמך ההטיה של הפריים.
פיצול פריימים המצלמה יוצרת כמה צפיות בסרטון שצריך. בהתאם לאפשרות התאמה אוטומטית של הפריים בפידים, המערכת מרכיבה אותם כמשבצות בשידור אחד או יוצרת שידורי וידאו נפרדים לכל תצוגה.
תצוגה דינמית מצלמה אחת או יותר מנסות לספק את התצוגה הטובה ביותר של החדר. הוא יכול להחליט אם לשלב כמה פידים לאחד או לספק תצוגה 'מעניינת' של החדר הנוכחי.
המטרה של התצוגה הזו היא לספק תצוגה הוגנת ככל האפשר של המשתתפים בשיחה שנמצאים בחדר.
מועדף על הספק מערכת המצלמה משתמשת בלוגיקה משלה כדי לקבוע את התצוגה הטובה ביותר של החדר. שיטת המסגור הבסיסית עשויה להשתנות ללא הודעה מוקדמת. לדוגמה, אם מספר האנשים בחדר משתנה, או אם המצלמה יכולה לזהות את ההבדל בין פגישה עם מצגת חשובה לבין פגישה לשיתוף פעולה, המערכת יכולה להתאים או לשנות את אסטרטגיית המסגור לפי הצורך במצב הזה. במצב הזה, קריאה ל-getCur צריכה להחזיר VENDOR_PREFERRED, ולא את מצב המסגור הבסיסי שנבחר על ידי המערכת.

הטיה בפריים האוטומטי

תכונה תיאור
מצגת חשובה (מעקב אחרי הדובר) המצלמה מנסה למסגר בצורה הטובה ביותר את האדם שמדבר בחדר.
במקרה כזה, המצלמה צריכה להתמקד במציג. לדוגמה, מנכ"ל שמעביר מצגת בחדר ישיבות.
שיתוף פעולה
(מעקב אחרי חדרים)		 המצלמה מנסה להציג את כל המשתתפים בחדר בצורה הכי טובה. בתרחיש הזה, המצלמה צריכה להתייחס לכל המשתתפים באופן שווה.

פידים עם פריים אוטומטי

תכונה תיאור
שידור יחיד המצלמה שולחת וידאו אחד בסטרימינג למכשיר המארח.
Multi-Stream
(בתהליך פיתוח)		 המצלמה מפצלת את הסטרימינג ויוצרת כמה פריטי וידאו בסטרימינג כדי לשלוח למארח.
הערה: המפרט המלא וההתנהגות הצפויה של התכונה הזו נמצאים בבדיקה ולא נתמכים עד לתיקונים מאוחרים יותר במסמך הזה.

ערכי מפת סיביות של מצב מסגור אוטומטי

מלבד מצב ברירת המחדל None שמיוצג על ידי מערך בייטים ריק, כל ביט במערך הבייטים מייצג מצב מצלמה שונה, שהוא שילוב ספציפי של שיטת החיתוך האוטומטי, הטיה של החיתוך האוטומטי ופידים של החיתוך האוטומטי.

פידים עם פריים אוטומטי CAZ מסך מפוצל דינמית מועדף על הספק הטיה בפריים האוטומטי
Single-Stream D1
D2		 ‫–
D3		 D5
D7		 D9 (רמקול או חדר) רמקול
חדר
Multi-Stream ‫-
-		 ‫-
D4		 D6
D8		 - רמקול
חדר
מצבי מסגרת ערך מצב הפריים (הבייט הכי פחות משמעותי)
None 0x0000
CAZ, Speaker, Single-Stream 0x0001
CAZ, Room, Single-Stream 0x0002
Split-Frame, Room, Single-Stream 0x0004
Split-Frame, Room, Multi-Stream 0x0008
Dynamic, Speaker, Single-Stream 0x0010
Dynamic, Speaker, Multi-Stream 0x0020
Dynamic, Room, Single-Stream 0x0040
Dynamic, Room, Multi-Stream 0x0080
Vendor-preferred, Single-Stream 0x0100

שליטה: 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 מפת סיביות (bitmap) הגדרה או חזרה למצב מצלמה פעילה
הערות:

ההתנהגות של סוגי הבקשות הנתמכים היא כדלקמן:

היסט 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 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 מפת סיביות (bitmap) ‫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_SATELLITE_INFO

אמצעי הבקרה הזה משמש לשאילתות של מכשירי הלוויין שמחוברים למערכת המצלמה הזו.

בורר אמצעי הבקרה 0x0A
פעולה GET
wLength 20
היסט שדה גודל ערך תיאור
0 bSatelliteList 20 מפת סיביות (bitmap) רשימה של סוגי הלוויינים שמחוברים למערכת. כולל ארבעה משבצות נפרדות של 5 בייט. כל אחד מהמשבצות מתואר באופן הבא:
היסט תיאור
0 הכמות של סוג הלוויין הזה.
1-2 מזהה הספק של סוג הלוויין הזה.
3-4 מזהה המוצר של סוג הלוויין הזה.

ההתנהגות של סוגי הבקשות הנתמכים היא כדלקמן:

היסט 0 תיאור
GET_MIN 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
GET_MAX 0xFF 0xFF 0xFF 0xFF 0xFF
0xFF 0xFF 0xFF 0xFF 0xFF
0xFF 0xFF 0xFF 0xFF 0xFF
0xFF 0xFF 0xFF 0xFF 0xFF
GET_RES 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
GET_LEN 0x14 ‫20 בייטים
GET_INFO 0x09 עדכון אוטומטי / קריאה
GET_DEF 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 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 שממופות לאינדקס. הערך 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 תמיכה ב-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 (Absolute) Control של מפרט UVC 1.5 Class.

שליטה: GOOGXU_PAN_TILT_RELATIVE (הוצאה משימוש)

הגדרות המיפוי של כפתורי הזזה והטיה מוגדרות בפרק 4: בקשות ספציפיות לסוג, קטע 4.2.2.1.15 PanTilt (Relative) Control של מפרט UVC 1.5 Class.

הערות מוצר

כאן מפורטים השיפורים והתכונות החדשות בכל עדכון של המסמך הזה.

‫13 באוגוסט 2025

‫27 בינואר 2025

21 במאי 2024

‫15 בנובמבר 2023

עדכנו את סקריפט הבדיקה כדי לבדוק ולפרש מצבי מסגור תקינים. הבהרות לגבי ייצוגים של בייטים

‫21 ביולי 2023

הוספנו סקריפט בדיקה לשותפים כדי לאמת הטמעות לצורך עמידה במפרט הזה.

‫25 במאי 2023

תוקן GOOGXU_PRESETS הערה לגבי מספר ההגדרות הקבועות מראש. המספר צריך להיות N, ולא N-1.

17 באפריל 2023

זו הגרסה הראשונה.