README.md
15.4 KB · 266 lines · markdown Raw
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 ![text in → ESP32 → speech out](https://raw.githubusercontent.com/Ampixa/sanoTTS/master/docs/assets/saanotts-mcu-hero.png)
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 ![text → duration → acoustic → decoder → audio](https://raw.githubusercontent.com/Ampixa/sanoTTS/master/docs/assets/saanotts-signal-path.png)
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