API Unit Ekstensi Kelas Video USB Google Meet hardware

Dokumen ini menguraikan USB Video Class Extension Unit (XU) API yang didukung yang digunakan oleh sistem konferensi Google Meet untuk mengaktifkan fitur kamera cerdas. Tujuan pembuatan spesifikasi ini adalah untuk memengaruhi praktik guna mengaktifkan fitur ini dan memungkinkan skalabilitas dan pengujian asinkron yang lebih baik bagi partner kami.

Untuk mengetahui detail tentang perubahan terbaru pada dokumen ini, buka Catatan rilis.

Fasilitas pengujian

Untuk membantu partner memvalidasi kepatuhan terhadap spesifikasi ini, kami menyediakan fasilitas pengujian di perangkat Chromebox-for-Meetings yang disetel dalam mode developer. Aktifkan penulisan ke sistem file. Tambahkan baris berikut ke /etc/chrome_dev.conf:

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

Mulai ulang perangkat, hubungkan kamera dan keyboard USB, tekan Ctrl-Alt-X, dan kepatuhan spesifikasi kamera yang aktif akan diterapkan dan dicatat ke dalam log ke /home/chronos/user/log/chrome.

Konvensi little-endian

USB adalah standar little-endian. Dalam dokumen ini:

  • Angka multi-byte muncul dalam big-endian (dan dikirim dalam little-endian).
  • Array byte berada dalam tata letak memori little-endian.

Misalnya, 0x12345678 sama dengan [0x78, 0x56, 0x34, 0x12].

GUID unit ekstensi

Unit ekstensi yang mendukung spesifikasi kontrol Meet XU ini harus menggunakan GUID ini.

Unit Ekstensi GUID
XU Kontrol Periferal {74D7E924-49C9-4A45-98A3-8A9F60061E83}

Pemilih XU kontrol periferal

Ini adalah pemilih XU kontrol periferal yang ditentukan.

Pemilih kontrol Nilai
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

Jenis permintaan kontrol

Jenis permintaan kontrol ditentukan dalam Bab 4: Permintaan Khusus Class dari Spesifikasi Class UVC 1.5.

Operasi Kontrol UVC
GET GET_CUR, GET_MIN, GET_MAX, GET_RES, GET_LEN, GET_INFO, GET_DEF
SET SET_CUR

Mode kamera

Mode kamera digunakan untuk membingkai individu di ruang rapat dan merupakan tuple dari:

  • Strategi (tampilan kamera)
  • Bias (speaker atau ruang)
  • Feed (satu atau beberapa streaming)

Setiap dimensi dapat mengambil nilai yang dijelaskan di bagian berikut.

Strategi framing otomatis

Fitur Deskripsi
Tidak ada Kamera menonaktifkan semua fitur penyesuaian frame cerdas dan memungkinkan klien mengontrol nilai PTZ dengan bebas.
Catatan: Jika ditetapkan ke strategi penyesuaian frame ini, kamera akan tetap berada di posisi geser, kemiringan, dan zoom saat ini.
Framing Berkelanjutan (CAZ) Berdasarkan bias framing, kamera terus melacak orang-orang di ruangan.
Catatan: PTZ dinonaktifkan dalam mode ini.
Frame Terpisah Kamera membuat tampilan video sebanyak yang diperlukan. Berdasarkan opsi Feed framing otomatis, fitur ini akan menyusunnya menjadi tile dalam satu streaming atau membuat streaming video terpisah untuk setiap tampilan.
Catatan: PTZ dinonaktifkan dalam mode ini.
Tampilan Dinamis Satu atau beberapa kamera mencoba memberikan tampilan terbaik ke ruangan. Fungsi ini dapat memutuskan apakah akan menggabungkan beberapa feed menjadi satu atau memberikan tampilan "menarik" dari ruangan saat ini.
Tujuan tampilan ini adalah untuk memberikan tampilan yang paling setara tentang peserta dalam ruangan terhadap panggilan.
Catatan:
  • Sebagian besar rapat sebaiknya menggunakan strategi ini.
  • PTZ dinonaktifkan dalam mode ini.

Bias framing otomatis

Fitur Deskripsi
Presenter dengan Taruhan Tinggi (Pelacakan Pembicara) Kamera mencoba membingkai terbaik orang yang sedang aktif berbicara di ruangan.
Dalam skenario ini, kamera harus condong ke arah presenter. Misalnya, CEO di ruang rapat memberikan presentasi.
Kolaborasi
(Pelacakan Ruang)		 Kamera akan mencoba menampilkan semua peserta di ruang dengan sebaik mungkin. Dalam skenario ini, kamera harus memperlakukan setiap peserta secara adil. Sebagian besar rapat harus menggunakan strategi ini.

Feed dengan framing otomatis

Fitur Deskripsi
Single-Stream Kamera mengirimkan satu streaming video ke perangkat host.
Multi-Stream
(Dalam Proses)		 Kamera akan membagi streaming dan membuat beberapa streaming video untuk dikirim ke host.
Catatan: Spesifikasi lengkap dan perilaku yang diharapkan dari fitur ini sedang menunggu peninjauan dan tidak didukung hingga dokumen ini direvisi pada lain waktu.

Nilai bitmap mode pembingkaian otomatis

Kecuali untuk status default None yang direpresentasikan oleh array byte kosong, setiap bit dalam array byte mewakili mode kamera berbeda yang merupakan kombinasi spesifik dari strategi Framing otomatis, bias framing otomatis, dan Feed framing otomatis.

Indeks bit CAZ Split-Frame Dinamis -
Speaker D1
-		 -
-		 H5
H6		 Aliran Tunggal
Multi-Stream
Room D2
-		 D3
D4		 D7
D8		 Aliran Tunggal
Multi-Stream
Mode frame Nilai mode frame (byte yang paling tidak signifikan)
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

Kontrol: GOOGXU_FRAME_STRATEGY

Kontrol ini digunakan untuk mendapatkan atau menyetel mode framing kamera seperti yang tercantum dalam Nilai bitmap mode framing otomatis. Setiap mode direpresentasikan sebagai bit dalam bitmap masing-masing. Perintah GET_RES menampilkan bitmask panjang 8 byte dengan nilai nol (0) atau satu (1) untuk masing-masing menunjukkan apakah fitur tidak didukung atau didukung oleh perangkat. Misalnya, jika kamera mendukung CAZ, Speaker, Single-Stream, Split-Frame, Room, Single-Stream, dan Dynamic, Room, Multi-Stream, tetapi tidak ada mode lain, GET_RES akan menampilkan 0x000000000000000085 (yaitu 0b10000101 diikuti dengan tujuh byte nol).

Perintah SET_CUR digunakan untuk mengirim bitmap guna memberi tahu kamera mode kamera SINGLE yang akan diaktifkan.

Pemilih kontrol 1
Operasi GET / SET
wLength 8
Offset Kolom Ukuran Nilai Deskripsi
0 bActiveMode 8 Bitmap Menetapkan atau menampilkan Mode Kamera Aktif
Catatan:

Perilaku jenis permintaan yang didukung adalah sebagai berikut:

Offset 0 Deskripsi
GET_CUR Mendapatkan Mode Kamera Framing Aktif
GET_MIN Tergantung kamera
GET_MAX Bergantung pada kamera
GET_RES Menampilkan bitmask panjang 8 byte dari mode kamera yang didukung
GET_LEN 0x0008 Panjang
GET_INFO 0x0 M AutoUpdate / Tulis / Baca
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 Nilai default
SET_CUR Menetapkan mode Kamera Penyesuaian Frame Aktif

Kontrol: GOOGXU_REFRAME

Kontrol ini digunakan untuk memicu Framing Satu Kali, yang juga dikenal sebagai OTAZ. Saat OTAZ dipicu, tampilan kamera akan beralih ke tampilan terbaik ruangan. Setelah itu, klien akan mendapatkan kembali kemampuan untuk mengontrol nilai PTZ. Jika framing satu kali tidak didukung, kamera tidak boleh menentukan kontrol ini.

Pemilih kontrol 2
Operasi SET
wLength 1
Offset Kolom Ukuran Nilai Deskripsi
0 bReframe 1 Angka 0x01 Jalankan Permintaan Pembingkaian Ulang

Perilaku jenis permintaan yang didukung adalah sebagai berikut:

Offset 0 Deskripsi
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x02 Hanya Tulis
GET_DEF 0x00
SET_CUR Menetapkan permintaan untuk Framing Satu Kali

Penghitungan jumlah tamu

Penghitungan jumlah tamu (OC) adalah fitur yang digunakan untuk memperkirakan jumlah peserta di ruang rapat, meskipun tampilan kamera dipangkas.

Tabel ini menunjukkan perilaku yang diharapkan dari kontrol OC dan interaksinya dengan streaming video kamera dan indikator LED kamera.

Jika Penghitungan Tingkat Keterisian &streaming video kamera adalah: Indikator LED kamera harus GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR harus GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR harus
Diaktifkan Tidak melakukan streaming dan tidak dibisukan Aktif 0x01 Jumlah orang dalam ruang pandang penuh kamera.
Diaktifkan Streaming Aktif 0x01 Jumlah orang dalam ruang pandang penuh kamera.
Diaktifkan Dibisukan Nonaktif 0x01 Dinonaktifkan
Dinonaktifkan Tidak melakukan streaming dan tidak dibisukan Nonaktif 0x00 Dinonaktifkan
Dinonaktifkan Streaming Aktif 0x00 Dinonaktifkan
Dinonaktifkan Dibisukan Nonaktif 0x00 Dinonaktifkan

Kontrol: GOOGXU_OCCUPANCY_COUNTING_TOGGLE

Kontrol ini digunakan untuk mengaktifkan atau menonaktifkan fitur untuk menghitung jumlah tamu di ruang. Menetapkan nilai nol (0) akan menonaktifkan fitur ini dan satu (1) akan mengaktifkan fitur ini. Jika fitur ini tidak didukung, kamera tidak boleh menentukan kontrol ini.

Pemilih kontrol 3
Operasi GET / SET
wLength 1
Offset Kolom Ukuran Nilai Deskripsi
0 bOccupancy 1 Boolean Menetapkan fungsi penghitungan tingkat keterisian
0x00 Menonaktifkan fungsi
0x01 Mengaktifkan fungsi

Perilaku jenis permintaan yang didukung adalah sebagai berikut:

Offset 0 Deskripsi
GET_CUR Menampilkan apakah penghitungan tingkat keterisian diaktifkan
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x0B Update Otomatis / Tulis / Baca
GET_DEF 0x00
SET_CUR Mengaktifkan atau menonaktifkan fitur penghitungan tingkat keterisian

Kontrol: GOOGXU_OCCUPANCY_COUNTING_READ

Kontrol ini digunakan untuk membaca jumlah peserta di ruang yang dilaporkan oleh kamera saat penghitungan jumlah orang diaktifkan. Saat penghitungan tingkat keterisian dinonaktifkan, kamera akan menonaktifkan kontrol ini. Jika penghitungan jumlah orang tidak didukung, kamera tidak boleh menentukan kontrol ini.

Pemilih kontrol 4
Operasi GET
wLength 2
Offset Kolom Ukuran Nilai Deskripsi
0 bNumPeople 2 Angka Jumlah penghuni yang terdeteksi dalam tampilan. (Hanya Baca)

Perilaku jenis permintaan yang didukung adalah sebagai berikut:

Offset 0 Deskripsi
GET_CUR Menampilkan jumlah penumpang yang terdeteksi
GET_MIN 0x0000
GET_MAX 0x00FF
GET_RES 0x0001
GET_LEN 0x0002
GET_INFO 0x09 AutoUpdate / Read
GET_DEF 0x0000

Telemetri & diagnostik perangkat

Kontrol ini dimaksudkan untuk mendorong praktik proses debug yang lebih baik dengan hardware Meet dan biasanya tidak ditampilkan kepada pengguna.

Kontrol: GOOGXU_STATUS_INFO

Kontrol ini digunakan untuk mengkueri informasi dari kamera host agar dapat dibagikan dengan partner untuk proses debug.

Pemilih kontrol 5
Operasi GET
wLength 8
Offset Kolom Ukuran Nilai Deskripsi
0 bNumCameras 1 Angka Jumlah satelit tambahan yang terpasang ke kamera utama yang dapat memengaruhi streaming kamera yang ditampilkan ke host.
1 bIsMoving 1 Bitmap 0 saat kamera tidak ada aktivitas, dan bukan nol saat nilai PTZ-nya berubah. Vendor bebas memetakan sumbu atau motor yang berbeda ke bit yang berbeda.
2 Undef 6 Undef Akan diperpanjang pada masa mendatang.

Perilaku jenis permintaan yang didukung adalah sebagai berikut:

Offset 0 1 2 Deskripsi
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 Update / Baca Otomatis
GET_DEF 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00

Kontrol: GOOGXU_STATUS_RESET

Kontrol ini digunakan untuk mengeluarkan permintaan reset ke kamera. Menetapkan nilai satu (1) akan meminta kamera direset. Kamera menampilkan nol (0) jika tidak ada permintaan untuk memulai ulang kamera sejak reset terakhir dan satu (1) jika kamera direset. Reset harus memicu mulai ulang kamera. (Hal ini diperlukan untuk perangkat mandiri yang tidak memerlukan daya eksternal sehingga memaksa pemutusan koneksi USB untuk mengemulasi hotplug tidak berguna.)

Pemilih kontrol 6
Operasi GET / SET
wLength 1
Offset Kolom Ukuran Nilai Deskripsi
0 bResetRequest 1 Boolean Kirimkan permintaan reset ke host dan kamera yang terhubung.
Menampilkan 0x01 jika permintaan reset dikeluarkan sejak reset terakhir, atau 0x00.

Perilaku jenis permintaan yang didukung adalah sebagai berikut:

Offset 0 Deskripsi
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x03 Tulis / Baca
GET_DEF 0x00

Preset PTZ

Digunakan untuk mengonfigurasi dan memulihkan ruang pandang kamera ke posisi preset.

Kontrol: GOOGXU_PRESETS

Kontrol ini digunakan untuk menyetel nilai geser, kemiringan, dan zoom (PTZ) kamera ke konfigurasi preset.

Preset Action digunakan untuk menyatakan tindakan yang diinginkan dari perintah. Menetapkan nilai satu (1) digunakan untuk memetakan nilai geser, miring, dan zoom saat ini ke indeks preset yang disediakan. Menetapkan nilai dua (2) harus mentransisikan penggeseran, kemiringan, dan zoom kamera ke nilai yang dipetakan sebelumnya untuk indeks yang diberikan, atau koordinat pabrik default (jika tidak dipetakan sebelumnya). Menetapkan nilai tiga (3) akan mereset indeks ke koordinat default pabrik.

Preset Index digunakan untuk menentukan koordinat PTZ yang dipetakan ke indeks. Preset index nol (0) dipetakan ke koordinat rumah dan harus menjadi posisi default kamera saat aktif saat GOOGXU_FRAME_STRATEGY ditetapkan ke NONE.

Pemilih kontrol 7
Operasi SET
wLength 2
Offset Kolom Ukuran Nilai Deskripsi
0 bPresetAction 1 Angka 0x01: Menyimpan preset
0x02: Memulihkan preset
0x03: Mereset preset ke default. (Defaultnya harus berupa koordinat preset yang valid.)
1 bPresetIndex 1 Angka Indeks Setelan Default Aktif. 0~N-1
Dengan 0 dianggap sebagai posisi awal kamera default dan N-1 adalah konstanta yang ditentukan vendor untuk jumlah preset.

Perilaku jenis permintaan yang didukung adalah sebagai berikut:

Offset 0 1 Deskripsi
GET_MIN 0x00 0x00
GET_MAX 0x03 N-1 Preset maksimum N didukung
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 Hanya tulis
GET_DEF 0x00 0x00

Pemetaan tambahan geser & miringkan

Beberapa kamera memiliki komponen khusus, seperti motor untuk kamera mekanis, atau kemampuan PTZ digital. Untuk ini, gunakan kontrol V4L2 standar untuk menggeser, memiringkan, dan memperbesar.

Kontrol: GOOGXU_PAN_TILT_ABSOLUTE (tidak digunakan lagi)

Kontrol pemetaan tambahan geser dan kemiringan ditentukan dalam Bab 4: Permintaan Spesifik Per Kelas Bagian 4.2.2.1.14 Kontrol PanTilt (Absolut) untuk Spesifikasi Kelas UVC 1.5.

Kontrol: GOOGXU_PAN_TILT_RELATIVE (tidak digunakan lagi)

Kontrol pemetaan tambahan geser dan kemiringan ditentukan dalam Bab 4: Permintaan Spesifik Per Kelas Bagian 4.2.2.1.15 PanTilt (Relatif) Kontrol Spesifikasi Kelas UVC 1.5.

Catatan rilis

Catatan rilis ini mencerminkan peningkatan dan fitur baru dalam setiap revisi dokumen ini.

21 Mei 2024

15 November 2023

Memperbarui skrip pengujian untuk memeriksa dan menafsirkan mode framing yang valid. Mengklarifikasi representasi byte.

21 Juli 2023

Menambahkan skrip pengujian untuk partner guna memvalidasi implementasi untuk kepatuhan terhadap spesifikasi ini.

25 Mei 2023

Mengoreksi catatan GOOGXU_PRESETS terkait jumlah preset. Seharusnya N, bukan N-1.

17 April 2023

Rilis awal.