במסמך הזה מפורטים ממשקי ה-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 מושבת במצב הזה. |
תצוגה דינמית | מצלמה אחת או יותר מנסות לספק את התצוגה הטובה ביותר של החדר. הוא יכול להחליט אם לשלב כמה פידים ליצירת פיד אחד או לספק תצוגה 'מעניינת' של החדר הנוכחי. מטרת התצוגה הזו היא לספק לשיחה את התצוגה השווה ביותר למשתתפים מתוך החדר. הערות:
|
הטיה של הפריים האוטומטי
התכונה | התיאור |
---|---|
הצגה של תוכן מעולה (מעקב אחר דוברים) | המצלמה מנסה לבצע את הפריים הטוב ביותר של האדם שמדבר בחדר. בתרחיש הזה, המצלמה צריכה לפנות לכיוון המציג. למשל, מנכ"ל שנמצא בחדר ישיבות ומעביר מצגת. |
שיתוף פעולה (מעקב חדרים) |
המצלמה מנסה להציג את כל המשתתפים בחדר בצורה הטובה ביותר. במקרה כזה, המצלמה צריכה להתייחס לכל המשתתפים באופן שווה. ברוב הפגישות מומלץ להשתמש בשיטה הזו. |
פריים אוטומטי של פידים
התכונה | התיאור |
---|---|
זרם יחיד | המצלמה שולחת שידור וידאו אחד למכשיר המארח. |
זרם מרובה (עבודה בתהליך) |
המצלמה תפצל את השידור ויוצרת מספר זרמי וידאו לשליחה למארח. הערה: המפרט המלא ואופן הפעולה הצפוי של התכונה הזו ממתינים לבדיקה ולא נתמכים עד לגרסאות קודמות של המסמך. |
ערכי מפת סיביות של מצב פריים אוטומטי
מלבד מצב ברירת המחדל 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 |
נושאים קשורים
- מנהל התקן Linux USB Video Class (UVC)
- קבוצת מסמכים מסוג Video Class v1.5
- מפרט USB 2.0
- מרכז העזרה בנושא ציוד ל-Google Meet
- הקטע 'ציוד ל-Google Meet' במרכז העזרה לאדמינים ב-Google Workspace
- סקריפט לבדיקה של ממשקי ה-API של יחידת תוסף לווידאו מסוג USB ל-Google Meet
הערות מוצר
נתוני הגרסה האלה משקפים שיפורים ותכונות חדשות בכל גרסה של המסמך.
15 בנובמבר 2023
עודכן test Script כדי לבדוק ולפרש מצבי פריים תקינים. ייצוגים של בייטים ברורים.
21 ביולי 2023
הוספנו סקריפט בדיקה לשותפים כדי לוודא שההטמעות תואמות למפרט הזה.
25 במאי 2023
הערה GOOGXU_PRESETS שתוקנה לגבי מספר ההגדרות הקבועות מראש. הוא צריך להיות N ולא N-1.
17 באפריל 2023
גרסה ראשונית.