API Unit Ekstensi Kelas Video USB Google Meet hardware

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

Untuk membantu partner memvalidasi kepatuhan terhadap spesifikasi ini, skrip pengujian ini menganalisis dan melaporkan penerapan Anda.

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

Konvensi Little-endian

USB adalah standar {i>small-endian<i}. Dalam dokumen ini:

  • Angka multi-byte tampak big-endian (dan ditransmisikan small-endian).
  • Array byte ada di tata letak memori small-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
Kontrol Periferal XU {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 (pembicara atau ruangan)
  • 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 framing cerdas dan memungkinkan klien mengontrol nilai PTZ dengan bebas.
Catatan: Jika ditetapkan ke strategi framing ini, kamera akan tetap dalam 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.
Bingkai Terpisah Kamera membuat jumlah tontonan video sebanyak yang diperlukan. Berdasarkan opsi Feed framing otomatis, feed akan disusun menjadi kotak 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 ruangan. Fitur ini dapat memutuskan apakah akan menggabungkan beberapa feed menjadi satu atau memberikan tampilan "menarik" dari ruangan saat ini.
Tujuan tampilan ini adalah untuk memberikan pandangan yang paling setara tentang peserta dalam ruang terhadap panggilan.
Catatan:
  • Sebagian besar rapat sebaiknya menggunakan strategi ini.
  • PTZ dinonaktifkan dalam mode ini.

Bias framing otomatis

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

Feed framing otomatis

Fitur Deskripsi
Streaming Tunggal Kamera mengirimkan satu streaming video ke perangkat host.
Multi-Streaming
(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 dokumen ini direvisi nanti.

Nilai bitmap mode framing otomatis

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

Indeks bit KAS Bingkai Terpisah Dinamis -
Speaker H1
-		 -
-		 D5
H6		 Single-Stream
Multi-Stream
Room H+2
-		 D3
H4		 D7
H8		 Single-Stream
Multi-Stream
Mode frame Nilai mode frame (byte 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-nya masing-masing. Perintah GET_RES menampilkan bitmask sepanjang 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 untuk memberi tahu kamera mode kamera SINGLE mana yang harus diaktifkan.

Pemilih kontrol 1
Operasi GET / SET
wLength 8
Offset Kolom Ukuran Nilai Deskripsi
0 bActiveMode 8 Bitmap Menyetel 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 Tergantung kamera
GET_RES Menampilkan bitmask sepanjang 8 byte dari mode kamera yang didukung
GET_LEN 0x0008 Durasi
GET_INFO 0x0 M Update Otomatis / Tulis / Baca
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 Nilai default
SET_CUR Menetapkan mode Kamera Framing Aktif

Kontrol: GOOGXU_REFRAME

Kontrol ini digunakan untuk memicu Framing Satu Kali, yang juga dikenal sebagai OTAZ. Saat OTAZ dipicu, tampilan kamera akan mengarah ke tampilan terbaik ruangan. Setelah itu, klien 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 Menjalankan Permintaan Bingkai 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 Tetapkan permintaan untuk Framing Satu Kali

Penghitungan jumlah tamu

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

Tabel ini menunjukkan perkiraan perilaku kontrol OC dan interaksinya dengan streaming video kamera serta indikator LED kamera.

Ketika Penghitungan Kehadiran adalah & streaming video kamera adalah: Indikator LED kamera harus GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR harus GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR harus
Aktif Tidak streaming dan tidak dibisukan Aktif 0x01 Jumlah orang dalam ruang pandang penuh kamera.
Aktif Streaming Aktif 0x01 Jumlah orang dalam ruang pandang penuh kamera.
Aktif Dibisukan Nonaktif 0x01 Dinonaktifkan
Dinonaktifkan Tidak 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 guna menghitung tamu di ruang. Menetapkan nilai nol (0) akan menonaktifkan fitur ini dan satu (1) akan mengaktifkan fitur ini. Jika fitur ini tidak didukung, kamera seharusnya tidak menentukan kontrol ini.

Pemilih kontrol 3
Operasi GET / SET
wLength 1
Offset Kolom Ukuran Nilai Deskripsi
0 bOccupancy 1 Boolean Setel fungsi penghitungan tingkat keterisian
0x00 Nonaktifkan fungsi
0x01 Aktifkan fungsi

Perilaku jenis permintaan yang didukung adalah sebagai berikut:

Offset 0 Deskripsi
GET_CUR Menampilkan kembali jika penghitungan tingkat keterisian diaktifkan
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x0 M Update Otomatis / Tulis / Baca
GET_DEF 0x00
SET_CUR Mengaktifkan atau menonaktifkan fitur penghitungan jumlah tamu

Kontrol: GOOGXU_OCCUPANCY_COUNTING_READ

Kontrol ini digunakan untuk membaca jumlah peserta dalam ruangan yang dilaporkan oleh kamera saat penghitungan tingkat keterisian diaktifkan. Jika fitur ini dinonaktifkan, kamera harus menonaktifkan kontrol ini. Jika penghitungan tingkat keterisian 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 tamu yang terdeteksi dan terlihat. (Hanya Baca)

Perilaku jenis permintaan yang didukung adalah sebagai berikut:

Offset 0 Deskripsi
GET_CUR Jumlah tamu yang terdeteksi kembali
GET_MIN 0x0000
GET_MAX 0x00FF
GET_RES 0x0001
GET_LEN 0x0002
GET_INFO 0x09 Update Otomatis / Baca
GET_DEF 0x0000

Telemetri & diagnostik perangkat

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

Kontrol: GOOGXU_STATUS_INFO

Kontrol ini digunakan untuk membuat kueri informasi dari kamera host yang akan dibagikan kepada partner untuk proses debug.

Pemilih kontrol 5
Operasi GET
wLength 8
Offset Kolom Ukuran Nilai Deskripsi
0 bNumCameras 1 Angka Jumlah kamera tambahan yang terpasang ke perangkat utama.
1 bIsMoving 1 Bitmap 0 saat kamera tidak ada aktivitas, dan bukan nol saat bergerak. Vendor bebas memetakan sumbu atau motor yang berbeda ke bit yang berbeda.
2 Undef 6 Tidak ditentukan Akan diperpanjang di 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 Otomatis / Baca
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 untuk direset. Kamera menampilkan nol (0) jika tidak ada permintaan untuk memulai ulang kamera sejak reset terakhir dan satu (1) jika kamera direset. Reset memicu perilaku yang sama seperti koneksi ulang hardware. Hal ini berguna untuk perangkat yang didukung daya sendiri, yang tidak akan berguna jika memaksa pemutusan koneksi USB untuk mengemulasi hotplug.

Pemilih kontrol 6
Operasi GET / SET
wLength 1
Offset Kolom Ukuran Nilai Deskripsi
0 bResetRequest 1 Boolean Berikan permintaan reset ke host dan kamera yang terhubung.
Menampilkan 0x01 jika permintaan reset dikeluarkan sejak terakhir kali direset, atau menampilkan 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 perintah yang dimaksud. Menetapkan nilai satu (1) digunakan untuk memetakan nilai geser, kemiringan, dan zoom saat ini ke indeks preset yang diberikan. Menetapkan nilai dua (2) akan mentransisikan geser, kemiringan, dan zoom kamera ke nilai yang dipetakan sebelumnya untuk indeks yang disediakan, atau koordinat factory 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 dari 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: 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 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, yang memerlukan pemetaan perintah XU pada kontrol V4L2 standar agar dapat berfungsi sebagaimana mestinya.

Kontrol ini meniru kontrol absolut dan relatif atas geser dan kemiringan dalam dokumentasi spesifikasi UVC, yang memberikan cara standar bagi perangkat host untuk memetakan kontrol ini dengan benar.

Kontrol: GOOGXU_PAN_TILT_ABSOLUTE

Kontrol pemetaan bantu geser dan miring ditentukan dalam Bab 4: Permintaan Khusus Kelas Bagian 4.2.2.1.14 Kontrol PanTilt (Absolut) Spesifikasi Class UVC 1.5.

Pemilih kontrol 8
Operasi GET/SET
wLength 8
Offset Kolom Ukuran Nilai Deskripsi
0 dwPanAbsolute 4 Nomor yang Ditandatangani Setelan untuk atribut Kontrol Geser (Absolut) yang dialamatkan.
4 dwTiltAbsolute 4 Nomor yang Ditandatangani Setelan untuk atribut Kontrol Kemiringan (Absolut) yang ditetapkan.

Perilaku jenis permintaan yang didukung adalah sebagai berikut:

Offset 0 4 Deskripsi
GET_MIN Tergantung kamera
GET_MAX Tergantung kamera
GET_RES Tergantung kamera
GET_LEN 0x0008
GET_INFO 0x0 M Update Otomatis / Tulis / Baca
GET_DEF 0x00000000 0x00000000

Kontrol: GOOGXU_PAN_TILT_RELATIVE

Kontrol pemetaan bantu geser dan kemiringan didefinisikan dalam Bab 4: Permintaan Khusus Kelas Bagian 4.2.2.1.15 Kontrol PanTilt (Relatif) untuk Spesifikasi Class UVC 1.5.

Pemilih kontrol 9
Operasi GET/SET
wLength 4
Offset Kolom Ukuran Nilai Deskripsi
0 bPanRelative 1 Nomor yang Ditandatangani Setelan untuk atribut Kontrol Geser (Relatif) yang dialamatkan:
0: Berhenti
1: bergerak ke arah searah jarum jam
0xFF: bergerak ke arah berlawanan arah jarum jam
1 bPanSpeed 1 Angka Kecepatan gerakan geser.
2 bTiltRelative 1 Nomor yang Ditandatangani Setelan untuk atribut Kontrol Kemiringan (Relatif) yang dialamatkan:
0: Hentikan
1: arahkan bidang pencitraan ke atas
0xFF: arahkan bidang pencitraan ke bawah
3 bTiltSpeed 1 Angka Kecepatan gerakan kemiringan.

Perilaku jenis permintaan yang didukung adalah sebagai berikut:>

Offset 0 1 2 3 Deskripsi
GET_MIN Tergantung kamera
GET_MAX Tergantung kamera
GET_RES Tergantung kamera
GET_LEN 0x04 0x00 0x0004
GET_INFO 0x0 M Update Otomatis / Tulis / Baca
GET_DEF 0x00 0x00 0x00 0x00

Catatan rilis

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

15 November 2023

Memperbarui skrip pengujian untuk memeriksa dan menafsirkan mode framing yang valid. Representasi byte yang diklarifikasi.

21 Juli 2023

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

25 Mei 2023

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

17 April 2023

Rilis awal.