avatar-container

아바타 비디오를 표시하는 Web Component입니다. 비디오 트랙이 자동으로 바인딩됩니다.

사용법

<avatar-container
  style="width: 400px; height: 400px;"
  volume="80"
  fit="cover"
></avatar-container>

속성

속성	타입	기본값	설명
volume	number	100	오디오 볼륨 (0-100). 변경 시 SDK.setVolume()을 자동 호출합니다.
fit	string	"cover"	비디오 맞춤 모드. "cover" | "contain" | "fill"

fit 옵션

값	설명
"cover"	컨테이너를 꽉 채우며 비율 유지 (넘치는 부분 잘림)
"contain"	비율 유지하며 컨테이너 안에 전체 표시 (여백 발생 가능)
"fill"	비율 무시하고 컨테이너에 맞춤

이벤트

이벤트	설명
avatar-connected	컴포넌트가 DOM에 마운트되고 첫 렌더가 완료된 후 발생합니다. SDK가 이 이벤트를 수신하여 비디오 트랙을 자동으로 바인딩합니다.

비디오 자동 바인딩

비디오 트랙은 다음 순서로 자동 연결됩니다:

1. <avatar-container>가 DOM에 추가되면 첫 렌더 완료 후 avatar-connected 이벤트를 발생시킵니다.
2. SDK Core가 이 이벤트를 수신하여 Agora 비디오 트랙을 컴포넌트 내부의 .avatar 요소에 재생합니다.
3. 비디오 트랙이 먼저 수신된 경우에도, <avatar-container>가 나중에 DOM에 추가되면 자동으로 바인딩됩니다.

배치 순서

웰컴 메시지가 설정된 아바타의 경우, <avatar-container>를 init() 호출 전에 DOM에 배치하세요. 웰컴 메시지는 연결 즉시 재생되므로, <avatar-container>가 DOM에 없으면 영상 없이 소리만 먼저 나올 수 있습니다.

스타일링

Shadow DOM

Shadow DOM으로 캡슐화되어 있어, style 속성은 컴포넌트의 크기, 위치, 테두리 등 외부 레이아웃에만 적용됩니다. 내부 비디오 요소의 스타일은 변경할 수 없습니다.

<avatar-container
  style="
    width: 100%;
    max-width: 500px;
    aspect-ratio: 9/16;
    border-radius: 16px;
    overflow: hidden;
  "
></avatar-container>

볼륨 제어

// 방법 1: 속성 변경 (내부적으로 SDK.setVolume()을 호출)
document.querySelector('avatar-container').volume = 50;

// 방법 2: SDK API 직접 호출
SDK.setVolume(50);

두 방법 모두 동일한 결과를 냅니다. 속성 변경 시 컴포넌트가 SDK.setVolume()을 자동 호출합니다.