# narrate

Local text-to-speech with multiple engine support.

## Install

```bash
pip install narrate[kokoro]       # Kokoro 82M — fast, runs on CPU
pip install narrate[chatterbox]   # Chatterbox 500M — high quality, emotion control
pip install narrate[all]          # Both engines + audio playback
```

## Usage

```python
from narrate import narrate

# Uses the best available engine and default voice
narrate("Hello world")

# Choose voice (second positional argument)
narrate("Hello world", "am_adam")        # male voice
narrate("Hello world", "bf_emma")        # British female
narrate("Hello world", "af_sarah")       # soft female

# Keyword style with speed control
narrate("Hello world", voice="af_heart", speed=1.2)

# Chatterbox with emotion control (0.0 = neutral, 1.0 = expressive)
narrate("Hello world", engine="chatterbox", emotion=0.8)

# Save to file without playing
narrate("Hello world", output="hello.wav", play=False)
```

## Available Voices (Kokoro)

| Voice ID | Name | Description |
|----------|------|-------------|
| `af_heart` | Heart | Female, warm (default) |
| `af_bella` | Bella | Female, clear |
| `af_nicole` | Nicole | Female, professional |
| `af_sarah` | Sarah | Female, soft |
| `af_sky` | Sky | Female, bright |
| `am_adam` | Adam | Male, deep |
| `am_michael` | Michael | Male, natural |
| `bf_emma` | Emma | British female |
| `bm_george` | George | British male |

```python
# List all available voices programmatically
from narrate import list_voices
for v in list_voices():
    print(f"{v['id']:15} {v['name']:10} {v['description']}")
```

## Engines

| Engine | Params | Speed | Quality | Features |
|--------|--------|-------|---------|----------|
| Kokoro | 82M | Fast (CPU) | Good | 9 voices, speed control |
| Chatterbox | 500M | Moderate | Excellent | Emotion control, voice cloning |

## License

MIT
