README.md

---
language:
- en
- es
- fr
- hi
- it
- ja
- pt
- zh
license: apache-2.0
library_name: kokoro.cpp
pipeline_tag: text-to-speech
base_model: hexgrad/Kokoro-82M
base_model_relation: quantized
inference: false
tags:
- audio
- text-to-speech
- tts
- kokoro
- gguf
- ggml
- cpp
- cpu
- gpu
- multilingual
---

# Kokoro-82M for `kokoro.cpp` — F16, Q8_0, and all 54 voices

Reproducible GGUF conversions of the official
[Hexgrad Kokoro-82M v1.0](https://huggingface.co/hexgrad/Kokoro-82M) checkpoint for
[**`kokoro.cpp`**](https://github.com/simonfxr/kokoro.cpp), a standalone C/C++ runtime powered by GGML.

> **What is included:** the reference F16 model, a validated Q8_0 model, and
> every one of the 54 official v1.0 voice packs across all supported languages.
> No unofficial or third-party voices are mixed into this repository.

## Files

| File | Precision | Size | Notes |
|---|---:|---:|---|
| `kokoro-82m-f16.gguf` | F16/F32 | 156.14 MiB | Reference-quality conversion |
| `kokoro-82m-q8_0.gguf` | Q8_0/F16/F32 | 134.78 MiB | 111 matrix tensors quantized; sensitive/unsupported tensors retained |
| `voices/kokoro-voice-*.gguf` | F32 | 26.91 MiB total | All 54 official voices; about 510 KiB each |
| `manifest.json` | — | — | SHA256, size, source revision, and checkpoint provenance |
| `VALIDATION.md` | — | — | Tensor and fixed-seed audio comparison results |

Voice packs remain F32 because they are small and are indexed style embeddings,
not matrix-multiplication weights. A model file and one voice file are both
required for synthesis.

## Quick start with `kokoro.cpp`

```bash
# Download one model and one voice.
hf download simonfxr/kokoro.cpp-GGUF \
  kokoro-82m-q8_0.gguf \
  voices/kokoro-voice-af_heart.gguf \
  --local-dir models

# Build the runtime. See the GitHub README for platform/backend options.
git clone --recursive https://github.com/simonfxr/kokoro.cpp.git
cd kokoro.cpp
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

# Synthesize 24 kHz mono audio.
./build/kokoro-cli \
  -m ../models/kokoro-82m-q8_0.gguf \
  -v ../models/voices/kokoro-voice-af_heart.gguf \
  -l en-us \
  -o output.wav \
  "Hello from Kokoro dot C P P."
```

GPU execution is available when `kokoro.cpp` is built with a supported Vulkan,
Metal, or CUDA backend. GGUF is the container format; llama.cpp and whisper.cpp
do not implement this Kokoro architecture.

## Languages and voices

Kokoro reports eight languages. Its pipeline distinguishes American and British
English, resulting in nine language variants. `kokoro.cpp` takes the espeak-ng
voice shown in the third column, not Kokoro's one-letter pipeline code.

| Language | Kokoro code | `kokoro.cpp -l` | Voices |
|---|:---:|:---:|---|
| American English | `a` | `en-us` | 20 |
| British English | `b` | `en-gb` | 8 |
| Spanish | `e` | `es` | 3 |
| French | `f` | `fr-fr` | 1 |
| Hindi | `h` | `hi` | 4 |
| Italian | `i` | `it` | 2 |
| Japanese | `j` | `ja` | 5 |
| Brazilian Portuguese | `p` | `pt-br` | 3 |
| Mandarin Chinese | `z` | `cmn` | 8 |

See [`voices/README.md`](voices/README.md) for every voice name and ready-to-copy
commands. The machine-readable mapping is in
[`voices/languages.json`](voices/languages.json).

## Conversion and provenance

- Base model: [`hexgrad/Kokoro-82M`](https://huggingface.co/hexgrad/Kokoro-82M)
- Pinned source revision: `f3ff3571791e39611d31c381e3a41a3af07b4987`
- Official checkpoint SHA256: `496dba118d1a58f5f3db2efc88dbdc216e0483fc89fe6e47ee1f2c53f18ad1e4`
- Runtime and converters: [`simonfxr/kokoro.cpp`](https://github.com/simonfxr/kokoro.cpp)
- Output checksums: [`manifest.json`](manifest.json)

The conversion pipeline fuses PyTorch weight normalization, preserves Kokoro's
sparse 178-entry IPA vocabulary, maps all 459 runtime tensors, and emits GGUF
metadata expected by `kokoro.cpp`. Q8_0 quantizes only eligible two-dimensional
matrix weights whose GGML row width supports 32-element blocks. Convolutional
kernels remain F16 and rank-one tensors remain F32.

Reproduce these files from the official weights:

```bash
git clone --recursive https://github.com/simonfxr/kokoro.cpp.git
cd kokoro.cpp
python3 -m venv .venv-convert
. .venv-convert/bin/activate
pip install -r models/requirements-convert.txt
./models/convert-original.sh
```

## Validation

The generated files were checked for tensor names, shapes, dtypes, metadata,
and source hashes. Both models were loaded by `kokoro.cpp`; F16 and Q8_0 English
and Q8_0 Spanish synthesis produced valid 24 kHz WAV files.

Against the previously published cstr files:

- The F16 file has the same size and cosine similarity `0.999999999986` over all
  81,731,256 dequantized elements.
- Our Q8_0-versus-F16 relative L2 error is `0.00512913`, essentially matching
  cstr's `0.00512568`.
- Shared official voices `af_heart`, `ef_dora`, and `ff_siwis` are exactly equal
  element-for-element.
- Fixed-seed cstr-F16 versus this F16 output has waveform correlation `0.999920`
  and log-spectral distance `0.529 dB`.

Full methodology, caveats, and pairwise results are in
[`VALIDATION.md`](VALIDATION.md). PCM comparisons are phase-sensitive and do not
replace multilingual listening tests or perceptual metrics.

## Limitations

- Maximum input is 510 raw phoneme tokens because the model adds two boundary
  tokens to PL-BERT's 512-position context.
- Phonemization is provided by espeak-ng in `kokoro.cpp`, while the official
  Python package uses Misaki. Pronunciation can therefore differ.
- Mandarin tone numbers are not represented in Kokoro's 178-token vocabulary.
- espeak-ng Japanese kanji coverage is incomplete; pre-phonemized IPA can be
  supplied when needed.
- Q8_0 is smaller and validated, but F16 remains the reference choice for
  maximum fidelity. Lower-bit quantizations are intentionally not published.
- Voice availability does not imply identical quality across languages. Consult
  the [official model card](https://huggingface.co/hexgrad/Kokoro-82M) and
  [official voice notes](https://huggingface.co/hexgrad/Kokoro-82M/blob/main/VOICES.md).

## Intended use

This repository is for local and embedded text-to-speech inference with
`kokoro.cpp`, including research, accessibility, applications, and deployment
permitted by the upstream Apache-2.0 license. Users remain responsible for
appropriate disclosure, consent, and compliance when publishing synthetic
speech. Do not use generated audio to impersonate people or facilitate fraud.

## License and attribution

The Kokoro-82M weights and official voice packs are Apache-2.0 licensed. The
GGUF files are numerical conversions of those weights and retain that license.
`kokoro.cpp` has its own software/dependency licensing details; consult its
[LICENSE](https://github.com/simonfxr/kokoro.cpp/blob/main/LICENSE) and
[NOTICE](https://github.com/simonfxr/kokoro.cpp/blob/main/NOTICE) before distributing binaries.

Architecture: StyleTTS 2 / ISTFTNet. Original model, training information,
datasets, acknowledgements, and citations are documented by
[Hexgrad](https://huggingface.co/hexgrad/Kokoro-82M).