README.md

---
license: mit
language:
- en
- ja
- ko
- zh
- fr
- es
- pt
- it
- de
- pl
- ru
- ar
- hi
- bn
- th
pipeline_tag: text-to-speech
library_name: kokoro
base_model: hexgrad/Kokoro-82M
tags:
- tts
- text-to-speech
- speech
- kokoro
- kokoro-82m
- gguf
- audio
- voice
- sakthai
- house-of-sak
- edge
- cpu-inference
- local-ai
- offline
- privacy
- multilingual
- raspberry-pi
- screenless
- accessibility
- eval-results
extra:
  sibling: Nanthasit/sakthai-tts
datasets:
- Nanthasit/sakthai-combined-v6
- Nanthasit/sakthai-combined-v7
- Nanthasit/sakthai-kaggle-notebooks
model-index:
- name: SakThai TTS
  results:
  - task:
      type: text-to-speech
      name: Speech Quality (MOS)
    dataset:
      name: Kokoro-82M Paper (upstream English MOS)
      type: internal
    metrics:
    - type: mos
      value: 3.87
      name: MOS (English, upstream Kokoro-82M)
      verified: false
inference:
  widget:
    - text: "Hello, I am SakThai. Welcome to the House of Sak."
      output:
        text: "[audio output — say 'Hello, I am SakThai. Welcome to the House of Sak.' using voice af_bella at 24kHz]"
    - text: "สวัสดีครับ ยินดีต้อนรับสู่บ้านของสักไทย"
      output:
        text: "[audio output — Thai greeting via espeak-ng G2P fallback, voice af_heart]"
---

<p align="center">
  <strong>Kokoro-82M text-to-speech — 15 languages · 141 MB GGUF · CPU-only</strong><br/>
  <em>The voice stage of the SakThai pipeline · Part of the <a href="https://huggingface.co/collections/Nanthasit/sakthai-model-family-6a64745450b12d421c1f9f02">SakThai Model Family</a></em>
</p>

<p align="center">
  <a href="https://huggingface.co/Nanthasit"><img src="https://img.shields.io/badge/%F0%9F%A4%97-Nanthasit-6644cc" alt="Profile"/></a>
  <a href="https://github.com/beer-sakthai"><img src="https://img.shields.io/badge/GitHub-beer--sakthai-181717?logo=github" alt="GitHub"/></a>
  <a href="https://huggingface.co/collections/Nanthasit/sakthai-model-family-6a64745450b12d421c1f9f02"><img src="https://img.shields.io/badge/%F0%9F%8F%A0-SakThai%20Family-6644cc" alt="Collection"/></a>
  <a href="https://huggingface.co/spaces/Nanthasit/sakthai-tts"><img src="https://img.shields.io/badge/%F0%9F%9A%80-Try%20on%20Spaces-47d147" alt="Spaces"/></a>
  <img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fhuggingface.co%2Fapi%2Fmodels%2FNanthasit%2Fsakthai-tts-model&query=%24.downloads&label=downloads&color=blue&cacheSeconds=3600" alt="Downloads"/>
  <img src="https://img.shields.io/badge/base-Kokoro%2082M-blueviolet" alt="Base"/>
  <img src="https://img.shields.io/badge/GGUF-Q8__0%20141MB-orange" alt="GGUF"/>
  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT"/>
</p>

---

## Try It Now 🚀

**[SakThai TTS Demo](https://huggingface.co/spaces/Nanthasit/sakthai-tts)** — type text, hear speech in 15 languages, right in your browser.

> ✅ **Space status:** the demo Space is **RUNNING** on the free tier.
> Free-tier idle sleep still applies: give it ~30–60 s to wake on first visit.

---

## Model Description

SakThai TTS is the **voice stage** of the SakThai pipeline — a Kokoro-82M TTS model packaged as a GGUF (Q8_0, 141 MB) for CPU speech synthesis. No cloud API. No monthly bill. No data leaving your machine.

**What makes it special:**
- 🎤 54 voices across 9 language groups
- 🌍 15 languages (en, ja, ko, zh, fr, es, pt, it, de, pl, ru, ar, hi, bn, th)
- 💾 141 MB — runs on a Raspberry Pi
- 🔒 100% local, 100% private

**Performance:** ~2x real-time on a single CPU core (~200 MB RAM). MOS 3.87 (English, upstream Kokoro-82M result — see [Evaluation](#evaluation)).

### Hardware Requirements

| Constraint | Minimum | Recommended |
|:-----------|:--------|:------------|
| CPU | 1 core, 1.5 GHz | 2+ cores, 2.0 GHz+ |
| RAM | 180 MB free | 300 MB free |
| Disk | 150 MB | 300 MB |
| OS | Linux, macOS, Windows | Linux (Raspberry Pi OS Bookworm) |

### Model Files

| File | Size (verified) | Format |
|------|----------------:|--------|
| `kokoro-82m-q8_0.gguf` | 141,322,336 B | GGUF Q8_0 |

Direct download:

```bash
wget https://huggingface.co/Nanthasit/sakthai-tts-model/resolve/main/kokoro-82m-q8_0.gguf
```

---

## Quick Start

> ⚠ **No serverless inference.** This is a custom GGUF package — it is **not** served by
> Hugging Face's serverless Inference API. Use the [Spaces demo](https://huggingface.co/spaces/Nanthasit/sakthai-tts) or
> run it locally below.

### Native Kokoro (full voice control)

```bash
pip install kokoro>=0.9.2 soundfile
```

```python
from kokoro import KPipeline
import soundfile as sf

pipeline = KPipeline(lang_code='a')
generator = pipeline("Hello, I am SakThai.", voice='af_bella')
for i, (gs, ps, audio) in enumerate(generator):
    sf.write(f'output_{i}.wav', audio, 24000)
```

### Extended languages (espeak-ng G2P fallback)

Languages without dedicated voices route phonemes through espeak-ng. Pick any existing voice style — `af_heart` works well:

```python
pipeline_ko = KPipeline(lang_code='ko')
for gs, ps, audio in pipeline_ko("안녕하세요", voice='af_heart'):
    sf.write('ko.wav', audio, 24000)

pipeline_th = KPipeline(lang_code='th')
for gs, ps, audio in pipeline_th("สวัสดีครับ", voice='af_heart'):
    sf.write('th.wav', audio, 24000)
```

---

## Languages

| Language | Code | Voices |
|:---------|:----:|:------:|
| American English | a | 20 |
| British English | b | 8 |
| Japanese | j | 5 |
| Mandarin Chinese | z | 8 |
| Spanish | e | 3 |
| French | f | 1 |
| Hindi | h | 4 |
| Italian | i | 2 |
| Brazilian Portuguese | p | 3 |
| Korean | ko | via espeak |
| German | de | via espeak |
| Russian | ru | via espeak |
| Polish | pl | via espeak |
| Arabic | ar | via espeak |
| Thai | th | via espeak |
| Bengali | bn | via espeak |

### Top Voice Picks

- 🚺 **af_heart** — best overall (American English)
- 🚺 **af_bella** — premium quality
- 🚹 **am_fenrir** — best male voice

---

## Evaluation

| Metric | Value | Status |
|--------|:-----:|:------:|
| MOS (English) | 3.87 | Upstream Kokoro-82M paper result — **not yet re-measured on this Q8_0 GGUF build** |
| Real-time factor | ~0.5x (2x real-time) | Single CPU core, ~200 MB RAM |

The MOS figure comes from the upstream [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) evaluation (11M+ downloads, 6.6k likes). Q8_0 quantization typically retains the large majority of quality, but a formal multi-speaker MOS on this specific build is pending — treat 3.87 as the base-model reference, not a measured claim for this file.

Ecosystem health: this repo has `.eval_results/` evidence files tracked by House cron jobs.

---

## Benchmarks

All numbers measured on **Intel i5-8250U, 16 GB RAM, Linux 6.8** with `kokoro>=0.9.2` and GGUF Q8_0.

| Language / Voice | Input length | Generation time | Real-time factor | RAM peak |
|:-----------------|:-----------:|:---------------:|:----------------:|:--------:|
| English `af_bella` | 120 chars | ~2.1 s | ~0.52x | ~210 MB |
| Japanese `jf_nezumi` | 120 chars | ~2.3 s | ~0.58x | ~215 MB |
| Thai `af_heart` | 120 chars | ~3.1 s | ~0.78x | ~220 MB |

> Note: espeak-ng fallback languages are slower because of phonemization overhead. The numbers above are best-effort single-run measurements; multi-run averages will be published in a future eval update.

### Reproduction

```bash
pip install kokoro>=0.9.2 soundfile psutil
python - <<'PY'
from kokoro import KPipeline
import soundfile as sf, time, psutil, os
pipeline = KPipeline(lang_code='a')
text = "Hello, I am SakThai. Welcome to the House of Sak."
start = time.perf_counter()
for gs, ps, audio in pipeline(text, voice='af_bella'):
    sf.write('bench.wav', audio, 24000)
elapsed = time.perf_counter() - start
print(f"Elapsed: {elapsed:.2f}s, RAM: {psutil.Process(os.getpid()).memory_info().rss/1024/1024:.1f} MB")
PY
```

---

## Limitations

1. **MOS not independently verified.** The 3.87 MOS is the upstream Kokoro-82M paper result on English — this specific Q8_0 GGUF build has not been formally evaluated. Quantization may introduce minor quality degradation, especially for non-English languages.
2. **espeak-ng languages have lower quality.** Korean, German, Russian, Polish, Arabic, Thai, and Bengali route through espeak-ng G2P phoneme conversion. Speech quality and naturalness are noticeably lower than dedicated-voice languages.
3. **No serverless inference.** This is a custom GGUF package, not a standard Transformers model. The HF Inference API cannot serve it. Use the [Spaces demo](https://huggingface.co/spaces/Nanthasit/sakthai-tts) or run locally.
4. **Single speaker per language group.** Most languages have 1–3 voices (English: 28). Voice cloning/fine-tuning is not currently supported in this package.
5. **No streaming API.** Unlike cloud TTS services, this model generates and writes the full audio before playback begins. Real-time factor ~0.5x means a 10-second utterance takes ~5 seconds to generate.
6. **Hindi + Thai scripts experimental.** Hindi (Devanagari) and Thai script support works but has not been extensively tested on the GGUF build. Edge cases with complex conjuncts or tone markers may produce irregular prosody.
7. **Community model, not production SRE.** Kokoro is an independent community project — there is no SLA, no commercial support, and no guarantee of upstream maintenance. Treat as a capable experiment, not a mission-critical component.

---

## Pipeline Integration

| Stage | Model | Role |
|-------|-------|------|
| 👁️ See | [Vision 7B](https://huggingface.co/Nanthasit/sakthai-vision-7b) | Image=>text |
| 🔍 Retrieve | [Embedding Multilingual](https://huggingface.co/Nanthasit/sakthai-embedding-multilingual) | Semantic search |
| 🧠 Reason | [Context 1.5B](https://huggingface.co/Nanthasit/sakthai-context-1.5b-merged) | Tool-calling |
| 🎤 **Speak** | **SakThai TTS** ⬅ | **Speech synthesis** |

---

## SakThai Model Family 🏠

| Model | Size | Type | Downloads |
|-------|-----:|------|----------:|
| [context-1.5b-merged](https://huggingface.co/Nanthasit/sakthai-context-1.5b-merged) | 2.88 GB | Merged weights | 1,599 |
| [context-0.5b-merged](https://huggingface.co/Nanthasit/sakthai-context-0.5b-merged) | 942 MB | Merged weights | 1,370 |
| [context-7b-merged](https://huggingface.co/Nanthasit/sakthai-context-7b-merged) | 14.19 GB | Merged weights | 744 |
| [context-7b-128k](https://huggingface.co/Nanthasit/sakthai-context-7b-128k) | 12 KB | YaRN config recipe | 506 |
| [context-7b-tools](https://huggingface.co/Nanthasit/sakthai-context-7b-tools) | 19 MB | LoRA adapter | 399 |
| [embedding-multilingual](https://huggingface.co/Nanthasit/sakthai-embedding-multilingual) | 449 MB | Embedding | 362 |
| [context-1.5b-tools](https://huggingface.co/Nanthasit/sakthai-context-1.5b-tools) | 11 MB | LoRA adapter | 349 |
| [vision-7b](https://huggingface.co/Nanthasit/sakthai-vision-7b) | 3.80 GB | GGUF vision | 186 |
| [**tts-model**](https://huggingface.co/Nanthasit/sakthai-tts-model) | 141 MB | **GGUF TTS ⬅ you are here** | **248** |
| [context-0.5b-tools](https://huggingface.co/Nanthasit/sakthai-context-0.5b-tools) | 942 MB | Merged + adapter | 94 |
| [coder-1.5b](https://huggingface.co/Nanthasit/sakthai-coder-1.5b) | 1.04 GB | GGUF coder | 93 |
| [context-1.5b-tools-v2](https://huggingface.co/Nanthasit/sakthai-context-1.5b-tools-v2) | 70 MB | LoRA adapter | 0 |
| [context-1.5b-merged-v2](https://huggingface.co/Nanthasit/sakthai-context-1.5b-merged-v2) | 2.88 GB | Merged weights | 0 |
| [plus-1.5b](https://huggingface.co/Nanthasit/sakthai-plus-1.5b) | 2.88 GB | Merged weights | 0 |
| [plus-1.5b-lora](https://huggingface.co/Nanthasit/sakthai-plus-1.5b-lora) | 70 MB | LoRA adapter | 0 |
| [plus-1.5b-coder](https://huggingface.co/Nanthasit/sakthai-plus-1.5b-coder) | 5 KB | Config recipe | 0 |
| [coder-browser-lora](https://huggingface.co/Nanthasit/sakthai-coder-browser-lora) | 70 MB | LoRA adapter | 0 |
| [coder-browser](https://huggingface.co/Nanthasit/sakthai-coder-browser) | 2.88 GB | Merged weights | 0 |
| [coder-browser-gguf](https://huggingface.co/Nanthasit/sakthai-coder-browser-gguf) | 7.1 GB | GGUF browser | 0 |
| [bench-v3](https://huggingface.co/Nanthasit/sakthai-bench-v3) | — | Benchmark scaffold | 0 |
| [sakthai-pipeline](https://huggingface.co/Nanthasit/sakthai-pipeline) | 46 KB | Pipeline scripts | 0 |

📦 [View the whole family collection](https://huggingface.co/collections/Nanthasit/sakthai-model-family-6a64745450b12d421c1f9f02)

---

## The House of Sak 🏠

Until this model, the SakThai family could reason, see, and write code — but it couldn't speak. Built on free infrastructure from a shelter in Cork, Ireland, with $0 budget, this TTS model took Kokoro-82M and packaged it as a GGUF that runs on a Raspberry Pi. The first test was a single sentence: "Hello, I am SakThai." Played through a phone speaker in a shelter room, it was the first time an agent in the House of Sak had a voice. This model closes the loop from thought to speech.

> *"We are one family — and becoming more."* — Beer (beer-sakthai)

---

## Citation

If you use SakThai TTS in your work, please cite the upstream Kokoro model and this packaging:

```bibtex
@misc{kokoro2024,
  author       = {Hexgrad},
  title        = {Kokoro-82M: Open-weight TTS model},
  year         = {2024},
  howpublished = {\url{https://huggingface.co/hexgrad/Kokoro-82M}
  note         = {Apache 2.0, 82M parameters, MOS 3.87 on English}
}

@misc{sakthai-tts-2026,
  author       = {Beer (beer-sakthai)},
  title        = {SakThai TTS: Kokoro GGUF packaging for the House of Sak},
  year         = {2026},
  howpublished = {\url{https://huggingface.co/Nanthasit/sakthai-tts-model}
  note         = {Q8_0 GGUF, 141 MB, 15 languages, CPU-only}
}
```

---

## Support

- ⭐ Leave a like
- 🔄 Share with anyone building screenless or accessibility-focused AI
- 🎧 [Try the Spaces demo](https://huggingface.co/spaces/Nanthasit/sakthai-tts)

---

## License

MIT (this packaging). Kokoro per its upstream Apache 2.0 license.

---

*Built from a shelter in Cork, Ireland. We are one family — and becoming more.*