README.md
| 1 | --- |
| 2 | license: gpl-3.0 |
| 3 | language: [en, ne, hi, vi, id, zh, de, fr, es, it, pt, ru, cs, ro, tr, ar, pl] |
| 4 | pipeline_tag: text-to-speech |
| 5 | tags: [text-to-speech, tiny, microcontroller, esp32, wasm, piper, distillation] |
| 6 | library_name: sanotts |
| 7 | --- |
| 8 | |
| 9 | # sanoTTS — a tiny neural voice that runs anywhere |
| 10 | |
| 11 | **Release status: Ready for release.** |
| 12 | |
| 13 | ***sano*** (सानो) — Nepali for **"small."** A family of tiny neural |
| 14 | text-to-speech voices — **294k to 2.27M parameters** — that run with |
| 15 | **no cloud and no NPU**: real-time on a ~$3 ESP32-S3 (out a GPIO into an |
| 16 | LM386 and a speaker), or live in the browser via WASM. |
| 17 | |
| 18 |  |
| 19 | |
| 20 | | | | |
| 21 | | --- | --- | |
| 22 | | Parameter range | **294,279 – 2,272,145** | |
| 23 | | Runs real-time on a $3 microcontroller | ESP32-S3, out a GPIO into an LM386 | |
| 24 | | Runs in the browser | WebAssembly, no server | |
| 25 | | Per-voice footprint | **337 KB to 8.7 MB**, zero dependencies (espeak-ng phonemizer included) | |
| 26 | | Live browser demo | **31 voices** across **17 languages** — English, Nepali (नेपाली), Hindi (हिन्दी), Vietnamese (Tiếng Việt), Indonesian (Bahasa), Chinese (中文), German, French, Spanish, Italian, Portuguese, Russian, Czech, Romanian, Turkish, Arabic, and Polish | |
| 27 | | License | open source, **GPL-3.0** | |
| 28 | |
| 29 | **Live demo:** [tts.ampixa.com/sanoTTS](https://tts.ampixa.com/sanoTTS) — |
| 30 | **31 voices across 17 languages**, synthesizing your text live in the browser, no server, no upload. |
| 31 | |
| 32 | The count is the live demo's voice-picker inventory, including separate model sizes for the same language. **Polish is currently demo-only:** its weights are not yet hosted in this Hugging Face repository. The repository also retains the older Chinese voice for compatibility; the live picker uses its Chinese Xiaoya replacement. |
| 33 | |
| 34 | ## Download |
| 35 | |
| 36 | Both packages stream their weights from **this repo** by default. |
| 37 | |
| 38 | ```python |
| 39 | import sanotts |
| 40 | sanotts.synthesize("Hello world", voice="heart") # downloads heart/ from here |
| 41 | ``` |
| 42 | |
| 43 | ```js |
| 44 | import { SanoTTS } from 'sanotts-web'; // fetches web/voices/ from here |
| 45 | const tts = await SanoTTS.load(); |
| 46 | const result = await tts.synthesize('Hello world', { voice: 'heart' }); |
| 47 | ``` |
| 48 | |
| 49 | Python needs `sanotts` >= 0.3.0, the browser `sanotts-web` >= 0.3.0. Both fall |
| 50 | back to the GitHub releases or the Pages host if Hugging Face cannot be |
| 51 | reached, so an outage here cannot break an install. Python packages land in |
| 52 | `~/.cache/sanotts/`; set `SANOTTS_VOICE_SOURCE=hf` or `=github` to pin one |
| 53 | host. In the browser, passing `voiceBase` yourself turns the fallback off, so |
| 54 | a self-hosted deployment never quietly reaches back to our servers. |
| 55 | |
| 56 | ## Samples |
| 57 | |
| 58 | Selected samples are embedded below; this is not the full 31-voice demo inventory. |
| 59 | "Package here" links to a voice's Python/C package when available. Browser |
| 60 | bundles for Nepali, Hindi, and Chinese are also hosted here under `web/voices/`. |
| 61 | The older Chinese sample below is retained for compatibility; the live demo |
| 62 | uses [Chinese Xiaoya](https://huggingface.co/ampixa/sanoTTS/tree/main/web/voices/chinese-xiaoya). |
| 63 | |
| 64 | The browser collection additionally includes German, French, Spanish, Italian, |
| 65 | Portuguese, Russian, Czech, Romanian, Turkish, Arabic, and the experimental |
| 66 | English Trellis voice. Browse the [browser bundles](https://huggingface.co/ampixa/sanoTTS/tree/main/web/voices) |
| 67 | and try all 31 voices, including demo-only Polish, in the [live demo](https://tts.ampixa.com/sanoTTS). |
| 68 | |
| 69 | | Voice | Language | Params | SCOREQ | Package here | Sample | |
| 70 | | --- | --- | ---: | :---: | :---: | --- | |
| 71 | | heart | English 🇺🇸 | 2.27 M | 3.48 | [`heart/`](https://huggingface.co/ampixa/sanoTTS/tree/main/heart) | <audio controls src="https://huggingface.co/ampixa/sanoTTS/resolve/main/samples/english-heart-1.mp3"></audio> | |
| 72 | | hfc | English 🇺🇸 | 1.83 M | 3.94 | [`hfc-en-1p8m/`](https://huggingface.co/ampixa/sanoTTS/tree/main/hfc-en-1p8m) | <audio controls src="https://huggingface.co/ampixa/sanoTTS/resolve/main/samples/english-hfc-1.mp3"></audio> | |
| 73 | | amy | English 🇺🇸 | 1.46 M | **4.13** | [`amy-en-1p46m/`](https://huggingface.co/ampixa/sanoTTS/tree/main/amy-en-1p46m) | <audio controls src="https://huggingface.co/ampixa/sanoTTS/resolve/main/samples/english-amy-1.mp3"></audio> | |
| 74 | | kristin | English 🇺🇸 | 1.40 M | 4.09 | [`kristin-en-1p4m/`](https://huggingface.co/ampixa/sanoTTS/tree/main/kristin-en-1p4m) | <audio controls src="https://huggingface.co/ampixa/sanoTTS/resolve/main/samples/english-kristin-1.mp3"></audio> | |
| 75 | | amy-small | English 🇺🇸 | 1.08 M | 3.70 | [`amy-en-1p1m/`](https://huggingface.co/ampixa/sanoTTS/tree/main/amy-en-1p1m) | <audio controls src="https://huggingface.co/ampixa/sanoTTS/resolve/main/samples/english-amy-small-1.mp3"></audio> | |
| 76 | | robot (on-device, int8) | English 🇺🇸 | 567 k | — | not packaged here (int8 MCU format) | <audio controls src="https://huggingface.co/ampixa/sanoTTS/resolve/main/samples/mcu-567k.mp3"></audio> | |
| 77 | | heart-nano | English 🇺🇸 | 294 k | 2.29 | [`heartnano/`](https://huggingface.co/ampixa/sanoTTS/tree/main/heartnano) | <audio controls src="https://huggingface.co/ampixa/sanoTTS/resolve/main/samples/english-heart-nano-1.mp3"></audio> | |
| 78 | | Indonesian | Bahasa | 1.46 M | — | [`id-newstts-1p46m/`](https://huggingface.co/ampixa/sanoTTS/tree/main/id-newstts-1p46m) | <audio controls src="https://huggingface.co/ampixa/sanoTTS/resolve/main/samples/indonesian-1.mp3"></audio> | |
| 79 | | Vietnamese | Tiếng Việt | 1.46 M | — | [`vi-vais1000-1p46m/`](https://huggingface.co/ampixa/sanoTTS/tree/main/vi-vais1000-1p46m) | <audio controls src="https://huggingface.co/ampixa/sanoTTS/resolve/main/samples/vietnamese-1.mp3"></audio> | |
| 80 | | Nepali | नेपाली | 1.47 M | — | [browser bundle](https://huggingface.co/ampixa/sanoTTS/tree/main/web/voices/nepali) | <audio controls src="https://huggingface.co/ampixa/sanoTTS/resolve/main/samples/nepali-1.mp3"></audio> | |
| 81 | | Hindi | हिन्दी | 1.50 M | — | [browser bundle](https://huggingface.co/ampixa/sanoTTS/tree/main/web/voices/hindi) | <audio controls src="https://huggingface.co/ampixa/sanoTTS/resolve/main/samples/hindi-1.mp3"></audio> | |
| 82 | | Chinese | 中文 | 1.50 M | — | [browser bundle](https://huggingface.co/ampixa/sanoTTS/tree/main/web/voices/chinese) | <audio controls src="https://huggingface.co/ampixa/sanoTTS/resolve/main/samples/chinese-1.mp3"></audio> | |
| 83 | |
| 84 | SCOREQ is a no-reference naturalness predictor, higher is better; it is only |
| 85 | reported for the English voices, which share one 24-sentence eval set. The |
| 86 | other languages haven't been scored against a comparable reference yet. |
| 87 | |
| 88 | **Size does not order this table, and we are not going to pretend it does.** |
| 89 | `amy` at 1.46M scores higher than `heart` at 2.27M because they come from |
| 90 | different teachers and different architectures, not because one is bigger. |
| 91 | `amy` and the voices above it are the **piperlite** lineage, distilled from a |
| 92 | Piper/VITS teacher at 22.05 kHz. `heart` and `heart-nano` are the newer |
| 93 | **nano** lineage — 24 kHz, mel-100 → ConvNeXt1D → iSTFT, distilled from a |
| 94 | Kokoro teacher through a frozen Vocos — which is the one that quantizes to |
| 95 | int8 and runs on a microcontroller. The two are not interchangeable and the |
| 96 | `sanotts` package picks the right runtime for you. |
| 97 | |
| 98 | The `heart` and `heart-nano` scores were re-measured on 2026-09-04; the eval |
| 99 | set, checkpoint hashes, exact commands and all 24 per-clip scores are in |
| 100 | [`evidence/heart-diverse24-remeasure-20260904.json`](https://huggingface.co/ampixa/sanoTTS/blob/main/evidence/heart-diverse24-remeasure-20260904.json). |
| 101 | They were scored on the float32 reference render. The shipped `heart-nano` |
| 102 | int8 export tracks that render at 0.981 waveform correlation, and `heart` |
| 103 | ships as float32 because its int8 export reached only 0.951 against a 0.98 |
| 104 | gate. |
| 105 | |
| 106 | The "robot" row is the 567,008-parameter model that runs on the ESP32-S3. |
| 107 | |
| 108 | ## Install & use |
| 109 | |
| 110 | | Platform | Install | Then | |
| 111 | | --- | --- | --- | |
| 112 | | Python | `pip install sanotts` | `sanotts say "Hello" --voice heart -o hello.wav` | |
| 113 | | Web (npm) | `npm install sanotts-web` | `const tts = await SanoTTS.load(); await tts.synthesize('Hello', {voice:'heart'})` | |
| 114 | | Web (no build) | copy `dist/` + `voices/` | see [Deploy on your own site](https://github.com/Ampixa/sanoTTS#deploy-on-your-own-site) in the GitHub README | |
| 115 | | Arduino / PlatformIO | zip-install or `lib_deps = https://github.com/Ampixa/sanoTTS.git` | [`arduino/README.md`](https://github.com/Ampixa/sanoTTS/blob/master/arduino/README.md) | |
| 116 | | Hugging Face | this repo | the voice packages above, downloaded for you by `pip install sanotts` | |
| 117 | | Browser | nothing | [tts.ampixa.com/sanoTTS](https://tts.ampixa.com/sanoTTS) | |
| 118 | |
| 119 | Pip voices: `heart`, `hfc`, `amy-1p8m`, `amy`, `kristin`, `vi`, `id`, |
| 120 | `amy-1p1m`, `heart-nano`. Pure numpy inference, no torch, no onnxruntime. |
| 121 | |
| 122 | ## Streaming and the Open TTS Leaderboard |
| 123 | |
| 124 | `sanotts` streams: `Synthesizer.synthesize_stream(text)` yields audio chunk by |
| 125 | chunk, and the chunks join to exactly what `synthesize()` returns, up to |
| 126 | float32 rounding. |
| 127 | |
| 128 | ```python |
| 129 | from sanotts import Synthesizer |
| 130 | syn = Synthesizer("heart-nano") |
| 131 | for chunk in syn.synthesize_stream("Hello from a 294k-parameter voice."): |
| 132 | ... # float32 at syn.sample_rate, ready to play |
| 133 | ``` |
| 134 | |
| 135 | The three English voices were evaluated by the maintainers of the |
| 136 | [Open TTS Leaderboard](https://huggingface.co/spaces/hf-audio/open_tts_leaderboard) |
| 137 | on HF Jobs ([PR #53](https://github.com/huggingface/open-tts-leaderboard/pull/53), sanotts 0.5.4). |
| 138 | Time to first audio is measured on CPU (`cpu-upgrade`, one thread, batch size 1) |
| 139 | over the 497 CV3-Eval English prompts; RTFx is the main eval's throughput, run |
| 140 | on one CPU thread. WER is from Qwen3-ASR over Seed-TTS, CV3-Eval and MiniMax English. |
| 141 | |
| 142 | | Voice | Params | TTFA p50 | TTFA p95 | RTFx | WER | UTMOS | |
| 143 | | --- | ---: | ---: | ---: | ---: | ---: | ---: | |
| 144 | | heart-nano | 294 k | 2.8 ms | 5.9 ms | 214 | 1.07 % | 2.39 | |
| 145 | | heart | 2.27 M | 6.4 ms | 9.8 ms | 49 | 0.86 % | 3.30 | |
| 146 | | amy | 1.46 M | 22.7 ms | 36.3 ms | 15 | 1.12 % | 3.99 | |
| 147 | |
| 148 | On that board, larger and newer models score higher on UTMOS than these voices |
| 149 | do; what sanoTTS brings is the latency, the throughput and the size. |
| 150 | |
| 151 | ## How it stacks up |
| 152 | |
| 153 | Open small-scale TTS on an honest gate — a diverse 24-sentence set scored |
| 154 | with the **same** no-reference suite (SCOREQ / UTMOS are naturalness |
| 155 | predictors, DNSMOS-SIG is signal quality; higher is better). Parameter |
| 156 | counts are inference-time and exclude the shared external G2P. |
| 157 | |
| 158 | | System | Params | SCOREQ | UTMOS | DNS-SIG | |
| 159 | | --- | ---: | :---: | :---: | :---: | |
| 160 | | **sanoTTS (amy)** | **1.46 M** | **4.13** | **4.10** | 3.61 | |
| 161 | | TinyTTS | 1.62 M | 3.94 | 3.65 | **3.62** | |
| 162 | | Inflect Nano | 4.63 M | 3.81 | 3.65 | 3.58 | |
| 163 | | Kitten TTS nano | 15 M | 3.02 | 3.58 | 3.43 | |
| 164 | | _Piper (our teacher)_ | _~15 M_ | _4.71_ | _4.47_ | _3.65_ | |
| 165 | | _Kokoro_ | _82 M_ | _4.89_ | _4.52_ | _3.69_ | |
| 166 | |
| 167 | Among the systems in this table, sanoTTS amy is the **smallest** and scores |
| 168 | **highest on naturalness (SCOREQ and UTMOS) below Piper** — beating TinyTTS |
| 169 | while being smaller. This is our own 24-sentence comparison; on the Open TTS |
| 170 | Leaderboard's larger sets, several small models (for example Paradee-8M and |
| 171 | PiVo-1.4M) have higher UTMOS than amy. On DNSMOS-SIG, TinyTTS edges us by 0.01 — no single |
| 172 | metric tells the whole story. It's the only one that runs a full neural |
| 173 | stack on a $3 MCU. The frontier only pulls ahead at Piper, the ~15M teacher |
| 174 | we distilled from, and Kokoro (82M, 56× larger) — a gap we don't claim to |
| 175 | close. Reproduce it with `tools/eval_mos_all.py` + `tools/eval_scorecard.py` |
| 176 | in the GitHub repo. |
| 177 | |
| 178 | Shipped-file sizes: sanoTTS amy 2.8 MB fp16 and TinyTTS 3.5 MB fp16, both |
| 179 | verified from the released files; Kokoro's ~330 MB fp32 is its widely cited |
| 180 | public figure. |
| 181 | |
| 182 | ## How it works |
| 183 | |
| 184 |  |
| 185 | |
| 186 | espeak-ng provides phoneme IDs; a duration model predicts timing; an |
| 187 | acoustic model predicts generator latents; a decoder renders audio. The |
| 188 | piperlite voices (amy, kristin, hfc, and the other languages) use a compact |
| 189 | time-domain decoder running in fp32 at 22.05 kHz. The nano voices (heart, |
| 190 | heart-nano) and the 567,008-parameter on-device model use an iSTFT decoder |
| 191 | at 24 kHz, quantized to int8 where it has to fit and run in real time on the |
| 192 | ESP32-S3. Models are distilled from a Piper/VITS or Kokoro teacher — see |
| 193 | [`docs/distillation-recipe.md`](https://github.com/Ampixa/sanoTTS/blob/master/docs/distillation-recipe.md) |
| 194 | in the GitHub repo for the full recipe. |
| 195 | |
| 196 | ## Deploy |
| 197 | |
| 198 | - **ESP32-S3 talking device** — a standalone WiFi dashboard: type text, the |
| 199 | board phonemizes (on-chip espeak-ng) and speaks. See |
| 200 | [`mcu/ports/esp32s3/`](https://github.com/Ampixa/sanoTTS/tree/master/mcu/ports/esp32s3). |
| 201 | Board-by-board measurements are in |
| 202 | [`BOARDS.md`](https://github.com/Ampixa/sanoTTS/blob/master/BOARDS.md); the |
| 203 | silicon figures there are for the `en_us_e12nano` lineage, which is a |
| 204 | sibling of `heart-nano`, not the same weights. |
| 205 | - **Browser** — the full stack in WASM, no server. **[▶ Hear and synthesize |
| 206 | all 31 voices across 17 languages live](https://tts.ampixa.com/sanoTTS)**; source in |
| 207 | [`web/`](https://github.com/Ampixa/sanoTTS/tree/master/web). |
| 208 | - **Other MCUs** — which chips can run it and how well: |
| 209 | [`docs/mcu-classes-and-porting.md`](https://github.com/Ampixa/sanoTTS/blob/master/docs/mcu-classes-and-porting.md). |
| 210 | |
| 211 | ## Links |
| 212 | |
| 213 | - Source, recipes, eval tooling: [github.com/Ampixa/sanoTTS](https://github.com/Ampixa/sanoTTS) |
| 214 | - Live browser demo: [tts.ampixa.com/sanoTTS](https://tts.ampixa.com/sanoTTS) |
| 215 | - npm package: [sanotts-web](https://www.npmjs.com/package/sanotts-web) |
| 216 | - PyPI package: [sanotts](https://pypi.org/project/sanotts/) |
| 217 | |
| 218 | ## License |
| 219 | |
| 220 | GPLv3 — see [`LICENSE`](https://github.com/Ampixa/sanoTTS/blob/master/LICENSE). |
| 221 | The pipeline builds on GPLv3 components (notably |
| 222 | [espeak-ng](https://github.com/espeak-ng/espeak-ng) for G2P, and |
| 223 | [piper](https://github.com/OHF-Voice/piper1-gpl)), so the project as a |
| 224 | whole is GPLv3. |
| 225 | |
| 226 | Copyright (C) 2026 Ampixa. |
| 227 | |
| 228 | ## Files here |
| 229 | |
| 230 | Two package layouts, because there are two graphs. |
| 231 | |
| 232 | **piperlite** (`amy-en-1p46m/`, `kristin-en-1p4m/`, `hfc-en-1p8m/`, |
| 233 | `amy-en-1p1m/`, `id-newstts-1p46m/`, `vi-vais1000-1p46m/`) — a flat fp16 |
| 234 | blob addressed by manifest offsets: |
| 235 | |
| 236 | ``` |
| 237 | manifest.json weights.fp16.bin |
| 238 | piper-phoneme-config.json (+ sibilant-injection calibration where applicable) |
| 239 | ``` |
| 240 | |
| 241 | **nano** (`heart/`, `heartnano/`) — the mel-100 stack, two blobs plus the |
| 242 | generated offset header: |
| 243 | |
| 244 | ``` |
| 245 | meta.json lineage, per-file sha256, sample rate, vocab |
| 246 | front_*.bin duration + acoustic |
| 247 | model_*.bin decoder |
| 248 | nano_q8_meta.h tensor offsets |
| 249 | ``` |
| 250 | |
| 251 | `heartnano/` ships `*_q8.bin` (int8, 345,232 bytes total); `heart/` ships |
| 252 | `*_f32.bin` (float32, 9,137,920 bytes) because its int8 export missed the |
| 253 | fidelity gate. Both layouts are consumed by the `sanotts` Python package and |
| 254 | the portable C runtime. |
| 255 | |
| 256 | **`web/voices/`** is a third thing and exists for the browser. The piperlite |
| 257 | voices ship there as `front_f32.bin` + `dec_f32.bin`, a different artifact |
| 258 | from the `weights.fp16.bin` the Python package reads, which is why the same |
| 259 | voice appears twice in this repo under two names. It mirrors `web/` in the |
| 260 | GitHub repo byte for byte and is what `sanotts-web` fetches. The nano voices |
| 261 | are not duplicated: `web/voices/heart/` and `heart/` hold the same blobs. |
| 262 | |
| 263 | `samples/` holds the audio clips embedded above (mp3, one or two per voice, |
| 264 | plus the on-device `mcu-567k.mp3`), and `evidence/` the eval report behind the |
| 265 | heart scores. |
| 266 | |