update README demo

README.md

@@ -39,6 +39,42 @@ Built for the Hugging Face Hackathon. Runs entirely on local models inside a Gra
 | **Answer** | A short grounded answer is generated from the story context and spoken by the low-latency Q&A audio model. It does not use the cloned narrator voice. | LFM2.5-Audio-1.5B |
 | **Resume** | Story continues from where it left off. Play also pauses on tab switch. | Cached chunks |
 
+## Application Demo
+
+> Full step-by-step walkthrough: [docs/DEMO_WALKTHROUGH.md](docs/DEMO_WALKTHROUGH.md)
+
+### Explore Space — Browse the Story Shelf
+
+![Explore Space](docs/demo01.png)
+
+### My Library — Now Playing with Pause & Resume
+
+![My Library Now Playing](docs/demo02.png)
+
+### Voice Q&A — Ask a Question by Recording
+
+![Voice Q&A Panel](docs/demo03.png)
+
+### LFM2.5-Audio Answer — Spoken Response Generated Instantly
+
+![LFM Answer Audio](docs/demo04.png)
+
+### Clone Voice Studio — Record Your Voice (10s minimum)
+
+![Clone Studio Recording](docs/demo05_clone.png)
+
+### Clone Voice Studio — Voice Embedding Extraction in Progress
+
+![Clone Studio Processing](docs/demo06_clone.png)
+
+### Clone Voice Studio — Cloning Complete, Preview Ready
+
+![Clone Studio Complete](docs/demo07_clone.png)
+
+### Narration Playing in Cloned Voice
+
+![Narration with Cloned Voice](docs/demo08_clone.png)
+
 ## Models
 
 | Model | Role | Size |
@@ -58,6 +94,32 @@ The stock narration model and LFM Q&A model are preloaded at startup for fast re
 - **TTS Backends:** Qwen3-TTS Base (cloned voice) + CustomVoice 0.6B (stock fallback)
 - **Q&A Backend:** LFM2.5-Audio for direct audio-in/audio-out answers with lower interaction latency
 
+## System Requirements
+
+| GPU | VRAM | Status | Notes |
+|---|---|---|---|
+| Nvidia A10G (24 GB) | 24 GB | ✅ Recommended | All three models load comfortably; narration + Q&A run without memory pressure |
+| Nvidia T4 (16 GB) | 16 GB | ⚠️ Functional | Works but is tight — voice cloning model may OOM if loaded concurrently with LFM; restart may be needed between heavy operations |
+| CPU only | — | ❌ Not viable | LFM2.5-Audio and Qwen3-TTS inference is too slow for real-time use |
+
+**Hugging Face Spaces:**
+- **A10G Small** — confirmed working, recommended for the hackathon demo
+- **T4 Small** — runs with limitations; recommend disabling concurrent model loading
+
+![HuggingFace Space Hardware Options](docs/hf_spec.png)
+
+**Memory breakdown (approximate):**
+
+| Model | VRAM (bfloat16) |
+|---|---|
+| LFM2.5-Audio-1.5B | ~3 GB |
+| Qwen3-TTS-0.6B-CustomVoice | ~1.2 GB |
+| Qwen3-TTS-1.7B-Base (cloning) | ~3.4 GB |
+| KV cache + activations at inference | ~1–2 GB |
+| **Total (all models loaded)** | **~8–9 GB** |
+
+The 1.7B cloning model is loaded on demand (not at startup), so idle VRAM usage is ~5–6 GB with only the narration and Q&A models preloaded.
+
 ## Features
 
 - 🎤 **Voice Cloning** — Record 15s, get a narrator that sounds like you
@@ -138,3 +200,105 @@ All inference runs on the Hugging Face Space GPU. Voice samples, story text, and
 
 Hackathon project. Stories are public domain.
 test push verification
+
+
+## Application Demo
+
+# MomsVoice — Demo Walkthrough
+
+Step-by-step guide through the app with screenshots.
+
+---
+
+## Step 1: Explore the Story Shelf
+
+![Explore Space](docs/demo01.png)
+
+Open the **Explore Space** tab to browse available stories displayed as warm bookshelf cards. Each card shows the cover art, title, author, and a short excerpt. Click **"Tap to Play"** on any card to open it in My Library, or click **"More Info"** for the full story description.
+
+The featured story highlights the current pick. All 10 stories are public domain classics sourced from Project Gutenberg.
+
+---
+
+## Step 2: Open My Library and Start Narration
+
+![My Library — Now Playing](docs/demo02.png)
+
+Switch to the **My Library** tab. Click any story card to load it into the **Now Playing** panel on the right. The panel shows:
+
+- Cover art and title
+- Active narrator label (stock Vivian voice or your cloned voice)
+- **Pause** / **Resume Story** buttons
+- Story text scrolling in sync with narration
+
+Narration starts immediately, playing one paragraph at a time using the TTS model. The player highlights the current paragraph as audio streams.
+
+---
+
+## Step 3: Ask a Question About the Story
+
+![Voice Q&A Panel](docs/demo03.png)
+
+Scroll down in the Library panel to find the **Ask About the Story** section. Click **❓ Ask a Question** — narration pauses automatically and the microphone starts recording.
+
+Speak your question naturally (e.g. *"What did Puss in Boots do to help his master?"*). When you stop recording, the question is submitted automatically — no button press needed. You can also type a question in the text fallback field and press **Get Answer** manually.
+
+---
+
+## Step 4: Hear the Spoken Answer (LFM2.5-Audio)
+
+![LFM Answer Audio](docs/demo04.png)
+
+The recorded question waveform appears in the audio widget. Below it, the **LFM2.5-Audio** model generates a grounded answer in 1–2 sentences, based only on the current story context.
+
+The answer is delivered in two ways simultaneously:
+- **Answer text** shown inline (e.g. *"Puss in Boots, a poor man, bargained for boots and a bag, and Grimalkin, ailient rabbit, rescued him from a king's wrath."*)
+- **Answer Audio** waveform auto-plays the spoken response
+
+After the answer finishes, narration resumes from where it paused.
+
+---
+
+## Step 5: Open Clone Voice Studio and Record Your Voice
+
+![Clone Studio — Recording](docs/demo05_clone.png)
+
+Go to the **Clone Voice Studio** tab. Fill in:
+- **Voice Nickname** — a name for this profile (e.g. *"Mom"*, *"Grandpa Joe"*)
+- **Voice Gender Avatar** — Female or Male
+
+A story script is displayed to read aloud. Click the **Record** button and read the script naturally for at least 10 seconds. The waveform displays your voice in real time. Click **Stop** when done.
+
+---
+
+## Step 6: Analyze & Synthesize the Vocal Profile
+
+![Clone Studio — Processing](docs/demo06_clone.png)
+
+Click **Analyze & Synthesize Customized Vocal Profile**. The **Status Pipeline Visualizer** on the right tracks progress through extraction, de-noising, and pitch tuning stages.
+
+A progress bar shows synthesis percentage (e.g. *"Generating voice preview... 70.0%"*) with elapsed time. This step runs Qwen3-TTS-1.7B Base to extract the speaker embedding from your recording.
+
+---
+
+## Step 7: Voice Profile Ready
+
+![Clone Studio — Complete](docs/demo07_clone.png)
+
+When synthesis completes, the Status Pipeline Visualizer shows:
+- Your **avatar** and nickname with a **"Cloned successfully"** badge
+- *"Synthesized today using Qwen3-TTS voice cloning"*
+- A **preview audio player** — tap Play to hear a short sample in your cloned voice
+- **"Synced successfully! Bind Companion Voice to Inventory"** confirmation
+
+The profile is saved to disk and will persist across Space restarts.
+
+---
+
+## Step 8: Story Narration in Your Cloned Voice
+
+![Narration with Cloned Voice](docs/demo08_clone.png)
+
+Return to **My Library** and select a story. The Now Playing panel shows **Active Narrator: [your nickname]** — confirming the cloned voice is active.
+
+Narration plays in your recorded voice, paragraph by paragraph (*"Paragraph 1 / 32"*). The story text scrolls in the reader below the player. All TTS inference runs locally on the Space GPU — no audio leaves the server.