kokoro-tts-tool
A CLI that provides local text-to-speech using Kokoro TTS on Apple Silicon. No API keys required.
Table of Contents
About
kokoro-tts-tool is a Python CLI tool for local text-to-speech synthesis using the Kokoro-82M model. It runs entirely on your machine with no cloud dependencies, optimized for Apple Silicon Macs.
Key highlights:
- Local inference: Uses ONNX runtime for fast, CPU-optimized synthesis
- 60+ voices: Multiple languages and accents (English, Japanese, Mandarin, etc.)
- Near real-time: Fast enough for interactive use on Apple Silicon
- Infinite streaming: Continuous TTS for long documents without audio artifacts
- No API keys: Everything runs locally, completely free
Features
- Local TTS with Kokoro-82M (82 million parameters)
- 60+ voices across 8 languages
- Near real-time synthesis on Apple Silicon
- Auto-download of model files (~350MB)
- WAV output or direct speaker playback
- Infinite streaming for long documents (books, articles)
- Seamless audio without pop artifacts between chunks
- Fast offline rendering (20-50x real-time on M4)
- Type-safe with mypy strict mode
- Tested with pytest
- Multi-level verbosity logging (-v/-vv/-vvv)
- Shell completion for bash, zsh, and fish
- Security scanning with bandit, pip-audit, and gitleaks
Installation
Prerequisites
- Python 3.14 or higher
- uv package manager
- Apple Silicon Mac (recommended) or any platform with Python 3.14+
Install from source
# Clone the repository
git clone https://github.com/dnvriend/kokoro-tts-tool.git
cd kokoro-tts-tool
# Install globally with uv
uv tool install .
Install with mise (recommended for development)
cd kokoro-tts-tool
mise trust
mise install
uv sync
uv tool install .
Verify installation
kokoro-tts-tool --version
Quick Start
# 1. Initialize (downloads models on first run, ~350MB)
kokoro-tts-tool init
# 2. Synthesize text to speakers
kokoro-tts-tool synthesize "Hello world!"
# 3. Save to file
kokoro-tts-tool synthesize "Hello world!" --output hello.wav
# 4. Use different voice
kokoro-tts-tool synthesize "This is Adam." --voice am_adam
# 5. List available voices
kokoro-tts-tool list-voices
Usage
Commands
# Show all commands
kokoro-tts-tool --help
# Download/update models
kokoro-tts-tool init
# Synthesize text
kokoro-tts-tool synthesize "Your text here"
kokoro-tts-tool synthesize "Your text" --output speech.wav
kokoro-tts-tool synthesize "Your text" --voice bf_emma --speed 1.2
# Read from stdin
echo "Hello from stdin" | kokoro-tts-tool synthesize --stdin
# List voices
kokoro-tts-tool list-voices
kokoro-tts-tool list-voices --language English
kokoro-tts-tool list-voices --gender Female
kokoro-tts-tool list-voices --json
# Show configuration
kokoro-tts-tool info
Synthesize Options
| Option | Description | Default |
|---|
--voice, -v | Voice ID (e.g., af_heart, am_adam) | af_heart |
--output, -o | Output WAV file path | (plays to speakers) |
--speed | Speech speed (0.5 to 2.0) | 1.0 |
--stdin, -s | Read text from stdin | false |
Infinite Streaming
Stream long documents (books, articles, study materials) without audio artifacts:
# Stream a markdown file to speakers
kokoro-tts-tool infinite --input book.md
# Render to WAV file (fast offline mode, 20-50x real-time on M4)
kokoro-tts-tool infinite --input book.md --output audiobook.wav
# Pipe from stdin
cat chapter.md | kokoro-tts-tool infinite --stdin
# With custom voice and speed
kokoro-tts-tool infinite --input notes.md --voice am_adam --speed 1.2
