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 aktif akan dijalankan dan dicatat 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 ditransmisikan 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
GOOGXU_SATELLITE_INFO 0x0A

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 ruangan)
  • Feed (satu atau beberapa aliran)

Setiap dimensi dapat menggunakan nilai yang dijelaskan di bagian berikut.

Strategi framing otomatis

Di semua mode penyesuaian frame otomatis selain "Tidak ada", geser, miring, dan zoom manual dinonaktifkan.

Fitur Deskripsi
Tidak ada Kamera menonaktifkan semua fitur framing cerdas dan memungkinkan klien mengontrol nilai PTZ secara bebas.
Catatan: Jika disetel ke strategi framing ini, kamera akan tetap berada di posisi geser, naik-turun, dan zoom saat ini.
Framing Berkelanjutan (CAZ) Berdasarkan bias framing, kamera terus melacak orang di ruangan.
Frame Terpisah Kamera membuat tampilan video sebanyak yang diperlukan. Berdasarkan opsi Feed framing otomatis, feed akan menyusunnya menjadi kartu dalam satu streaming atau membuat streaming video terpisah untuk setiap tampilan.
Tampilan Dinamis Satu atau beberapa kamera mencoba memberikan tampilan terbaik 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 adil dari peserta dalam ruangan ke panggilan.
Pilihan vendor Sistem kamera menggunakan logikanya sendiri untuk menentukan tampilan ruangan yang terbaik. Strategi framing yang mendasarinya dapat berubah tanpa pemberitahuan. Misalnya, jika jumlah orang di ruangan berubah, atau kamera dapat mendeteksi perbedaan antara rapat "Presenter dengan Risiko Tinggi" versus rapat "Kolaborasi", sistem dapat bebas beradaptasi atau mengubah strategi framing sesuai keinginan dalam mode ini. Saat dalam mode ini, memanggil getCur akan menampilkan VENDOR_PREFERRED, bukan mode framing yang mendasarinya yang telah dipilih oleh sistem.

Bias framing otomatis

Fitur Deskripsi
Presentasi Berpotensi Tinggi (Pelacakan Pembicara) Kamera akan mencoba membingkai orang yang aktif berbicara di ruangan dengan sebaik mungkin.
Dalam skenario ini, kamera harus diarahkan ke 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.

Feed dengan framing otomatis

Fitur Deskripsi
Single-Stream Kamera mengirim 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 masih menunggu peninjauan dan tidak didukung hingga revisi selanjutnya dari dokumen ini.

Nilai bitmap mode pembingkaian otomatis

Kecuali untuk status default None yang direpresentasikan oleh array byte kosong, setiap bit dalam array byte mewakili mode kamera yang berbeda yang merupakan kombinasi spesifik dari Strategi pembingkaian otomatis, Bias pembingkaian otomatis, dan Feed pembingkaian otomatis.

Feed dengan framing otomatis CAZ Split-Frame Dinamis Pilihan vendor Bias framing otomatis
Single-Stream D1
D2		 -
D3		 D5
D7		 D9 (speaker atau ruang) Speaker
Room
Multi-Streaming -
-		 -
D4		 D6
D8		 - Speaker
Room
Mode frame Nilai mode frame (byte yang paling tidak signifikan)
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

Kontrol: GOOGXU_FRAME_STRATEGY

Kontrol ini digunakan untuk mendapatkan atau menetapkan 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 sepanjang 8 byte dengan nilai nol (0) atau satu (1) untuk 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 Bergantung pada kamera
GET_MAX Bergantung pada kamera
GET_RES Menampilkan bitmask panjang 8 byte dari mode kamera yang didukung
GET_LEN 0x0008 Panjang
GET_INFO 0x0B 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 penghuni di ruangan. 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 jika penghitungan tingkat keterisian diaktifkan
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x0B AutoUpdate / 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. Jika penghitungan jumlah tamu 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 membuat kueri informasi dari kamera penyelenggara untuk dibagikan kepada partner guna 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 AutoUpdate / Read
GET_DEF 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00

Kontrol: GOOGXU_SATELLITE_INFO

Kontrol ini digunakan untuk membuat kueri perangkat satelit yang terhubung ke sistem kamera ini.

Pemilih kontrol 0x0A
Operasi GET
wLength 20
Offset Kolom Ukuran Nilai Deskripsi
0 bSatelliteList 20 Bitmap Daftar jenis satelit yang terpasang ke sistem. Mencakup empat slot 5 byte terpisah. Setiap slot dijelaskan sebagai berikut:
Offset Deskripsi
0 Jumlah untuk jenis satelit ini.
1-2 ID vendor jenis satelit ini.
3-4 ID produk untuk jenis satelit ini.

Perilaku jenis permintaan yang didukung adalah sebagai berikut:

Offset 0 Deskripsi
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 byte
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

Kontrol: GOOGXU_STATUS_RESET

Kontrol ini digunakan untuk mengeluarkan permintaan reset ke kamera. Menetapkan nilai satu (1) akan meminta kamera untuk 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 Mengirim 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 menetapkan nilai pan, tilt, 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) akan mentransisikan pan, 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 jika 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/memperkecil.

Kontrol: GOOGXU_PAN_TILT_ABSOLUTE (tidak digunakan lagi)

Kontrol pemetaan tambahan geser dan miring ditentukan di Bab 4: Permintaan Khusus Class Bagian 4.2.2.1.14 Kontrol PanTilt (Absolut) dari Spesifikasi Class UVC 1.5.

Kontrol: GOOGXU_PAN_TILT_RELATIVE (tidak digunakan lagi)

Kontrol pemetaan tambahan geser dan miring ditentukan di Bab 4: Permintaan Khusus Class Bagian 4.2.2.1.15 Kontrol PanTilt (Relatif) dari Spesifikasi Class UVC 1.5.

Catatan rilis

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

27 Januari 2025

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

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

17 April 2023

Rilis awal.