{"id":7343,"library":"kokoro","title":"Kokoro Text-to-Speech (TTS)","description":"Kokoro is a Python library for Text-to-Speech (TTS) synthesis, leveraging ONNX models for efficient audio generation. It provides a straightforward API to convert text into spoken audio. As of version 0.9.4, it targets Python 3.10-3.12 and is under active development, with releases occurring as new features or bug fixes are integrated.","status":"active","version":"0.9.4","language":"en","source_language":"en","source_url":"https://github.com/hexgrad/kokoro","tags":["TTS","Speech Synthesis","ONNX","Audio","AI","Machine Learning"],"install":[{"cmd":"pip install kokoro","lang":"bash","label":"For CPU-only inference"},{"cmd":"pip install kokoro[gpu]","lang":"bash","label":"For GPU-accelerated inference (requires CUDA)"}],"dependencies":[{"reason":"Core dependency for running ONNX models (CPU backend by default).","package":"onnxruntime","optional":false},{"reason":"Enables GPU acceleration for ONNX models when installed via `kokoro[gpu]`.","package":"onnxruntime-gpu","optional":true}],"imports":[{"symbol":"TextToSpeech","correct":"from kokoro.tts import TextToSpeech"}],"quickstart":{"code":"import os\nfrom kokoro.tts import TextToSpeech\nfrom scipy.io.wavfile import write\n\n# IMPORTANT: Model assets are NOT included in the package.\n# Download a model and config from https://huggingface.co/hexgrad/kokoro_models\n# For example, 'hexgrad/kokoro_models/tree/main/vits/vctk_ljs'\n\n# Placeholder paths - REPLACE with actual paths to your downloaded files\nmodel_path = os.environ.get('KOKORO_MODEL_PATH', 'path/to/your_model.onnx')\nconfig_path = os.environ.get('KOKORO_CONFIG_PATH', 'path/to/your_config.json')\n\nif not os.path.exists(model_path) or not os.path.exists(config_path):\n    print(f\"Error: Model or config files not found.\\n\")\n    print(f\"Please download them from https://huggingface.co/hexgrad/kokoro_models\\n\")\n    print(f\"And set KOKORO_MODEL_PATH and KOKORO_CONFIG_PATH environment variables, or update the script.\\n\")\n    exit(1)\n\ntry:\n    tts = TextToSpeech(model_path=model_path, config_path=config_path)\n    audio = tts.synthesize(\"Hello, this is a test from the Kokoro library.\")\n\n    # Save the generated audio\n    sampling_rate = tts.config.sampling_rate # Access sampling_rate from the loaded config\n    output_filename = \"kokoro_output.wav\"\n    write(output_filename, sampling_rate, audio)\n    print(f\"Audio saved to {output_filename}\")\nexcept Exception as e:\n    print(f\"An error occurred during TTS synthesis: {e}\")\n    print(\"Ensure your model_path and config_path are correct and the ONNX runtime is properly installed.\")","lang":"python","description":"This quickstart demonstrates how to initialize the `TextToSpeech` model and synthesize audio. It requires you to first download an ONNX model file (`.onnx`) and its corresponding configuration file (`.json`) from the official Hugging Face repository, as these are not bundled with the package. Ensure the paths are correctly set before running."},"warnings":[{"fix":"Download the desired model and config files, then provide their full paths to the `TextToSpeech` constructor.","message":"Model and configuration files are NOT included in the Kokoro package. Users MUST manually download an ONNX model (`.onnx`) and its corresponding config file (`.json`) from the official Hugging Face repository (e.g., `huggingface.co/hexgrad/kokoro_models`) before synthesis.","severity":"gotcha","affected_versions":"All"},{"fix":"For CPU: `pip install kokoro`. For GPU: ensure `nvcc --version` shows CUDA, then `pip install kokoro[gpu]`.","message":"The `onnxruntime` dependency requires careful installation for CPU vs. GPU. Installing `pip install kokoro` provides CPU-only support. For GPU acceleration, `pip install kokoro[gpu]` is required, along with a compatible CUDA setup. Mismatched `onnxruntime` versions or attempting to use GPU without `[gpu]` extra will lead to errors like 'Failed to find provider 'CUDAExecutionProvider''.","severity":"breaking","affected_versions":"All"},{"fix":"Use a Python environment manager (e.g., `conda` or `pyenv`) to set up a compatible Python version (3.10, 3.11, or 3.12) for your project.","message":"Kokoro strictly requires Python versions 3.10, 3.11, or 3.12. Using unsupported versions (e.g., Python 3.9 or 3.13) will result in installation failures or runtime errors due to dependency constraints.","severity":"gotcha","affected_versions":"All"},{"fix":"For long texts, consider splitting them into smaller segments. Monitor resource usage and, if necessary, choose smaller ONNX models that require less memory.","message":"Synthesizing long texts or using very large models can lead to high memory (RAM/VRAM) consumption, potentially causing out-of-memory errors on systems with limited resources.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `onnxruntime` (for CPU) or `onnxruntime-gpu` (for GPU) is installed. Usually, `pip install kokoro` or `pip install kokoro[gpu]` should handle this, but manual installation (`pip install onnxruntime`) might be needed in some environments.","cause":"The core ONNX runtime library is not installed, or the environment is not correctly configured.","error":"ModuleNotFoundError: No module named 'onnxruntime'"},{"fix":"Download the `.onnx` model and `.json` config file from `huggingface.co/hexgrad/kokoro_models` and verify the `model_path` and `config_path` variables in your code match their actual location.","cause":"The specified ONNX model file or its configuration file does not exist at the given path. This means the model assets haven't been downloaded or the paths are incorrect.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'path/to/your_model.onnx'"},{"fix":"If you intend to use GPU, ensure you installed with `pip install kokoro[gpu]`. Verify your NVIDIA drivers and CUDA Toolkit are installed and compatible with `onnxruntime-gpu`.","cause":"You are attempting to use the GPU (CUDA) backend without `onnxruntime-gpu` being installed, or your CUDA setup (drivers, toolkit) is not correctly configured or compatible.","error":"RuntimeError: Failed to find provider 'CUDAExecutionProvider'"},{"fix":"Ensure your `config_path` points to a valid and correctly formatted JSON configuration file compatible with your ONNX model. If upgrading, check library's changelog for breaking changes to the `TextToSpeech` API.","cause":"This error might occur if the library's internal structure changes or if the `TextToSpeech` object failed to initialize its configuration property due to an invalid config file.","error":"The 'TextToSpeech' object has no attribute 'config'"}]}