Google Meet 하드웨어 USB 동영상 클래스 확장 단위 API

이 문서에서는 Google Meet 회의 시스템에서 지능형 카메라 기능을 사용 설정하는 데 사용되는 지원되는 USB XU (Video Class Extension Unit) API에 관해 간략히 설명합니다. 이 사양을 만드는 목적은 이러한 기능을 사용 설정하고 파트너가 더 나은 비동기식 확장성과 테스트를 수행할 수 있도록 관행에 영향을 주기 위한 것입니다.

파트너가 이 사양의 준수 여부를 확인할 수 있도록 이 테스트 스크립트는 구현을 분석하고 보고합니다.

이 문서의 최신 변경사항에 관한 자세한 내용은 출시 노트를 참고하세요.

리틀 엔디언 회의

USB는 리틀 엔디언 표준입니다. 본 문서에서 다루는 내용은 다음과 같습니다.

  • 멀티바이트 숫자는 빅 엔디언으로 나타나며 리틀 엔디언으로 전송됩니다.
  • 바이트 배열은 Little Endian 메모리 레이아웃에 있습니다.

예를 들어 0x12345678는 [0x78, 0x56, 0x34, 0x12]와 동일합니다.

확장 단위 GUID

이 Meet XU 제어 사양을 지원하는 확장 프로그램 단위는 이 GUID를 사용해야 합니다.

확장 단위 GUID
주변기기 제어 XU {74D7E924-49C9-4A45-98A3-8A9F60061E83}

주변기기 컨트롤 XU 선택기

정의된 주변기기 제어 XU 선택기입니다.

컨트롤 선택기 값
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

관리 요청 유형

제어 요청 유형은 UVC 1.5 클래스 사양의 4장: 클래스별 요청에 정의되어 있습니다.

작업 UVC 제어
GET GET_CUR, GET_MIN, GET_MAX, GET_RES, GET_LEN, GET_INFO, GET_DEF
SET SET_CUR

카메라 모드

카메라 모드는 회의실에서 개인을 프레이밍하는 데 사용되며 다음 tuple입니다.

  • 전략 (카메라 뷰)
  • 편향 (스피커 또는 회의실)
  • 피드 (단일 또는 여러 스트림)

각 측정기준은 다음 섹션에 설명된 값을 사용할 수 있습니다.

자동 프레이밍 전략

기능 설명
없음 카메라가 모든 지능형 프레이밍 기능을 사용 중지하고 클라이언트가 PTZ 값을 자유롭게 제어할 수 있도록 합니다.
참고: 이 프레이밍 전략으로 설정하면 카메라가 현재 화면 이동, 기울이기, 확대/축소 위치를 유지합니다.
연속 프레이밍 (CAZ) 프레임의 편향에 따라 카메라는 방 안에 있는 사람들을 계속 추적합니다.
참고: 이 모드에서는 PTZ가 사용 중지됩니다.
프레임 분할 카메라가 필요한 만큼 동영상 조회수를 생성합니다. 자동 프레이밍 피드 옵션에 따라 단일 스트림에서 타일로 구성하거나 보기마다 별도의 동영상 스트림을 만듭니다.
참고: 이 모드에서는 PTZ가 사용 중지됩니다.
동적 뷰 회의실을 가장 잘 볼 수 있도록 하나 이상의 카메라가 시도합니다. 여러 피드를 하나로 합성할지 여부를 결정하거나 현재 방에 대한 '흥미로운' 뷰를 제공할 수 있습니다.
이 뷰의 목적은 통화에 회의실 내 참석자를 가장 공평하게 볼 수 있도록 하는 것입니다.
참고:
  • 대부분의 회의에서 이 전략을 사용해야 합니다.
  • 이 모드에서는 PTZ가 사용 중지됩니다.

자동 프레이밍 편향

기능 설명
중요한 발표자 (발표자 추적) 카메라는 방에서 실제로 말하는 사람을 가장 잘 담보려고 시도합니다.
이 시나리오에서는 카메라가 발표자를 향하도록 편중해야 합니다. 예를 들어 CEO가 회의실에서 발표하고 있습니다.
공동작업
(회의실 추적)		 카메라는 회의실에 있는 모든 참여자를 가장 잘 프레임화하려고 시도합니다. 이 시나리오에서 카메라는 모든 참여자를 공평하게 취급해야 합니다. 대부분의 회의에서 이 전략을 사용해야 합니다.

자동 프레이밍 피드

기능 설명
단일 스트림 카메라가 단일 동영상 스트림을 호스트 기기로 전송합니다.
멀티 스트림
(작업 진행 중)		 카메라가 스트림을 분할하고 여러 동영상 스트림을 만들어 호스트로 전송합니다.
참고: 이 기능의 전체 사양 및 예상 동작은 검토 대기 중이며 이 문서의 이후 버전이 나올 때까지 지원되지 않습니다.

자동 프레이밍 모드 비트맵 값

빈 바이트 배열로 표시되는 None의 기본 상태를 제외하고 바이트 배열의 각 비트는 자동 프레이밍 전략, 자동 프레이밍 편향, 자동 프레이밍 피드의 특정 조합인 다른 카메라 모드를 나타냅니다.

비트 색인 캐나다 분할 프레임 동적 -
스피커 D1
-		 -
-		 5일
6일		 단일 스트림
멀티 스트림
Room D2
-		 3일
, 4일		 7일
일 8일		 단일 스트림
멀티 스트림
프레임 모드 프레임 모드 값 (최하위 바이트)
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

대조군: GOOGXU_FRAME_STRATEGY

이 컨트롤은 자동 프레이밍 모드 비트맵 값에 나열된 카메라의 프레이밍 모드를 가져오거나 설정하는 데 사용됩니다. 각 모드는 각 비트맵에 비트로 표시됩니다. 명령어 GET_RES는 값이 0 또는 1인 8바이트 길이의 비트마스크를 반환하여 이 기능이 기기에서 지원되지 않거나 지원되는지 표시합니다. 예를 들어 카메라가 CAZ, Speaker, Single-Stream, Split-Frame, Room, Single-Stream, Dynamic, Room, Multi-Stream를 지원하지만 다른 모드는 지원하지 않는 경우 GET_RES는 0x000000000000000085를 반환해야 합니다 (즉, 0b10000101 다음에 7바이트 0바이트).

SET_CUR 명령어는 비트맵을 전송하여 어떤 단일 카메라 모드를 사용 설정할지 카메라에 알리는 데 사용됩니다.

컨트롤 선택기 1
작업 GET / SET
wLength 8
오프셋 필드 크기 값 설명
0 bActiveMode 8 비트맵 활성 카메라 모드 설정 또는 반환
참고:

지원되는 요청 유형의 동작은 다음과 같습니다.

오프셋 0 설명
GET_CUR 액티브 프레이밍 카메라 모드 사용하기
GET_MIN 카메라에 따라 다름
GET_MAX 카메라에 따라 다름
GET_RES 지원되는 카메라 모드의 8바이트 긴 비트마스크를 반환합니다.
GET_LEN 0x0008 길이
GET_INFO 0x0B 자동 업데이트 / 쓰기 / 읽기
GET_DEF 0x00 0x00 0x00 0x00
0x00 0x00 0x00 0x00		 기본값
SET_CUR 액티브 프레이밍 카메라 모드 설정

대조군: GOOGXU_REFRAME

이 컨트롤은 OTAZ라고도 하는 원샷 프레이밍을 트리거하는 데 사용됩니다. OTAZ가 트리거되면 카메라 뷰가 방을 가장 잘 보여주는 방향으로 맞춰집니다. 그러면 클라이언트는 PTZ 값을 제어할 수 있는 기능을 다시 얻습니다. 원샷 프레이밍이 지원되지 않는 경우 카메라는 이 컨트롤을 정의해서는 안 됩니다.

컨트롤 선택기 2
작업 SET
wLength 1
오프셋 필드 크기 값 설명
0 bReframe 1 숫자 0x01 프레임 재조정 요청 실행

지원되는 요청 유형의 동작은 다음과 같습니다.

오프셋 0 설명
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x02 쓰기 전용
GET_DEF 0x00
SET_CUR 원샷 프레이밍 요청 설정

인원/차량 수 계산

점유율 계산 (OC)은 카메라의 잘린 뷰에 관계없이 회의실의 참여자 수를 추정하는 데 사용되는 기능입니다.

이 표는 OC 컨트롤의 예상 동작과 카메라 동영상 스트림 및 카메라 LED 표시기와의 상호작용을 보여줍니다.

인원/차량 수 계산이 설정된 경우 카메라 동영상 스트림이 다음과 같은 경우: 카메라 LED 표시기가 GOOGXU_OCCUPANCY_COUNTING_TOGGLE GET_CUR이(가) 다음과 같아야 합니다. GOOGXU_OCCUPANCY_COUNTING_READ GET_CUR이(가) 다음과 같아야 합니다.
사용 설정됨 스트리밍 안함 및 음소거 안함 사용 0x01 카메라의 전체 시야에 있는 사람의 수입니다.
사용 설정됨 스트리밍 사용 0x01 카메라의 전체 시야에 있는 사람의 수입니다.
사용 설정됨 음소거됨 사용 안함 0x01 사용 중지
사용 중지 스트리밍 안함 및 음소거 안함 사용 안함 0x00 사용 중지
사용 중지 스트리밍 사용 0x00 사용 중지
사용 중지 음소거됨 사용 안함 0x00 사용 중지

대조군: GOOGXU_OCCUPANCY_COUNTING_TOGGLE

이 컨트롤은 회의실에 있는 사람 수를 계산하는 기능을 사용 설정하거나 중지하는 데 사용됩니다. 값을 0으로 설정하면 이 기능이 사용 중지되고 1로 설정하면 이 기능이 사용 설정됩니다. 이 기능이 지원되지 않는 경우 카메라는 이 컨트롤을 정의해서는 안 됩니다.

컨트롤 선택기 3
작업 GET / SET
wLength 1
오프셋 필드 크기 값 설명
0 bOccupancy 1 불리언 점유율 계산 기능 설정
0x00 기능 끄기
0x01 기능 켜기

지원되는 요청 유형의 동작은 다음과 같습니다.

오프셋 0 설명
GET_CUR 숙박 인원 계산 기능이 사용 설정된 경우 반환
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x0B 자동 업데이트 / 쓰기 / 읽기
GET_DEF 0x00
SET_CUR 숙박 인원 계산 기능 사용 설정 또는 사용 중지

대조군: GOOGXU_OCCUPANCY_COUNTING_READ

이 컨트롤은 숙박 인원 집계가 사용 설정된 경우 카메라가 보고한 회의실 참석자 수를 읽는 데 사용됩니다. 이 기능이 사용 중지되면 카메라는 이 컨트롤을 사용 중지해야 합니다. 점유율 계산이 지원되지 않는 경우 카메라는 이 컨트롤을 정의해서는 안 됩니다.

컨트롤 선택기 4
작업 GET
wLength 2
오프셋 필드 크기 값 설명
0 bNumPeople 2 숫자 뷰에서 감지된 승객의 수입니다. (읽기 전용)

지원되는 요청 유형의 동작은 다음과 같습니다.

오프셋 0 설명
GET_CUR 감지된 숙박 인원 반환
GET_MIN 0x0000
GET_MAX 0x00FF
GET_RES 0x0001
GET_LEN 0x0002
GET_INFO 0x09 자동 업데이트 / 읽기
GET_DEF 0x0000

기기 텔레메트리 및 진단

이러한 컨트롤은 Meet 하드웨어를 사용한 디버깅 방법을 개선하기 위한 것으로 일반적으로 사용자에게 표시되지 않습니다.

대조군: GOOGXU_STATUS_INFO

이 컨트롤은 호스트 카메라의 정보를 쿼리하여 디버깅을 위해 파트너와 공유하는 데 사용됩니다.

컨트롤 선택기 5
작업 GET
wLength 8
오프셋 필드 크기 값 설명
0 bNumCameras 1 숫자 기본 기기에 연결된 추가 카메라 수입니다.
1 bIsMoving 1 비트맵 카메라가 유휴 상태이면 0이고 움직일 때는 0이 아닙니다. 공급업체는 다양한 축 또는 모터를 다른 비트에 자유롭게 매핑할 수 있습니다.
2 Undef 6 무역 향후 연장될 예정입니다.

지원되는 요청 유형의 동작은 다음과 같습니다.

오프셋 0 1 2 설명
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 자동 업데이트 / 읽기
GET_DEF 0x00 0x00 0x00, 0x00, 0x00,
, 0x00, 0x00, 0x00

대조군: GOOGXU_STATUS_RESET

이 컨트롤은 카메라에 재설정 요청을 전송하는 데 사용됩니다. 값을 1로 설정하면 카메라가 재설정되도록 요청합니다. 카메라는 마지막 재설정 이후 카메라 다시 시작 요청이 없는 경우 0을 반환하고 재설정 중인 경우에는 1을 반환합니다. 재설정은 하드웨어 재연결과 동일한 동작을 트리거합니다. 이는 핫플러그를 에뮬레이션하기 위해 USB 연결을 강제 해제하는 것이 유용하지 않은 자체 전원 공급 장치에 유용합니다.

컨트롤 선택기 6
작업 GET / SET
wLength 1
오프셋 필드 크기 값 설명
0 bResetRequest 1 불리언 호스트 및 연결된 카메라에 재설정 요청을 보냅니다.
마지막 재설정 이후에 재설정 요청이 발행된 경우 0x01을 반환하고 그렇지 않으면 0x00을 반환합니다.

지원되는 요청 유형의 동작은 다음과 같습니다.

오프셋 0 설명
GET_MIN 0x00
GET_MAX 0x01
GET_RES 0x01
GET_LEN 0x0001
GET_INFO 0x03 쓰기 / 읽기
GET_DEF 0x00

PTZ 사전 설정

카메라의 시야를 미리 설정된 위치로 구성하고 복원하는 데 사용됩니다.

대조군: GOOGXU_PRESETS

이 컨트롤은 카메라의 화면 이동, 기울기, 확대/축소 (PTZ) 값을 사전 설정 구성으로 설정하는 데 사용됩니다.

Preset Action는 명령어의 의도된 작업을 명시하는 데 사용됩니다. 값을 1로 설정하면 현재 화면 이동, 기울기, 확대/축소 값을 사전 설정된 제공된 색인에 매핑하는 데 사용됩니다. 값을 2로 설정하면 카메라의 화면 이동, 기울기, 확대/축소가 제공된 색인의 이전에 매핑된 값 또는 기본 팩토리 좌표(이전에 매핑되지 않은 경우)로 전환되어야 합니다. 값을 3으로 설정하면 색인이 공장 출고 시 기본 좌표로 재설정됩니다.

Preset Index는 색인에 매핑된 PTZ 좌표를 지정하는 데 사용됩니다. Preset index가 0인 경우 홈 좌표에 매핑되며 GOOGXU_FRAME_STRATEGY이 NONE로 설정된 경우 절전 모드 해제 시 카메라의 기본 위치여야 합니다.

컨트롤 선택기 7
작업 SET
wLength 2
오프셋 필드 크기 값 설명
0 bPresetAction 1 숫자 0x01: 사전 설정 저장
0x02: 사전 설정 복원
0x03: 사전 설정을 기본값으로 재설정합니다. 기본값은 유효한 미리 설정된 좌표여야 합니다.
1 bPresetIndex 1 숫자 활성 사전 설정 색인입니다. 0~N-1
. 여기서 0은 기본 카메라 시작 위치로 간주되고 N-1은 사전 설정 수에 관한 공급업체 정의 상수입니다.

지원되는 요청 유형의 동작은 다음과 같습니다.

오프셋 0 1 설명
GET_MIN 0x00 0x00
GET_MAX 0x03 N-1 최대 N개의 사전 설정 지원됨
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 쓰기 전용
GET_DEF 0x00 0x00

화면 이동 및 기울이기 보조 매핑

일부 카메라에는 기계식 카메라용 모터와 같은 특수 구성요소가 있으며, 이 구성요소에서는 화면 이동 및 기울기가 의도한 대로 작동하려면 표준 V4L2 컨트롤에 XU 명령어를 매핑해야 합니다.

이러한 컨트롤은 UVC 사양 문서에 있는 화면 이동 및 기울기의 절대적 및 상대적 컨트롤을 모방하여 호스트 기기에서 이러한 컨트롤을 올바르게 매핑할 수 있는 표준 방법을 제공합니다.

대조군: GOOGXU_PAN_TILT_ABSOLUTE

팬 및 기울기 보조 매핑 컨트롤은 UVC 1.5 클래스 사양의 4장: 클래스별 요청 섹션 4.2.2.1.14 PanTilt (절대적) 제어에 정의되어 있습니다.

컨트롤 선택기 8
작업 GET/SET
wLength 8
오프셋 필드 크기 값 설명
0 dwPanAbsolute 4 부호가 있는 숫자 주소 화면 이동 (절대) 컨트롤의 속성 설정입니다.
4 dwTiltAbsolute 4 부호가 있는 숫자 주소 지정된 기울기 (절대적) 컨트롤의 속성에 대한 설정입니다.

지원되는 요청 유형의 동작은 다음과 같습니다.

오프셋 0 4 설명
GET_MIN 카메라에 따라 다름
GET_MAX 카메라에 따라 다름
GET_RES 카메라에 따라 다름
GET_LEN 0x0008
GET_INFO 0x0B 자동 업데이트 / 쓰기 / 읽기
GET_DEF 0x00000000 0x00000000

대조군: GOOGXU_PAN_TILT_RELATIVE

팬 및 기울기 보조 매핑 컨트롤은 UVC 1.5 클래스 사양의 4장: 클래스별 요청 섹션 4.2.2.1.15 PanTilt (상대) 제어에 정의되어 있습니다.

컨트롤 선택기 9
작업 GET/SET
wLength 4
오프셋 필드 크기 값 설명
0 bPanRelative 1 부호가 있는 숫자 주소가 지정된 화면 이동 (상대) 컨트롤의 속성 설정:
0: 중지
1: 시계 방향으로 이동
0xFF: 시계 반대 방향으로 이동
1 bPanSpeed 1 숫자 팬 이동 속도입니다.
2 bTiltRelative 1 부호가 있는 숫자 주소를 지정한 기울기 (상대) 컨트롤의 속성에 대한 설정입니다.
0: 중지
1: 이미징 평면을 위로 향하게
0xFF: 이미징 평면을 아래로 향하게 합니다.
3 bTiltSpeed 1 숫자 기울기 이동 속도입니다.

지원되는 요청 유형의 동작은 다음과 같습니다.>

오프셋 0 1 2 3 설명
GET_MIN 카메라에 따라 다름
GET_MAX 카메라에 따라 다름
GET_RES 카메라에 따라 다름
GET_LEN 0x04 0x00 0x0004
GET_INFO 0x0B 자동 업데이트 / 쓰기 / 읽기
GET_DEF 0x00 0x00 0x00 0x00

출시 노트

이 출시 노트에는 이 문서의 각 버전에 포함된 개선사항 및 새로운 기능이 반영되어 있습니다.

2023년 11월 15일

유효한 프레이밍 모드를 확인하고 해석하도록 테스트 스크립트를 업데이트했습니다. 바이트 표현을 명확히 했습니다.

2023년 7월 21일

구현에서 이 사양을 준수하는지 확인할 수 있도록 파트너가 테스트 스크립트를 추가했습니다.

2023년 5월 25일

사전 설정 수에 관한 GOOGXU_PRESETS 메모를 수정했습니다. N-1이 아닌 N이어야 합니다.

2023년 4월 17일

첫 출시입니다.