Kokoros (Kokoro Rust)

You can use pre-built images from GHCR or build locally.

1. Pull or Build:

   docker pull ghcr.io/lucasjinreal/kokoros:main
   # OR
   docker build -t kokoros .

2. Run CLI mode (mount a volume for output):

   docker run -v ./tmp:/app/tmp kokoros text "Hello from docker!" -o tmp/hello.wav

3. Run OpenAI Server:

   docker run -p 3000:3000 kokoros openai

To install and build kokoros locally, follow these steps:

1. Install System Dependencies:

   • macOS: brew install pkg-config opus
   • Linux (Ubuntu/Debian): sudo apt-get install pkg-config libopus-dev

2. Download Models and Voices: Run the provided script to download the Kokoro ONNX model and voices data:

   bash download_all.sh

   Alternatively, download them separately using:

   bash scripts/download_models.sh
   bash scripts/download_voices.sh

3. Build the Project:

   cargo build --release

4. (Optional) System-wide Installation: To make the koko binary available globally and install voice data to $HOME/.cache/kokoros/:

   bash install.sh

# Full installation sequence
bash download_all.sh
cargo build --release
bash install.sh

You can use Nix to manage the build environment. For standard builds:

nix develop
cargo build --release

For builds with CUDA support:

nix develop .#cuda
cargo build --features kokoros/cuda --release

When using the --timestamps global flag, the CLI will generate a sidecar .tsv file for every generated .wav file. The TSV file uses the same base name as the audio file and contains word-level start and end times.

TSV Format:

word	start_sec	end_sec

Example: If you save audio to output.wav, the timestamps will be in output.tsv.

koko text "Hello world" --timestamps -o output.wav

The API provides backwards compatibility by mapping common OpenAI voice names to their closest Kokoro equivalents:

When running the OpenAI-compatible server, you can use the --instances flag to control parallel processing. This helps balance latency (Time-to-First-Audio) and total throughput.

• Low Latency (Real-time): Use --instances 1.
• Balanced (Default): Use 2 instances (default behavior).
• High Throughput (Batch): Use higher numbers (e.g., --instances 4) to improve total processing time, especially on multi-core CPUs or NVIDIA GPUs.

# Best for real-time (lowest latency)
./target/release/koko openai --instances 1

# Best for batch processing (highest throughput)
./target/release/koko openai --instances 4

Kokoro voices are categorized by a two-letter prefix representing the language and gender. When the system logs available voices, it groups them into the following categories:

If a prefix does not match these, the prefix itself is used as the category name.

The OrtKoko engine uses two internal ModelStrategy modes depending on the ONNX model's output count:

1. Standard Strategy: Activated when the model has a single output. It expects the audio output to be keyed as audio (or falls back to waveforms). It returns None for durations.
2. Timestamped Strategy: Activated when the model has multiple outputs. It expects the audio output to be keyed as waveform (or falls back to audio) and specifically looks for a durations output tensor. It returns Some(Vec<f32>) for durations.

You can inspect the active strategy using the .strategy() method.

Kokoro allows blending multiple voice styles using a specific string syntax in the style_name parameter. The format is style_name.weight, where weight is a decimal (e.g., 0.5). Multiple styles are joined by +.

Example Syntax: af_heart.0.5+af_bella.0.5 blends 50% of af_heart and 50% of af_bella.

// In a TTSOpts or API call:
let mixed_style = "af_heart.0.5+af_bella.0.5";

To use the Kokoro TTS engine, initialize a TTSKoko instance. You can use TTSKoko::new(model_path, voices_path) for default settings or TTSKoko::from_config to provide a custom InitConfig (which allows specifying custom URLs for model and voice files and the sample rate).

// Using default config
let tts = TTSKoko::new("path/to/model.onnx", "path/to/voices.bin").await;

// Using custom config
let cfg = InitConfig {
    model_url: "https://example.com/model.onnx".into(),
    voices_url: "https://example.com/voices.bin".into(),
    sample_rate: 24000,
};
let tts = TTSKoko::from_config("path/to/model.onnx", "path/to/voices.bin", cfg).await;