Metadata-Version: 2.4
Name: narrate
Version: 0.1.1
Summary: Local text-to-speech with Kokoro and Chatterbox engines
Project-URL: Homepage, https://github.com/yu314-coder/narrate
Project-URL: Repository, https://github.com/yu314-coder/narrate
Author: Manim Studio
License-Expression: MIT
License-File: LICENSE
Keywords: chatterbox,kokoro,narration,text-to-speech,tts,voice
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.9
Requires-Dist: numpy
Requires-Dist: soundfile>=0.12
Provides-Extra: all
Requires-Dist: chatterbox-tts>=0.1; extra == 'all'
Requires-Dist: kokoro-onnx>=0.4; extra == 'all'
Requires-Dist: onnxruntime>=1.17; extra == 'all'
Requires-Dist: sounddevice>=0.4; extra == 'all'
Requires-Dist: torch>=2.0; extra == 'all'
Requires-Dist: torchaudio>=2.0; extra == 'all'
Provides-Extra: chatterbox
Requires-Dist: chatterbox-tts>=0.1; extra == 'chatterbox'
Requires-Dist: torch>=2.0; extra == 'chatterbox'
Requires-Dist: torchaudio>=2.0; extra == 'chatterbox'
Provides-Extra: kokoro
Requires-Dist: kokoro-onnx>=0.4; extra == 'kokoro'
Requires-Dist: onnxruntime>=1.17; extra == 'kokoro'
Provides-Extra: play
Requires-Dist: sounddevice>=0.4; extra == 'play'
Description-Content-Type: text/markdown

# 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
