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

이 문서에서는 Google Meet 회의 시스템에서 지능형 카메라 기능을 사용 설정하는 데 사용되는 지원되는 USB 비디오 클래스 확장 프로그램 단위 (XU) API를 간략하게 설명합니다. 이 사양을 만드는 목적은 이러한 기능을 사용 설정하는 관행에 영향을 미치고 파트너가 더 나은 비동기 확장성과 테스트를 할 수 있도록 하는 것입니다.

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

테스트 시설

파트너가 이 사양 준수를 검증할 수 있도록 개발자 모드로 설정된 Chromebox-for-Meetings 기기에서 테스트 기능을 제공합니다. 파일 시스템에 쓰기를 사용 설정합니다. /etc/chrome_dev.conf에 다음 줄을 추가합니다.

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

기기를 다시 시작하고 카메라와 USB 키보드를 연결하고 Ctrl-Alt-X를 누르면 활성 카메라의 사양 준수가 실행되고 /var/log/chrome/chrome(서명된 이미지를 사용하는 경우 /home/chronos/user/log/chrome)에 로깅됩니다.

Little-endian 규칙

USB는 리틀 엔디언 표준입니다. 이 문서에서

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

예를 들어 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
GOOGXU_SATELLITE_INFO 0x0A

제어 요청 유형

제어 요청 유형은 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) 프레이밍 편향에 따라 카메라가 회의실에 있는 사용자를 지속적으로 추적합니다.
프레임 분할 카메라에서 필요한 만큼 동영상 뷰를 만듭니다. 자동 프레이밍 피드 옵션에 따라 단일 스트림에 타일로 구성하거나 각 뷰에 별도의 동영상 스트림을 만듭니다.
동적 뷰 하나 이상의 카메라가 방의 최적의 뷰를 제공하려고 시도합니다. 여러 피드를 하나로 합성할지 아니면 현재 방의 '흥미로운' 뷰를 제공할지 결정할 수 있습니다.
이 뷰의 목적은 통화에 참여하는 회의실 내 참가자에게 가장 공정한 뷰를 제공하는 것입니다.
공급업체 선호 카메라 시스템은 자체 로직을 사용하여 방의 최적 뷰를 결정합니다. 기본 프레이밍 전략은 예고 없이 변경될 수 있습니다. 예를 들어 회의실에 있는 인원수가 변경되거나 카메라가 '중요한 발표자'와 '협업' 회의의 차이를 감지할 수 있는 경우 시스템은 이 모드에서 적절하다고 판단되는 대로 프레임 전략을 조정하거나 변경할 수 있습니다. 이 모드에서는 getCur를 호출하면 시스템에서 선택한 기본 프레임 모드가 아닌 VENDOR_PREFERRED가 반환되어야 합니다.

자동 프레이밍 편향

기능 설명
중요한 발표자 (발표자 추적) 카메라가 회의실에서 현재 발언하는 사람을 가장 잘 프레임에 담으려고 시도합니다.
이 시나리오에서는 카메라가 발표자 쪽으로 기울어져야 합니다. 예를 들어 회의실에서 CEO가 프레젠테이션을 하는 장면을 생각해 보세요.
공동작업
(회의실 추적)
카메라가 회의실의 모든 참여자를 가장 잘 프레임에 담으려고 시도합니다. 이 시나리오에서 카메라는 모든 참여자를 공정하게 대해야 합니다.

자동 프레이밍 피드

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

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

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

자동 프레이밍 피드 CAZ 분할 프레임 동적 공급업체 선호 자동 프레이밍 편향
단일 스트림 D1
D2
-
D3
D5
D7
D9 (스피커 또는 회의실) 스피커
멀티 스트림 -
-
-
D4
D6
D8
- 스피커
프레임 모드 프레임 모드 값 (최하위 바이트)
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

제어: 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 뒤에 0 바이트 7개)를 반환해야 합니다.

SET_CUR 명령어를 사용하여 비트맵을 전송하여 사용 설정할 SINGLE 카메라 모드를 카메라에 알립니다.

제어 선택기 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 AutoUpdate / Read
GET_DEF 0x0000

기기 텔레메트리 및 진단

이러한 컨트롤은 Meet 하드웨어에서 더 나은 디버깅 관행을 장려하기 위한 것이며 일반적으로 사용자에게 표시되지 않습니다.

제어: GOOGXU_STATUS_INFO

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

제어 선택기 5
작업 GET
wLength 8
오프셋 필드 크기 설명
0 bNumCameras 1 숫자 호스트에 반환된 카메라 스트림에 영향을 줄 수 있는 기본 카메라에 연결된 추가 위성 수입니다.
1 bIsMoving 1 비트맵 카메라가 유휴 상태일 때는 0이고 PTZ 값이 변경될 때는 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 AutoUpdate / Read
GET_DEF 0x00 0x00 0x00 0x00 0x00
0x00 0x00 0x00

제어: GOOGXU_SATELLITE_INFO

이 컨트롤은 이 카메라 시스템에 연결된 위성 기기를 쿼리하는 데 사용됩니다.

제어 선택기 0x0A
작업 GET
wLength 20
오프셋 필드 크기 설명
0 bSatelliteList 20 비트맵 시스템에 연결된 위성 유형 목록입니다. 4개의 별도 5바이트 슬롯이 포함됩니다. 각 슬롯은 다음과 같이 설명됩니다.
오프셋 설명
0 이 위성 유형의 수량입니다.
1-2 이 위성 유형의 공급업체 ID입니다.
3-4 이 위성 유형의 제품 ID입니다.

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

오프셋 0 설명
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바이트
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

제어: 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 좌표를 지정하는 데 사용됩니다. 0의 Preset index은 홈 좌표에 매핑되며 GOOGXU_FRAME_STRATEGYNONE로 설정된 경우 절전 모드 해제 시 카메라의 기본 위치여야 합니다.

제어 선택기 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 지원되는 최대 사전 설정 수
GET_RES 0x01 0x01
GET_LEN 0x02 0x00 0x0002
GET_INFO 0x02 쓰기 전용
GET_DEF 0x00 0x00

보조 매핑 이동 및 기울이기

일부 카메라에는 기계식 카메라용 모터나 디지털 PTZ 기능과 같은 특수 구성요소가 있습니다. 이러한 경우 팬, 틸트, 줌에 표준 V4L2 컨트롤을 사용합니다.

제어: GOOGXU_PAN_TILT_ABSOLUTE (지원 중단됨)

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

제어: GOOGXU_PAN_TILT_RELATIVE (지원 중단됨)

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

출시 노트

이 출시 노트에는 이 문서의 각 수정사항에 따른 개선사항과 새로운 기능이 반영되어 있습니다.

2025년 8월 13일

2025년 1월 27일

2024년 5월 21일

2023년 11월 15일

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

2023년 7월 21일

파트너가 이 사양 준수 구현을 검증할 수 있도록 테스트 스크립트를 추가했습니다.

2023년 5월 25일

프리셋 수에 관한 GOOGXU_PRESETS 참고사항이 수정되었습니다. N-1이 아닌 N이어야 합니다.

2023년 4월 17일

첫 출시입니다.