kokorosay

kokorosay is a fast, lightweight command-line text-to-speech (TTS) tool built on top of Kokoro.

Pass text as an argument or pipe it via standard input; kokorosay will immediately stream speech through your speakers or export it to high-quality WAV or MP3 audio files.

Features

• ⚡ Fast & Lightweight: Built on the open-weights 82M parameter Kokoro model (hexgrad/Kokoro-82M).
• 🔊 Direct Low-Latency Playback: Streams audio chunks to your default audio device in real time as they are generated.
• 💾 WAV & MP3 Export: Concatenates synthesized chunks into a seamless 24 kHz audio file; parent directories are created automatically.
• 🌐 9 Languages & 50+ Voices: Supports English, Japanese, Mandarin Chinese, Spanish, French, Hindi, Italian, and Brazilian Portuguese (pre-generated samples in examples/).
• 🔀 Automatic Language Detection: The target language is derived directly from the voice name prefix (e.g. jf_nezumi → Japanese, zf_xiaobei → Mandarin, af_heart → American English).
• 📥 Pipeline & Stdin Friendly: Supports - as input with explicit UTF-8 and BOM decoding, ideal for shell pipes and automation scripts.
• 🎛️ Synthesis Controls: Easily adjust speech rate multiplier (--speed) or provide custom segment-splitting regexes (--split-pattern).
• 🛡️ Clean CLI & Standard Exit Codes: Suppresses third-party noise, outputs errors to stderr, and adheres to standard exit codes (0, 1, 2, 130).

Installation

kokorosay requires Python 3.14+.

Recommended: Using uv

Install kokorosay as a globally isolated command-line tool:

uv tool install kokorosay

Alternative: Using pipx or pip

# Using pipx
pipx install kokorosay

# Using standard pip (inside an active virtual environment)
pip install kokorosay

System Prerequisites (Linux only)

On Windows and macOS, audio dependencies are bundled automatically. On Linux systems, portaudio might be needed for direct speaker playback:

# Debian / Ubuntu
sudo apt-get install libportaudio2

Setup

Before first use, run the one-time dictionary setup:

kokorosay --setup

• Japanese UniDic: kokorosay --setup downloads the full UniDic dictionary required for Japanese G2P (grapheme-to-phoneme) processing.
• Model weights: The Kokoro-82M model and voice weights (~330 MB) are automatically fetched from Hugging Face on your first speech synthesis and cached locally for future offline use.

Quick Start & Examples

1. Direct Playback

Provide text in quotes to play speech instantly through the default audio device:

# Play using default voice (af_heart - American English female)
kokorosay "Hello! Kokorosay brings text to life right from your terminal."

# British English voice, slightly faster
kokorosay "Mind the gap between the train and the platform." --voice bm_george --speed 1.15

2. Exporting to Audio Files (.wav / .mp3)

Specify an output file path as the second positional argument. Only .mp3 and .wav formats are supported (case-insensitive). Missing directories will be created automatically:

# Save as MP3
kokorosay "Speech saved to an MP3 file." output.mp3

# Japanese voice saved to a nested directory
kokorosay "こんにちは、世界。" audio/japanese/hello.wav --voice jf_nezumi

# Mandarin Chinese voice
kokorosay "你好，欢迎使用文本转语音工具。" out/welcome.mp3 --voice zf_xiaobei

3. Piping from Stdin (-)

Pass - as INPUT to read text from standard input. kokorosay decodes standard input as UTF-8 (and strips PowerShell's UTF-8 BOM if present):

# Pipe the output of any command
fortune | kokorosay -

# Read from a file via stdin
cat story.txt | kokorosay - story.mp3 --voice bf_emma

# In PowerShell:
Get-Content notes.txt -Raw | kokorosay - notes.wav

4. Text Starting with Hyphens (--)

If your input text begins with a dash or minus sign, use -- so the argument parser does not interpret it as a flag:

kokorosay -- "-5 degrees Celsius outside today."

CLI Reference

Synopsis

kokorosay INPUT [OUTPUT] [OPTIONS]
kokorosay --list-voices
kokorosay --setup

Arguments and Options

Note: --setup and --list-voices are standalone modes. They cannot be combined with positional arguments (INPUT / OUTPUT) or with each other.

Supported Languages & Voices

Kokoro determines the language from the first letter of the voice name. The second letter indicates voice gender (f for female, m for male).

To view the complete list of available voices grouped by language, run:

kokorosay --list-voices

Voice Samples

Pre-generated audio samples for all supported voices are available in the examples/ directory. You can open that folder and listen to the .mp3 files (e.g. af_heart.mp3, jf_nezumi.mp3, zf_xiaobei.mp3) to experience each voice firsthand. The samples can also be regenerated using examples/00_gen_all_voices.ps1.

Exit Codes

Development

If you wish to contribute or modify kokorosay:

# Clone repository
git clone https://github.com/ecator/kokorosay.git
cd kokorosay

# Install runtime and dev dependencies
uv sync

# Lint and check formatting
uv run ruff check .
uv run ruff format --check .

# Run unit tests (offline, mocked Kokoro/sounddevice)
uv run pytest

# Run integration tests (requires real model weights & audio device)
uv run pytest -m integration

See AGENTS.md for full architecture specifications and coding conventions.

Acknowledgments

• Kokoro for the TTS model.
• Misaki for G2P text pre-processing.
• UniDic for Japanese morphological analysis.