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

Bu dokümanda, Google Meet konferans sistemleri tarafından akıllı kamera özelliklerini etkinleştirmek için kullanılan desteklenen USB Video Class Extension Unit (XU) API'leri açıklanmaktadır. Bu spesifikasyonu oluşturmanın amacı, bu özellikleri etkinleştirmeye yönelik uygulamaları etkilemek ve iş ortaklarımız için daha iyi eşzamansız ölçeklenebilirlik ve testler yapılmasını sağlamaktır.

İş ortaklarının bu spesifikasyona uygunluğunu doğrulamasına yardımcı olmak için bu test komut dosyası, uygulamanızı analiz edip raporlar.

Bu belgede yapılan son değişiklikler hakkında ayrıntılı bilgi için Sürüm notları'na gidin.

Little-endian kongresi

USB bir küçük endian standardıdır. Bu dokümanda:

  • Çok baytlı sayılar büyük uç olarak görünür (ve küçük uçlara iletilir).
  • Bayt dizileri, küçük uç 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.

Uzantı Birimi GUID
Çevre Birimi Kontrol XU {74D7E924-49C9-4A45-98A3-8A9F60061E83}

Çevre birimi denetimi XU seçicileri

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

Seçicileri kontrol et 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

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 Ö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 çerçevelemek için kullanılır ve şunlardan tuple tanesidir:

  • Strateji (kamera görünümü)
  • Yanlı olma (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

Öne Çıkarın 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 kadraj stratejisine ayarlandığında, kamera mevcut kaydırma, yatırma ve yakınlaştırma konumunda kalır.
Sürekli Çerçeveleme (CAZ) Kamera, kadraj ayarındaki yanlılığa bağlı olarak odadaki kişileri sürekli olarak takip eder.
Not: PTZ, bu modda devre dışıdır.
Çerçeveleri Böl Kamera gerektiği kadar video görüntülemesi oluşturur. Feed'leri otomatik çerçeveleme seçeneğine bağlı olarak, bu özellik tek bir akışta karolar halinde veya her görünüm için ayrı video akışları oluşturur.
Not: PTZ, bu modda devre dışıdır.
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'in bir feed'de birleştirilip birleştirilmeyeceğine karar verebilir veya geçerli odanın "ilginç" bir görünümünü sunabilir.
Bu görünümün amacı, odadaki katılımcıların görüşmede en adil şekilde görünümünü sağlamaktır.
Notlar:
  • Çoğu toplantıda bu strateji kullanılmalıdır.
  • PTZ, bu modda devre dışı bırakılır.

Otomatik çerçeveleme ağırlıklandırması

Öne Çıkarın Açıklama
Riskli Sunucu (Konuşmacı İzleme) Kamera, odada aktif olarak konuşan kişiyi en iyi şekilde çerçevelemeye çalışır.
Bu senaryoda kamera, sunucuya yönelmelidir. Örneğin, yönetim kurulunda 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ıya eşit davranmalıdır. Çoğu toplantıda bu strateji kullanılmalıdır.

Feed'leri otomatik çerçeveleme

Öne Çıkarın Açıklama
Tek Yayın Kamera, ana cihaza tek bir video akışı gönderir.
Çoklu Yayın
(Devam Eden Çalışma)		 Kamera, yayını böler ve düzenleyene göndermek üzere birden çok video akışı oluşturur.
Not: Bu özelliğin tam spesifikasyonu ve beklenen davranışı incelenmeyi beklemektedir ve bu belgenin sonraki düzeltmelerine kadar desteklenmeyecektir.

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

Boş bir bayt dizisiyle temsil edilen varsayılan None durumu dışında, bayt dizisindeki her bit farklı bir kamera modunu temsil eder. Bu mod; Otomatik çerçeveleme stratejisi, Otomatik çerçeveleme sapmaları ve Otomatik çerçeveleme feed'lerinin belirli bir kombinasyonudur.

Bit dizini CAZ Bölünmüş Çerçeve Dinamik -
Hoparlör 1. Gün
-		 -
-		 D5
D6		 Tek Yayın
Çoklu Yayın
Oda 2. Gün
-		 D3
D4		 7. Gün
D8		 Tek Yayın
Çoklu Yayın
Kare modları Kare modu değeri (en az anlamlı bayt)
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

Bu kontrol, Otomatik çerçeveleme modu bit eşlem değerleri bölümünde listelendiği gibi kameranın çerçeveleme modlarını almak veya ayarlamak için kullanılır. Her mod, ilgili bit eşleminde bitler 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 modunu destekliyor ancak diğer modları desteklemiyorsa GET_RES, 0x000000000000000085 değerini döndürmelidir (ör. 0b10000101 ve ardından yedi sıfır bayt).

SET_CUR komutu, kameraya hangi TEK kamera modunun etkinleştirileceğini bildirmek üzere bit eşlemleri göndermek için 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 Aktif Kamera Modu'nu ayarlama veya 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 Modu'nu edinin
GET_MIN Kameraya bağlı
GET_MAX Kameraya bağlı
GET_RES Desteklenen kamera modlarının 8 bayt uzunluğunda bir bit maskesi döndürür
GET_LEN 0 x 0.008 Uzunluk
GET_INFO 0x0 Mr Otomatik Güncelleme / Yazma / Okuma
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 Varsayılan değer
SET_CUR Aktif Çerçeveleme Kamera modunu ayarlama

Kontrol: GOOGXU_REFRAME

Bu denetim, OTAZ olarak da bilinen Tek Çekimli Çerçeveleme'yi tetiklemek için kullanılır. OTAZ tetiklendiğinde, kamera görünümü odanın en iyi görünümüne tutturulur. Sonrasında istemci, PTZ değerlerini kontrol etme yetkisini yeniden kazanır. Tek çekim çerçeveleme desteklenmiyorsa bu kontrolü kamera 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 Yürütme Yeniden Çerçeve İsteği

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 Çerçeveleme isteği ayarla

Doluluk sayımı

Doluluk sayma (OC), kameranın kırpılmış görünümüne rağmen 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 etkileşimleri gösterilmektedir.

Doluluk Sayma: ve kamera video akışı: Kameranın LED göstergesi GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR şu olmalıdır: GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR şu olmalıdır:
Açık Canlı oynatı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 Sesi kapatılır. Kapalı 0x01 Kapatıldı
Kapatıldı Canlı oynatılmıyor ve ses kapatılmadı Kapalı 0x00 Kapatıldı
Kapatıldı Canlı Yayın Açık 0x00 Kapatıldı
Kapatıldı Sesi kapatılır. Kapalı 0x00 Kapatıldı

Kontrol: GOOGXU_OCCUPANCY_COUNTING_TOGGLE

Bu denetim, odadaki kişileri sayma özelliğini etkinleştirmek veya devre dışı bırakmak için kullanılır. Sıfır (0) değeri ayarlandığında bu özellik devre dışı bırakılır ve bir (1) bu özelliği 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 sayma işlevini ayarla
0x00 İşlevi kapat
0x01 İşlevi etkinleştir

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

Göreli konum 0 Açıklama
GET_CUR Doluluk sayma özelliği etkinse iade
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x0 Mr Otomatik Güncelleme / Yazma / Okuma
GET_DEF 0x00
SET_CUR Doluluk sayma ö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. Bu özellik devre dışı bırakılırsa kameranın bu kontrolü devre dışı bırakması gerekir. 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ı Ekranda tespit edilen kişi sayısıdır. (Salt Okunur)

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

Göreli konum 0 Açıklama
GET_CUR Algılanan konukların iade sayısı
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 kontrollerin amacı, Meet Donanım ile daha iyi hata ayıklama uygulamalarını teşvik etmektir ve genellikle kullanıcılara gösterilmez.

Kontrol: GOOGXU_STATUS_INFO

Bu kontrol, hata ayıklama amacıyla iş ortaklarıyla paylaşmak üzere ana makine kamerasından bilgi 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 cihaza takılı ek kameraların sayısı.
1 bIsMoving 1 Bit eşlem Kamera boştayken 0, hareket halindeyken ise sıfır değildir. Tedarikçiler farklı eksenleri veya motorları farklı bitlere eşleyebilir.
2 Undef 6 Belirlenmedi 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 0 x 0.008
GET_INFO 0x09 Otomatik Güncelleme / Okuma
GET_DEF 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00

Kontrol: GOOGXU_STATUS_RESET

Bu denetim, kameraya sıfırlama isteği göndermek için kullanılır. Bir (1) değeri ayarlanırsa kameranın sıfırlanması istenir. Kamera, son sıfırlamadan sonra kamerayı yeniden başlatma isteği gelmediyse sıfır (0) değerini ve sıfırlanıyorsa bir (1) değerini döndürür. Sıfırlama işlemi, donanımın yeniden bağlanmasıyla aynı davranışı tetikler. Bu, USB-bağlantısını kesmeye zorlamanın hotspot'a benzetilmesinin faydalı olmadığı, kendi kendine çalışan cihazlarda faydalıdır.

Kontrol seçici 6
İşlem GET / SET
wLength 1
Göreli konum Alan Boyut Değer Açıklama
0 bResetRequest 1 Boole Ana makineye 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ı önceden ayarlanmış konuma yapılandırmak ve geri yüklemek için kullanılır.

Kontrol: GOOGXU_PRESETS

Bu kontrol, kameranın kaydırma, yatırma ve yakınlaştırma (PTZ) değerlerini hazır ayar yapılandırmasına ayarlamak için kullanılır.

Preset Action, komutun amaçlanan işlemini belirtmek için kullanılır. Bir (1) değeri ayarlamak, geçerli kaydırma, yatırma ve yakınlaştırma değerlerini, sağlanan bir hazır ayar diziniyle eşlemek için kullanılır. İki (2) değerini ayarlamak, kameranın kaydırma, yatırma ve yakınlaştırma özelliklerini, sağlanan dizin için önceden eşlenen değerlere veya varsayılan fabrika koordinatlarına (daha önce eşlenmemişse) geçirmelidir. Üç (3) değerine ayarlanırsa 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ın (0) Preset index değeri, ev koordinatlarıyla eşlenir ve GOOGXU_FRAME_STRATEGY NONE değerine ayarlandığında kameranın uyanık kalma 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ılana sıfırla. (Varsayılan geçerli bir hazır ayar koordinatı olmalıdır.)
1 bPresetIndex 1 Sayı Etkin Hazır Ayar dizini. 0~N-1
Burada 0, varsayılan kamera başlangıç konumu, N-1 ise hazır ayar sayısı için tedarikçi tarafından tanımlanan bir sabit kabul edilir.

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 maks. hazır ayarı destekleniyor
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 Yalnızca yazma
GET_DEF 0x00 0x00

Kaydırma ve yatırma yardımcı haritalama

Bazı kameraların, mekanik kamera motorları gibi özel bileşenleri vardır. Bu bileşenler, istenen şekilde kaydırma ve yatırma için standart V4L2 kontrolleri üzerinde XU komutlarının eşleştirilmesini gerektirir.

Bu denetimler, UVC teknik belgelerindeki yatay kaydırma ve yatırmanın mutlak ve göreli kontrollerini taklit ederek ana cihazların bu kontrolleri doğru şekilde eşlemesi için standart bir yol sunar.

Kontrol: GOOGXU_PAN_TILT_ABSOLUTE

Kaydırma ve yatırma yardımcı haritalama denetimleri Bölüm 4: Sınıfa Özel Talepler Bölüm 4.2.2.1.14 UVC 1.5 Sınıfı Spesifikasyonu'nun Kaydırma (Mutlak) Kontrolü'nde tanımlanmıştır.

Kontrol seçici 8
İşlem GET/SET
wLength 8
Göreli konum Alan Boyut Değer Açıklama
0 dwPanAbsolute 4 İmzalı Numara Adreslendirilen Kaydırma (Mutlak) Denetimi'nin özelliği için ayar.
4 dwTiltAbsolute 4 İmzalı Numara Adresli Yatırma (Mutlak) Kontrolü özelliği için ayar.

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

Göreli konum 0 4 Açıklama
GET_MIN Kameraya bağlı
GET_MAX Kameraya bağlı
GET_RES Kameraya bağlı
GET_LEN 0 x 0.008
GET_INFO 0x0 Mr Otomatik Güncelleme / Yazma / Okuma
GET_DEF 0x00000000 0x00000000

Kontrol: GOOGXU_PAN_TILT_RELATIVE

Kaydırma ve yatırma yardımcı haritalama kontrolleri UVC 1.5 Sınıfı Spesifikasyonu'nun 4. Bölüm: Sınıfa Özel Talepler Bölüm 4.2.2.1.15 Kaydırma (Göreli) Kontrolü'nde tanımlanmıştır.

Kontrol seçici 9
İşlem GET/SET
wLength 4
Göreli konum Alan Boyut Değer Açıklama
0 bPanRelative 1 İmzalı Numara Adresli Kaydırma (Göreli) Denetimi özelliğinin ayarı:
0: Durdur
1: Saat yönüne
0xFF: Saat yönünün tersine gidiliyor
1 bPanSpeed 1 Sayı Kaydırma hareketinin hızı.
2 bTiltRelative 1 İmzalı Numara Adresli Yatırma (Göreli) Denetimi özelliğinin ayarı:
0: Dur
1: Görüntüleme düzlemini yukarı doğrult
0xFF: Görüntüleme düzlemini aşağı doğrult
3 bTiltSpeed 1 Sayı Eğme hareketinin hızı.

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

Göreli konum 0 1 2 3 Açıklama
GET_MIN Kameraya bağlı
GET_MAX Kameraya bağlı
GET_RES Kameraya bağlı
GET_LEN 0x04 0x00 0x0004
GET_INFO 0x0 Mr Otomatik Güncelleme / Yazma / Okuma
GET_DEF 0x00 0x00 0x00 0x00

Sürüm notları

Bu sürüm notları, bu belgenin her bir revizyonunda yapılan iyileştirmeleri ve yeni özellikleri yansıtmaktadır.

15 Kasım 2023

Geçerli çerçeveleme modlarını kontrol etmek ve yorumlamak için test komut dosyası güncellendi. Daha net bayt gösterimleri.

21 Temmuz 2023

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

25 Mayıs 2023

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

17 Nisan 2023

İlk sürüm.