Spaces:
Runtime error
Runtime error
| # ReadBookMom | |
| **A parent records their voice. A bedtime story plays in that voice. The child can ask questions and hear answers — all in mom or dad's voice.** | |
| Built for the Hugging Face Hackathon. Runs entirely on local models inside a Gradio app on Hugging Face Spaces — no external APIs, no data leaves the server. | |
| ## Demo | |
| ``` | |
| 🎤 Record 15s of your voice → 📖 Pick a story → ▶️ Story plays in your voice | |
| ↓ | |
| ❓ Child taps Ask → Story pauses | |
| ↓ | |
| Child asks a question → Hears answer in your voice | |
| ↓ | |
| ▶️ Story resumes | |
| ``` | |
| ## How It Works | |
| | Step | What Happens | Model | | |
| |---|---|---| | |
| | **Clone** | Parent records or uploads 15–30s of audio. Speaker embedding is extracted and cached server-side. | Qwen3-TTS-1.7B (`voice_clone.py`) | | |
| | **Listen** | Story plays in the cloned voice as interruptible sentence chunks. Falls back to Supertonic stock voice if no clone. | Qwen3-TTS-1.7B / Supertonic (`tts.py`) | | |
| | **Ask** | Child taps Ask, narration pauses, child types or speaks a question. | Whisper-small (ASR, on-demand, `inference.py`) | | |
| | **Answer** | A short grounded answer is generated from the story context and spoken in the cloned voice. | Qwen2.5-3B-Instruct + Qwen3-TTS-1.7B (`inference.py` + `tts.py`) | | |
| | **Resume** | Story continues from where it left off. | Cached chunks | | |
| ## Models | |
| | Model | Role | Size | | |
| |---|---|---| | |
| | [Qwen3-TTS-1.7B-Base](https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-Base) | Zero-shot voice cloning + TTS | 1.7B params | | |
| | [Supertonic TTS](https://huggingface.co/niclas-pham/supertonic-3) | Fast stock-voice TTS fallback | ONNX model | | |
| | [Qwen2.5-3B-Instruct](https://huggingface.co/Qwen/Qwen2.5-3B-Instruct) | Story Q&A | 3B params (4-bit on T4) | | |
| | [Whisper-small](https://huggingface.co/openai/whisper-small) | Child speech-to-text | 244M params (loaded on demand) | | |
| ## Tech Stack | |
| - **UI:** Gradio 5.x + gr.Server (custom CSS/JS for Google Stitch-inspired design) | |
| - **Runtime:** Single `app.py` process on HF Spaces (T4 or A10G GPU) | |
| - **Stories:** 10 public domain `.txt` files (downloaded and cleaned from Project Gutenberg) | |
| - **Storage:** In-memory session cache (no database) | |
| ## Quick Start (Local Dev) | |
| ```bash | |
| git clone https://github.com/MomsVoiceAI/HuggingFace_Hack.git | |
| cd HuggingFace_Hack | |
| pip install -r requirements.txt | |
| python app.py | |
| # → http://localhost:7860 | |
| ``` | |
| ## Project Structure | |
| ``` | |
| ├── app.py # Main Gradio app (UI + wiring) | |
| ├── voice_clone.py # Qwen3-TTS voice cloning + profile cache | |
| ├── tts.py # Unified TTS interface (Qwen3 or Supertonic) | |
| ├── inference.py # ASR (Whisper) + Q&A (Qwen2.5-3B-Instruct) | |
| ├── requirements.txt # Python deps | |
| ├── stories/ # 10 cleaned public domain story texts (TTS-ready) | |
| ├── story_downloader/ # Story acquisition & cleaning pipeline | |
| │ ├── gutenberg_downloader.py # Reusable Project Gutenberg downloader/parser | |
| │ ├── download_stories.py # Downloads 10 children's stories | |
| │ └── clean_stories.py # Strips Gutenberg boilerplate for TTS | |
| ├── static/ # Custom CSS/JS for Stitch-style UI | |
| ├── assets/covers/ # Story cover images | |
| ├── mission.md # Product vision | |
| ├── sprint.md # 2-day hackathon sprint plan | |
| ├── tech_stack.md # Technical architecture | |
| └── future_mobile_app_considerations.md # Mobile deployment guidance | |
| ``` | |
| ## Stories Included | |
| | Story | Words | Source | | |
| |---|---|---| | |
| | The Tale of Peter Rabbit | 948 | Beatrix Potter | | |
| | The Tale of Benjamin Bunny | 1,118 | Beatrix Potter | | |
| | The Tale of Jemima Puddle-Duck | 1,245 | Beatrix Potter | | |
| | The Tale of Tom Kitten | 691 | Beatrix Potter | | |
| | The History of Tom Thumb | 2,912 | Traditional | | |
| | The Story of the Three Little Pigs | 956 | Traditional | | |
| | The Little Red Hen | 1,295 | Traditional | | |
| | The Little Gingerbread Man | 1,823 | Traditional | | |
| | The Sleeping Beauty | 1,783 | Traditional | | |
| | The Adventures of Puss in Boots | 503 | Traditional (verse) | | |
| All stories are public domain from [Project Gutenberg](https://www.gutenberg.org/). Each file uses a simple format: title on line 1, blank line, then story prose — ready for direct TTS consumption. | |
| ## Key Design Decisions | |
| - **All local inference** — voice, Q&A, and ASR run on the Space GPU. No external APIs. | |
| - **Interruptible chunked streaming** — paragraphs synthesized and played one at a time for fast start and clean pause/resume. | |
| - **Pre-generated Q&A** — anticipated questions are generated in the background during narration for sub-1s response on cache hits. | |
| - **Button-based interruption** — tap Ask to pause. No always-listening mic (privacy + complexity). | |
| - **Privacy-first** — no audio leaves the server, no user accounts, no database. | |
| ## Privacy | |
| All inference runs on the Hugging Face Space GPU. Voice samples, story text, and generated audio stay on the server runtime and are not persisted after the session ends. No external APIs are called. | |
| ## License | |
| Hackathon project. Stories are public domain. | |