ממשקי 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 של יחידת ההרחבה

יחידות הרחבה שתומכות במפרט הזה של בקרת XU ב-Meet חייבות להשתמש ב-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, ולא את מצב המסגור הבסיסי שנבחר על ידי המערכת.

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

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

פידים עם שינוי אוטומטי של הפריים

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

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

חוץ ממצב ברירת המחדל 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 Execute Reframe Request

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

היסט 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

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