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 Lớp video USB (XU) được hỗ trợ mà các hệ thống hội nghị Google Meet dùng để bật các tính năng của 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 giúp cải thiện khả năng mở rộng và kiểm thử không đồng bộ cho các đối tác.

Để giúp các đối tác xác thực việc tuân thủ quy cách này, tập lệnh kiểm thử này sẽ phân tích và báo cáo về quá trình triển khai của bạn.

Để 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 chuyển đến Ghi chú phát hành.

Hội nghị Little-endian

USB là một chuẩn cuối nhỏ. Trong tài liệu này:

  • Số nhiều byte xuất hiện theo phân số cuối lớn (và được truyền theo số cuối nhỏ).
  • Các mảng byte nằm trong bố cục bộ nhớ phân cuối nhỏ.

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

GUID đơn vị phần mở rộng

Các đơn vị tiện ích hỗ trợ thông số kỹ thuật điều khiển XU của Meet này phải sử dụng GUID này.

Đơn vị phần 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 dành riêng cho lớp của Thông số kỹ thuật của lớp UVC 1.5.

Hoạt động Kiểm soát UVC
GET GET_CUR, GET_MIN, GET_MAX, GET_RES, GET_LEN, GET_INFO, GET_DEF
SET SET_CUR

Các chế độ của máy ảnh

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

  • Chiến lược (chế độ xem máy ảnh)
  • Thiên vị (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 Nội dung mô tả
Không có Máy ảnh tắt tất cả các tính năng lấy khung hình thông minh và cho phép khách hàng tự do điều khiển các giá trị PTZ.
Lưu ý: Khi đặt chiến lược lấy khung hình này, máy ảnh vẫn ở vị trí kéo, nghiêng và thu phóng hiện tại.
Khung hình liên tục (CAZ) Dựa trên xu hướng khung hình, máy ảnh liên tục theo dõi mọi người trong phòng.
Lưu ý: PTZ bị tắt ở chế độ này.
Tách khung Máy ảnh sẽ tạo ra bao nhiêu lượt xem video tuỳ ý. Dựa trên tuỳ chọn Tự động lấy khung hình nguồn cấp dữ liệu, công cụ này sẽ kết hợp nguồn cấp dữ liệu 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 mỗi chế độ xem.
Lưu ý: 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 về phòng. Bạn có thể quyết định xem có nên gộp nhiều nguồn cấp dữ liệu vào một nguồn cấp dữ liệu hoặc mang đến một chế độ xem "thú vị" cho phòng hiện tại hay không.
Mục đích của chế độ xem này là mang đến cái nhìn công bằng nhất về những người tham gia trong phòng đối với cuộc gọi.
Lưu ý:
  • Hầu hết các cuộc họp nên sử dụng chiến lược này.
  • PTZ bị tắt ở chế độ này.

Bù trừ khung hình tự động

Tính năng Nội dung mô tả
Người trình bày có khả năng cao (Theo dõi người nói) Camera cố gắng lấy khung hình chính xác nhất khi người đang nói trong phòng.
Trong tình huống này, máy quay nên thiên về người trình bày. Ví dụ: Giám đốc điều hành ở trong phòng họp đang thuyết trình.
Cộng tác
(Theo dõi Room)		 Máy ảnh sẽ cố gắng lấy khung hình chính xác nhất cho tất cả những người tham gia trong phòng. Trong tình huống này, camera phải đối xử công bằng với mọi người tham gia. Hầu hết các cuộc họp nên sử dụng chiến lược này.

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

Tính năng Nội dung mô tả
Một luồng Camera gửi một luồng video duy nhất tới thiết bị lưu trữ.
Nhiều luồng
(Đang tiến hành)		 Máy quay chia luồng nội dung rồi tạo nhiều luồng video để gửi đến người tổ chức.
Lưu ý: Quy cách đầy đủ cũng như hoạt động 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 tài liệu này được sửa đổi trong tương lai.

Giá trị bitmap 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 đại diện cho một chế độ máy ảnh riêng. Đây là sự kết hợp cụ thể của Chiến lược tự động lấy khung hình, Tự động lấy khung hình và Nguồn cấp dữ liệu tự động lấy khung hình.

Chỉ số bit CAZ (Canada) Khung hình tách Động -
Loa Ngày 1
–		 –
–		 Ngày 5
Ngày 6		 Một luồng
Nhiều luồng
Room Ngày 2
–		 Ngày 3
Ngày 4		 D7
D8		 Một luồng
Nhiều luồng
Chế độ khung hình Giá trị chế độ khung (số byte ít quan trọng 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

Kiểm soát: GOOGXU_FRAME_STRATEGY

Đ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ư 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ị là 0 (0) hoặc một (1) để cho biết tính năng đó có được thiết bị hỗ trợ hay không. Ví dụ: nếu 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).

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

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ị Nội dung 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 Nội dung mô tả
GET_CUR Bật chế độ máy ảnh lấy khung hình đang hoạt động
GET_MIN Phụ thuộc vào máy ảnh
GET_MAX Phụ thuộc vào máy ảnh
GET_RES Trả về bitmask dài 8 byte của các chế độ máy ảnh được hỗ trợ
GET_LEN 0x0008 Chiều dài
GET_INFO 0 x 0 tỷ 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 đang hoạt động

Kiểm soát: GOOGXU_REFRAME

Chế độ điều khiển này dùng để kích hoạt chế độ Lấy khung hình một lần chụp, còn gọi là OTAZ. Khi OTAZ được kích hoạt, chế độ xem máy ảnh sẽ chụp theo chế độ xem tốt nhất của phòng. Sau đó, ứng dụng có 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, 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ị Nội dung mô tả
0 bReframe 1 Số 0x01 Thực thi yêu cầu lấy khung hình lại

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

Độ lệch 0 Nội dung mô tả
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x02 Chỉ viết
GET_DEF 0x00
SET_CUR Đặt yêu cầu khung một lần chụp

Đang đếm số người lưu trú

Đếm số người lưu trú (OC) là tính năng dùng để ước tính số lượng người tham gia trong phòng họp, mặc dù máy ảnh đã ở chế độ xem bị cắt.

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

Khi đếm số người lưu trú và luồng video của camera là: Chỉ báo bằng đèn LED của máy ảnh sẽ 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ộ góc nhìn của camera.
Đã bật Phát trực tiếp Đang bật 0x01 Số người trong toàn bộ góc nhìn của camera.
Đã bật Bị tắt tiếng 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ị tắt tiếng Tắt 0x00 Đã tắt

Kiểm soát: 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 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ị Nội dung mô tả
0 bOccupancy 1 Boolean Đặt chức năng đếm 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 Nội dung mô tả
GET_CUR Trả phòng nếu tính năng đếm số người lưu trú đang bật
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0 x 0 tỷ 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ú

Kiểm soát: GOOGXU_OCCUPANCY_COUNTING_READ

Chế độ điều khiển này dùng để đọc số người tham gia trong một phòng mà camera báo cáo khi tính năng đếm số người lưu trú đang bật. Nếu tính năng này tắt, máy ảnh sẽ tắt chế độ điều khiển này. Nếu tính năng đếm số người lưu trú không được hỗ trợ, camera sẽ không xác định chế độ kiểm soát 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ị Nội dung mô tả
0 bNumPeople 2 Số Số người lưu trú được phát hiện trong chế độ xem. (Chỉ Đọc)

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

Độ lệch 0 Nội dung mô tả
GET_CUR Trả lại số người lưu trú đượ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à thông tin chẩn đoán về thiết bị

Các chế độ kiểm soá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 hiển thị với 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 máy chủ nhằm 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ị Nội dung mô tả
0 bNumCameras 1 Số Số lượng máy ảnh bổ sung được gắn vào thiết bị chính.
1 bIsMoving 1 Bitmap 0 khi máy ảnh ở trạng thái rảnh và khác 0 khi máy ảnh di chuyển. Các nhà cung cấp có thể tự do ánh xạ các trục hoặc động cơ khác nhau đến các bit khác nhau.
2 Undef 6 Bỏ đánh dấu Sẽ được gia hạn 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 Nội dung 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

Kiểm soát: GOOGXU_STATUS_RESET

Chế độ điều khiển này dùng để đưa ra 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. Máy ảnh sẽ trả về 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 nhất và một (1) nếu đang đặt lại. Thao tác đặt lại sẽ kích hoạt hành vi tương tự như quá trình kết nối lại phần cứng. Điều này hữu ích cho các thiết bị tự cấp nguồn vì việc buộc ngắt kết nối USB để mô phỏng phích 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ị Nội dung mô tả
0 bResetRequest 1 Boolean Gửi yêu cầu đặt lại tới máy chủ lưu trữ và các 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 nhất, nếu không thì giá trị này sẽ là 0x00.

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

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

Giá trị đặ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ề vị trí đặt trước.

Kiểm soát: GOOGXU_PRESETS

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

Preset Action được dùng để đưa ra hành động dự kiến của lệnh. Việc đặt giá trị là một (1) được dùng để ánh xạ các giá trị xoay, nghiêng và thu phóng hiện tại với một chỉ mục đặt trước đã cung cấp. Việc đặt giá trị là hai (2) sẽ chuyển đổi phương thức xoay, nghiêng và thu phóng của máy ảnh thành các giá trị đã ánh xạ trước đó cho chỉ mục được cung cấp hoặc toạ độ gốc mặc định (nếu chưa được ánh xạ trước đó). Việc đặt giá trị ba (3) sẽ đặt lại chỉ mục về toạ độ mặc định ban đầu.

Preset Index được dùng để chỉ định toạ độ PTZ được ánh xạ tới chỉ mục. Preset index của 0 (0) được liên kết với toạ độ nhà 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ị Nội dung mô tả
0 bPresetAction 1 Số 0x01: Lưu giá trị đặt trước
0x02: Khôi phục giá trị đặt trước
0x03: Đặt lại giá trị đặ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 giá trị đặt trước đang hoạt động. 0~N-1
Trong đó 0 được coi là vị trí bắt đầu máy ảnh mặc định và N-1 là hằng số do nhà cung cấp xác định cho số lượng giá trị đặ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 Nội dung 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ỉ viết
GET_DEF 0x00 0x00

Bản đồ phụ trợ xoay và nghiêng

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ơ học, yêu cầu ánh xạ các lệnh XU qua các bộ điều khiển V4L2 tiêu chuẩn để xoay và nghiêng để hoạt động như dự kiến.

Các chế độ điều khiển này bắt chước chế độ điều khiển tuyệt đối và tương đối của chế độ xoay và nghiêng trong tài liệu về thông số kỹ thuật UPC, cung cấp cách thức tiêu chuẩn để thiết bị lưu trữ liên kết chính xác các chế độ điều khiển này.

Kiểm soát: GOOGXU_PAN_TILT_ABSOLUTE

Các chế độ điều khiển ánh xạ phụ trợ 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 PanTilt (Tuyệt đối) Kiểm soát Thông số kỹ thuật của lớp UVC 1.5.

Bộ chọn điều khiển 8
Hoạt động GET/SET
wLength 8
Độ lệch Trường Kích thước Giá trị Nội dung mô tả
0 dwPanAbsolute 4 Số đã ký Chế độ cài đặt cho thuộc tính của chế độ Kiểm soát xoay (Tuyệt đối) được chỉ định.
4 dwTiltAbsolute 4 Số đã ký Chế độ cài đặt cho thuộc tính của chế độ Điều khiển Nghiêng (Tuyệt đối) được đề cập.

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

Độ lệch 0 4 Nội dung mô tả
GET_MIN Phụ thuộc vào máy ảnh
GET_MAX Phụ thuộc vào máy ảnh
GET_RES Phụ thuộc vào máy ảnh
GET_LEN 0x0008
GET_INFO 0 x 0 tỷ Tự động cập nhật / Ghi / Đọc
GET_DEF 0x00000000 0x00000000

Kiểm soát: GOOGXU_PAN_TILT_RELATIVE

Các chế độ điều khiển ánh xạ phụ trợ 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) Kiểm soát Thông số kỹ thuật của lớp UVC 1.5.

Bộ chọn điều khiển 9
Hoạt động GET/SET
wLength 4
Độ lệch Trường Kích thước Giá trị Nội dung mô tả
0 bPanRelative 1 Số đã ký Chế độ cài đặt cho thuộc tính của chế độ điều khiển Lia máy (Tương đối) được chỉ định:
0: Dừng
1: di chuyển theo chiều kim đồng hồ
0xFF: di chuyển sang chiều ngược kim đồng hồ
1 bPanSpeed 1 Số Tốc độ chuyển động của thao tác kéo.
2 bTiltRelative 1 Số đã ký Chế độ cài đặt cho thuộc tính của Điều khiển Nghiêng (Tương đối) được chỉ định:
0: Dừng
1: trỏ mặt phẳng hình ảnh lên
0xFF: hướng mặt phẳng hình ảnh xuống
3 bTiltSpeed 1 Số Tốc độ chuyển động nghiêng.

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

Độ lệch 0 1 2 3 Nội dung mô tả
GET_MIN Phụ thuộc vào máy ảnh
GET_MAX Phụ thuộc vào máy ảnh
GET_RES Phụ thuộc vào máy ảnh
GET_LEN 0x04 0x00 0x0004
GET_INFO 0 x 0 tỷ Tự động cập nhật / Ghi / Đọc
GET_DEF 0x00 0x00 0x00 0x00

Ghi chú phát hành

Những 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 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ế độ lấy khung hình hợp lệ. Làm rõ cách biểu diễn byte.

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

Thêm tập lệnh kiểm thử cho các đối tác để xác thực các quy trình triển khai về việc 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 giá trị đặt trước. Giá trị phải là N, không phải N-1.

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

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