> ## Documentation Index
> Fetch the complete documentation index at: https://typecast.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# LlamaIndex

<Info>
  [LlamaIndex](https://www.llamaindex.ai/)는 LLM 애플리케이션을 구축하기 위한 강력한 데이터 프레임워크입니다. Typecast 도구 연동을 통해 AI 에이전트가 감정 조절이 가능한 표현력 있는 음성을 생성할 수 있습니다.
</Info>

## LlamaIndex란?

LlamaIndex는 컨텍스트 기반 LLM 애플리케이션을 구축하기 위한 Python 프레임워크입니다. 데이터 수집, 인덱싱, 쿼리 도구와 외부 도구를 사용할 수 있는 에이전트 기능을 제공합니다.

Typecast 도구를 사용하면 LlamaIndex 에이전트에서:

- **텍스트로부터 음성 생성** - 다양한 목소리로 커스터마이징 가능
- **감정 조절** - 행복, 슬픔, 화남, 속삭임 등 다양한 감정 표현
- **목소리 탐색** - 모델, 성별, 연령, 용도별 필터링
- **재현 가능한 오디오 생성** - seed 파라미터 활용

---

## 사전 요구사항

시작하기 전에 다음을 준비하세요:

| 요구사항 | 버전 |
|----------|------|
| Python | 3.11+ |
| LlamaIndex Core | 0.13–0.14 |
| 타입캐스트 API 키 | [여기서 발급받기](https://studio.typecast.ai/developers/api/) |

---

## 설치

LlamaIndex용 Typecast 도구를 설치합니다:

```bash
pip install llama-index-tools-typecast
```

<Tip>
  에이전트 사용을 위해 LLM 프로바이더도 설치하세요: `pip install llama-index-llms-openai`
</Tip>

---

## 빠른 시작

LlamaIndex 에이전트에서 Typecast TTS를 사용하는 간단한 예제입니다:

```python
from llama_index.tools.typecast import TypecastToolSpec
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

# Typecast 도구 초기화
speech_tool = TypecastToolSpec(api_key="your-typecast-key")

# Typecast 기능을 가진 에이전트 생성
agent = FunctionAgent(
    tools=speech_tool.to_tool_list(),
    llm=OpenAI(model="gpt-4o-mini"),
)

# 에이전트를 통해 음성 생성
result = await agent.run(
    'Create speech from the text "Hello world!" with a happy emotion '
    'and output the file to "speech.wav"'
)
print(result)
```

<Note>
  환경 변수 설정:
  - `OPENAI_API_KEY` - OpenAI API 키 (에이전트의 LLM용)
  - 타입캐스트 API 키는 `TypecastToolSpec` 생성자에 직접 전달
</Note>

---

## 제공되는 도구

`TypecastToolSpec`은 에이전트에서 사용할 수 있는 세 가지 도구를 제공합니다:

<CardGroup cols={3}>
  <Card title="text_to_speech" icon="volume-high">
    텍스트를 음성으로 변환. 감정, 피치, 템포 조절 및 재현 가능한 결과 생성.
  </Card>
  <Card title="get_voices" icon="users">
    선택적 필터링과 함께 사용 가능한 모든 Typecast 목소리 목록 조회.
  </Card>
  <Card title="get_voice" icon="user">
    ID로 특정 목소리의 상세 정보 조회.
  </Card>
</CardGroup>

---

## 직접 사용 (에이전트 없이)

더 세밀한 제어가 필요한 경우 도구를 직접 사용할 수 있습니다:

### 목소리 탐색

```python
from llama_index.tools.typecast import TypecastToolSpec

speech_tool = TypecastToolSpec(api_key="your-typecast-key")

# 선택적 필터로 사용 가능한 목소리 조회
voices = speech_tool.get_voices(
    model="ssfm-v30",
    gender="female",
    age="young_adult",
    use_case="Audiobook"
)
print(f"{len(voices)}개의 목소리를 찾았습니다")

for voice in voices:
    print(f"{voice['voice_name']} ({voice['voice_id']})")
```

### 목소리 상세 정보 조회

```python
# 특정 목소리 정보 조회
voice = speech_tool.get_voice("tc_62a8975e695ad26f7fb514d1")
print(f"목소리: {voice['voice_name']}")
print(f"성별: {voice.get('gender')}, 연령: {voice.get('age')}")
print(f"용도: {voice.get('use_cases')}")

# 모델별 지원 감정 확인
for model in voice["models"]:
    print(f"모델 {model['version']}: 감정 = {model['emotions']}")
```

### 음성 생성

```python
# 모든 파라미터를 사용한 텍스트-음성 변환
output_path = speech_tool.text_to_speech(
    text="안녕하세요! 테스트입니다.",
    voice_id="tc_62a8975e695ad26f7fb514d1",
    output_path="speech.wav",
    model="ssfm-v30",
    language="kor",
    emotion_preset="happy",
    emotion_intensity=1.5,
    volume=100,
    audio_pitch=0,
    audio_tempo=1.0,
    audio_format="wav",
    seed=42,  # 부호 없는 정수 시드 (재현 가능한 결과)
)
print(f"오디오 저장 완료: {output_path}")
```

---

## 기능

### 다양한 음성 모델

Typecast는 여러 AI 음성 모델 버전을 지원합니다:

| 모델 | 설명 |
|------|------|
| `ssfm-v30` | 향상된 감정 표현이 가능한 최신 모델 (권장) |
| `ssfm-v21` | 하위 호환성을 위한 레거시 모델 |

### 감정 조절

생성되는 음성의 감정 표현을 조절할 수 있습니다:

| 감정 | ssfm-v30 | ssfm-v21 |
|------|----------|----------|
| `normal` | ✓ | ✓ |
| `happy` | ✓ | ✓ |
| `sad` | ✓ | ✓ |
| `angry` | ✓ | ✓ |
| `whisper` | ✓ | - |
| `toneup` | ✓ | - |
| `tonedown` | ✓ | - |

`emotion_intensity` (0.0 - 2.0)로 표현력을 조절합니다. 1.0보다 큰 값은 강도를 높입니다.

### 다국어 지원

Typecast는 27개 이상의 언어를 지원합니다:

- 영어 (`eng`)
- 한국어 (`kor`)
- 일본어 (`jpn`)
- 중국어 (`zho`)
- 스페인어 (`spa`)
- 그 외 다수...

### 오디오 커스터마이징

오디오 출력을 세밀하게 조정할 수 있습니다:

| 파라미터 | 범위 | 설명 |
|----------|------|------|
| `volume` | 0 - 200 | 오디오 볼륨 (백분율) |
| `audio_pitch` | -12 ~ 12 | 반음 단위 조정 |
| `audio_tempo` | 0.5 - 2.0 | 재생 속도 (권장: 0.85 - 1.15) |
| `audio_format` | `wav`, `mp3` | 출력 형식 |
| `seed` | uint32 | 재현 가능한 오디오 생성을 위한 부호 없는 정수 시드 (≥ 0) |

---

## 전체 에이전트 예제

목소리를 탐색하고 음성을 생성하는 에이전트의 전체 예제입니다:

```python
import os
from llama_index.tools.typecast import TypecastToolSpec
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

# API 키 설정
os.environ["OPENAI_API_KEY"] = "your-openai-key"

# Typecast 도구 초기화
speech_tool = TypecastToolSpec(api_key="your-typecast-key")

# Typecast 기능을 가진 에이전트 생성
agent = FunctionAgent(
    tools=speech_tool.to_tool_list(),
    llm=OpenAI(model="gpt-4o-mini"),
)

# 에이전트가 목소리를 탐색하고 음성을 생성하도록 요청
result = await agent.run(
    'Get the list of available voices, select the first female voice, '
    'and use it to create speech from the text "Welcome to Typecast!" '
    'with a happy emotion, saving to "welcome.wav"'
)
print(result)
```

---

## 문제 해결

<AccordionGroup>
  <Accordion title="API 키를 찾을 수 없음 오류">
    - `TypecastToolSpec`에 올바른 API 키를 전달했는지 확인하세요
    - [타입캐스트 API 콘솔](https://studio.typecast.ai/developers/api/)에서 키를 확인하세요
    - 키에 불필요한 공백이 있는지 확인하세요
  </Accordion>
  <Accordion title="오디오 파일이 생성되지 않음">
    - 출력 경로에 쓰기 권한이 있는지 확인하세요
    - API 키에 충분한 크레딧이 있는지 확인하세요
    - voice_id가 유효한지 확인하세요
  </Accordion>
  <Accordion title="Import 오류">
    - `llama-index-tools-typecast`를 설치했는지 확인하세요
    - 에이전트 사용 시 `llama-index-llms-openai` 또는 선호하는 LLM 프로바이더도 설치하세요
    - Python 버전이 3.11 이상인지 확인하세요
    - `llama-index-core` 버전이 0.13 또는 0.14인지 확인하세요
  </Accordion>
  <Accordion title="에이전트가 도구를 올바르게 사용하지 않음">
    - 에이전트에게 원하는 작업을 구체적으로 프롬프트하세요
    - 복잡한 작업은 간단한 단계로 나누세요
    - 오디오 파일의 출력 경로 예시를 제공하세요
  </Accordion>
</AccordionGroup>

---

## 리소스

<CardGroup cols={2}>
  <Card
    title="GitHub 저장소"
    icon="github"
    href="https://github.com/run-llama/llama_index/tree/main/llama-index-integrations/tools/llama-index-tools-typecast"
  >
    소스 코드 및 예제
  </Card>
  <Card
    title="LlamaHub"
    icon="book"
    href="https://llamahub.ai/l/tools/llama-index-tools-typecast"
  >
    LlamaHub에서 보기
  </Card>
  <Card
    title="LlamaIndex 문서"
    icon="book-open"
    href="https://docs.llamaindex.ai/"
  >
    LlamaIndex 더 알아보기
  </Card>
  <Card
    title="목소리 라이브러리"
    icon="microphone"
    href="https://studio.typecast.ai/developers/api/voices"
  >
    사용 가능한 목소리 탐색
  </Card>
</CardGroup>