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ộ 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-for-Meetings được đặt ở chế độ nhà phát triển. Cho phép 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

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

Tính năng Mô tả
Không có Camera này tắt tất cả tính năng lấy khung hình thông minh và cho phép khách hàng thoải mái 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.
Lưu ý: Chế độ PTZ bị tắt ở chế độ này.
Khung hình phân tách Camera tạo ra số lượt xem video 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.
Lưu ý: Chế độ PTZ bị tắt ở chế độ này.
Chế độ xem động Một hoặc nhiều camera cố gắng cung cấp chế độ xem tốt nhất của 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.
Lưu ý:
  • Hầu hết các cuộc họp đều nên sử dụng chiến lược này.
  • Chế độ PTZ bị tắt ở chế độ này.

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 tất cả người tham gia. Hầu hết các cuộc họp đều nên sử dụng chiến lược này.

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 ảnh chia luồng và tạo nhiều luồng video để gửi đến người tổ chức.
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.

Chỉ mục bit CAZ Chia khung hình Động -
Loa D1
–		 –
–		 D5
D6		 Một luồng
Nhiều luồng
Room D2
–		 D3
D4		 D7
D8		 Một luồng
Nhiều luồng
Chế độ khung Giá trị chế độ khung (byte có ý nghĩa ít nhất)
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

Đ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 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 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ả lại 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 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 đó, máy khách 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ỉ 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 camera phải GET_CUR của GOOGXU_OCCUPANCY_COUNTING_TOGGLE 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 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ị không (0) sẽ tắt tính năng này và một (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 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 tính số người lưu trú

Điều khiển: GOOGXU_OCCUPANCY_COUNTING_READ

Nút đ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 tính số người lưu trú 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, máy ảnh sẽ không xác định 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ố người lưu trú được phát hiện trong khung nhìn. (Chỉ Đọc)

Các loại yêu cầu được hỗ trợ sẽ có hành vi như sau:

Độ lệch 0 Mô tả
GET_CUR Số người trả lại hàng đượ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.

Kiểm soát: 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 Bỏ đánh bại 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_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 máy ảnh đặt lại. Máy ảnh trả về giá trị 0 (không) 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 (có) 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 tính năng 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.

Các loại yêu cầu được hỗ trợ sẽ có hành vi 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.

Kiểm soát: 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 hành động dự định 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ị đã liên kết trước đó cho chỉ mục được cung cấp hoặc toạ độ ban đầu của nhà sản xuất (nếu trước đó chưa được liên kết). 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ụ trợ

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 chế độ này, hãy sử dụng các chế độ điều khiển V4L2 chuẩn để xoay, nghiêng và thu phóng.

Nhóm đối chứng: 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 cụ thể của 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 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.