kokoro-onnx: TTS with Kokoro and ONNX Runtime

Common errors

• Error: Model files not found. Please download 'kokoro-v1.0.onnx' and 'voices-v1.0.bin' from ...

  cause The required ONNX model and voice data files are not present in the expected location.
  fix Download `kokoro-v1.0.onnx` and `voices-v1.0.bin` from `https://github.com/thewh1teagle/kokoro-onnx/releases/tag/model-files-v1.0` and place them in your script's directory, or explicitly provide their full paths to the `Kokoro` constructor.

• Non-zero status code returned while running ConvTranspose node. Name:'/N.1/pool/ConvTranspose' Status Message: ... The parameter is incorrect.

  cause This error often occurs when using the DirectML execution provider for GPU acceleration on Windows due to operator incompatibilities.
  fix If on Windows, try running with the CPU execution provider by ensuring `onnxruntime` (CPU) is installed and not `onnxruntime-gpu` with DirectML. On Linux, ensure CUDA is properly configured for `onnxruntime-gpu`.

• DLL load failed while importing onnx_cpp2py_export: A dynamic link library (DLL) initialization routine failed.

  cause This is a common Windows-specific issue related to `onnx` or `onnxruntime` installation, often indicating missing Visual C++ redistributables or conflicts in the environment path.
  fix Ensure all required Visual C++ redistributables are installed. Consider creating a fresh virtual environment and reinstalling `onnxruntime` and `kokoro-onnx`. Check system environment variables for conflicting DLL paths.

• ERROR: the text-to-speech generation did not return audio. Make sure you have a valid text string.

  cause The input text provided for speech generation was invalid, empty, or caused an internal processing error.
  fix Verify that the input text is not empty, contains meaningful characters, and is a string. Check for any other error messages preceding this one that might indicate issues with model loading or parameters.

Warnings

• breaking Model files (`.onnx` and `.bin`) are mandatory for the application to start. If these files are missing or incorrectly located, the application will exit with an error.
  Fix: Download `kokoro-v1.0.onnx` and `voices-v1.0.bin` from the latest model-files release (e.g., `thewh1teagle/kokoro-onnx/releases/tag/model-files-v1.0`) and ensure they are accessible by the application, either in the script directory or via specified paths.
• gotcha Users have reported issues with GPU acceleration using the DirectML execution provider on Windows, often resulting in 'Non-zero status code returned while running ConvTranspose node' errors. CUDA execution provider on Linux (e.g., WSL) seems to work better.
  Fix: On Windows, consider using the CPU execution provider, or if on Linux, ensure CUDA/cuDNN are correctly set up and use `onnxruntime-gpu`.
• gotcha A memory leak issue has been reported when synthesizing longer sentences, where memory is not released after synthesis. This might be an upstream model issue, but it impacts `kokoro-onnx` usage.
  Fix: Monitor memory usage for long text generations. Consider processing text in shorter segments if feasible, or restarting the process for critical applications.
• deprecated In related `kokoro-onnx` integrations (e.g., `pipecat-ai`'s `KokoroTTSService`), direct parameters like `voice_id` and `params` in the constructor are being deprecated in favor of a `settings` object (e.g., `settings=KokoroTTSService.Settings(...)`). This indicates an evolving API design pattern.
  Fix: Refer to the latest documentation or examples for the recommended way to configure voice and other parameters, favoring a `settings` object if available.

Install

• pip install -U kokoro-onnx Latest stable version

Imports

• Kokoro

  from kokoro_onnx import Kokoro

Quickstart

This quickstart demonstrates how to initialize the `Kokoro` class, generate speech from text, and save the output to a WAV file. It is crucial to manually download the `kokoro-v1.0.onnx` and `voices-v1.0.bin` model files from the official GitHub releases and place them in the same directory as your script, or provide their full paths.

import os
import soundfile as sf
from kokoro_onnx import Kokoro

# --- IMPORTANT: Download model files first ---
# Download 'kokoro-v1.0.onnx' and 'voices-v1.0.bin' from:
# https://github.com/thewh1teagle/kokoro-onnx/releases/tag/model-files-v1.0
# Place them in the same directory as this script, or specify full paths.
# -----------------------------------------------

MODEL_PATH = os.environ.get('KOKORO_MODEL_PATH', 'kokoro-v1.0.onnx')
VOICES_PATH = os.environ.get('KOKORO_VOICES_PATH', 'voices-v1.0.bin')

# Ensure model files exist before proceeding
if not os.path.exists(MODEL_PATH) or not os.path.exists(VOICES_PATH):
    print(f"Error: Model files not found. Please download '{MODEL_PATH}' and '{VOICES_PATH}'")
    print("from https://github.com/thewh1teagle/kokoro-onnx/releases/tag/model-files-v1.0")
    print("and place them in the current directory or set KOKORO_MODEL_PATH/KOKORO_VOICES_PATH.")
    exit(1)

try:
    # Initialize Kokoro with model and voice files
    kokoro = Kokoro(MODEL_PATH, VOICES_PATH)

    # Text to synthesize
    text = "Hello, this is a test from kokoro-onnx. How are you today?"

    # Generate speech (default voice is often 'am_michael')
    # You can list available voices via kokoro.get_voices()
    samples, sample_rate = kokoro.create(text, voice='af_alloy')

    # Save the audio to a WAV file
    output_filename = "audio.wav"
    sf.write(output_filename, samples, sample_rate)

    print(f"Speech generated and saved to {output_filename}")
except Exception as e:
    print(f"An error occurred: {e}")
    print("Ensure 'onnxruntime' and 'soundfile' are installed and model files are correct.")