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

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

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

מתקן בדיקה

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

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

מפעילים מחדש את המכשיר, מחברים את המצלמה למקלדת USB, לוחצים על Ctrl-Alt-X והמערכת תבדוק את תאימות המצלמה הפעילה למפרט ותתעד את התוצאות ב-/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

סוג בקשת הבקרה

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

הפקודה SET_CUR משמשת לשליחת קובצי bitmap כדי להורות למצלמה איזה מצב מצלמה יחיד להפעיל.

בורר אמצעי הבקרה 1
פעולה GET / SET
wLength 8
היסט שדה גודל ערך תיאור
0 bActiveMode 8 מפת סיביות (bitmap) הגדרה או חזרה למצב 'מצלמה פעילה'
הערות:

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

היסט 0 תיאור
GET_CUR נהנים ממצב פעיל בפריים של המצלמה
GET_MIN תלוי במצלמה
GET_MAX תלוי במצלמה
GET_RES הפונקציה מחזירה מסיכת ביטים באורך 8 בייטים של מצבי המצלמה הנתמכים
GET_LEN 0x0,008 אורך
GET_INFO 0x0B AutoUpdate / Write / Read
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 ערך ברירת מחדל
SET_CUR הגדרת מצב המצלמה 'חיתוך פעיל'

אמצעי בקרה: GOOGXU_REFRAME

הפקד הזה משמש להפעלת One-Shot Framing, שנקרא גם OTAZ. כשהתכונה OTAZ מופעלת, תצוגת המצלמה עוברת לזו שהכי מתאימה לחדר. לאחר מכן, הלקוח יכול שוב לשלוט בערכי ה-PTZ. אם אין תמיכה בפריימים של צילום בבת אחת, המצלמה לא צריכה להגדיר את אמצעי הבקרה הזה.

בורר אמצעי הבקרה 2
פעולה SET
wLength 1
היסט שדה גודל ערך תיאור
0 bReframe 1 מספר 0x01 ביצוע בקשה לחיתוך מחדש

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

היסט 0 תיאור
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0,001
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 AutoUpdate / Write / Read
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 0x0,002
GET_INFO 0x09 AutoUpdate / Read
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 AutoUpdate / Read
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 (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.2.2.1.14 PanTilt (Absolute) Control (בקרת הזזה והטייה (מוחלטת)) של מפרט הכיתה UVC 1.5, בקטע 4: בקשות ספציפיות לכיתה.

אמצעי בקרה: GOOGXU_PAN_TILT_RELATIVE (הוצא משימוש)

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

הערות מוצר

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

21 במאי 2024

15 בנובמבר 2023

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

21 ביולי 2023

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

25 במאי 2023

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

17 באפריל 2023

הגרסה הראשונית.