Polish model card and add README banner

README.md

@@ -8,45 +8,30 @@ tags:
 - speech-synthesis
 - pytorch
 - ultra-small
-- tiny-tts
 - local-tts
+- efficient-inference
 - experimental
 pipeline_tag: text-to-speech
 library_name: pytorch
 ---
 
+<p align="center">
+  <img src="https://huggingface.co/owensong/Inflect-Nano-v1/resolve/main/assets/inflect-nano-banner.svg" alt="Inflect-Nano-v1 banner" width="100%">
+</p>
+
 # Inflect-Nano-v1
 
-Inflect-Nano-v1 is an **ultra-small English text-to-speech model** with only **4.63M inference parameters total**. That includes both the acoustic model and the neural vocoder.
+**Inflect-Nano-v1 is a 4.63M-parameter English text-to-speech model, including its neural vocoder.**
 
-The goal is simple: explore how far a truly tiny, fully local TTS stack can be pushed while staying small enough to run in places where normal TTS models are too large. It is one of the smallest neural TTS releases in this class, sitting far below the size of most modern speech synthesis systems.
+It is built around one question: how usable can a complete local TTS stack get when the entire inference model is smaller than many single embeddings tables in modern speech systems?
 
-This is an experimental release, not a production or SOTA voice model. It is small, fast to load, and usable for demos, but it still has audible quality limits.
+This is not a SOTA voice model. The point is the size-to-functionality ratio: a complete text-to-waveform TTS pipeline that is small enough for tiny local experiments, offline assistants, embedded prototypes, browser/WASM-style work, and efficient inference research.
 
-## Why It Is Notable
+<p align="center">
+  <b>4.632M total params</b> | <b>3.465M acoustic</b> | <b>1.167M vocoder</b> | <b>24 kHz</b> | <b>English</b>
+</p>
 
-- **4.63M total inference parameters**
+## Listen First
-- **Includes the vocoder**, not just a front-end acoustic model
-- English-only single-voice speech synthesis
-- 24 kHz waveform output
-- Compact non-autoregressive acoustic model
-- Small Snake-activation HiFi-GAN-style vocoder
-- Designed for local/offline experiments and tiny-model research
-
-## Quick Facts
-
-| Item | Value |
-|---|---:|
-| Total inference parameters | **4.632M** |
-| Acoustic model | **3.465M** |
-| Vocoder generator | **1.167M** |
-| Language | English |
-| Voice | single male voice |
-| Sample rate | 24 kHz |
-| Acoustic output | 80-bin mel spectrogram |
-| Vocoder | Snake V2Mid HiFi-GAN-style generator |
-
-## Audio Examples
 
 These examples cover punctuation, short questions, numbers, hard words, longer phrasing, and transition-heavy prompts.
 
@@ -61,7 +46,41 @@ These examples cover punctuation, short questions, numbers, hard words, longer p
 | If Logan sounded uneasy, then it happened near Long Beach, and the pause has to carry that. | <audio controls preload="none" src="https://huggingface.co/owensong/Inflect-Nano-v1/resolve/main/examples/example_07.wav"></audio> |
 | The word aluminum should not steal attention from the softer ending after entrepreneur. | <audio controls preload="none" src="https://huggingface.co/owensong/Inflect-Nano-v1/resolve/main/examples/example_08.wav"></audio> |
 
-## Install
+## Why This Exists
+
+Most strong TTS models are large. Many "small" TTS demos also depend on a larger external vocoder, which hides a lot of the real inference cost. Inflect-Nano-v1 counts both sides:
+
+```text
+text -> acoustic model -> mel spectrogram -> neural vocoder -> waveform
+```
+
+The model is intentionally constrained:
+
+| Capability | Inflect-Nano-v1 |
+|---|---:|
+| Complete text-to-waveform stack | Yes |
+| External vocoder required | No |
+| Total inference parameters | **4.632M** |
+| Sample rate | **24 kHz** |
+| Language | English |
+| Voice count | 1 |
+| Voice cloning | No |
+| Multilingual | No |
+
+## Size Context
+
+Approximate parameter comparison:
+
+| Model / class | Params | Relative to Inflect-Nano-v1 |
+|---|---:|---:|
+| Inflect-Nano-v1 | **4.63M** | 1.0x |
+| Kokoro-82M | ~82M | ~17.7x larger |
+| Chatterbox-sized TTS | ~500M | ~108x larger |
+| Multi-billion TTS systems | 1B+ | 216x+ larger |
+
+The comparison is about model scale, not quality parity. Larger models are expected to sound better.
+
+## Quickstart
 
 ```bash
 git clone https://huggingface.co/owensong/Inflect-Nano-v1
@@ -69,9 +88,7 @@ cd Inflect-Nano-v1
 pip install -r requirements.txt
 ```
 
-The text frontend may download tokenizer files on first run.
+Generate audio:
-
-## Usage
 
 ```bash
 python inference.py \
@@ -79,7 +96,7 @@ python inference.py \
   --out sample.wav
 ```
 
-CPU example:
+CPU:
 
 ```bash
 python inference.py \
@@ -99,20 +116,37 @@ python inference.py \
   --out sample_controlled.wav
 ```
 
-Gradio demo:
+Local Gradio demo:
 
 ```bash
 python app.py
 ```
 
+The text frontend may download tokenizer files on first run.
+
+## Model Summary
+
+| Component | Parameters | Notes |
+|---|---:|---|
+| Acoustic model | **3,465,125** | Compact non-autoregressive FastSpeech-style model |
+| Vocoder generator | **1,167,077** | Snake V2Mid HiFi-GAN-style generator |
+| Total inference model | **4,632,202** | Acoustic + vocoder |
+
+Model files:
+
+```text
+weights/inflect_nano_v1_acoustic.pt
+weights/inflect_nano_v1_vocoder.pt
+```
+
 ## Architecture
 
 Inflect-Nano-v1 is a two-part TTS stack:
 
 ```text
-text
+Text
--> normalization + English G2P frontend
+  -> English normalization + G2P frontend
--> compact FastSpeech-style acoustic model
+  -> Compact FastSpeech-style acoustic model
   -> 80-bin mel spectrogram
   -> Snake V2Mid HiFi-GAN-style vocoder
   -> 24 kHz waveform
@@ -120,7 +154,7 @@ text
 
 ### Acoustic Model
 
-The acoustic model is a compact non-autoregressive FastSpeech-style network. It predicts duration, energy, brightness, and pitch, expands token states into frame states, and decodes 80-bin mel spectrograms.
+The acoustic model predicts duration, energy, brightness, and pitch, expands token states into frame states, and decodes 80-bin mel spectrograms.
 
 Main config:
 
@@ -156,7 +190,7 @@ heads/embeds/projections: remainder
 
 ### Vocoder
 
-The vocoder is a custom Snake-activation HiFi-GAN-style generator.
+The vocoder is a custom Snake-activation HiFi-GAN-style generator. Discriminators are training-only and are not included in inference parameter counts.
 
 Main config:
 
@@ -178,14 +212,25 @@ Main config:
 }
 ```
 
-Discriminators are training-only and are not included in inference parameter counts.
+## Intended Use
 
-## Model Files
+Good fits:
 
-```text
+- Tiny local TTS experiments
-weights/inflect_nano_v1_acoustic.pt
+- Offline assistant prototypes
-weights/inflect_nano_v1_vocoder.pt
+- Embedded or low-resource speech demos
-```
+- Efficient inference research
+- Browser/WASM-style exploration
+- Baseline for sub-5M TTS work
+
+Poor fits:
+
+- Production narration
+- Accessibility-critical output
+- Voice cloning
+- Multilingual TTS
+- High-fidelity studio speech
+- Long-form audiobook generation
 
 ## Limitations
 
@@ -194,9 +239,10 @@ This model is intentionally tiny and has clear quality limits:
 - Unseen text can stumble or sound unstable.
 - The voice can sound robotic, buzzy, or artifacted.
 - Long or unusual prompts are less reliable.
+- The vocoder is a major quality bottleneck.
 - It is not a voice cloning model.
 - It is not multilingual.
-- It is not suitable for production accessibility, safety, or high-quality narration use.
+- It is not suitable for safety-critical or production accessibility use.
 
 ## Recommended Framing
 

assets/inflect-nano-banner.svg

@@ -0,0 +1,73 @@
+<svg width="1800" height="600" viewBox="0 0 1800 600" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1800" y2="600" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#101418"/>
+      <stop offset="0.55" stop-color="#151B21"/>
+      <stop offset="1" stop-color="#0D1116"/>
+    </linearGradient>
+    <linearGradient id="cyan" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#8EE8FF"/>
+      <stop offset="1" stop-color="#2EA7C8"/>
+    </linearGradient>
+    <linearGradient id="amber" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#FFC46B"/>
+      <stop offset="1" stop-color="#D58A2B"/>
+    </linearGradient>
+    <filter id="softGlow" x="-30%" y="-30%" width="160%" height="160%">
+      <feGaussianBlur stdDeviation="10" result="blur"/>
+      <feColorMatrix in="blur" type="matrix" values="0 0 0 0 0.15 0 0 0 0 0.75 0 0 0 0 0.95 0 0 0 0.35 0"/>
+      <feMerge>
+        <feMergeNode/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+    <pattern id="grid" width="42" height="42" patternUnits="userSpaceOnUse">
+      <path d="M42 0H0V42" stroke="#FFFFFF" stroke-opacity="0.035" stroke-width="1"/>
+    </pattern>
+  </defs>
+
+  <rect width="1800" height="600" rx="44" fill="url(#bg)"/>
+  <rect width="1800" height="600" rx="44" fill="url(#grid)"/>
+  <rect x="48" y="48" width="1704" height="504" rx="32" stroke="#FFFFFF" stroke-opacity="0.08"/>
+
+  <g opacity="0.9">
+    <text x="112" y="165" fill="#F5F1E8" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="76" font-weight="750" letter-spacing="-2">Inflect-Nano-v1</text>
+    <text x="116" y="228" fill="#9FAAB5" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="30" font-weight="500">4.63M parameter English TTS</text>
+    <text x="116" y="282" fill="#D7DEE5" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="24" font-weight="520">Complete stack  |  Includes vocoder  |  Runs locally</text>
+  </g>
+
+  <g transform="translate(116 350)">
+    <rect x="0" y="0" width="210" height="54" rx="27" fill="#FFFFFF" fill-opacity="0.06" stroke="#FFFFFF" stroke-opacity="0.08"/>
+    <text x="30" y="35" fill="#8EE8FF" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="22" font-weight="700">tiny local TTS</text>
+    <rect x="230" y="0" width="224" height="54" rx="27" fill="#FFFFFF" fill-opacity="0.06" stroke="#FFFFFF" stroke-opacity="0.08"/>
+    <text x="260" y="35" fill="#FFC46B" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="22" font-weight="700">24 kHz output</text>
+  </g>
+
+  <g transform="translate(850 132)">
+    <text x="0" y="0" fill="#F5F1E8" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="25" font-weight="700">Size comparison</text>
+    <text x="0" y="37" fill="#97A3AD" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="18">Inference parameters, approximate</text>
+
+    <g transform="translate(0 85)">
+      <text x="0" y="20" fill="#D7DEE5" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="22" font-weight="650">Inflect-Nano</text>
+      <rect x="220" y="0" width="54" height="26" rx="13" fill="url(#cyan)" filter="url(#softGlow)"/>
+      <text x="294" y="21" fill="#F5F1E8" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="20" font-weight="700">4.63M</text>
+    </g>
+
+    <g transform="translate(0 155)">
+      <text x="0" y="20" fill="#D7DEE5" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="22" font-weight="650">Kokoro</text>
+      <rect x="220" y="0" width="360" height="26" rx="13" fill="#2D6F82"/>
+      <text x="600" y="21" fill="#F5F1E8" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="20" font-weight="700">82M</text>
+    </g>
+
+    <g transform="translate(0 225)">
+      <text x="0" y="20" fill="#D7DEE5" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="22" font-weight="650">Chatterbox-size</text>
+      <rect x="220" y="0" width="700" height="26" rx="13" fill="#3F4854"/>
+      <text x="944" y="21" fill="#F5F1E8" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="20" font-weight="700">~500M</text>
+    </g>
+  </g>
+
+  <path d="M878 444 C922 444 930 388 965 388 C1004 388 1003 476 1046 476 C1091 476 1084 342 1135 342 C1187 342 1177 511 1231 511 C1293 511 1269 292 1339 292 C1396 292 1387 438 1439 438 C1490 438 1484 372 1531 372 C1576 372 1580 420 1634 420" stroke="url(#cyan)" stroke-width="5" stroke-linecap="round" opacity="0.82"/>
+  <path d="M878 474 C940 474 944 426 991 426 C1040 426 1031 508 1086 508 C1135 508 1129 397 1180 397 C1238 397 1216 536 1279 536 C1334 536 1339 474 1395 474 C1449 474 1440 518 1496 518 C1546 518 1547 480 1634 480" stroke="url(#amber)" stroke-width="3" stroke-linecap="round" opacity="0.55"/>
+
+  <text x="116" y="520" fill="#6F7A84" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="17">Experimental tiny speech synthesis research model - not SOTA, built to explore quality per parameter.</text>
+</svg>