{"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":"python","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,"search_vec":"'-3.12':45 '0.9.4':40 '3.10':44 'activ':49 'ai':67 'api':30 'audio':24,36,66 'bug':58 'convert':32 'develop':50 'effici':23 'featur':56 'fix':59 'generat':25 'integr':61 'kokoro':1,7 'learn':69 'leverag':19 'librari':11 'machin':68 'model':21 'new':55 'occur':53 'onnx':20,65 'provid':27 'python':10,43 'releas':52 'speech':5,16,63 'spoken':35 'straightforward':29 'synthesi':18,64 'target':42 'text':3,14,33 'text-to-speech':2,13 'tts':6,17,62 'version':39","created_at":"2026-04-16T13:54:12.563365+00:00","updated_at":"2026-04-16T13:54:12.563365+00:00","problems":{"verify_error":"/tmp/tmp7tjw5xvl/venv/lib/python3.12/site-packages/torch/cuda/__init__.py:187: UserWarning: CUDA initialization: The NVIDIA driver on your system is too old (found version 12080). Please update your GPU driver by downloading and installing a new version from the URL: http://www.nvidia.com/Download/i"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.9.4","cli_name":"kokoro","cli_version":"","type":"library","homepage":null,"github":"https://github.com/hexgrad/kokoro","docs":null,"changelog":null,"pypi":"https://pypi.org/project/kokoro/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"install_fail","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-09","install_tag":null}}