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

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

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

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

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

הערות מוצר

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

‫13 באוגוסט 2025

‫27 בינואר 2025

21 במאי 2024

‫15 בנובמבר 2023

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

‫21 ביולי 2023

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

‫25 במאי 2023

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

17 באפריל 2023

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