Simplify README and add final banner image

.gitattributes

@@ -1,3 +1,4 @@
 *.pt filter=lfs diff=lfs merge=lfs -text
 *.wav filter=lfs diff=lfs merge=lfs -text
+assets/inflect-nano-banner.png filter=lfs diff=lfs merge=lfs -text
 tiny_tts/text/cmudict_cache.pickle filter=lfs diff=lfs merge=lfs -text

README.md

@@ -16,26 +16,27 @@ 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%">
+  <img src="https://huggingface.co/owensong/Inflect-Nano-v1/resolve/main/assets/inflect-nano-banner.png" alt="Inflect-Nano banner" width="100%">
 </p>
 
 # Inflect-Nano-v1
 
-**Inflect-Nano-v1 is a 4.63M-parameter English text-to-speech model, including its neural vocoder.**
+**Inflect-Nano-v1 is a tiny English text-to-speech model with 4.63M total inference parameters, including its vocoder.**
 
-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?
+It is not trying to beat large TTS models. It is a small, local, complete text-to-waveform stack built to test how far ultra-lightweight speech synthesis can go.
 
-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.
+## Highlights
 
-<p align="center">
+- **4.63M parameters total**
-  <b>4.632M total params</b> | <b>3.465M acoustic</b> | <b>1.167M vocoder</b> | <b>24 kHz</b> | <b>English</b>
+- **Includes the vocoder**
-</p>
+- **24 kHz audio**
+- **Single English male voice**
+- **Runs locally with PyTorch**
+- Built for tiny-model experiments, local assistants, embedded demos, and efficient inference research
 
-## Listen First
+## Listen
 
-These examples cover punctuation, short questions, numbers, hard words, longer phrasing, and transition-heavy prompts.
+| Text | Audio |
-
-| Prompt | Audio |
 |---|---|
 | "Did the timing change?" she answered. "Then why did Logan leave?" | <audio controls preload="none" src="https://huggingface.co/owensong/Inflect-Nano-v1/resolve/main/examples/example_01.wav"></audio> |
 | Who puts a parking meter next to an ER label? | <audio controls preload="none" src="https://huggingface.co/owensong/Inflect-Nano-v1/resolve/main/examples/example_02.wav"></audio> |
@@ -46,41 +47,7 @@ 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> |
 
-## Why This Exists
+## Install
-
-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
@@ -88,28 +55,23 @@ cd Inflect-Nano-v1
 pip install -r requirements.txt
 ```
 
-Generate audio:
+## Generate Speech
 
 ```bash
-python inference.py \
+python inference.py --text "Wait, are you actually being for real now?" --out sample.wav
-  --text "Wait, are you actually being for real now? I can't believe it!" \
-  --out sample.wav
 ```
 
 CPU:
 
 ```bash
-python inference.py \
+python inference.py --device cpu --text "Please say neighborhood clearly." --out sample_cpu.wav
-  --device cpu \
-  --text "Please say neighborhood, statistics, and anesthesiologist clearly." \
-  --out sample_cpu.wav
 ```
 
-Optional controls:
+With simple controls:
 
 ```bash
 python inference.py \
-  --text "No, seriously, did Jordan leave the receipt in Albuquerque?" \
+  --text "The appointment moved to 1:25." \
   --length-scale 1.03 \
   --pitch-scale 1.00 \
   --energy-scale 1.00 \
@@ -122,138 +84,79 @@ Local Gradio demo:
 python app.py
 ```
 
-The text frontend may download tokenizer files on first run.
+## Model Size
 
-## Model Summary
+| Part | Parameters |
+|---|---:|
+| Acoustic model | **3.465M** |
+| Vocoder generator | **1.167M** |
+| Total inference stack | **4.632M** |
 
-| Component | Parameters | Notes |
+The model files are:
-|---|---:|---|
-| 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
+## What Makes It Different
 
-Inflect-Nano-v1 is a two-part TTS stack:
+Many small TTS projects depend on a separate larger vocoder. Inflect-Nano-v1 includes the vocoder in the published inference stack, so the full text-to-waveform path stays under 5M parameters.
+
+Pipeline:
 
 ```text
-Text
+text
-  -> English normalization + G2P frontend
+-> English text frontend
-  -> Compact FastSpeech-style acoustic model
+-> compact FastSpeech-style acoustic model
 -> 80-bin mel spectrogram
-  -> Snake V2Mid HiFi-GAN-style vocoder
+-> small Snake HiFi-GAN-style vocoder
 -> 24 kHz waveform
 ```
 
-### Acoustic Model
+## Architecture
 
-The acoustic model predicts duration, energy, brightness, and pitch, expands token states into frame states, and decodes 80-bin mel spectrograms.
+The acoustic model is a compact non-autoregressive FastSpeech-style network. It predicts duration, pitch, energy, and brightness, then decodes an 80-bin mel spectrogram.
 
-Main config:
+The vocoder is a small Snake-activation HiFi-GAN-style generator trained for 24 kHz waveform reconstruction.
 
-```json
+Main settings:
-{
-  "hidden": 168,
-  "encoder_layers": 5,
-  "decoder_layers": 6,
-  "decoder_ff_mult": 3,
-  "kernel_size": 7,
-  "speaker_dim": 64,
-  "dropout": 0.08,
-  "n_mels": 80,
-  "sample_rate": 24000,
-  "max_frames": 1400,
-  "postnet_scale": 0.1,
-  "use_frame_pitch": true,
-  "abs_frame_bins": 512
-}
-```
 
-Approximate acoustic split:
+| Setting | Value |
+|---|---:|
+| Sample rate | 24 kHz |
+| Mel bins | 80 |
+| Acoustic hidden size | 168 |
+| Encoder layers | 5 |
+| Decoder layers | 6 |
+| Vocoder upsample rates | 8, 8, 2, 2 |
 
-```text
+## Good For
-total acoustic: 3.465M
-encoder:        1.292M
-decoder:        1.211M
-postnet:        0.276M
-local context:  0.226M
-frame GRU:      0.128M
-heads/embeds/projections: remainder
-```
-
-### Vocoder
-
-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:
-
-```json
-{
-  "variant": "snake_v2mid",
-  "sample_rate": 24000,
-  "n_fft": 1024,
-  "hop_size": 256,
-  "win_size": 1024,
-  "num_mels": 80,
-  "fmax": 12000.0,
-  "upsample_rates": [8, 8, 2, 2],
-  "upsample_kernel_sizes": [16, 16, 4, 4],
-  "upsample_initial_channel": 144,
-  "resblock_kernel_sizes": [3, 7, 11],
-  "resblock_dilation_sizes": [[1, 3, 5], [1, 3, 5], [1, 3, 5]],
-  "activation": "snake"
-}
-```
-
-## Intended Use
-
-Good fits:
 
 - Tiny local TTS experiments
 - Offline assistant prototypes
-- Embedded or low-resource speech demos
 - Efficient inference research
+- Embedded speech demos
 - Browser/WASM-style exploration
-- Baseline for sub-5M TTS work
+- A baseline for sub-5M TTS work
 
-Poor fits:
+## Not Good For
 
 - Production narration
 - Accessibility-critical output
 - Voice cloning
-- Multilingual TTS
+- Multilingual speech
-- High-fidelity studio speech
+- High-fidelity audiobook generation
-- Long-form audiobook generation
+- Matching large modern TTS systems
 
 ## Limitations
 
-This model is intentionally tiny and has clear quality limits:
+This is a very small experimental model. It can sound robotic, buzzy, or unstable, especially on difficult unseen text. Long prompts and unusual phrasing are less reliable. The vocoder is also a clear quality bottleneck.
 
-- Unseen text can stumble or sound unstable.
+Use it as a tiny-model research/demo release, not as a production TTS engine.
-- 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 safety-critical or production accessibility use.
-
-## Recommended Framing
-
-Use this as:
-
-> An experimental 4.63M-parameter English TTS model exploring the quality/size tradeoff for ultra-small local speech synthesis.
-
-Do not present it as SOTA or production-quality.
 
 ## License
 
 Apache-2.0.
 
-This repository includes a small third-party English text frontend derived from TinyTTS-style code for tokenization/G2P compatibility. Its license is included as `TINY_TTS_LICENSE`.
+This repository includes a small third-party English text frontend for tokenization/G2P compatibility. Its license is included as `TINY_TTS_LICENSE`.