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 Đơn vị mở rộng (XU) Lớp video USB được các hệ thống hội nghị Google Meet sử dụng để bật các tính năng thông minh của camera. 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 những tính năng này, đồng thời cho phép khả năng mở rộng và thử nghiệm không đồng bộ tốt 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 cho cuộc họp đượ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 camera và bàn phím USB, nhấn Ctrl-Alt-X, sau đó thông tin tuân thủ quy cách của camera đang hoạt động sẽ được thực hiện và ghi vào /var/log/chrome/chrome (nếu dùng hình ảnh đã ký thì là /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:

  • Các số có nhiều byte xuất hiện ở dạng big-endian (và được truyền ở dạng 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ã GUID của đơn vị mở rộng

Các đơn vị mở rộng hỗ trợ quy cách điều khiển XU của Meet này phải sử dụng GUID này.

Đơn vị mở rộng GUID
Peripheral Control XU {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 được xác định cho chế độ điều khiển thiết bị ngoại vi.

Bộ chọn thành phầ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 điều khiển được xác định trong Chương 4: Yêu cầu cụ thể về lớp của Quy cách 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ế độ camera

Các chế độ camera được dùng để lấy khung hình cho từng người trong phòng họp và là một tuplecủa:

  • Chiến lược (chế độ xem camera)
  • Thiên kiến (người nói 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 trừ chế độ "Không có", chế độ xoay, nghiêng và thu phóng thủ công sẽ bị tắt.

Tính năng Mô tả
Không có Camera sẽ tắt tất cả các tính năng khung hình thông minh và cho phép ứng dụng khách tự do kiểm soát các giá trị PTZ.
Lưu ý: Khi bạn đặt chiến lược lấy khung hình này, camera sẽ giữ nguyê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.
Chia khung hình Camera sẽ tạo ra số lượng chế độ xem video cần thiết. Dựa trên lựa chọn Nguồn cấp dữ liệu tự động tạo khung hình, hệ thống sẽ kết hợp các nguồn cấp dữ liệu này thành các ô trong một luồng duy nhất hoặc tạo các luồng video riêng biệt cho từng chế độ xem.
Chế độ xem động Một hoặc nhiều camera cố gắng cung cấp chế độ xem tốt nhất về căn phòng. Ứng dụng 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 một chế độ xem "thú vị" về 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 cuộc gọi trong phòng.
Nhà cung cấp được ưu tiên Hệ thống camera sử dụng logic riêng để xác định chế độ xem tốt nhất cho căn phòng. Chiến lược đóng khung cơ bản có thể thay đổi mà không cần thông báo. Ví dụ: nếu số người trong phòng thay đổi hoặc camera có thể phát hiện sự khác biệt giữa cuộc họp "Người thuyết trình quan trọng" 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 khung hình cho phù hợp trong chế độ này. Khi ở chế độ này, việc gọi getCur sẽ trả về VENDOR_PREFERRED chứ không phải chế độ đóng khung cơ bản do hệ thống chọn.

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

Tính năng Mô tả
Người trình bày quan trọng (Theo dõi người nói) Camera sẽ cố gắng lấy khung hình đẹp nhất cho người đang phát biểu trong phòng.
Trong trường hợp này, camera nên ưu tiên người trình bày. Ví dụ: Giám đốc điều hành đang thuyết trình trong phòng họp.
Cộng tác
(Theo dõi phòng)		 Camera sẽ cố gắng lấy khung hình đẹp nhất cho tất cả những người tham gia trong phòng. Trong trường hợp này, camera 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ả
Single-Stream Camera gửi một luồng video duy nhất đến thiết bị chủ.
Nhiều luồng
(Đang thực hiện)		 Camera sẽ chia luồng và tạo nhiều luồng video để gửi đến máy chủ.
Lưu ý: Toàn bộ quy cách 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 này của tài liệu này.

Giá trị bitmap của chế độ tự động điều chỉnh 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 đại diện cho một chế độ camera khác nhau, đó là một tổ hợp cụ thể của Chiến lược tự động lấy khung hình, Độ lệch 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 Chia khung hình Động Nhà cung cấp được ưu tiên Thiên vị tự động lấy khung hình
Single-Stream D1
D2		 –
D3		 D5
D7		 D9 (loa hoặc phòng) Loa
Room
Multi-Stream –
–		 –
D4		 D6
D8		 - Loa
Room
Chế độ khung hình Giá trị chế độ khung (byte í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 được dùng để nhận hoặc đặt chế độ khung hình của camera như được liệt kê trong Giá trị bitmap của chế độ tự động tạo 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 có 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 camera hỗ trợ CAZ, Speaker, Single-Stream, Split-Frame, Room, Single-Stream và Dynamic, Room, Multi-Stream nhưng không hỗ trợ chế độ nào khác, thì GET_RES sẽ trả về 0x000000000000000085 (tức là 0b10000101 theo sau là 7 byte không).

Lệnh SET_CUR được dùng để gửi bitmap nhằm cho camera biết chế độ camera SINGLE nào cần bật.

Bộ chọn chế độ cài đặt 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ế độ camera đang hoạt động
Lưu ý:

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

Độ lệch 0 Mô tả
GET_CUR Sử dụng chế độ camera Lấy khung hình động
GET_MIN Phụ thuộc vào camera
GET_MAX Phụ thuộc vào camera
GET_RES Trả về một mặt nạ bit dài 8 byte của các chế độ camera được hỗ trợ
GET_LEN 0x0008 Chiều dài
GET_INFO 0x0B AutoUpdate / Write / Read
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 Giá trị mặc định
SET_CUR Đặt chế độ Camera lấy khung hình chủ động

Điều khiển: GOOGXU_REFRAME

Chế độ điều khiển này được dùng để kích hoạt tính năng Lấy khung hình một lần, còn gọi là OTAZ. Khi OTAZ được kích hoạt, chế độ xem camera sẽ chuyển nhanh sang 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 lấy khung hình một lần, thì camera không được xác định chế độ kiểm soát này.

Bộ chọn chế độ cài đặt 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 điều chỉnh khung hình

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

Độ lệch 0 Mô tả
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x02 Chỉ ghi
GET_DEF 0x00
SET_CUR Đặt yêu cầu cho tính năng Lấy khung hình một lần

Đếm số người

Tính năng đếm số người (OC) được 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 camera.

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à tương tác của chúng với luồng video của camera và đèn LED chỉ báo của camera.

Khi tính năng Đếm số người và luồng video của camera là: Đèn báo LED của camera 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 tuyến 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 camera.
Đã 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 camera.
Đã bật Bị ẩn Tắt 0x01 Đã tắt
Đã tắt Không phát trực tuyến 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ế độ cài đặt 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ợ, camera không nên xác định chế độ kiểm soát này.

Bộ chọn chế độ cài đặt 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 chức năng đếm số người
0x00 Tắt chức năng
0x01 Bật chức năng

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

Độ lệch 0 Mô tả
GET_CUR Trả về nếu tính năng đếm số người đang ở trong phòng được bật
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x0B AutoUpdate / Write / Read
GET_DEF 0x00
SET_CUR Bật hoặc tắt tính năng đếm số người

Điều khiển: GOOGXU_OCCUPANCY_COUNTING_READ

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

Bộ chọn chế độ cài đặt 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 lưu trú được phát hiện trong khung hình. (Chỉ Đọc)

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

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

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

Các chế độ cài đặt 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ế độ kiểm soát này được dùng để truy vấn thông tin từ camera của thiết bị lưu trữ để chia sẻ với các đối tác nhằm mục đích gỡ lỗi.

Bộ chọn chế độ cài đặt 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 camera chính có thể ảnh hưởng đến luồng camera được trả về cho máy chủ lưu trữ.
1 bIsMoving 1 Bitmap 0 khi camera ở trạng thái rảnh và khác 0 khi các giá trị PTZ của camera đang thay đổi. Các 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.

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

Độ 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 AutoUpdate / Read
GET_DEF 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00

Điều khiển: GOOGXU_SATELLITE_INFO

Chế độ kiểm soát này được 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 chế độ cài đặt 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 gắn vào hệ thống. Bao gồm 4 khe cắm riêng biệt 5 byte. Mỗi khe cắm đượ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 cho loại vệ tinh này.

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

Độ 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 AutoUpdate / Read
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 để gửi yêu cầu đặt lại cho camera. Việc đặt giá trị là một (1) sẽ yêu cầu máy ảnh đặt lại. Camera sẽ trả về giá trị 0 nếu không có yêu cầu khởi động lại camera kể từ lần đặt lại gần nhất và giá trị 1 nếu camera đang đặt lại. Thao tác đặt lại phải kích hoạt quá trình khởi động lại camera. (Điều này là cần thiết đối với 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 thao tác cắm nóng không hữu ích.)

Bộ chọn chế độ cài đặt 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 đến thiết bị chủ và camera đã 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.

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

Độ 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ế độ đặt sẵn cho camera PTZ

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

Điều khiển: GOOGXU_PRESETS

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

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ị xoay ngang, xoay dọc và thu phóng hiện tại với một chỉ mục đặt sẵn được cung cấp. Việc đặt giá trị là 2 sẽ chuyển chế độ xoay ngang, xoay dọc và thu phóng của camera sang các giá trị đã được ánh xạ trước đó cho chỉ mục được cung cấp hoặc toạ độ mặc định của nhà máy (nếu chưa được ánh xạ trước đó). Việc đặt giá trị là 3 (3) sẽ đặt lại chỉ mục về toạ độ mặc định ban đầu.

Preset Index được dùng để chỉ định các 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 camera khi đánh thức nếu GOOGXU_FRAME_STRATEGY được đặt thành NONE.

Bộ chọn chế độ cài đặt 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ế độ đặt sẵn
0x02: Khôi phục chế độ đặt sẵn
0x03: Đặt lại chế độ đặt sẵn về mặc định. (Giá trị mặc định phải là một toạ độ đặt sẵn hợp lệ.)
1 bPresetIndex 1 Số Chỉ số Active Preset. 0~N-1
Trong đó 0 được coi là vị trí bắt đầu mặc định của camera và N-1 là một hằng số do nhà cung cấp xác định cho số lượng chế độ đặt sẵn.

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

Độ lệch 0 1 Mô tả
GET_MIN 0x00 0x00
GET_MAX 0x03 N-1 Hỗ trợ tối đa N giá trị đặt trước
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ố camera có các thành phần đặc biệt, chẳng hạn như động cơ cho camera cơ học hoặc khả năng PTZ kỹ thuật số. Đối với những chế độ này, hãy sử dụng các chế độ điều khiển V4L2 tiêu chuẩn để xoay ngang, xoay dọc 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ụ cho chế độ xoay ngang và xoay dọc đượ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 PanTilt (Tuyệt đối) Control của UVC 1.5 Class Specification (Quy cách 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: Yêu cầu dành riêng cho lớp, Mục 4.2.2.1.15 PanTilt (Tương đối) Control của UVC 1.5 Class Specification (Quy cách lớp UVC 1.5).

Ghi chú phát hành

Các ghi chú phát hành này phản ánh những đ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 13 tháng 8 năm 2025

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ế độ đóng khung hợp lệ. Đã làm rõ các biểu thị 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

Lưu ý đã được chỉnh sửa GOOGXU_PRESETS liên quan đến số lượng chế độ đặt sẵn. 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.