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

Bu belgede, Google Meet konferans sistemleri tarafından akıllı kamera özelliklerini etkinleştirmek için kullanılan desteklenen USB Video Sınıfı Uzatma Birimi (XU) API'leri açıklanmaktadır. Bu spesifikasyonun oluşturulmasının amacı, bu özellikleri etkinleştirmek için uygulamaları etkilemek ve iş ortaklarımız için daha iyi eşzamansız ölçeklenebilirlik ve test olanağı sağlamaktır.

Bu dokümanda yapılan son değişikliklerle ilgili ayrıntılar için Sürüm notlarına göz atın.

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 olanağı sunuyoruz. Dosya sistemine yazma özelliğini etkinleştirin. /etc/chrome_dev.conf dosyasına aşağıdaki satırları ekleyin:

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

Cihazı yeniden başlatın, kamerayı ve bir USB klavyeyi bağlayın, Ctrl-Alt-X tuşuna basın. Etkin kameranın spesifikasyonlara uygunluğu test edilir ve /home/chronos/user/log/chrome dosyasına kaydedilir.

Küçük uçlu gösterim

USB, küçük endian standarttır. Bu dokümanda:

  • Çok baytlı sayılar büyük endian olarak görünür (ve küçük endian olarak iletilir).
  • Bayt dizileri küçük endian bellek düzenindedir.

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

Uzantı birimi GUID'si

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

Uzatma birimi GUID
Çevre Birimi Kontrol 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 Bölüm 4: Sınıfa Özel İstekler bölümünde tanımlanmıştı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 aşağıdakilerden biri olabilir:

  • Strateji (kamera görünümü)
  • Önyargı (hoparlör 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ı kadraj özelliklerini devre dışı bırakır ve istemcinin PTZ değerlerini özgürce 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) Kamera, çerçeveleme önyargısıyla odadaki kişileri sürekli olarak izler.
Bölünmüş kareler Kamera, gerektiği kadar video görüntüleme oluşturur. Otomatik kadrajlama feed'leri seçeneğine bağlı olarak, feed'leri tek bir akışta karolar halinde oluşturur 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üntüsünü sunmaya çalışır. Birden fazla feed'in tek bir feed halinde birleştirilip birleştirilmeyeceğ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üşmedeki odadaki katılımcıları en eşit şekilde görüntülemektir.
Tedarikçinin tercihi Kamera sistemi, odanın en iyi görüntüsü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 sunucu" ile "Ortak çalışma" toplantısı arasındaki farkı algılayabilirse sistem, bu modda çerçeveleme stratejisini uygun gördüğü şekilde uyarlayabilir veya değiştirebilir. Bu moddayken 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
Riskli Konuşmacı (Konuşmacı İzleme) Kamera, odada aktif olarak konuşan kişiyi en iyi şekilde kadraja almaya çalışır.
Bu senaryoda kamera, sunucunun bulunduğu tarafa doğru eğilmelidir. Örneğin, yönetim kurulu odasında sunum yapan CEO.
Ortak çalışma
(Oda İzleme)		 Kamera, odadaki tüm katılımcıları en iyi şekilde çerçevelemeye çalışır. Bu senaryoda kamera, her katılımcıyı eşit şekilde göstermelidir.

Otomatik kadraja alma 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öler ve sunucunun göndereceği birden fazla video akışı oluşturur.
Not: Bu özelliğin tam spesifikasyonu ve beklenen davranışı incelenmeyi beklemektedir ve bu dokümanın sonraki düzeltmelerine kadar desteklenmemektedir.

Otomatik çerçeveleme modu bitmap değerleri

Boş bir bayt dizisiyle temsil edilen None varsayılan durumu hariç olmak üzere, bayt dizisindeki her bit farklı bir kamera modunu temsil eder. Bu mod, otomatik kadraj stratejisi, otomatik kadraj yönü ve otomatik kadraj feed'lerinin belirli bir kombinasyonudur.

Otomatik kadraja alma feed'leri CAZ Bölünmüş çerçeve Dinamik Tedarikçinin tercihi Otomatik çerçeveleme önyargısı
Tek Akış D1
D2		 -
D3		 D5
D7		 D9 (hoparlör veya oda) Konuşmacı
Oda
Çoklu yayın -
-		 -
D4		 D6
D8		 - Konuşmacı
Oda
Çerçeve modları Çerçeve modu değeri (en az önemli 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 denetim, Otomatik çerçeveleme modu bitmap değerleri bölümünde listelenen kamera çerçeveleme modlarını almak veya ayarlamak için kullanılır. Her mod, ilgili bitmap'te bir bit olarak temsil edilir. GET_RES komutu, özelliğin cihaz tarafından desteklenip desteklenmediğini 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 modlarını destekliyorsa 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 TEK kamera modunun etkinleştirileceğini bildirmek için bitmap göndermek amacıyla 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 Etkin çerçeveleme kamera modunu alma
GET_MIN Kameraya bağlı
GET_MAX Kameraya bağlı
GET_RES Desteklenen kamera modlarının 8 bayt uzunluğunda bir 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 Kadrajlama Kamera modunu ayarlama

Kontrol: GOOGXU_REFRAME

Bu kontrol, OTAZ olarak da bilinen tek seferlik kadraj ayarını 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 seferlik kadraj belirleme 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 Yeniden çerçeveleme isteğini yürüt

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 seferlik 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ışı ve kamera video akışı ile kamera LED göstergesiyle olan etkileşimleri gösterilmektedir.

Doluluk durumu sayımı şu durumlarda: 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 Akış yapılmıyor ve ses kapatılmadı Açık 0x01 Kameranın tam görüş alanındaki kişilerin sayısı.
Açık Canlı Yayın Açık 0x01 Kameranın tam görüş alanındaki kişilerin sayısı.
Açık Sesin kapatıldığını Kapalı 0x01 Kapalı
Kapalı Akış yapılmıyor ve ses kapatılmadı 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 denetim, bir odadaki kullanıcı sayısını sayma özelliğini etkinleştirmek veya devre dışı bırakmak için kullanılır. Sıfır (0) değerini ayarladığınızda bu özellik devre dışı bırakılır, bir (1) değerini ayarladığınızda ise bu özellik etkinleştirilir. 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 sayma işlevini ayarlama
0x00 İşlevi kapat
0x01 İşlevi aç

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

Göreli konum 0 Açıklama
GET_CUR Doluluk sayımı açıksa döndürme
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 sayımı özelliğini etkinleştirme veya devre dışı bırakma

Kontrol: GOOGXU_OCCUPANCY_COUNTING_READ

Bu denetim, doluluk sayımı etkinleştirildiğinde kamera tarafından bildirilen bir odadaki katılımcı sayısını okumak için kullanılır. Doluluk sayımı devre dışı bırakıldığında kamera bu kontrolü devre dışı bırakı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üntüdeki 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 Tespit edilen kullanıcıların sayısını döndürme
GET_MIN 0x0000
GET_MAX 0x00FF
GET_RES 0x0001
GET_LEN 0x0002
GET_INFO 0x09 Otomatik güncelleme / okuma
GET_DEF 0x0000

Cihaz telemetrisi ve teşhisi

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

Kontrol: GOOGXU_STATUS_INFO

Bu kontrol, ana kameradan alınan bilgileri sorgulayarak hata ayıklama amacıyla iş ortaklarıyla paylaşmak 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ştayken 0, PTZ değerleri değişirken sıfır olmayan bir değerdir. Tedarikçi firmalar, farklı eksenleri veya motorları farklı bitlerle eşleyebilir.
2 Undef 6 Undef Gelecekte uzatılacak.

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 Otomatik güncelleme / okuma
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 yuva içerir. Her bir slot aşağıdaki gibi açıklanır:
Göreli konum Açıklama
0 Bu uydu türü için miktar.
1-2 Bu uydu türünün tedarikçi firma kimliği.
3-4 Bu uydu türü için ü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 Otomatik güncelleme / okuma
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. Bir (1) değerini ayarlamak, kameranın sıfırlanmasını ister. Son sıfırlamadan bu yana kamerayı yeniden başlatma isteği gönderilmemişse kamera sıfır (0) değerini, 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, USB bağlantısını zorlayıp hotplug taklit etmenin yararlı olmadığı kendinden güç alan 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 Ana cihaza 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 değerini 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. Mevcut kaydırma, eğme ve yakınlaştırma değerlerini sağlanan önceden ayarlanmış bir dizinle eşlemek için bir (1) değerinin ayarlanması kullanılır. İki (2) değerini ayarlamak, kameranın yatay kaydırma, dikey kaydırma ve yakınlaştırma ayarlarını, sağlanan dizin için önceden eşlenmiş değerlere veya varsayılan fabrika koordinatlarına (daha önce eşlenmemişse) geçirir. Üç (3) değerini ayarlamak, dizini fabrika varsayılan koordinatlarına sıfırlar.

Preset Index, dizinle eşlenen PTZ koordinatlarını belirtmek için kullanılır. Sıfır (0) olan Preset index, ev koordinatlarıyla eşlenir ve GOOGXU_FRAME_STRATEGY NONE olarak ayarlandığında kameranın uyanma sırasındaki 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ı kaydet
0x02: Hazır ayarı geri yükle
0x03: Hazır ayarı varsayılan ayarlarına sıfırla. (Varsayılan değer, geçerli bir hazır 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, hazır ayar sayısı için tedarikçi firma 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 N maksimum hazır ayar desteklenir.
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 Yalnızca yazma
GET_DEF 0x00 0x00

Yatay kaydırma ve yatırma yardımcı eşleme

Bazı kameralarda mekanik kameralar için motorlar veya dijital PTZ özellikleri gibi özel bileşenler bulunur. Bunlar için 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ı)

Pan ve tilt yardımcı eşleme kontrolleri, UVC 1.5 Sınıf Spesifikasyonu Bölüm 4: Sınıfa Özel İstekler Bölüm 4.2.2.1.14 PanTilt (Mutlak) Kontrolü'nde tanımlanmıştır.

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

Kaydırma ve eğme yardımcı eşleme kontrolleri, UVC 1.5 Sınıf Spesifikasyonu Bölüm 4: Sınıfa Özel İstekler Bölüm 4.2.2.1.15 PanTilt (İlişkili) Kontrolü'nde tanımlanmıştır.

Sürüm notları

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

27 Ocak 2025

21 Mayıs 2024

15 Kasım 2023

Geçerli kadraj modlarını kontrol edip yorumlamak için test komut dosyası güncellendi. Açıklanmış bayt temsilleri.

21 Temmuz 2023

İş ortaklarının bu spesifikasyona uygunluk açısından uygulamalarını doğrulaması için test komut dosyası eklendi.

25 Mayıs 2023

Hazır ayarların sayısıyla ilgili GOOGXU_PRESETS not düzeltildi. N-1 değil, N olmalıdır.

17 Nisan 2023

İlk sürüm.