# Klleon SDK

> AI 아바타와 실시간 대화를 구현하는 브라우저용 JavaScript SDK.
> CDN UMD 번들로 배포. window.KlleonSDK 글로벌 변수로 접근.

> llms-full.txt: https://klleon.docs.klleon.io/llms-full.txt

## 문서 목록

- [소개](https://klleon.docs.klleon.io/ko/index)
- [설치 및 설정](https://klleon.docs.klleon.io/ko/guide/getting-started)
- [init() — 초기화](https://klleon.docs.klleon.io/ko/api/init)
- [라이프사이클 (destroy, reconnect)](https://klleon.docs.klleon.io/ko/api/lifecycle)
- [메시징 (sendTextMessage, speak)](https://klleon.docs.klleon.io/ko/api/messaging)
- [음성 인식 (STT)](https://klleon.docs.klleon.io/ko/api/stt)
- [아바타 제어](https://klleon.docs.klleon.io/ko/api/avatar)
- [이벤트 (시그널, 상태, 에러)](https://klleon.docs.klleon.io/ko/api/events)
- [avatar-container 컴포넌트](https://klleon.docs.klleon.io/ko/components/avatar-container)
- [chat-container 컴포넌트](https://klleon.docs.klleon.io/ko/components/chat-container)
- [에러 처리 가이드](https://klleon.docs.klleon.io/ko/guides/error-handling)
- [TypeScript 지원](https://klleon.docs.klleon.io/ko/guides/typescript)
- [v1 마이그레이션](https://klleon.docs.klleon.io/ko/guides/migration-v1)
- [Vanilla JS 예제](https://klleon.docs.klleon.io/ko/examples/vanilla-js)
- [React 예제](https://klleon.docs.klleon.io/ko/examples/react)

---

# Klleon SDK

Klleon SDK는 웹 애플리케이션에 클레온의 실시간 인터랙티브 아바타를 통합하는 JavaScript SDK입니다. WebRTC 연결과 시그널링을 추상화하여 API 호출만으로 아바타 대화를 구현합니다.

## 주요 기능

- `<script>` 태그로 설치, UMD 번들 제공
- 텍스트/음성 양방향 통신
- 기본 Web Component 제공 또는 직접 UI 구성
- 콜백 기반 이벤트 구독 (상태, 시그널, 에러)
- TypeScript 타입 정의 제공

## 사전 준비 사항

SDK를 사용하기 전에 다음 준비가 필요합니다.

1. **클레온 스튜디오 계정** — [클레온 스튜디오](https://www.studio.klleon.io/)에서 가입
2. **도메인 등록** — SDK를 사용할 웹사이트의 [도메인 등록](https://www.studio.klleon.io/sdk) (SDK 관리 메뉴)
3. **SDK 키 발급** — 도메인 등록 후 `sdk_key` 발급
4. **아바타 ID 확인** — [아바타 목록](https://www.studio.klleon.io/avatar)에서 `avatar_id` 확인 (ID 복사가 가능한 아바타만 SDK 연동 가능)

> **TIP**
도메인 등록 또는 SDK 사용에 어려움이 있다면 `partnership@klleon.io`로 문의해 주세요.

## 빠른 시작


```js
const SDK = window.KlleonSDK;

// 이벤트 등록
SDK.onStatus((status) => console.log(status));
SDK.onSignal((data) => console.log(data.signal, data.payload));
SDK.onError((error) => console.error(error.code));

// 초기화
SDK.init({ sdk_key: 'YOUR_SDK_KEY', avatar_id: 'YOUR_AVATAR_ID' })
  .then(() => SDK.sendMessage('안녕하세요'))
  .catch((e) => console.error(e.message));
```

```jsx
import { useEffect, useRef } from 'react';

function AvatarChat() {
  const initialized = useRef(false);

  useEffect(() => {
    const SDK = window.KlleonSDK;

    SDK.onStatus((status) => console.log(status));
    SDK.onSignal((data) => console.log(data.signal, data.payload));
    SDK.onError((error) => console.error(error.code));

    SDK.init({ sdk_key: 'YOUR_SDK_KEY', avatar_id: 'YOUR_AVATAR_ID' })
      .then(() => { initialized.current = true; })
      .catch((e) => console.error('초기화 실패:', e.message));

    return () => {
      if (initialized.current) SDK.destroy();
    };
  }, []);

  return (
    <>
      <avatar-container style={{ width: 400, height: 400 }} />
      <button onClick={() => window.KlleonSDK.sendMessage('안녕하세요')}>
        전송
      </button>
    </>
  );
}
```

## LLM 참조

LLM에서 이 문서를 참조하려면 플레인 텍스트 버전을 사용하세요.

- [`/llms.txt`](/llms.txt) — 요약본
- [`/llms-full.txt`](/llms-full.txt) — 전체 문서

---

# init()

SDK를 초기화하고 아바타 연결을 시작합니다.

## 사용법

```js
await SDK.init(options);
```

## InitOption

| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
|---------|------|------|--------|------|
| `sdk_key` | `string` | O | - | SDK 인증 키 |
| `avatar_id` | `string` | O | - | 아바타 ID |
| `log_level` | `LogLevel` | X | `"debug"` | 로그 레벨 |
| `language` | `LanguageCode` | X | `"ko_kr"` | 언어 코드 (TTS 음성 + 자막) |
| `enable_microphone` | `boolean` | X | `true` | 마이크 활성화 (STT용) |
| `auto_send` | `boolean` | X | `false` | `false`(Push to Send): `startListening`/`endListening`으로 수동 제어. `true`(Auto Send): STT 상시 활성, 서버 VAD가 발화를 감지하여 자동 응답. Auto Send는 아바타가 지원하는 경우에만 동작하므로, 사전에 해당 아바타의 지원 여부를 확인하세요. |
| `stt_only` | `boolean` | X | `false` | STT 전용 모드. `true`이면 아바타가 응답하지 않고 STT 결과만 반환합니다. `false`이면 STT 결과를 반환하고, 해당 결과를 기반으로 아바타가 응답합니다. |

### LogLevel

브라우저 콘솔에 출력되는 로그 수준을 제어합니다. 설정한 레벨 이상만 출력됩니다.

| 값 | 출력 범위 | 용도 |
|----|----------|------|
| `"debug"` | debug, info, warn, error | 개발 중 상세 디버깅 (기본값) |
| `"info"` | info, warn, error | 주요 이벤트만 확인 (연결 완료, 초기화 등) |
| `"warn"` | warn, error | 잠재적 문제만 확인 |
| `"error"` | error | 에러만 출력 |
| `"silent"` | 없음 | 콘솔 출력 완전 비활성화 |

### LanguageCode

아바타의 TTS 음성 및 자막 언어를 지정합니다.

| 값 | 언어 |
|----|------|
| `"ko_kr"` | 한국어 (기본값) |
| `"en_us"` | 영어 |
| `"ja_jp"` | 일본어 |
| `"id_id"` | 인도네시아어 |

## 연결 흐름

```mermaid
sequenceDiagram
    participant App
    participant SDK
    participant API
    participant WS as WebSocket
    participant Streaming

    App->>SDK: init(options)
    SDK->>API: checkStatus (SDK 키 검증)
    API-->>SDK: OK
    SDK->>WS: connect
    WS-->>SDK: MATCHED (channel, token, uid)
    SDK->>Streaming: join(channel, token, uid)
    Streaming-->>SDK: video + audio track 수신
    SDK-->>App: status: CONNECTED_FINISH
```

## 에러 처리

실패 시 내부 cleanup 후 `IDLE`로 리셋하고 `Error`를 throw합니다.

```js
try {
  await SDK.init(options);
} catch (error) {
  // error.message에 실패 원인 포함
  // "Failed to connect: ..."          → SDK 키 검증 또는 WebSocket 연결 실패
  // "Failed to connect streaming: ..." → 스트리밍 연결 실패
  console.error(error.message);
}
```

- init/destroy 진행 중 재호출 시 이전 작업 완료를 기다린 후 실행됩니다 (Mutex 직렬화).

---

# 라이프사이클

## destroy()

SDK를 종료하고 모든 연결을 해제합니다.

```js
await SDK.destroy();
```

- WebSocket, 스트리밍 연결 종료
- 상태를 `IDLE`로 초기화
- 메시지 목록, 시그널 상태 초기화
- 원격 로거 분리

> **WARNING**
`destroy()`는 비동기 함수입니다. 반드시 `await`를 사용해야 합니다.

비활성 상태(`IDLE`)에서 호출하면 무시됩니다.
`destroy()` 후에도 이벤트 콜백은 유지되므로, 재초기화 시 다시 등록할 필요가 없습니다.

## 재연결

재연결이 필요한 경우 `destroy()` → `init()`을 사용하세요.

```js
await SDK.destroy();
await SDK.init(options);
```

## 라이프사이클 흐름

```mermaid
sequenceDiagram
    participant App
    participant SDK

    App->>SDK: 이벤트 콜백 등록
    App->>SDK: init(options)
    SDK-->>App: CONNECTING
    SDK-->>App: SOCKET_CONNECTED
    SDK-->>App: STREAMING_CONNECTED
    SDK-->>App: CONNECTED_FINISH
    Note over App,SDK: 아바타 사용 중
    App->>SDK: await destroy()
    SDK-->>App: IDLE
    Note over App,SDK: 콜백 유지됨
    App->>SDK: init(options)
    SDK-->>App: CONNECTING ...
```

## 상태 전이

```mermaid
flowchart TD
    IDLE -->|init| CONNECTING
    CONNECTING -->|WebSocket 연결| SOCKET_CONNECTED
    SOCKET_CONNECTED -->|비디오+오디오 수신| STREAMING_CONNECTED
    STREAMING_CONNECTED -->|완료| CONNECTED_FINISH
    CONNECTED_FINISH -->|destroy| IDLE

    CONNECTING -.->|연결 실패| IDLE
    SOCKET_CONNECTED -.->|스트리밍 실패| IDLE
    CONNECTED_FINISH -.->|런타임 에러| IDLE
```

### SDKStatus

| 값 | 설명 |
|----|------|
| `IDLE` | 초기/리셋 상태 |
| `CONNECTING` | HTTP 검증 + WebSocket 연결 중 |
| `CONNECTING_FAILED` | 연결 실패 (IDLE로 복귀) |
| `SOCKET_CONNECTED` | WebSocket 연결 완료 |
| `SOCKET_FAILED` | WebSocket 연결 실패 (IDLE로 복귀) |
| `STREAMING_CONNECTED` | 비디오+오디오 트랙 수신 완료 |
| `STREAMING_FAILED` | 스트리밍 연결 실패 (IDLE로 복귀) |
| `CONNECTED_FINISH` | 모든 연결 완료. 사용 가능 |

---

# 메시징

## sendMessage(text)

아바타에게 텍스트 메시지를 전송합니다. 아바타가 LLM 응답을 생성하여 음성으로 답합니다.

```js
SDK.sendMessage('안녕하세요');
```

| 파라미터 | 타입 | 설명 |
|---------|------|------|
| `text` | `string` | 전송할 메시지 |

## speak(text)

아바타가 주어진 텍스트를 그대로 읽도록 합니다 (LLM 처리 없이).

```js
SDK.speak('이 문장을 그대로 읽어주세요');
```

| 파라미터 | 타입 | 설명 |
|---------|------|------|
| `text` | `string` | 아바타가 읽을 텍스트 |

> **WARNING**
`stopSpeaking()` 직후 `speak()`나 `sendMessage()`를 바로 호출하면, 서버가 요청을 드랍할 수 있습니다. `RESPONSE_ENDED` 시그널을 수신한 후에 호출하세요.

```js
let pendingText = null;

SDK.onSignal((data) => {
  if (data.signal === 'RESPONSE_ENDED' && pendingText) {
    SDK.speak(pendingText);
    pendingText = null;
  }
});

function stopAndSpeak(text) {
  pendingText = text;
  SDK.stopSpeaking();
}
```

## sendSpeakAudio(audio)

Base64 인코딩된 오디오 데이터를 전송하여 아바타가 해당 음성으로 lip-sync 합니다.

```js
SDK.sendSpeakAudio(base64AudioData);
```

| 파라미터 | 타입 | 설명 |
|---------|------|------|
| `audio` | `string` | Base64 인코딩된 오디오 데이터 (최대 0.1MB) |

0.1MB 초과 또는 유효하지 않은 Base64 형식은 거부됩니다. 여러 번 호출하여 청크 단위로 전송할 수 있으며, 전송 완료 후 `endSpeakAudio()`를 호출하세요.

## endSpeakAudio()

오디오 에코 전송을 종료합니다. 서버가 이 신호를 받으면 수신한 오디오로 lip-sync 처리를 시작합니다.

```js
// 청크 단위로 전송 후 종료
for (const chunk of audioChunks) {
  SDK.sendSpeakAudio(chunk);
}
SDK.endSpeakAudio();
```

## clearMessages()

`<chat-container>` 사용 시 대화 메시지 목록을 비웁니다.

```js
SDK.clearMessages();
```

---

# 음성 인식 (STT)

> **TIP**
음성 입력을 기본 인터페이스로 사용하는 아바타의 경우, 연결 완료 시 자동으로 음성 인식을 시작할 수 있습니다.

```js
SDK.onStatus((status) => {
  if (status === 'CONNECTED_FINISH') {
    SDK.startListening();
  }
});
```

## startListening()

마이크를 활성화하고 음성 인식을 시작합니다.

```js
SDK.startListening();
```

## endListening()

음성 인식을 종료하고 마이크를 비활성화합니다.
인식된 텍스트가 있으면 아바타가 응답합니다.

```js
SDK.endListening();
```

## cancelListening()

음성 인식을 취소하고 마이크를 비활성화합니다.
인식된 텍스트를 폐기하고 아바타가 응답하지 않습니다.

```js
SDK.cancelListening();
```

## STT 관련 시그널

> **WARNING**
`startListening()` / `endListening()`은 **STT 세션**(마이크 ON/OFF)을 제어합니다.
`USER_SPEECH_STARTED` / `USER_SPEECH_STOPPED`는 세션 내 **발화 구간 감지**이며, 마이크는 계속 켜져 있습니다.
`USER_SPEECH_STOPPED`을 수신해도 STT 세션은 종료되지 않습니다. `endListening()`을 호출해야 종료됩니다.

```js
SDK.onSignal((data) => {
  switch (data.signal) {
    case 'USER_SPEECH_STARTED':
      // 사용자가 말하기 시작 (마이크는 이미 켜져 있음)
      console.log('사용자 발화 시작');
      break;
    case 'USER_SPEECH_STOPPED':
      // 사용자가 말을 멈춤 (마이크는 여전히 켜져 있음)
      console.log('사용자 발화 종료');
      break;
    case 'STT_RESULT':
      console.log('인식 결과:', data.payload.text);
      break;
  }
});
```

## 전체 STT 흐름

```mermaid
sequenceDiagram
    participant App
    participant SDK
    participant Server

    App->>SDK: startListening()
    Server-->>SDK: USER_SPEECH_STARTED
    Server-->>SDK: USER_SPEECH_STOPPED
    App->>SDK: endListening()
    Server-->>SDK: STT_RESULT (인식된 텍스트)
    Server-->>SDK: RESPONSE_TEXT (아바타 응답)
    Server-->>SDK: RESPONSE_ENDED
```

---

# 아바타 제어

## stopSpeaking()

아바타의 현재 발화를 즉시 중단합니다.

```js
SDK.stopSpeaking();
```

> **TIP**
`stopSpeaking()` 직후 `speak()`나 `sendMessage()`를 호출하면 서버가 요청을 드랍할 수 있습니다. 안전한 호출 패턴은 [메시징 > speak()](/ko/api/messaging#speak-text)를 참고하세요.

## setVolume(volume)

아바타 음성 볼륨을 설정합니다.

```js
SDK.setVolume(50); // 0 ~ 100
```

| 파라미터 | 타입 | 설명 |
|---------|------|------|
| `volume` | `number` | 볼륨 (0 ~ 100) |

## getStatus()

현재 SDK 연결 상태를 반환합니다.

```js
const status = SDK.getStatus();
// 'IDLE', 'CONNECTED_FINISH', ...
```

---

# 이벤트

### 이벤트 등록 타이밍

콜백은 `init()` 전후 언제든 등록할 수 있습니다. 단, `onStatus`는 `init()` 중 상태 변경(`CONNECTING`, `SOCKET_CONNECTED` 등)을 수신하려면 `init()` 호출 전에 등록하세요.

- 각 타입당 콜백 1개만 등록 가능하며, 마지막 등록이 이전을 덮어씁니다.
- `destroy()` 후에도 콜백은 유지되므로 재초기화 시 다시 등록할 필요 없습니다.

## onSignal(callback)

서버로부터 수신한 시그널을 받습니다.


```js
SDK.onSignal((data) => {
  console.log(data.signal, data.payload);
});
```

```jsx
useEffect(() => {
  window.KlleonSDK.onSignal((data) => {
    console.log(data.signal, data.payload);
  });
}, []);
```

### 콜백 파라미터

| 필드 | 타입 | 필수 | 설명 |
|------|------|------|------|
| `signal` | `IncomingSignal` | O | 시그널 종류 (enum, 런타임에는 문자열) |
| `payload` | `object` | X | 시그널별 추가 데이터 |
| `id` | `string` | O | 시그널 UUID |
| `type` | `string` | O | `"SESSION"` \| `"INPUT"` \| `"OUTPUT"` |

### 주요 시그널

#### 대화 흐름

| 시그널 | 설명 | payload |
|--------|------|---------|
| `RESPONSE_TEXT` | 아바타 응답 텍스트 | `{ text: string, language: string }` |
| `STT_RESULT` | 음성 인식 결과 | `{ text: string }` |
| `RESPONSE_PREPARING` | 응답 준비 중 (LLM 요청 직전) | - |
| `RESPONSE_STARTED` | 응답 시작 | - |
| `RESPONSE_ENDED` | 응답 완료 | - |
| `USER_SPEECH_STARTED` | STT 세션 내 발화 구간 시작 (마이크는 이미 켜져 있음) | - |
| `USER_SPEECH_STOPPED` | STT 세션 내 발화 구간 종료 (마이크는 여전히 켜져 있음) | - |
| `ERROR` | 서버 에러 (세션 유지) | `{ type: "STT_ERROR" \| "LLM_ERROR" \| ... }` |
| `REJECTED` | 입력 거절 (세션 유지) | `{ type: "STT_EMPTY" \| "MODERATION" \| ... }` |

#### 세션 관리

| 시그널 | 설명 | payload |
|--------|------|---------|
| `MATCH_WAITING` | 매칭 대기 중 (로딩 UI 표시용) | - |
| `WAIT` | 서버 준비 중 (계속 대기) | - |
| `SESSION_ENDED` | 세션 정상 종료 | - |
| `SESSION_TIMED_OUT` | 세션 타임아웃 | - |
| `TIME_EXHAUSTED` | 사용 시간 소진 | - |
| `QUOTA_EXCEEDED` | 동접 quota 초과 | - |
| `SUSPEND_WARNED` | 오랜 대기 경고 | - |

## onStatus(callback)

SDK 연결 상태 변경을 받습니다.


```js
SDK.onStatus((status) => {
  console.log('상태:', status);
  if (status === 'CONNECTED_FINISH') {
    console.log('아바타 준비 완료');
  }
});
```

```jsx
const [status, setStatus] = useState('IDLE');

useEffect(() => {
  window.KlleonSDK.onStatus((s) => setStatus(s));
}, []);
```

## onError(callback)

SDK 내부 에러 + 서버 에러를 받습니다.


```js
SDK.onError((error) => {
  console.error(error.code, error.message);
});
```

```jsx
useEffect(() => {
  window.KlleonSDK.onError((error) => {
    console.error(error.code, error.message);
  });
}, []);
```

### 콜백 파라미터

| 필드 | 타입 | 필수 | 설명 |
|------|------|------|------|
| `code` | `string` | O | 에러 코드 |
| `message` | `string` | X | 상세 메시지 |

### 에러 코드 상세

#### 초기화 에러 (init 실패 시)

| 코드 | 발생 시점 | message 예시 |
|------|-----------|-------------|
| `SOCKET_FAILED` | SDK 키 검증 실패 또는 WebSocket 연결 실패 | `"Failed to connect: ..."` |
| `STREAMING_FAILED` | 스트리밍 연결 실패 | `"Failed to connect streaming: ..."` |

> init 실패 시 `onError`는 호출되지 않습니다. `init()`이 `Error`를 throw하므로 `try/catch`로 처리하세요.

#### 런타임 에러 (연결 중 발생)

| 코드 | 발생 시점 | message 예시 |
|------|-----------|-------------|
| `SOCKET_DISCONNECTED_UNEXPECTEDLY` | WebSocket 에러 발생 | `"WebSocket disconnected unexpectedly"` |
| `STREAMING_FAILED` | 원격 트랙 구독 실패 | `"Failed to subscribe to remote track"` |
| `STREAMING_DISCONNECTED_UNEXPECTEDLY` | 스트리밍 비정상 종료 | `"Streaming disconnected: NETWORK_ERROR"` |

#### 서버 에러

| 코드 | 발생 시점 | message 예시 |
|------|-----------|-------------|
| `SERVER_ERROR` | 서버에서 `SERVER_ERROR` 시그널 수신 | 서버가 보낸 메시지 또는 `"SERVER_ERROR"` |
| `WORKER_DISCONNECTED` | 서버 연결 종료 시그널 수신 | `"WORKER_DISCONNECTED"` |

## 이벤트 등록 예제


```js
const SDK = window.KlleonSDK;

SDK.onStatus((status) => console.log('상태:', status));

SDK.onSignal((data) => {
  if (data.signal === 'RESPONSE_TEXT') {
    console.log('아바타:', data.payload.text);
  }
});

SDK.onError((error) => {
  console.error(`[${error.code}] ${error.message}`);
});

SDK.init({
  sdk_key: 'YOUR_SDK_KEY',
  avatar_id: 'YOUR_AVATAR_ID',
}).catch((e) => console.error(e.message));
```

```jsx
import { useEffect, useRef } from 'react';

function App() {
  const initialized = useRef(false);

  useEffect(() => {
    const SDK = window.KlleonSDK;

    SDK.onStatus((status) => console.log('상태:', status));

    SDK.onSignal((data) => {
      if (data.signal === 'RESPONSE_TEXT') {
        console.log('아바타:', data.payload.text);
      }
    });

    SDK.onError((error) => {
      console.error(`[${error.code}] ${error.message}`);
    });

    SDK.init({
      sdk_key: 'YOUR_SDK_KEY',
      avatar_id: 'YOUR_AVATAR_ID',
    })
      .then(() => { initialized.current = true; })
      .catch((e) => console.error(e.message));

    return () => {
      if (initialized.current) SDK.destroy();
    };
  }, []);

  return <avatar-container style={{ width: 400, height: 600 }} />;
}
```

---

# avatar-container

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

## 사용법

```html
<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에 추가되면 자동으로 바인딩됩니다.

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

## 스타일링

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

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

## 볼륨 제어

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

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

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

---

# chat-container

채팅 인터페이스를 제공하는 Web Component입니다. 텍스트 입력과 음성 입력 모드를 지원합니다.

## 사용법

```html
<chat-container delay="50"></chat-container>
```

## 속성

| 속성 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `type` | `string` | `"text"` | 입력 모드. `"text"` \| `"voice"` |
| `delay` | `number` | `30` | 응답 텍스트 타이핑 효과 딜레이 (글자당 ms). `0`이면 즉시 표시. |
| `isShowCount` | `boolean` | `true` | 텍스트 모드에서 글자 수 카운터 표시 여부 |
| `scrollbar` | `boolean` | `false` | 메시지 영역 스크롤바 표시 여부. `false`이면 스크롤바를 숨깁니다. |

## 입력 모드

### 텍스트 모드 (`type="text"`)

텍스트 입력창과 전송 버튼을 표시합니다.

- **전송**: Enter 키 또는 전송 아이콘 클릭
- **줄바꿈**: Shift + Enter
- **IME 처리**: 한국어/일본어 등 조합 중에는 Enter로 전송되지 않습니다.
- **글자 제한**: 최대 350자
- **모바일**: 모바일 환경에서는 Enter 키가 줄바꿈으로 동작합니다 (전송 버튼 사용).
- **자동 포커스**: 아바타 응답 완료 후 텍스트 입력창에 자동 포커스됩니다.

우측의 마이크 아이콘을 클릭하면 음성 모드로 전환됩니다.

### 음성 모드 (`type="voice"`)

마이크 버튼을 표시합니다.

- **녹음 시작**: 마이크 버튼 클릭
- **녹음 종료**: 정지 버튼 클릭 또는 **10초** 경과 시 자동 종료
- **시각 피드백**: 녹음 중 파형 애니메이션과 카운트다운 타이머 표시
- 내부적으로 `SDK.startListening()`, `SDK.endListening()`을 호출합니다.

좌측의 키보드 아이콘을 클릭하면 텍스트 모드로 전환됩니다.

## 메시지 표시

- SDK의 메시지 목록(`sendMessage`, `speak`, STT 결과, 아바타 응답)을 자동으로 표시합니다.
- 가상 스크롤링을 사용하여 대량의 메시지도 성능 저하 없이 렌더링합니다.
- 새 메시지 수신 시 자동으로 하단으로 스크롤됩니다.

### 타이핑 효과

- 아바타 응답(response) 메시지는 `delay` 속성에 지정된 간격으로 한 글자씩 표시됩니다.
- 사용자 메시지(request)는 타이핑 효과 없이 즉시 표시됩니다.
- 새 메시지가 도착하면 진행 중인 타이핑이 즉시 완료되고 새 메시지의 타이핑이 시작됩니다.

### 로딩 표시

아바타가 응답을 준비 중일 때(`RESPONSE_PREPARING` 시그널) 마지막 사용자 메시지 아래에 로딩 애니메이션이 표시됩니다.

## 비활성 상태

SDK 상태가 `CONNECTED_FINISH`가 아니거나, 아바타가 응답 중일 때 입력이 비활성화됩니다.
다음 시그널이 수신되면 입력이 다시 활성화됩니다:

- `RESPONSE_ENDED` — 아바타 응답 완료
- `ERROR` — 에러 수신
- `REJECTED` — 요청 거절
- `SLEEP_STARTED` / `SLEEP_ENDED` — 수면 상태 변경

## 스타일링

> **WARNING**
Shadow DOM으로 캡슐화되어 있어, `style` 속성은 컴포넌트의 크기, 위치, 테두리 등 **외부 레이아웃**에만 적용됩니다. 내부 요소(배경색, 메시지 버블 등)의 스타일은 변경할 수 없습니다.

```html
<chat-container
  style="
    height: 300px;
    border: 1px solid #e0e0e0;
    border-radius: 12px;
  "
></chat-container>
```

---

## 전체 레퍼런스

상세 내용은 [llms-full.txt](https://klleon.docs.klleon.io/llms-full.txt)를 참조.