API Unit Ekstensi Kelas Video USB Google Meet hardware

Dokumen ini menguraikan API Unit Ekstensi (XU) Kelas Video USB 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 /var/log/chrome/chrome (jika menggunakan image bertanda tangan, maka /home/chronos/user/log/chrome).

Konvensi little-endian

USB adalah standar little-endian. Dalam dokumen ini:

  • Angka multi-byte muncul sebagai big-endian (dan ditransmisikan sebagai 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 XU Meet ini harus menggunakan GUID ini.

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

Pemilih XU kontrol periferal

Berikut 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 mengatur posisi individu di ruang rapat dan merupakan tuple dari:

  • Strategi (tampilan kamera)
  • Bias (speaker atau ruangan)
  • Feed (satu atau beberapa aliran)

Setiap dimensi dapat mengambil nilai yang dijelaskan di bagian berikut.

Strategi penyesuaian frame otomatis

Dalam semua mode penyesuaian frame otomatis selain "Tidak Ada", geser, kemiringan, dan zoom manual dinonaktifkan.

Fitur Deskripsi
Tidak ada Kamera menonaktifkan semua fitur penyesuaian frame 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 pembingkaian, kamera terus melacak orang di dalam ruangan.
Membagi Frame Kamera membuat tampilan video sebanyak yang diperlukan. Berdasarkan opsi Feed pembingkaian otomatis, opsi ini 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. Sistem dapat memutuskan apakah akan menggabungkan beberapa feed menjadi satu atau memberikan tampilan "menarik" dari ruangan saat ini.
Tujuan tampilan ini adalah untuk memberikan tampilan peserta di dalam ruangan yang paling adil ke panggilan.
Pilihan vendor Sistem kamera menggunakan logikanya sendiri untuk menentukan tampilan terbaik ruangan. Strategi pembingkaian yang mendasarinya dapat berubah tanpa pemberitahuan. Misalnya, jika jumlah orang di ruangan berubah, atau kamera dapat mendeteksi perbedaan antara rapat "Presenter Penting" dan rapat "Kolaborasi", sistem bebas menyesuaikan atau mengubah strategi pembingkaian sesuai kebutuhan dalam mode ini. Saat dalam mode ini, memanggil getCur akan menampilkan VENDOR_PREFERRED, dan bukan mode penyesuaian frame pokok yang telah dipilih oleh sistem.

Bias penyesuaian frame otomatis

Fitur Deskripsi
Presenter Penting (Pelacakan Pembicara) Kamera mencoba membingkai orang yang sedang berbicara di dalam ruangan dengan sebaik mungkin.
Dalam skenario ini, kamera harus lebih fokus pada presenter. Misalnya, CEO di ruang rapat sedang memberikan presentasi.
Kolaborasi
(Pelacakan Ruangan)		 Kamera akan mencoba membingkai semua peserta dalam ruangan dengan sebaik mungkin. Dalam skenario ini, kamera harus memperlakukan setiap peserta secara adil.

Feed penyesuaian frame otomatis

Fitur Deskripsi
Single-Stream Kamera mengirimkan satu streaming video ke perangkat host.
Multi-Stream
(Dalam Proses)		 Kamera 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 revisi selanjutnya dari dokumen ini.

Nilai bitmap mode pembingkaian otomatis

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

Feed penyesuaian frame otomatis CAZ Frame Terpisah Dinamis Pilihan vendor Bias penyesuaian frame otomatis
Single-Stream D1
D2		 -
D3		 D5
D7		 D9 (speaker atau ruang) Speaker
Room
Multi-Stream -
-		 -
D4		 D6
D8		 - Speaker
Room
Mode frame Nilai mode frame (byte 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 menyetel mode pembingkaian kamera seperti yang tercantum dalam Nilai bitmap mode pembingkaian otomatis. Setiap mode ditampilkan 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 mendukung mode lainnya, maka GET_RES harus menampilkan 0x000000000000000085 (yaitu 0b10000101 diikuti dengan tujuh byte nol).

Perintah SET_CUR digunakan untuk mengirim bitmap guna memberi tahu kamera mode kamera SINGLE mana 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 Pembingkaian 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 / Write / Read
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 Nilai default
SET_CUR Menyetel mode Kamera Penyesuaian Aktif

Kontrol: GOOGXU_REFRAME

Kontrol ini digunakan untuk memicu Pembingkaian Sekali Ambil, yang juga dikenal sebagai OTAZ. Saat OTAZ dipicu, tampilan kamera akan beralih ke tampilan terbaik ruangan. Setelah itu, klien mendapatkan kembali kemampuan untuk mengontrol nilai PTZ. Jika pembingkaian sekali pengambilan 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 Menjalankan Permintaan Penyusunan 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 Menyetel permintaan untuk Pembingkaian Sekali Ambil

Penghitungan hunian

Penghitungan jumlah peserta (OC) adalah fitur yang digunakan untuk memperkirakan jumlah peserta dalam 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.

Saat 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 disenyapkan 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 disenyapkan 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 penghuni di dalam 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 hunian
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 AutoUpdate / Write / Read
GET_DEF 0x00
SET_CUR Mengaktifkan atau menonaktifkan fitur penghitungan tingkat keterisian

Kontrol: GOOGXU_OCCUPANCY_COUNTING_READ

Kontrol ini digunakan untuk membaca jumlah peserta dalam ruang yang dilaporkan oleh kamera saat penghitungan tingkat keterisian diaktifkan. Jika penghitungan hunian dinonaktifkan, kamera harus menonaktifkan kontrol ini. Jika penghitungan hunian 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 penghuni 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 penelusuran bug 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 host 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 terhubung ke kamera utama yang dapat memengaruhi streaming kamera yang dikembalikan ke host.
1 bIsMoving 1 Bitmap 0 saat kamera tidak digunakan, 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 terhubung 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 untuk 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 mengirim 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 sedang direset. Reset harus memicu mulai ulang kamera. (Hal ini diperlukan untuk perangkat yang memiliki daya sendiri yang tidak dapat menggunakan fitur pencabutan USB untuk meniru hotplug.)

Pemilih kontrol 6
Operasi GET / SET
wLength 1
Offset Kolom Ukuran Nilai Deskripsi
0 bResetRequest 1 Boolean Mengirimkan 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 pan, tilt, dan zoom (PTZ) kamera ke konfigurasi preset.

Preset Action digunakan untuk menyatakan tindakan yang dimaksudkan dari perintah. Menetapkan nilai satu (1) digunakan untuk memetakan nilai geser, kemiringan, dan zoom saat ini ke indeks preset yang diberikan. Menetapkan nilai dua (2) akan mengalihkan pan, kemiringan, dan zoom kamera ke nilai yang sebelumnya dipetakan untuk indeks yang diberikan, atau koordinat pabrik default (jika belum 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 awal dan harus menjadi posisi default kamera saat aktif jika GOOGXU_FRAME_STRATEGY disetel ke NONE.

Pemilih kontrol 7
Operasi SET
wLength 2
Offset Kolom Ukuran Nilai Deskripsi
0 bPresetAction 1 Angka 0x01: Simpan preset
0x02: Pulihkan preset
0x03: Reset preset ke default. (Default harus berupa koordinat preset yang valid.)
1 bPresetIndex 1 Angka Indeks Preset 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 N maks yang didukung
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 Hanya tulis
GET_DEF 0x00 0x00

Menggeser & memiringkan pemetaan tambahan

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

Kontrol: GOOGXU_PAN_TILT_ABSOLUTE (tidak digunakan lagi)

Kontrol pemetaan tambahan geser dan miring didefinisikan dalam Bab 4: Class Specific Requests Section 4.2.2.1.14 PanTilt (Absolute) Control of the UVC 1.5 Class Specification.

Kontrol: GOOGXU_PAN_TILT_RELATIVE (tidak digunakan lagi)

Kontrol pemetaan tambahan geser dan miring ditentukan dalam Bab 4: Class Specific Requests Section 4.2.2.1.15 PanTilt (Relative) Control of the UVC 1.5 Class Specification.

Catatan rilis

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

13 Agu 2025

27 Jan 2025

21 Mei 2024

15 November 2023

Memperbarui skrip pengujian untuk memeriksa dan menafsirkan mode pembingkaian yang valid. Memperjelas representasi byte.

21 Juli 2023

Menambahkan skrip pengujian bagi partner untuk memvalidasi implementasi agar mematuhi spesifikasi ini.

25 Mei 2023

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

17 April 2023

Rilis awal.