kokoro-tts-tool

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
• Features
• Installation
• Quick Start
• Usage
• Infinite Streaming
• Available Voices
• Multi-Level Verbosity Logging
• Shell Completion
• Development
• Testing
• Security
• Contributing
• License
• Author

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