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

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

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

מתקן בדיקה

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

הפקדים האלה משמשים לאחזור או להגדרה של מצבי הפריים של המצלמה, כפי שמפורטים בקטע ערכים של תמונת בייטמאפ של מצב פריים אוטומטי. כל מצב מיוצג כביט ב-bitmap המתאים. הפקודה 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 0x0008 אורך
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 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 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 0x0002
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_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 AutoUpdate / Read
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.2.2.1.14 PanTilt (Absolute) Control (בקרת הזזה והטייה (מוחלטת)) של מפרט הכיתה UVC 1.5, בקטע 4: בקשות ספציפיות לכיתה.

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

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

הערות מוצר

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

27 בינואר 2025

21 במאי 2024

15 בנובמבר 2023

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

21 ביולי 2023

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

25 במאי 2023

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

17 באפריל 2023

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