> ## 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/) is a powerful data framework for building LLM applications. The Typecast tool integration allows your AI agents to generate expressive speech from text with emotion control.
</Info>

## What is LlamaIndex?

LlamaIndex is a Python framework for building context-augmented LLM applications. It provides tools for data ingestion, indexing, and querying, as well as agent capabilities that can use external tools.

With the Typecast tool, your LlamaIndex agents can:

- **Generate speech** from text with customizable voices
- **Control emotions** (happy, sad, angry, whisper, and more)
- **Discover voices** by filtering model, gender, age, or use case
- **Create reproducible audio** using seed parameters

---

## Prerequisites

Before you start, make sure you have:

| Requirement | Version |
|-------------|---------|
| Python | 3.11+ |
| LlamaIndex Core | 0.13–0.14 |
| Typecast API Key | [Get yours here](https://studio.typecast.ai/developers/api/) |

---

## Installation

Install the Typecast tool for LlamaIndex:

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

<Tip>
  For agent usage, also install an LLM provider: `pip install llama-index-llms-openai`
</Tip>

---

## Quick Start

Here's a minimal example of using Typecast TTS with a LlamaIndex agent:

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

# Initialize the Typecast tool
speech_tool = TypecastToolSpec(api_key="your-typecast-key")

# Create an agent with Typecast capabilities
agent = FunctionAgent(
    tools=speech_tool.to_tool_list(),
    llm=OpenAI(model="gpt-4o-mini"),
)

# Generate speech through the agent
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>
  Set your environment variables:
  - `OPENAI_API_KEY` - Your OpenAI API key (for the agent's LLM)
  - Use your Typecast API key directly in the `TypecastToolSpec` constructor
</Note>

---

## Available Tools

The `TypecastToolSpec` provides three tools for your agents:

<CardGroup cols={3}>
  <Card title="text_to_speech" icon="volume-high">
    Convert text to speech with emotion, pitch, tempo control, and reproducible results.
  </Card>
  <Card title="get_voices" icon="users">
    List all available Typecast voices with optional filtering.
  </Card>
  <Card title="get_voice" icon="user">
    Get details of a specific voice by ID.
  </Card>
</CardGroup>

---

## Direct Usage (Without Agent)

You can also use the tool directly for more control:

### Discover Voices

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

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

# Get all available voices with optional filters
voices = speech_tool.get_voices(
    model="ssfm-v30",
    gender="female",
    age="young_adult",
    use_case="Audiobook"
)
print(f"Found {len(voices)} voices")

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

### Get Voice Details

```python
# Get specific voice information
voice = speech_tool.get_voice("tc_62a8975e695ad26f7fb514d1")
print(f"Voice: {voice['voice_name']}")
print(f"Gender: {voice.get('gender')}, Age: {voice.get('age')}")
print(f"Use cases: {voice.get('use_cases')}")

# Models include supported emotions
for model in voice["models"]:
    print(f"Model {model['version']}: emotions = {model['emotions']}")
```

### Generate Speech

```python
# Text-to-speech with full parameter control
output_path = speech_tool.text_to_speech(
    text="Hello world! This is a test.",
    voice_id="tc_62a8975e695ad26f7fb514d1",
    output_path="speech.wav",
    model="ssfm-v30",
    language="eng",
    emotion_preset="happy",
    emotion_intensity=1.5,
    volume=100,
    audio_pitch=0,
    audio_tempo=1.0,
    audio_format="wav",
    seed=42,  # Unsigned seed for reproducible results
)
print(f"Audio saved to: {output_path}")
```

---

## Features

### Multiple Voice Models

Typecast supports multiple AI voice model versions:

| Model | Description |
|-------|-------------|
| `ssfm-v30` | Latest model with enhanced emotions (recommended) |
| `ssfm-v21` | Legacy model for backward compatibility |

### Emotion Control

Control the emotional expression of generated speech:

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

Use `emotion_intensity` (0.0 - 2.0) to adjust expressiveness. Values greater than 1.0 increase intensity.

### Multi-Language Support

Typecast supports 27+ languages including:

- English (`eng`)
- Korean (`kor`)
- Japanese (`jpn`)
- Chinese (`zho`)
- Spanish (`spa`)
- And many more...

### Audio Customization

Fine-tune your audio output:

| Parameter | Range | Description |
|-----------|-------|-------------|
| `volume` | 0 - 200 | Audio volume as percentage |
| `audio_pitch` | -12 to 12 | Semitone adjustment |
| `audio_tempo` | 0.5 - 2.0 | Playback speed (recommended: 0.85 - 1.15) |
| `audio_format` | `wav`, `mp3` | Output format |
| `seed` | uint32 | Unsigned integer seed for reproducible audio generation (≥ 0) |

---

## Complete Agent Example

Here's a full example with an agent that can discover voices and generate speech:

```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

# Set up API keys
os.environ["OPENAI_API_KEY"] = "your-openai-key"

# Initialize Typecast tool
speech_tool = TypecastToolSpec(api_key="your-typecast-key")

# Create agent with Typecast capabilities
agent = FunctionAgent(
    tools=speech_tool.to_tool_list(),
    llm=OpenAI(model="gpt-4o-mini"),
)

# Let the agent discover voices and generate speech
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)
```

---

## Troubleshooting

<AccordionGroup>
  <Accordion title="API key not found error">
    - Ensure you're passing the correct API key to `TypecastToolSpec`
    - Verify your key at [Typecast API Console](https://studio.typecast.ai/developers/api/)
    - Check for extra spaces in the key
  </Accordion>
  <Accordion title="No audio file created">
    - Check that the output path is writable
    - Verify your API key has sufficient credits
    - Ensure the voice_id is valid
  </Accordion>
  <Accordion title="Import errors">
    - Make sure you installed `llama-index-tools-typecast`
    - For agent usage, also install `llama-index-llms-openai` or your preferred LLM provider
    - Verify Python version is 3.11 or higher
    - Verify `llama-index-core` is version 0.13 or 0.14
  </Accordion>
  <Accordion title="Agent not using the tools correctly">
    - Be specific in your prompts about what you want the agent to do
    - Break down complex tasks into simpler steps
    - Provide example output paths for audio files
  </Accordion>
</AccordionGroup>

---

## Resources

<CardGroup cols={2}>
  <Card
    title="GitHub Repository"
    icon="github"
    href="https://github.com/run-llama/llama_index/tree/main/llama-index-integrations/tools/llama-index-tools-typecast"
  >
    Source code and examples
  </Card>
  <Card
    title="LlamaHub"
    icon="book"
    href="https://llamahub.ai/l/tools/llama-index-tools-typecast"
  >
    View on LlamaHub
  </Card>
  <Card
    title="LlamaIndex Documentation"
    icon="book-open"
    href="https://docs.llamaindex.ai/"
  >
    Learn more about LlamaIndex
  </Card>
  <Card
    title="Voice Library"
    icon="microphone"
    href="https://studio.typecast.ai/developers/api/voices"
  >
    Browse available voices
  </Card>
</CardGroup>