API đơn vị mở rộng lớp video USB trên thiết bị Google Meet

Tài liệu này trình bày các API USB Video Class Extension Unit (XU) được hỗ trợ mà hệ thống hội nghị Google Meet sử dụng để bật các tính năng máy ảnh thông minh. Mục đích của việc tạo quy cách này là để tác động đến các phương pháp nhằm bật các tính năng này, đồng thời cho phép kiểm thử và mở rộng quy mô không đồng bộ hiệu quả hơn cho các đối tác của chúng tôi.

Để biết thông tin chi tiết về những thay đổi mới nhất đối với tài liệu này, hãy xem Ghi chú phát hành.

Cơ sở thử nghiệm

Để giúp các đối tác xác thực việc tuân thủ quy cách này, chúng tôi cung cấp một cơ sở thử nghiệm trong các thiết bị Chromebox-for-Meetings được đặt ở chế độ nhà phát triển. Bật tính năng ghi vào hệ thống tệp. Thêm các dòng sau vào /etc/chrome_dev.conf:

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

Khởi động lại thiết bị, kết nối máy ảnh và bàn phím USB, nhấn Ctrl-Alt-X, sau đó máy ảnh đang hoạt động sẽ thực thi và ghi lại việc tuân thủ thông số kỹ thuật vào /home/chronos/user/log/chrome.

Quy ước little-endian

USB là một tiêu chuẩn little-endian. Trong tài liệu này:

  • Số nhiều byte xuất hiện theo thứ tự big-endian (và được truyền theo thứ tự little-endian).
  • Mảng byte nằm trong bố cục bộ nhớ little-endian.

Ví dụ: 0x12345678 giống với [0x78, 0x56, 0x34, 0x12].

Mã nhận dạng duy nhất (GUID) của đơn vị mở rộng

Các đơn vị mở rộng hỗ trợ thông số kỹ thuật điều khiển Meet XU này phải sử dụng GUID này.

Đơn vị mở rộng GUID
XU điều khiển thiết bị ngoại vi {74D7E924-49C9-4A45-98A3-8A9F60061E83}

Bộ chọn XU điều khiển thiết bị ngoại vi

Đây là các bộ chọn XU điều khiển thiết bị ngoại vi đã xác định.

Bộ chọn điều khiển Giá trị
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

Loại yêu cầu kiểm soát

Các loại yêu cầu kiểm soát được xác định trong Chương 4: Yêu cầu cụ thể theo lớp của Thông số kỹ thuật lớp UVC 1.5.

Hoạt động Điều khiển UVC
GET GET_CUR, GET_MIN, GET_MAX, GET_RES, GET_LEN, GET_INFO, GET_DEF
SET SET_CUR

Chế độ máy ảnh

Chế độ máy ảnh được dùng để lấy khung hình cá nhân trong phòng họp và là một tuple của:

  • Chiến lược (chế độ xem camera)
  • Độ lệch (loa hoặc phòng)
  • Nguồn cấp dữ liệu (một hoặc nhiều luồng)

Mỗi phương diện có thể nhận các giá trị được mô tả trong các phần sau.

Chiến lược tự động lấy khung hình

Trong tất cả các chế độ lấy khung hình tự động ngoài "Không có", tính năng xoay, nghiêng và thu phóng thủ công sẽ bị tắt.

Tính năng Mô tả
Không có Máy ảnh tắt tất cả tính năng lấy khung hình thông minh và cho phép ứng dụng tự do kiểm soát các giá trị PTZ.
Lưu ý: Khi được đặt thành chiến lược lấy khung hình này, máy ảnh sẽ vẫn ở vị trí xoay, nghiêng và thu phóng hiện tại.
Liên tục đặt trong khung hình (CAZ) Dựa trên độ lệch khung hình, camera liên tục theo dõi những người trong phòng.
Khung phân tách Máy ảnh sẽ tạo bao nhiêu chế độ xem video tuỳ theo nhu cầu. Dựa trên tuỳ chọn Cung cấp tự động tạo khung, tính năng này sẽ kết hợp các nguồn cấp dữ liệu đó thành thẻ thông tin trong một luồng hoặc tạo các luồng video riêng biệt cho mỗi chế độ xem.
Chế độ xem động Một hoặc nhiều máy ảnh cố gắng cung cấp góc nhìn tốt nhất về căn phòng. Thành phần này có thể quyết định có kết hợp nhiều nguồn cấp dữ liệu thành một hay không hoặc cung cấp chế độ xem "hấp dẫn" của phòng hiện tại.
Mục đích của chế độ xem này là cung cấp chế độ xem công bằng nhất về những người tham gia trong phòng cho cuộc gọi.
Nhà cung cấp ưu tiên Hệ thống máy ảnh sử dụng logic riêng để xác định góc nhìn tốt nhất của căn phòng. Chiến lược lập khung cơ bản có thể thay đổi mà không cần thông báo. Ví dụ: nếu số lượng người trong phòng thay đổi hoặc máy ảnh có thể phát hiện sự khác biệt giữa cuộc họp "Người trình bày có nhiều áp lực" và cuộc họp "Cộng tác", thì hệ thống có thể tự do điều chỉnh hoặc thay đổi chiến lược lấy khung hình sao cho phù hợp trong chế độ này. Khi ở chế độ này, lệnh gọi getCur sẽ trả về VENDOR_PREFERRED chứ không phải chế độ tạo khung cơ bản mà hệ thống đã chọn.

Thiên vị khi tự động lấy khung hình

Tính năng Mô tả
Người trình bày có nhiều áp lực (Theo dõi người nói) Máy ảnh cố gắng lấy khung hình tốt nhất cho người đang nói chuyện trong phòng.
Trong trường hợp này, máy ảnh nên nghiêng về phía người trình bày. Ví dụ: Giám đốc điều hành đang trình bày trong phòng họp.
Cộng tác
(Theo dõi phòng)		 Máy ảnh sẽ cố gắng lấy khung hình phù hợp nhất cho tất cả người tham gia trong phòng. Trong trường hợp này, máy ảnh phải đối xử công bằng với mọi người tham gia.

Nguồn cấp dữ liệu tự động lấy khung hình

Tính năng Mô tả
Một luồng Máy ảnh gửi một luồng video duy nhất đến thiết bị lưu trữ.

nhiều luồng(đang trong quá trình phát triển)		 Máy quay sẽ phân tách luồng và tạo nhiều luồng video để gửi đến máy chủ lưu trữ.
Lưu ý: Thông số kỹ thuật đầy đủ và hành vi dự kiến của tính năng này đang chờ xem xét và không được hỗ trợ cho đến khi có các bản sửa đổi sau của tài liệu này.

Giá trị bitmap của chế độ tự động lấy khung hình

Ngoại trừ trạng thái mặc định của None được biểu thị bằng một mảng byte trống, mỗi bit trong mảng byte biểu thị một chế độ máy ảnh khác nhau, là một tổ hợp cụ thể của Chiến lược tự động lấy khung hình, Thiên vị tự động lấy khung hình và Nguồn cấp dữ liệu tự động lấy khung hình.

Nguồn cấp dữ liệu tự động lấy khung hình CAZ Khung hình phân tách Động Nhà cung cấp ưu tiên Thiên vị khi tự động lấy khung hình
Luồng đơn D1
D2		 –
D3		 D5
D7		 D9 (loa hoặc phòng) Loa
Phòng
Nhiều luồng –
–		 –
D4		 D6
D8		 - Loa
Phòng
Chế độ khung Giá trị chế độ khung hình (byte có giá trị ít quan trọng nhất)
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

Điều khiển: GOOGXU_FRAME_STRATEGY

Chế độ điều khiển này dùng để lấy hoặc đặt các chế độ lấy khung hình của máy ảnh như được liệt kê trong Giá trị bitmap của chế độ tự động lấy khung hình. Mỗi chế độ được biểu thị dưới dạng một bit trong bitmap tương ứng. Lệnh GET_RES trả về một mặt nạ bit dài 8 byte với giá trị bằng 0 (0) hoặc 1 (1) để cho biết tương ứng liệu thiết bị có hỗ trợ tính năng này hay không. Ví dụ: nếu một máy ảnh hỗ trợ CAZ, Speaker, Single-Stream, Split-Frame, Room, Single-Stream và Dynamic, Room, Multi-Stream nhưng không có chế độ nào khác, thì GET_RES sẽ trả về 0x000000000000000085 (tức là 0b10000101 theo sau là 7 byte 0).

Lệnh SET_CUR dùng để gửi bitmap để cho máy ảnh biết cần bật chế độ máy ảnh SINGLE (ĐƠN).

Bộ chọn điều khiển 1
Hoạt động GET / SET
wLength 8
Độ lệch Trường Kích thước Giá trị Mô tả
0 bActiveMode 8 Bitmap Đặt hoặc trả về Chế độ máy ảnh đang hoạt động
Lưu ý:

Hành vi của các loại yêu cầu được hỗ trợ như sau:

Độ lệch 0 Mô tả
GET_CUR Nhận chế độ máy ảnh Cắt khung hình linh hoạt
GET_MIN Tuỳ thuộc vào máy ảnh
GET_MAX Tuỳ thuộc vào máy ảnh
GET_RES Trả về một mặt nạ bit dài 8 byte của các chế độ máy ảnh được hỗ trợ
GET_LEN 0x0008 Chiều dài
GET_INFO 0x0B Tự động cập nhật / Ghi / Đọc
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 Giá trị mặc định
SET_CUR Đặt chế độ Máy ảnh lấy khung hình chủ động

Điều khiển: GOOGXU_REFRAME

Chế độ điều khiển này dùng để kích hoạt tính năng Chụp một lần, còn gọi là OTAZ. Khi OTAZ được kích hoạt, chế độ xem camera sẽ chụp nhanh đến chế độ xem tốt nhất của căn phòng. Sau đó, ứng dụng sẽ lấy lại khả năng kiểm soát các giá trị PTZ. Nếu không hỗ trợ tính năng chụp một lần, máy ảnh sẽ không xác định chế độ điều khiển này.

Bộ chọn điều khiển 2
Hoạt động SET
wLength 1
Độ lệch Trường Kích thước Giá trị Mô tả
0 bReframe 1 Số 0x01 Thực thi yêu cầu định dạng lại

Hành vi của các loại yêu cầu được hỗ trợ như sau:

Độ lệch 0 Mô tả
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x02 Chỉ có thể ghi
GET_DEF 0x00
SET_CUR Đặt yêu cầu cho tính năng Chụp một lần

Tính số người lưu trú

Tính năng đếm số người tham gia (OC) dùng để ước tính số lượng người tham gia trong phòng họp, bất kể chế độ xem bị cắt của máy ảnh.

Bảng này cho thấy hành vi dự kiến của các nút điều khiển OC và hoạt động tương tác của các nút này với luồng video của máy ảnh và chỉ báo LED của máy ảnh.

Khi tính năng Đếm số người lưu trú và luồng video của camera là: Chỉ báo LED của máy ảnh phải GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR phải là GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR phải là
Đã bật Không phát trực tiếp và không bị tắt tiếng Đang bật 0x01 Số người trong toàn bộ trường nhìn của máy ảnh.
Đã bật Phát trực tiếp Đang bật 0x01 Số người trong toàn bộ trường nhìn của máy ảnh.
Đã bật Bị ẩn Tắt 0x01 Đã tắt
Đã tắt Không phát trực tiếp và không bị tắt tiếng Tắt 0x00 Đã tắt
Đã tắt Phát trực tiếp Đang bật 0x00 Đã tắt
Đã tắt Bị ẩn Tắt 0x00 Đã tắt

Điều khiển: GOOGXU_OCCUPANCY_COUNTING_TOGGLE

Chế độ điều khiển này dùng để bật hoặc tắt tính năng đếm số người trong phòng. Việc đặt giá trị bằng 0 (0) sẽ tắt tính năng này và giá trị bằng 1 (1) sẽ bật tính năng này. Nếu tính năng này không được hỗ trợ, máy ảnh sẽ không xác định được chế độ điều khiển này.

Bộ chọn điều khiển 3
Hoạt động GET / SET
wLength 1
Độ lệch Trường Kích thước Giá trị Mô tả
0 bOccupancy 1 Boolean Đặt hàm tính số người lưu trú
0x00 Tắt hàm
0x01 Bật hàm

Hành vi của các loại yêu cầu được hỗ trợ như sau:

Độ lệch 0 Mô tả
GET_CUR Trả về nếu tính năng tính số người lưu trú đang bật
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x0B Tự động cập nhật / Ghi / Đọc
GET_DEF 0x00
SET_CUR Bật hoặc tắt tính năng đếm số người lưu trú

Điều khiển: GOOGXU_OCCUPANCY_COUNTING_READ

Thành phần điều khiển này dùng để đọc số lượng người tham gia trong một phòng do máy ảnh báo cáo khi tính năng tính số người lưu trú được bật. Khi tính năng đếm số người sử dụng bị tắt, máy ảnh sẽ tắt chế độ điều khiển này. Nếu không hỗ trợ tính năng đếm số người, máy ảnh sẽ không xác định được chế độ điều khiển này.

Bộ chọn điều khiển 4
Hoạt động GET
wLength 2
Độ lệch Trường Kích thước Giá trị Mô tả
0 bNumPeople 2 Số Số lượng người được phát hiện trong khung hình. (Chỉ Đọc)

Hành vi của các loại yêu cầu được hỗ trợ như sau:

Độ lệch 0 Mô tả
GET_CUR Trả về số lượng người ngồi được phát hiện
GET_MIN 0x0000
GET_MAX 0x00FF
GET_RES 0x0001
GET_LEN 0x0002
GET_INFO 0x09 Tự động cập nhật / Đọc
GET_DEF 0x0000

Dữ liệu đo từ xa và chẩn đoán thiết bị

Các chế độ điều khiển này nhằm khuyến khích các phương pháp gỡ lỗi hiệu quả hơn với phần cứng Meet và thường không dành cho người dùng.

Điều khiển: GOOGXU_STATUS_INFO

Chế độ điều khiển này dùng để truy vấn thông tin từ máy ảnh lưu trữ để chia sẻ với các đối tác nhằm gỡ lỗi.

Bộ chọn điều khiển 5
Hoạt động GET
wLength 8
Độ lệch Trường Kích thước Giá trị Mô tả
0 bNumCameras 1 Số Số lượng vệ tinh bổ sung được gắn vào máy ảnh chính có thể ảnh hưởng đến luồng máy ảnh được trả về máy chủ.
1 bIsMoving 1 Bitmap 0 khi máy ảnh ở trạng thái rảnh và khác 0 khi các giá trị PTZ của máy ảnh đang thay đổi. Nhà cung cấp có thể tự do liên kết các trục hoặc động cơ khác nhau với các bit khác nhau.
2 Undef 6 Undef Sẽ được mở rộng trong tương lai.

Hành vi của các loại yêu cầu được hỗ trợ như sau:

Độ lệch 0 1 2 Mô tả
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 Tự động cập nhật / Đọc
GET_DEF 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00

Điều khiển: GOOGXU_SATELLITE_INFO

Thao tác điều khiển này dùng để truy vấn các thiết bị vệ tinh được kết nối với hệ thống camera này.

Bộ chọn điều khiển 0x0A
Hoạt động GET
wLength 20
Độ lệch Trường Kích thước Giá trị Mô tả
0 bSatelliteList 20 Bitmap Danh sách các loại vệ tinh được đính kèm vào hệ thống. Bao gồm 4 khe 5 byte riêng biệt. Mỗi khe được mô tả như sau:
Độ lệch Mô tả
0 Số lượng cho loại vệ tinh này.
1-2 Mã nhà cung cấp của loại vệ tinh này.
3-4 Mã sản phẩm của loại vệ tinh này.

Hành vi của các loại yêu cầu được hỗ trợ như sau:

Độ lệch 0 Mô tả
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 byte
GET_INFO 0x09 Tự động cập nhật / Đọc
GET_DEF 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00 0x00

Điều khiển: GOOGXU_STATUS_RESET

Chế độ điều khiển này dùng để đưa ra yêu cầu đặt lại cho máy ảnh. Việc đặt giá trị là một (1) sẽ yêu cầu đặt lại máy ảnh. Máy ảnh trả về giá trị 0 (0) nếu không có yêu cầu khởi động lại máy ảnh kể từ lần đặt lại gần đây nhất và giá trị 1 (1) nếu đang đặt lại. Quá trình đặt lại phải kích hoạt quá trình khởi động lại camera. (Điều này cần thiết cho các thiết bị tự cấp nguồn, trong đó việc buộc ngắt kết nối USB để mô phỏng một thiết bị cắm nóng là không hữu ích.)

Bộ chọn điều khiển 6
Hoạt động GET / SET
wLength 1
Độ lệch Trường Kích thước Giá trị Mô tả
0 bResetRequest 1 Boolean Gửi yêu cầu đặt lại cho máy chủ và các máy ảnh đã kết nối.
Trả về 0x01 nếu yêu cầu đặt lại được đưa ra kể từ lần đặt lại gần đây nhất, nếu không thì trả về 0x00.

Hành vi của các loại yêu cầu được hỗ trợ như sau:

Độ lệch 0 Mô tả
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x03 Ghi / Đọc
GET_DEF 0x00

Chế độ cài đặt trước PTZ

Dùng để định cấu hình và khôi phục trường nhìn của máy ảnh về một vị trí đặt trước.

Điều khiển: GOOGXU_PRESETS

Nút điều khiển này dùng để đặt các giá trị xoay, nghiêng và thu phóng (PTZ) của máy ảnh thành một cấu hình đặt trước.

Preset Action được dùng để nêu rõ hành động dự kiến của lệnh. Việc đặt giá trị là một (1) được dùng để liên kết các giá trị hiện tại của tính năng kéo, nghiêng và thu phóng với một chỉ mục đặt trước được cung cấp. Việc đặt giá trị là hai (2) sẽ chuyển đổi thao tác xoay, nghiêng và thu phóng của máy ảnh sang các giá trị đã ánh xạ trước đó cho chỉ mục được cung cấp hoặc toạ độ ban đầu của nhà sản xuất (nếu không được ánh xạ trước đó). Việc đặt giá trị là 3 sẽ đặt lại chỉ mục về toạ độ mặc định của nhà sản xuất.

Preset Index được dùng để chỉ định toạ độ PTZ được liên kết với chỉ mục. Preset index bằng 0 được liên kết với toạ độ ban đầu và phải là vị trí mặc định của máy ảnh khi thức khi GOOGXU_FRAME_STRATEGY được đặt thành NONE.

Bộ chọn điều khiển 7
Hoạt động SET
wLength 2
Độ lệch Trường Kích thước Giá trị Mô tả
0 bPresetAction 1 Số 0x01: Lưu chế độ cài đặt trước
0x02: Khôi phục chế độ cài đặt trước
0x03: Đặt lại chế độ cài đặt trước về mặc định. (Mặc định phải là toạ độ đặt trước hợp lệ.)
1 bPresetIndex 1 Số Chỉ mục của Giá trị đặt trước đang hoạt động. 0~N-1
Trong đó 0 được coi là vị trí bắt đầu mặc định của máy ảnh và N-1 là hằng số do nhà cung cấp xác định cho số lượng chế độ cài đặt trước.

Hành vi của các loại yêu cầu được hỗ trợ như sau:

Độ lệch 0 1 Mô tả
GET_MIN 0x00 0x00
GET_MAX 0x03 N-1 Hỗ trợ N giá trị đặt trước tối đa
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 Chỉ ghi
GET_DEF 0x00 0x00

Di chuyển và nghiêng bản đồ phụ

Một số máy ảnh có các thành phần đặc biệt, chẳng hạn như động cơ cho máy ảnh cơ hoặc tính năng PTZ kỹ thuật số. Đối với các thao tác này, hãy sử dụng các chế độ điều khiển V4L2 chuẩn để xoay, nghiêng và thu phóng.

Điều khiển: GOOGXU_PAN_TILT_ABSOLUTE (không dùng nữa)

Các chế độ điều khiển ánh xạ phụ xoay và nghiêng được xác định trong Chương 4: Yêu cầu dành riêng cho lớp, Mục 4.2.2.1.14 Điều khiển PanTilt (Tuyệt đối) của Thông số kỹ thuật lớp UVC 1.5.

Điều khiển: GOOGXU_PAN_TILT_RELATIVE (không dùng nữa)

Các chế độ điều khiển ánh xạ phụ xoay và nghiêng được xác định trong Chương 4: Các yêu cầu cụ thể về lớp, Mục 4.2.2.1.15 Điều khiển PanTilt (Tương đối) của Thông số kỹ thuật lớp UVC 1.5.

Ghi chú phát hành

Những ghi chú phát hành này phản ánh các điểm cải tiến và tính năng mới trong mỗi bản sửa đổi của tài liệu này.

Ngày 27 tháng 1 năm 2025

Ngày 21 tháng 5 năm 2024

Ngày 15 tháng 11 năm 2023

Cập nhật tập lệnh kiểm thử để kiểm tra và diễn giải các chế độ tạo khung hợp lệ. Giải thích rõ hơn về cách trình bày số byte.

Ngày 21 tháng 7 năm 2023

Thêm tập lệnh kiểm thử để các đối tác xác thực việc triển khai nhằm tuân thủ quy cách này.

Ngày 25 tháng 5 năm 2023

Sửa ghi chú GOOGXU_PRESETS về số lượng chế độ cài đặt trước. Giá trị này phải là N, chứ không phải N-1.

Ngày 17 tháng 4 năm 2023

Bản phát hành đầu tiên.