SPEC.md

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	Zero-shot voice cloning + TTS	1.7B params
Supertonic TTS	Fast stock-voice TTS fallback	ONNX model
Qwen2.5-3B-Instruct	Story Q&A	3B params (4-bit on T4)
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)

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. 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.