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ümandaki en son değişikliklerle ilgili ayrıntılar için Sürüm notları bölümüne gidin.

Test merkezi

İş ortaklarının bu spesifikasyona uygunluğu doğrulamasına yardımcı olmak için geliştirici modunda ayarlanmış Chromebox for Meetings 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 Endiyans kongresi

USB, küçük endian standardıdı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 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.

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

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

Ö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.
Not: PTZ bu modda devre dışıdır.
Çerçeveleri böl 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.
Not: PTZ bu modda devre dışıdır.
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ın en eşitlik görünümünü sunmaktır.
Notlar:
  • Çoğu toplantıda bu strateji kullanılır.
  • PTZ bu modda devre dışıdır.

Otomatik çerçeveleme önyargısı

Özellik Açıklama
Yüksek riskli sunucu (Konuşmacı takibi) 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. Çoğu toplantıda bu strateji kullanılır.

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, akışı böler ve ana makineye gönderilmek üzere 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 bit eşlem 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 yanlılığı ve otomatik kadraj feed'lerinin belirli bir kombinasyonudur.

Bit dizini CAZ Bölünmüş çerçeve Dinamik -
Hoparlör D1
-		 -
-		 D5
D6		 Tek Akış
Çoklu Akış
Oda D2
-		 D3
D4		 D7
D8		 Tek Akış
Çoklu Akış
Çerçeve modları Çerçeve modu değeri (en az önemli 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 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 bit eşleminde 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 Çekim Kadrajını tetiklemek için kullanılır. OTAZ tetiklendiğinde, kamera görünümü odanın en iyi görünümüne uyum sağlar. Daha sonra, müşteri PTZ değerlerini kontrol etme becerisini yeniden kazanır. Tek seferlik ç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 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ı 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 kameranın bu kontrolü tanımlamaması gerekir.

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 ayarlayın
0x00 İşlevi devre dışı bırak
0x01 İşlevi etkinleştir

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 0x0.001
GET_INFO 0x0B Otomatik Güncelleme / Yazma / Okuma
GET_DEF 0x00
SET_CUR Doluluk durumu sayma ö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 0x0.001
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 için iş ortaklarıyla paylaşmak amacıyla 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 İleride 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_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ırlama işlemi devam ediyorsa bir (1) değerini döndürür. Sıfırlama işlemi, kameranın yeniden başlatılmasını tetiklemelidir. (Bu, hotspot emüle etmek için USB bağlantısını kesmenin işe yaramadığı 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 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ış bir konuma yapılandırmak ve 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ın (0) Preset index değeri ev koordinatlarıyla eşlenir ve GOOGXU_FRAME_STRATEGY NONE olarak ayarlandığında kameranın uyanık kalma durumunda 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 ayarlara 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

Yardımcı haritalama kaydırma ve yatırma

Bazı kameralarda mekanik kameralar için motorlar veya dijital PTZ özellikleri gibi özel bileşenler bulunur. Bunlar için kaydırma, yatırma ve yakınlaştırmaya yönelik standart V4L2 kontrollerini kullanın.

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

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 İstekler Bölüm 4.2.2.1.14 Kaydırma (Mutlak) Kontrolü'nde tanımlanmıştır.

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

Yatay kaydırma ve dikey kaydırma 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 Yatay Kaydırma ve Dikey Kaydırma (İ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.

21 Mayıs 2024

15 Kasım 2023

Geçerli çerçeveleme modlarını kontrol etmek ve yorumlamak için test komut dosyası güncellendi. Açıklanmış bayt temsilleri.

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 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.