Upload README.md with huggingface_hub

README.md

@@ -42,11 +42,17 @@ correctly — phone numbers, emails, addresses, prices, dates, temperatures, %,
 
 Pick **v2.1** for multiple voices; pick **v1** when the budget is CPU-only and tight.
 
-> **Also: `v2_mbistft_16k/` — PrimeTTS v2, the peak-fidelity single Xinran voice.** Same architecture as v2.1
-> (one speaker) but trained on the *full* clean 29k Xinran corpus, so its Xinran is the most intelligible in
-> the family — **CER 0.027** vs v2.1's 0.059 — at the **same** on-device RTF (0.52 @4thr). Use v2 when you only
-> need Xinran and want the cleanest possible output; use v2.1 when you want a choice of voice.
-> (`v3_4.6M/` and the top-level `*.onnx` are legacy 24 kHz variants, kept for provenance.)
+**The full family** (all MB-iSTFT-VITS except v1; all 16 kHz; single Xinran voice unless noted):
+
+| model | folder | params (deploy) | CER | use when |
+|---|---|---|---|---|
+| **v2** | `v2_mbistft_16k/` | 34.7M (17.5M) | **0.027** | you want the cleanest single Xinran voice |
+| **v2.1** | `v21_mbistft_16k/` | 37.9M (~18M) | 0.059 | you want a choice of 3 voices |
+| **V2 Lite** | `v2lite_mbistft_16k/` | 24.8M (17.5M) | 0.041 | a lighter, still-good single voice for tighter GPU budgets |
+| **v1** | `v1b_16k/`,`v1b_8k/` | ~5M | 0.11–0.15 | pure-CPU, real-time on a Jetson Nano |
+
+(`v3_4.6M/` and the top-level `*.onnx` are legacy 24 kHz variants, kept for provenance.) V2 Lite uses the exact
+same ONNX I/O + frontend as v2 — it's a drop-in, smaller replacement.
 
 > 🔊 **Live demo:** https://huggingface.co/spaces/Luigi/PrimeTTS-vs-Inflect-Nano-v1 — pick a model, pick a voice, type text.
 
@@ -204,6 +210,33 @@ diverse code-mix**, and **the teacher** (a student's language is only as good as
 
 ---
 
+## Findings & lessons (what building tiny on-device zh/en TTS actually taught us)
+
+Transferable lessons from taking this from a babbling 5M model to a shippable family. Full analysis in
+[`docs/zh-en-tts-arch-survey-2026.md`](./docs) and [`docs/streaming-arch-design.md`](./docs).
+
+- **A tiny model's quality is bounded by its *inputs*, not its parameter count.** Held-out Mandarin CER fell
+  **0.88 → 0.06 at a fixed ~5M** purely from **phone-level forced alignment** + broad character coverage —
+  no architecture change. Sub-syllable (not character) boundaries are the difference between intelligible
+  speech and fluent babble. **Gate on resynth CER, not on how balanced the duration histogram looks.**
+- **CER-gate the *teacher* audio, never voice-similarity alone.** Our first multi-speaker attempt trained on
+  teacher clips filtered only for the right *voice*; four of the "voices" were speakers that can't actually
+  pronounce Mandarin (teacher CER 0.45–0.79), and the student faithfully learned garbled speech. Filtering on
+  intelligibility (teacher X-ASR CER < 0.05) fixed it.
+- **Deterministic (FastSpeech-class) models mean-regress prosody; distributional (VITS/flow) models don't.**
+  This is the wall that caps a tiny deterministic model at "intelligible but flat" — and why the flagship is
+  a VITS, not a bigger FastSpeech.
+- **On a launch-bound GPU (Maxwell sm_53, no CUDA-graph replay), RTF is set by kernel *count*, not FLOPs.** A
+  smaller VITS is a smaller download but **not faster** (~0.42 RTF floor regardless of params). The lever for
+  *speed* is an architecture with fewer, larger kernels (flow-matching + Vocos measured ~0.18) — a different
+  axis from *size*.
+- **On an ARMv8.0 CPU (Cortex-A57): fp32 is the fast format.** No int8 dot-product and no fp16 arithmetic, so
+  int8 either breaks the voice (static) or runs *slower* than fp32 (dynamic), fp16 casts to fp32, and XNNPACK
+  ≈ MLAS. The only CPU speed lever is a smaller/faster architecture — quantization is a *download-size* option.
+- **"Lighter" and "faster" are different goals.** VITS deploy size is dominated by flow + decoder + encoder,
+  which don't shrink with `hidden_channels`; below ~17M deploy, quality craters. **V2 Lite (17.5M) is the
+  practical quality floor** for this arch — there is no free "smaller *and* still good."
+
 ## Credits & licenses
 
 - **v2.1 architecture:** [MB-iSTFT-VITS](https://github.com/MasayaKawamura/MB-iSTFT-VITS) (Kawamura et al., Apache-2.0) ·