Google Meet Donanım USB Video Sınıfı Uzantı Birimi API'leri

Bu belgede, Google Meet konferans sistemlerinin akıllı kamera özelliklerini etkinleştirmek için kullandığı desteklenen USB Video Class Extension Unit (XU) API'leri açıklanmaktadır. Bu spesifikasyonu oluşturmanın amacı, bu özelliklerin etkinleştirilmesini sağlamak için uygulamaları etkilemek ve iş ortaklarımızın daha iyi eşzamansız ölçeklenebilirlik ve test yapmasına olanak tanımaktır.

Bu dokümanda yapılan en son değişikliklerle ilgili ayrıntılar için Sürüm notları'na gidin.

Test tesisi

İş ortaklarının bu spesifikasyona uygunluğu doğrulamasına yardımcı olmak için geliştirici modunda ayarlanmış Chromebox video konferans cihazlarında bir test tesisi sunuyoruz. Dosya sistemine yazmayı etkinleştirin. Aşağıdaki satırları /etc/chrome_dev.conf dosyasına ekleyin:

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

Cihazı yeniden başlatın, kamerayı ve USB klavyeyi bağlayın, Ctrl-Alt-X tuşuna basın. Etkin kameranın spesifikasyon uyumluluğu uygulanır ve /var/log/chrome/chrome konumuna kaydedilir (imzalı bir görüntü kullanılıyorsa /home/chronos/user/log/chrome).

Little-endian kuralı

USB, little-endian standardıdır. Bu belgede:

  • Çok baytlı sayılar big-endian olarak görünür (ve little-endian olarak iletilir).
  • Bayt dizileri, little-endian bellek düzenindedir.

Örneğin, 0x12345678 ile [0x78, 0x56, 0x34, 0x12] aynıdır.

Uzantı birimi GUID'si

Bu Meet XU kontrol spesifikasyonunu destekleyen uzantı birimleri bu GUID'yi kullanmalıdır.

Uzantı Birimi GUID
Peripheral Control XU {74D7E924-49C9-4A45-98A3-8A9F60061E83}

Çevre birimi kontrolü XU seçicileri

Bunlar, tanımlanmış çevre birimi kontrolü XU seçicileridir.

Kontrol seçicileri Değer
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

Kontrol isteği türü

Kontrol isteği türleri, UVC 1.5 Sınıfı Spesifikasyonu'nun 4. Bölümü: Sınıfa Özgü İstekler'de tanımlanır.

İşlem UVC kontrolü
GET GET_CUR, GET_MIN, GET_MAX, GET_RES, GET_LEN, GET_INFO, GET_DEF
SET SET_CUR

Kamera modları

Kamera modları, toplantı odasındaki kişileri kadraja almak için kullanılır ve tuple şunlardan oluşur:

  • Strateji (kamera görünümü)
  • Önyargı (konuşmacı veya oda)
  • Feed'ler (tek veya birden fazla akış)

Her boyut, aşağıdaki bölümlerde açıklanan değerleri alabilir.

Otomatik çerçeveleme stratejisi

"Yok" dışındaki tüm otomatik çerçeveleme modlarında manuel kaydırma, eğme ve yakınlaştırma devre dışıdır.

Özellik Açıklama
Yok Kamera, tüm akıllı çerçeveleme özelliklerini devre dışı bırakır ve istemcinin PTZ değerlerini serbestçe kontrol etmesine olanak tanır.
Not: Bu çerçeveleme stratejisine ayarlandığında kamera, mevcut kaydırma, yatırma ve yakınlaştırma konumunda kalır.
Kesintisiz Çerçeveleme (CAZ) Çerçeveleme önyargısına göre kamera, odadaki kişileri sürekli olarak takip eder.
Bölünmüş Çerçeveler Kamera, gerektiği kadar video görünümü oluşturur. Otomatik çerçeveleme feed'leri seçeneğine bağlı olarak, bunları tek bir akışta kutucuklar halinde birleştirir veya her görünüm için ayrı video akışları oluşturur.
Dinamik Görünüm Bir veya daha fazla kamera, odanın en iyi görünümünü sağlamaya çalışır. Birden fazla feed'i tek bir feed'de birleştirip birleştirmeyeceğine veya mevcut odanın "ilginç" bir görünümünü sağlayıp sağlamayacağına karar verebilir.
Bu görünümün amacı, görüşmeye odada katılan katılımcıların en adil şekilde gösterilmesini sağlamaktır.
Tedarikçi tercihli Kamera sistemi, odanın en iyi görünümünü belirlemek için kendi mantığını kullanır. Temel çerçeveleme stratejisi, bildirimde bulunulmaksızın değiştirilebilir. Örneğin, odadaki kişi sayısı değişirse veya kamera "önemli bir sunum" ile "işbirliği" toplantısı arasındaki farkı algılayabilirse sistem, bu modda uygun gördüğü şekilde çerçeveleme stratejisini uyarlayabilir veya değiştirebilir. Bu modda, getCur çağrısı, sistem tarafından seçilen temel kadraj modunu değil, VENDOR_PREFERRED değerini döndürmelidir.

Otomatik çerçeveleme önyargısı

Özellik Açıklama
Önemli Sunum Yapan Kişi (Konuşmacı Takibi) Kamera, odada aktif olarak konuşan kişiyi en iyi şekilde kadrajlamaya çalışır.
Bu senaryoda kamera, sunucuya odaklanmalıdır. Örneğin, bir toplantı odasında sunum yapan CEO.
Ortak çalışma
(Oda Takibi)		 Kamera, odadaki tüm katılımcıları en iyi şekilde kadrajlamaya çalışır. Bu senaryoda kamera, her katılımcıya eşit davranmalıdır.

Otomatik çerçeveleme feed'leri

Özellik Açıklama
Tek Akış Kamera, ana cihaza tek bir video akışı gönderir.
Çoklu Yayın
(Devam Eden Çalışma)		 Kamera, yayını bölerek ana bilgisayara gönderilecek birden fazla video yayını oluşturur.
Not: Bu özelliğin tam spesifikasyonu ve beklenen davranışı inceleme aşamasındadır ve bu belgenin sonraki revizyonlarına kadar desteklenmez.

Otomatik çerçeveleme modu bit eşlem değerleri

Boş bir bayt dizisiyle temsil edilen None varsayılan durumu hariç olmak üzere, bayt dizisindeki her bit, Otomatik çerçeveleme stratejisi, Otomatik çerçeveleme önyargısı ve Otomatik çerçeveleme feed'leri'nin belirli bir kombinasyonu olan farklı bir kamera modunu temsil eder.

Otomatik çerçeveleme feed'leri CAZ Bölünmüş Çerçeve Dinamik Tedarikçi tercihli Otomatik çerçeveleme önyargısı
Tek Akış (Single-Stream) D1
D2		 -
D3		 D5
D7		 D9 (hoparlör veya oda) Hoparlör
Oda
Çoklu akış (Multi-Stream) -
-		 -
D4		 D6
D8		 - Hoparlör
Oda
Çerçeve modları Kare modu değeri (en az anlamlı bayt)
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

Bu kontrol, kameranın Otomatik çerçeveleme modu bit eşlem değerleri bölümünde listelenen çerçeveleme modlarını almak veya ayarlamak için kullanılır. Her mod, kendi bit eşleminde bir bit olarak gösterilir. GET_RES komutu, özelliğin cihaz tarafından desteklenip desteklenmediğini belirtmek için sırasıyla sıfır (0) veya bir (1) değerine sahip 8 bayt uzunluğunda bir bit maskesi döndürür. Örneğin, bir kamera CAZ, Speaker, Single-Stream, Split-Frame, Room, Single-Stream ve Dynamic, Room, Multi-Stream'ı destekliyor ancak başka modları desteklemiyorsa GET_RES, 0x000000000000000085 değerini (yani 0b10000101 ve ardından yedi sıfır baytı) döndürmelidir.

SET_CUR komutu, kameraya hangi SINGLE kamera modunun etkinleştirileceğini bildirmek için bit eşlemler göndermek üzere kullanılır.

Kontrol seçici 1
İşlem GET / SET
wLength 8
Göreli konum Alan Boyut Değer Açıklama
0 bActiveMode 8 Bit eşlem Etkin kamera modunu ayarlama veya geri döndürme
Notlar:

Desteklenen istek türlerinin davranışı aşağıdaki gibidir:

Göreli konum 0 Açıklama
GET_CUR Aktif çerçeveleme kamera modunu kullanma
GET_MIN Kameraya bağlı
GET_MAX Kameraya bağlı
GET_RES Desteklenen kamera modlarının 8 bayt uzunluğunda bit maskesini döndürür.
GET_LEN 0x0008 Uzunluk
GET_INFO 0x0B Otomatik Güncelleme / Yazma / Okuma
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 Varsayılan değer
SET_CUR Aktif Kadraj Kamera modunu ayarlama

Kontrol: GOOGXU_REFRAME

Bu kontrol, OTAZ olarak da bilinen tek çekim çerçevelemeyi tetiklemek için kullanılır. OTAZ tetiklendiğinde kamera görünümü, odanın en iyi görünümüne geçer. Ardından, istemci PTZ değerlerini kontrol etme özelliğini yeniden kazanır. Tek çekim çerçeveleme desteklenmiyorsa kamera bu kontrolü tanımlamamalıdır.

Kontrol seçici 2
İşlem SET
wLength 1
Göreli konum Alan Boyut Değer Açıklama
0 bReframe 1 Sayı 0x01 Execute Reframe Request

Desteklenen istek türlerinin davranışı aşağıdaki gibidir:

Göreli konum 0 Açıklama
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x02 Yalnızca Yazma
GET_DEF 0x00
SET_CUR Tek çekim kadraj için istek ayarlama

Doluluk sayımı

Doluluk sayımı (DS), kameranın kırpılmış görünümüne rağmen bir toplantı odasındaki katılımcı sayısını tahmin etmek için kullanılan bir özelliktir.

Bu tabloda, OC kontrollerinin beklenen davranışı ile kamera video akışı ve kamera LED göstergesiyle etkileşimleri gösterilmektedir.

Doluluk durumu sayımı ve kamera video akışı: Kamera LED göstergesi GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR olmalıdır. GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR olmalıdır.
Açık Yayın yapılmıyor ve ses kapatılmamış Açık 0x01 Kameranın tam görüş alanındaki kişi sayısı.
Açık Canlı Yayın Açık 0x01 Kameranın tam görüş alanındaki kişi sayısı.
Açık Sesin kapatıldığını Kapalı 0x01 Kapalı
Kapalı Yayın yapılmıyor ve ses kapatılmamış Kapalı 0x00 Kapalı
Kapalı Canlı Yayın Açık 0x00 Kapalı
Kapalı Sesin kapatıldığını Kapalı 0x00 Kapalı

Kontrol: GOOGXU_OCCUPANCY_COUNTING_TOGGLE

Bu kontrol, bir odadaki kişileri sayma özelliğini etkinleştirmek veya devre dışı bırakmak için kullanılır. Değerin sıfır (0) olarak ayarlanması bu özelliği devre dışı bırakır, bir (1) olarak ayarlanması ise etkinleştirir. Bu özellik desteklenmiyorsa kamera bu kontrolü tanımlamamalıdır.

Kontrol seçici 3
İşlem GET / SET
wLength 1
Göreli konum Alan Boyut Değer Açıklama
0 bOccupancy 1 Boole Doluluk durumu sayma işlevini ayarlama
0x00 İşlevi devre dışı bırakma
0x01 İşlevi etkinleştirme

Desteklenen istek türlerinin davranışı aşağıdaki gibidir:

Göreli konum 0 Açıklama
GET_CUR Doluluk durumu sayımı etkinse döndürür.
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x0B Otomatik Güncelleme / Yazma / Okuma
GET_DEF 0x00
SET_CUR Doluluk durumu sayımı özelliğini etkinleştirme veya devre dışı bırakma

Kontrol: GOOGXU_OCCUPANCY_COUNTING_READ

Bu kontrol, doluluk sayımı etkinleştirildiğinde kamera tarafından bildirilen bir odadaki katılımcı sayısını okumak için kullanılır. Kişi sayısı özelliği devre dışı bırakıldığında kamera bu kontrolü devre dışı bırakmalıdır. Doluluk sayımı desteklenmiyorsa kamera bu kontrolü tanımlamamalıdır.

Kontrol seçici 4
İşlem GET
wLength 2
Göreli konum Alan Boyut Değer Açıklama
0 bNumPeople 2 Sayı Görünümdeki algılanan kişi sayısı. (Salt Okunur)

Desteklenen istek türlerinin davranışı aşağıdaki gibidir:

Göreli konum 0 Açıklama
GET_CUR Algılanan yolcu sayısını döndürür.
GET_MIN 0x0000
GET_MAX 0x00FF
GET_RES 0x0001
GET_LEN 0x0002
GET_INFO 0x09 AutoUpdate / Read
GET_DEF 0x0000

Cihaz telemetrisi ve teşhis bilgileri

Bu kontroller, Meet Donanım ile daha iyi hata ayıklama uygulamalarını teşvik etmek için tasarlanmıştır ve genellikle kullanıcıya yönelik değildir.

Kontrol: GOOGXU_STATUS_INFO

Bu kontrol, hata ayıklama amacıyla iş ortaklarıyla paylaşılacak bilgileri ana kameradan sorgulamak için kullanılır.

Kontrol seçici 5
İşlem GET
wLength 8
Göreli konum Alan Boyut Değer Açıklama
0 bNumCameras 1 Sayı Ana kameraya bağlı ve ana makineye döndürülen kamera akışını etkileyebilecek ek uydu sayısı.
1 bIsMoving 1 Bit eşlem Kamera boşta olduğunda 0, PTZ değerleri değiştiğinde ise sıfır olmayan bir değer. Tedarikçiler, farklı eksenleri veya motorları farklı bitlere eşleyebilir.
2 Undef 6 Undef Gelecekte bu özellik daha fazla kullanıcıya sunulacaktır.

Desteklenen istek türlerinin davranışı aşağıdaki gibidir:

Göreli konum 0 1 2 Açıklama
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

Bu kontrol, bu kamera sistemine bağlı uydu cihazlarını sorgulamak için kullanılır.

Kontrol seçici 0x0A
İşlem GET
wLength 20
Göreli konum Alan Boyut Değer Açıklama
0 bSatelliteList 20 Bit eşlem Sisteme bağlı uydu türlerinin listesi. Dört ayrı 5 baytlık alan içerir. Her bir yuva aşağıdaki gibi açıklanmıştır:
Göreli konum Açıklama
0 Bu uydu türünün miktarı.
1-2 Bu uydu türünün tedarikçi kimliği.
3-4 Bu uydu türünün ürün kimliği.

Desteklenen istek türlerinin davranışı aşağıdaki gibidir:

Göreli konum 0 Açıklama
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 bayt
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

Bu kontrol, kameraya sıfırlama isteği göndermek için kullanılır. Değeri bir (1) olarak ayarlamak kameranın sıfırlanmasını ister. Son sıfırlamadan bu yana kamerayı yeniden başlatma isteği olmadıysa kamera sıfır (0), sıfırlanıyorsa bir (1) değerini döndürür. Sıfırlama işlemi, kameranın yeniden başlatılmasını tetiklemelidir. (Bu, sıcak takmayı taklit etmek için USB bağlantısının kesilmesini zorlamanın yararlı olmadığı, kendi kendine çalışan cihazlar için gereklidir.)

Kontrol seçici 6
İşlem GET / SET
wLength 1
Göreli konum Alan Boyut Değer Açıklama
0 bResetRequest 1 Boole Toplantıyı düzenleyen kullanıcıya ve bağlı kameralara sıfırlama isteği gönderin.
Son sıfırlamadan sonra sıfırlama isteği gönderildiyse 0x01, aksi takdirde 0x00 döndürür.

Desteklenen istek türlerinin davranışı aşağıdaki gibidir:

Göreli konum 0 Açıklama
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x03 Yazma / Okuma
GET_DEF 0x00

PTZ hazır ayarları

Kameranın görüş alanını yapılandırmak ve önceden ayarlanmış bir konuma geri yüklemek için kullanılır.

Kontrol: GOOGXU_PRESETS

Bu kontrol, kameranın kaydırma, eğme ve yakınlaştırma (PTZ) değerlerini önceden ayarlanmış bir yapılandırmaya ayarlamak için kullanılır.

Preset Action, komutun amaçlanan işlemini belirtmek için kullanılır. Bir (1) değeri, mevcut kaydırma, eğme ve yakınlaştırma değerlerini sağlanan bir hazır ayar dizinine eşlemek için kullanılır. İki (2) değeri ayarlandığında kameranın kaydırma, eğme ve yakınlaştırma işlevleri, sağlanan dizin için daha önce eşlenen değerlere veya varsayılan fabrika koordinatlarına (daha önce eşlenmemişse) geçiş yapmalıdır. Üç (3) değeri ayarlandığında dizin, fabrika varsayılan koordinatlarına sıfırlanır.

Preset Index, dizinle eşlenen PTZ koordinatlarını belirtmek için kullanılır. Sıfır (0) Preset index değeri, başlangıç koordinatlarıyla eşlenir ve GOOGXU_FRAME_STRATEGY değeri NONE olarak ayarlandığında kameranın uyandığı andaki varsayılan konumu olmalıdır.

Kontrol seçici 7
İşlem SET
wLength 2
Göreli konum Alan Boyut Değer Açıklama
0 bPresetAction 1 Sayı 0x01: Hazır ayarı kaydetme
0x02: Hazır ayarı geri yükleme
0x03: Hazır ayarı varsayılana sıfırlama (Varsayılan değer, geçerli bir önceden ayarlanmış koordinat olmalıdır.)
1 bPresetIndex 1 Sayı Etkin hazır ayar dizini. 0~N-1
Burada 0, varsayılan kamera başlangıç konumu olarak kabul edilir ve N-1, ön ayar sayısı için satıcı tarafından tanımlanan bir sabittir.

Desteklenen istek türlerinin davranışı aşağıdaki gibidir:

Göreli konum 0 1 Açıklama
GET_MIN 0x00 0x00
GET_MAX 0x03 N-1 Desteklenen maksimum hazır ayar sayısı
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 Yalnızca yazma
GET_DEF 0x00 0x00

Yardımcı haritalamayı kaydırma ve eğme

Bazı kameralarda özel bileşenler (ör. mekanik kameralar için motorlar) veya dijital PTZ özellikleri bulunur. Bu tür kameralarda kaydırma, eğme ve yakınlaştırma için standart V4L2 kontrollerini kullanın.

Kontrol: GOOGXU_PAN_TILT_ABSOLUTE (desteği sonlandırıldı)

Yardımcı eşleme kontrolleri olan kaydırma ve eğme, UVC 1.5 Sınıf Spesifikasyonu Bölüm 4: Sınıfa Özgü İstekler, Bölüm 4.2.2.1.14 PanTilt (Mutlak) Kontrolü'nde tanımlanır.

Kontrol: GOOGXU_PAN_TILT_RELATIVE (desteği sonlandırıldı)

Kaydırma ve eğme yardımcı eşleme kontrolleri, UVC 1.5 Class Specification'ın Bölüm 4: Sınıfa Özel İstekler Bölüm 4.2.2.1.15 PanTilt (Relative) Control bölümünde tanımlanır.

Sürüm notları

Bu sürüm notları, bu dokümanın her düzeltmesindeki iyileştirmeleri ve yeni özellikleri açıklamaktadır.

13 Ağustos 2025

27 Ocak 2025

21 Mayıs 2024

15 Kasım 2023

Geçerli çerçeveleme modlarını kontrol edip yorumlamak için test komut dosyası güncellendi. Bayt gösterimleri netleştirildi.

21 Temmuz 2023

İş ortaklarının bu spesifikasyona uygunluk için uygulamaları doğrulamasına yönelik test komut dosyası eklendi.

25 Mayıs 2023

Düzeltildi GOOGXU_PRESETS Hazır ayar sayısı ile ilgili not. N-1 değil, N olmalıdır.

17 Nisan 2023

İlk sürüm.