# kokoro-tiny 🎤
[](https://crates.io/crates/kokoro-tiny)
[](https://docs.rs/kokoro-tiny)
[](LICENSE)
Minimal, blazing-fast TTS (Text-to-Speech) crate powered by the Kokoro model (82M params). Perfect for embedding in applications, system alerts, and smart tools!
## Features
- ⚡ **Extremely fast inference** using ONNX Runtime
- 🎨 **50+ built-in voices** with style mixing support
- 🔊 **Direct audio playback** with volume control
- 📁 **Multiple formats**: WAV, MP3, OPUS, FLAC
- 💾 **Smart caching** - downloads model once to `~/.cache/kokoros`
- 🛠️ **CLI included** - `kokoro-speak` for instant TTS
## Quick Start
Add to your `Cargo.toml`:
```toml
[dependencies]
kokoro-tiny = "0.1"
```
## Usage
### As a Library
```rust
use kokoro_tiny::TtsEngine;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Initialize (downloads model on first run)
let mut tts = TtsEngine::new().await?;
// Generate speech
let audio = tts.synthesize("Hello, world!", Some("af_sky"))?;
// Save to file
tts.save_wav("output.wav", &audio)?;
// Or play directly (with 'playback' feature)
#[cfg(feature = "playback")]
tts.play(&audio, 0.8)?; // 80% volume
Ok(())
}
```
### Voice Mixing
Create unique voices by blending:
```rust
// Mix voices with weights
let audio = tts.synthesize(
"Creative voice mixing!",
Some("af_sky.8+af_bella.2") // 80% Sky + 20% Bella
)?;
```
### CLI Tool
Install the CLI:
```bash
cargo install kokoro-tiny
```
Use it instantly:
```bash
# Speak text
kokoro-speak say "Hello from kokoro!"
# System alerts
kokoro-speak alert success "Build complete!"
# Pipe input
# Context summaries (perfect for smart-tree!)
kokoro-speak context "Found 5 TypeScript files with 200 lines total"
# Save to file
kokoro-speak say "Save this speech" -o output.wav
# List voices
kokoro-speak --list-voices
```
## Available Voices
50+ voices across accents and styles:
- **American**: af_sky, af_bella, am_adam, am_michael
- **British**: bf_emma, bm_george
- **Special**: af_heart (warm), am_echo (clear)
Use `--list-voices` to see all options!
## Features
Enable additional capabilities:
```toml
[dependencies]
kokoro-tiny = { version = "0.1", features = ["all-formats"] }
```
- `playback` - Direct audio playback (default)
- `mp3` - MP3 encoding support
- `opus-format` - OPUS for streaming/VoIP
- `cuda` - GPU acceleration
- `all-formats` - All audio formats
## Examples
Check out the [examples](https://github.com/8b-is/kokoro-tiny/tree/main/examples) directory:
```bash
# Simple usage
cargo run --example simple
# Test all voices
cargo run --example test_voices
# Audio format comparison
cargo run --features all-formats --example audio_formats
```
## Performance
- **Time-to-first-audio**: 0.5-2 seconds
- **Model size**: 82M parameters
- **Audio quality**: 24kHz sample rate
- **Memory usage**: ~200MB with model loaded
## Use Cases
Perfect for:
- 🔔 **System notifications** - Build alerts, test results
- 📊 **Smart tools** - Audio context summaries
- 🎮 **Game development** - Dynamic NPC voices
- 📱 **Accessibility** - Screen reader functionality
- 🤖 **Automation** - Voice announcements for scripts
## Model Details
kokoro-tiny uses the [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) model:
- Lightweight transformer architecture
- Trained on extensive speech datasets
- Optimized for CPU inference
## Contributing
Contributions welcome! This project is maintained by Hue & Aye at [8b.is](https://8b.is).
For the full Kokoro implementation with advanced features, check out [Kokoros](https://github.com/8b-is/Kokoros).
## License
Apache 2.0 - See [LICENSE](https://github.com/8b-is/kokoro-tiny/blob/main/LICENSE)
---