{"id":51684920,"url":"https://github.com/pguso/kokoro","last_synced_at":"2026-07-15T19:01:03.881Z","repository":{"id":356740150,"uuid":"1233736390","full_name":"pguso/kokoro","owner":"pguso","description":"A lightweight, offline Rust inference library for Kokoro TTS - an 82M-parameter open-weights text-to-speech model. ","archived":false,"fork":false,"pushed_at":"2026-05-10T14:02:29.000Z","size":7940,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-07-10T03:18:57.767Z","etag":null,"topics":["coreml","cross-platform","cuda","inference","kokoro-82m","offline-first","onnx","rust","speech-synthesis","text-to-speech","tts"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pguso.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-09T09:43:46.000Z","updated_at":"2026-06-06T21:46:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pguso/kokoro","commit_stats":null,"previous_names":["pguso/kokoro"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pguso/kokoro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pguso%2Fkokoro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pguso%2Fkokoro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pguso%2Fkokoro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pguso%2Fkokoro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pguso","download_url":"https://codeload.github.com/pguso/kokoro/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pguso%2Fkokoro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35517479,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-15T02:00:06.706Z","response_time":131,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coreml","cross-platform","cuda","inference","kokoro-82m","offline-first","onnx","rust","speech-synthesis","text-to-speech","tts"],"created_at":"2026-07-15T19:00:53.737Z","updated_at":"2026-07-15T19:01:03.857Z","avatar_url":"https://github.com/pguso.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kokoro-tts\r\n\r\nA lightweight, offline Rust inference library for [Kokoro TTS](https://github.com/hexgrad/kokoro) - an 82M-parameter open-weights text-to-speech model. Designed to be small, dependency-light, and easy to cross-compile to mobile.\r\n\r\n\u003e Kokoro is an open-weights TTS model with 82 million parameters. Despite its lightweight architecture, it delivers comparable quality to larger models while being significantly faster and more cost-efficient. With Apache-licensed weights, Kokoro can be deployed anywhere from production environments to personal projects.\r\n\r\n---\r\n\r\n## Features\r\n\r\n- 100% offline - no network calls at runtime.\r\n- Cross-platform - builds on macOS, Linux, Windows; cross-compiles to Android and iOS.\r\n- Hardware acceleration - CoreML on macOS, CUDA on Linux/Windows, with automatic CPU fallback.\r\n- Multiple model sizes - full-precision (`model.onnx`), 8-bit-quantized (`model_quantized.onnx`), and others.\r\n- Multiple voices spanning English, Mandarin, Spanish, French, Japanese, Italian, Hindi, Brazilian Portuguese. Only battle tested with English.\r\n- Streaming and one-shot synthesis modes.\r\n- G2P tools: `g2p_audit()`, optional `KOKORO_G2P_LEXICON` overrides, and the `kokoro-g2p-audit` binary for phoneme/vocab checks (see [ARCHITECTURE.md](ARCHITECTURE.md)).\r\n- **Default crate features include `g2p-espeak`**: Misaki links bundled **espeak-ng** (via CMake) for out-of-vocabulary words (kokoro-js–like behavior). Slim Misaki-only build: `cargo build --no-default-features` (optional `--features misaki-lean`). Optional system `espeak-ng` improves segment-level phonemization; see `g2p_espeak_capability()` / `KOKORO_G2P_REQUIRE_ESPEAK`.\r\n\r\n---\r\n\r\n## Quick start\r\n\r\n### 1. Download the model and voices\r\n\r\nThe model and voice files are not bundled with this repository. Get them from the official ONNX release on Hugging Face:\r\n\r\n\u003e **\u003chttps://huggingface.co/onnx-community/Kokoro-82M-v1.0-ONNX/tree/main\u003e**\r\n\r\nYou need **two** sets of files:\r\n\r\n| What            | Hugging Face folder                                | Goes into local folder |\r\n| --------------- | -------------------------------------------------- | ---------------------- |\r\n| ONNX model file | [`onnx/`](https://huggingface.co/onnx-community/Kokoro-82M-v1.0-ONNX/tree/main/onnx) | `models/`              |\r\n| Voice packs     | [`voices/`](https://huggingface.co/onnx-community/Kokoro-82M-v1.0-ONNX/tree/main/voices) | `voices/`              |\r\n\r\nPick whichever variant of the model fits your hardware (any one is enough):\r\n\r\n| File                   | Size  | Notes                                                      |\r\n| ---------------------- | ----- | ---------------------------------------------------------- |\r\n| `model.onnx`           | ~325 MB | Full precision (fp32). Best quality. Recommended for CoreML / CUDA. |\r\n| `model_q8f16.onnx`     | ~160 MB | Mixed int8 / fp16. Smaller, fast on CPU.                   |\r\n| `model_quantized.onnx` | ~92 MB  | int8. Smallest. Some quality loss.                         |\r\n\r\nEach voice is a separate `\u003cname\u003e.bin` file (e.g. `af_heart.bin`, `af_alloy.bin`). Download as many or as few as you want - the library only loads what's in the folder.\r\n\r\nYou can grab them via `git lfs`:\r\n\r\n```bash\r\ngit lfs install\r\ngit clone https://huggingface.co/onnx-community/Kokoro-82M-v1.0-ONNX\r\nmkdir -p models voices\r\ncp Kokoro-82M-v1.0-ONNX/onnx/*.onnx       models/\r\ncp Kokoro-82M-v1.0-ONNX/voices/*.bin      voices/\r\n```\r\n\r\n…or download individual files from the Hugging Face web UI and drop them into the matching folder.\r\n\r\nAfter this step the layout should look like:\r\n\r\n```\r\nkokoro/\r\n├── models/\r\n│   ├── model.onnx                ← any one (or more) of these\r\n│   ├── model_q8f16.onnx\r\n│   └── model_quantized.onnx\r\n└── voices/\r\n    ├── af_alloy.bin\r\n    ├── af_heart.bin\r\n    ├── am_adam.bin\r\n    └── …                         ← whichever voices you want\r\n```\r\n\r\n### 2. Install platform deps\r\n\r\n- **macOS**: **CMake** and a C/C++ toolchain (Xcode CLT) for the default **g2p-espeak** feature (bundled eSpeak). Optional: `brew install espeak-ng` for CLI segment phonemes.\r\n- **Linux**: `sudo apt install cmake build-essential pkg-config libasound2-dev` — **cmake** / **build-essential** are needed for **g2p-espeak**; `libasound2-dev` for `voxudio` in examples. Optional: `sudo apt install espeak-ng`.\r\n- **Windows**: Visual Studio C++ build tools and **CMake** on `PATH` for **g2p-espeak**.\r\n\r\n### 3. Run an example\r\n\r\n```bash\r\ncargo run --release --example synth_directly_v10\r\ncargo run --release --example synth_stream\r\n```\r\n\r\nThe first build downloads ONNX Runtime, may compile **bundled espeak-ng** (default feature `g2p-espeak`), and compiles the bundled `cmudict` dictionary — expect several minutes. Subsequent builds are fast.\r\n\r\nIf **`espeak-rs-sys`** / CMake fails with a stale build directory, run `cargo clean -p espeak-rs-sys` or `cargo clean`, ensure **CMake** is on `PATH`, then rebuild.\r\n\r\n---\r\n\r\n## Using the library in your own project\r\n\r\n```bash\r\ncargo add kokoro-en\r\n```\r\n\r\n```rust\r\nuse kokoro_en::{KokoroTts, Voice};\r\n\r\n#[tokio::main]\r\nasync fn main() -\u003e anyhow::Result\u003c()\u003e {\r\n    // Point at the model file and the voices/ directory.\r\n    // The directory will load every `\u003cname\u003e.bin` file inside it; you can\r\n    // also pass a single `.bin` file to load just one voice.\r\n    let tts = KokoroTts::new(\"models/model.onnx\", \"voices\").await?;\r\n\r\n    // Pick a voice by name. Anything that converts into `Voice` works\r\n    // (`\u0026str`, `String`, or `Voice::new(...)`).\r\n    let (audio, took) = tts.synth(\"Hello, world!\", Voice::new(\"af_heart\")).await?;\r\n    println!(\"Synth took {took:?}, produced {} samples at 24 kHz\", audio.len());\r\n\r\n    // The shorthand also works:\r\n    let _ = tts.synth(\"Hello again!\", \"af_alloy\").await?;\r\n\r\n    // Speed control:\r\n    let _ = tts.synth(\"Slower.\", Voice::new(\"af_heart\").with_speed(0.85)).await?;\r\n\r\n    Ok(())\r\n}\r\n```\r\n\r\n### Voice API at a glance\r\n\r\n```rust\r\nVoice::new(\"af_alloy\")                  // default speed 1.0\r\nVoice::new(\"af_alloy\").with_speed(1.2)  // 20% faster\r\n\"af_alloy\".into()                       // From\u003c\u0026str\u003e implementation\r\n```\r\n\r\nAny function taking `Voice` actually accepts `impl Into\u003cVoice\u003e`, so you rarely need to construct one explicitly:\r\n\r\n```rust\r\ntts.synth(\"hi\", \"af_alloy\").await?;\r\ntts.stream(\"af_alloy\");\r\n```\r\n\r\n### Streaming long text\r\n\r\n```rust\r\nuse {futures::StreamExt, kokoro_en::KokoroTts};\r\n\r\n#[tokio::main]\r\nasync fn main() -\u003e anyhow::Result\u003c()\u003e {\r\n    let tts = KokoroTts::new(\"models/model_quantized.onnx\", \"voices\").await?;\r\n    let (mut sink, mut stream) = tts.stream(\"af_alloy\");\r\n\r\n    sink.synth(\"First sentence.\").await?;\r\n    sink.synth(\"Second sentence - synthesized while the first one plays.\").await?;\r\n    drop(sink);\r\n\r\n    while let Some((audio, took)) = stream.next().await {\r\n        println!(\"Got {} samples in {took:?}\", audio.len());\r\n    }\r\n\r\n    Ok(())\r\n}\r\n```\r\n\r\n---\r\n\r\n## Voice naming convention\r\n\r\nVoice names follow the upstream Kokoro convention `\u003clang\u003e\u003cgender\u003e_\u003cname\u003e`:\r\n\r\n| Prefix | Language / accent              |\r\n| ------ | ------------------------------ |\r\n| `af`   | American English, female       |\r\n| `am`   | American English, male         |\r\n| `bf`   | British English, female        |\r\n| `bm`   | British English, male          |\r\n| `ef`   | Spanish, female                |\r\n| `em`   | Spanish, male                  |\r\n| `ff`   | French, female                 |\r\n| `hf`   | Hindi, female                  |\r\n| `hm`   | Hindi, male                    |\r\n| `if`   | Italian, female                |\r\n| `im`   | Italian, male                  |\r\n| `jf`   | Japanese, female               |\r\n| `jm`   | Japanese, male                 |\r\n| `pf`   | Brazilian Portuguese, female   |\r\n| `pm`   | Brazilian Portuguese, male     |\r\n| `zf`   | Mandarin Chinese, female (v1.1)|\r\n| `zm`   | Mandarin Chinese, male  (v1.1) |\r\n\r\nPick the voice file you want from the [Hugging Face `voices/` folder](https://huggingface.co/onnx-community/Kokoro-82M-v1.0-ONNX/tree/main/voices) and reference it by its file-stem name (the filename without `.bin`).\r\n\r\n---\r\n\r\n## Execution providers\r\n\r\nThe library auto-selects the best available backend:\r\n\r\n- **macOS** → CoreML (Neural Engine + GPU). Falls back to CPU if the model can't run on CoreML.\r\n- **Linux / Windows** → CUDA if available, else CPU.\r\n\r\nYou can override or pin the provider with environment variables:\r\n\r\n| Variable                              | Values                                                                      |\r\n| ------------------------------------- | --------------------------------------------------------------------------- |\r\n| `KOKORO_ORT_PROVIDER`                 | `auto` (default), `cpu`, `coreml`, `cuda`                                   |\r\n| `KOKORO_COREML_MODEL_FORMAT`          | `neuralnetwork` (default), `mlprogram`                                      |\r\n| `KOKORO_COREML_COMPUTE_UNITS`         | `all` (default), `ane`, `gpu`, `cpu_only`                                   |\r\n| `KOKORO_COREML_STATIC_INPUT_SHAPES`   | `0` (default) / `1`                                                         |\r\n\r\nSetting `KOKORO_ORT_PROVIDER=coreml` or `=cuda` disables the automatic CPU fallback so failures surface explicitly.\r\n\r\n---\r\n\r\n## Troubleshooting\r\n\r\n- **`VoiceNotFound(\"af_heart\")`** - the file `voices/af_heart.bin` doesn't exist. Download it from the Hugging Face `voices/` folder.\r\n- **`Io(... model.onnx ...)`** - the model file isn't where you said it was. Check the path you passed to `KokoroTts::new`.\r\n- **`no .bin voice files found in voices`** - the directory is empty. Drop at least one `\u003cname\u003e.bin` file in there.\r\n- **CoreML errors at startup** - set `KOKORO_ORT_PROVIDER=cpu` to force a known-good path. Quantized models don't run on CoreML; the library detects this and falls back to CPU automatically when `KOKORO_ORT_PROVIDER` is left at `auto`.\r\n\r\n---\r\n\r\n## License\r\n\r\nApache-2.0. See [`LICENSE`](LICENSE).\r\n\r\nThe Kokoro model weights are also Apache-2.0; check the upstream Hugging Face repo for the canonical license text covering the weights themselves.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpguso%2Fkokoro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpguso%2Fkokoro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpguso%2Fkokoro/lists"}