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

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

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

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

כנס אנדיאני קטן

USB הוא סוג של סטנדרטי קטן. במסמך זה:

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

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

GUID של יחידת תוסף

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

יחידת תוסף GUID
XU לבקרה היקפית {74D7E924-49C9-4A45-98A3-8A9F60061E83}

בוררי XU לבקרת ציוד היקפי

אלו הבוררים המוגדרים של XU לבקרה על הציוד ההיקפי.

שליטה בבוררים Value
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: Class Specific Requests של מפרט הסיווג של 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, שמיוצג על ידי מערך בייטים ריק, כל ביט במערך הבייטים מייצג מצב מצלמה שונה, שהוא שילוב ספציפי של האפשרויות Auto-Frames כחלק מהפריים האוטומטי, הטיית הפריים האוטומטי והפידים במסגרת הפריים האוטומטי.

אינדקס סיביות CAZ מסגרת מפוצלת דינמית -
רמקול ימים 1:
-		 -
-		 D5
D6		 סטרימינג יחיד
ריבוי שידורים
חדר ימים
-		 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 (1), כדי לציין בהתאמה אם התכונה נתמכת או לא נתמכת במכשיר. לדוגמה, אם המצלמה תומכת ב-CAZ, Speaker, Single-Stream, ב-Split-Frame, Room, Single-Stream וב-Dynamic, Room, Multi-Stream אבל לא במצבים אחרים, השדה GET_RES צריך להחזיר 0x000000000000000085 (כלומר, 0b10000101 ואחריו 7 אפס בייטים).

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

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

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

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

שליטה: GOOGXU_REFRAME

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

בורר שליטה 2
פעולה SET
wLength 1
היסט שדה גודל Value התיאור
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
היסט שדה גודל Value התיאור
0 bOccupancy 1 בוליאני הגדרת פונקציה של ספירת תפוסה
0x00 השבתת הפונקציה
0x01 הפעלת הפונקציה

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

היסט 0 התיאור
GET_CUR חזרה אם ספירת התפוסה מופעלת
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x0 מיליארד עדכון אוטומטי / כתיבה / קריאה
GET_DEF 0x00
SET_CUR הפעלה או השבתה של התכונה לספירת תפוסה

שליטה: GOOGXU_OCCUPANCY_COUNTING_READ

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

בורר שליטה 4
פעולה GET
wLength 2
היסט שדה גודל Value התיאור
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
היסט שדה גודל Value התיאור
0 bNumCameras 1 מספרים מספר המצלמות הנוספות שמחוברות למכשיר הראשי.
1 bIsMoving 1 מפת סיביות (bitmap) 0 כשהמצלמה לא פעילה ולא אפס כשהיא זזה. הספקים יכולים למפות צירים או מנועים שונים לביטים שונים.
2 Undef 6 ללא סיום תאריך הארכה בעתיד.

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

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

אמצעי הבקרה הזה משמש לשליחת בקשת איפוס למצלמה. אם מגדירים ערך של 1 (1) המערכת מבקשת לאפס את המצלמה. המצלמה מחזירה אפס (0) אם לא הייתה בקשה להפעיל מחדש את המצלמה מאז האיפוס האחרון, ובקשה אחת (1) אם היא מתאפסת. איפוס גורם לאותה התנהגות כמו התחברות מחדש של חומרה. זו אפשרות שימושית למכשירים שפועלים באופן עצמאי, שבהם לא מועיל לאלץ ניתוק USB כדי לדמות שקע חם.

בורר שליטה 6
פעולה GET / SET
wLength 1
היסט שדה גודל Value התיאור
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 (2) צריכה להעביר את ההזזה, הטייה ושינוי מרחק התצוגה של המצלמה לערכים שמופו קודם לכן עבור האינדקס שסופק, או לקואורדינטות ברירת המחדל של היצרן (אם לא מופו בעבר). הגדרת ערך של שלושה (3) מאפסת את האינדקס לקואורדינטות ברירת המחדל של היצרן.

הפונקציה Preset Index משמשת לציון קואורדינטות PTZ שממופות לאינדקס. הערך Preset index של אפס (0) ממופה לקואורדינטות הביתיות, והוא צריך להיות מיקום ברירת המחדל של המצלמה בזמן השינה, כאשר GOOGXU_FRAME_STRATEGY מוגדר ל-NONE.

בורר שליטה 7
פעולה SET
wLength 2
היסט שדה גודל Value התיאור
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

מיפוי עזר של תנועה והטיה

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

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

שליטה: GOOGXU_PAN_TILT_ABSOLUTE

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

בורר שליטה 8
פעולה GET/SET
wLength 8
היסט שדה גודל Value התיאור
0 dwPanAbsolute 4 מספר חתום ההגדרה עבור המאפיין של בקרת ההזזה (מוחלטת) הממוענת.
4 dwTiltAbsolute 4 מספר חתום ההגדרה עבור המאפיין של בקרת הטיה (מוחלטת) עם כתובת.

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

היסט 0 4 התיאור
GET_MIN תלוי במצלמה
GET_MAX תלוי במצלמה
GET_RES תלוי במצלמה
GET_LEN 0x0008
GET_INFO 0x0 מיליארד עדכון אוטומטי / כתיבה / קריאה
GET_DEF 0x00000000 0x00000000

שליטה: GOOGXU_PAN_TILT_RELATIVE

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

בורר שליטה 9
פעולה GET/SET
wLength 4
היסט שדה גודל Value התיאור
0 bPanRelative 1 מספר חתום ההגדרה של המאפיין של בקרת הזזה (יחסית) עם כתובת:
0: עצירה
1: מעבר לכיוון השעון
0xFF: מעבר לכיוון השעון
1 bPanSpeed 1 מספרים מהירות התנועה של ההזזה.
2 bTiltRelative 1 מספר חתום ההגדרה עבור המאפיין של בקרת הטיה (יחסית) עם כתובת:
0: עצירה
1: הפניית מישור ההדמיה למעלה
0xFF: הפניית מישור ההדמיה כלפי מטה
3 bTiltSpeed 1 מספרים מהירות תנועת ההטיה.

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

היסט 0 1 2 3 התיאור
GET_MIN תלוי במצלמה
GET_MAX תלוי במצלמה
GET_RES תלוי במצלמה
GET_LEN 0x04 0x00 0x0004
GET_INFO 0x0 מיליארד עדכון אוטומטי / כתיבה / קריאה
GET_DEF 0x00 0x00 0x00 0x00

הערות מוצר

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

15 בנובמבר 2023

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

21 ביולי 2023

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

25 במאי 2023

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

17 באפריל 2023

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