Hugging Face's logo

Spaces:
sshtel
/
Huggingface_Hack
Paused

App Files Community
sshtel commited on
Commit
353c4cc
·
1 Parent(s): 8ddfae2

commit README for hf space

Browse files
Files changed (2) hide show
  1. README.md +10 -103
  2. SPEC.md +103 -0
README.md CHANGED
@@ -1,103 +1,10 @@
1
- # ReadBookMom
2
-
3
- **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.**
4
-
5
- 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.
6
-
7
- ## Demo
8
-
9
- ```
10
- 🎤 Record 15s of your voice → 📖 Pick a story → ▶️ Story plays in your voice
11
- ↓
12
- ❓ Child taps Ask → Story pauses
13
- ↓
14
- Child asks a question → Hears answer in your voice
15
- ↓
16
- ▶️ Story resumes
17
- ```
18
-
19
- ## How It Works
20
-
21
- | Step | What Happens | Model |
22
- |---|---|---|
23
- | **Clone** | Parent records or uploads 15–30s of audio. Voice representation is computed and cached. | QWEN-TTS-0.6B |
24
- | **Listen** | Story plays in the cloned voice as interruptible paragraph chunks. | QWEN-TTS-0.6B |
25
- | **Ask** | Child taps Ask, narration pauses, child types or speaks a question. | Whisper-small (ASR, on-demand) |
26
- | **Answer** | A short grounded answer is generated from the story context and spoken in the cloned voice. | Qwen2.5-3B-Instruct + QWEN-TTS-0.6B |
27
- | **Resume** | Story continues from where it left off. | Cached chunks |
28
-
29
- ## Models
30
-
31
- | Model | Role | Size |
32
- |---|---|---|
33
- | [QWEN-TTS-0.6B](https://huggingface.co/Qwen/Qwen-TTS-0.6B) | Voice cloning + TTS | 0.6B params |
34
- | [Qwen2.5-3B-Instruct](https://huggingface.co/Qwen/Qwen2.5-3B-Instruct) | Story Q&A | 3B params (4-bit on T4) |
35
- | [Whisper-small](https://huggingface.co/openai/whisper-small) | Child speech-to-text | 244M params (loaded on demand) |
36
-
37
- ## Tech Stack
38
-
39
- - **UI:** Gradio 5.x + gr.Server (custom CSS/JS for Google Stitch-inspired design)
40
- - **Runtime:** Single `app.py` process on HF Spaces (T4 or A10G GPU)
41
- - **Stories:** 10 public domain `.txt` files (downloaded and cleaned from Project Gutenberg)
42
- - **Storage:** In-memory session cache (no database)
43
-
44
- ## Quick Start (Local Dev)
45
-
46
- ```bash
47
- git clone https://github.com/MomsVoiceAI/HuggingFace_Hack.git
48
- cd HuggingFace_Hack
49
- pip install gradio transformers torch accelerate bitsandbytes soundfile numpy
50
- python app.py
51
- # → http://localhost:7860
52
- ```
53
-
54
- ## Project Structure
55
-
56
- ```
57
- ├── app.py # Main Gradio app
58
- ├── requirements.txt # Python deps
59
- ├── stories/ # 10 cleaned public domain story texts (TTS-ready)
60
- ├── story_downloader/ # Story acquisition & cleaning pipeline
61
- │ ├── gutenberg_downloader.py # Reusable Project Gutenberg downloader/parser
62
- │ ├── download_stories.py # Downloads 10 children's stories
63
- │ └── clean_stories.py # Strips Gutenberg boilerplate for TTS
64
- ├── static/ # Custom CSS/JS for Stitch-style UI
65
- ├── assets/covers/ # Story cover images
66
- ├── mission.md # Product vision
67
- ├── sprint.md # 2-day hackathon sprint plan
68
- ├── tech_stack.md # Technical architecture
69
- └── future_mobile_app_considerations.md # Mobile deployment guidance
70
- ```
71
-
72
- ## Stories Included
73
-
74
- | Story | Words | Source |
75
- |---|---|---|
76
- | The Tale of Peter Rabbit | 948 | Beatrix Potter |
77
- | The Tale of Benjamin Bunny | 1,118 | Beatrix Potter |
78
- | The Tale of Jemima Puddle-Duck | 1,245 | Beatrix Potter |
79
- | The Tale of Tom Kitten | 691 | Beatrix Potter |
80
- | The History of Tom Thumb | 2,912 | Traditional |
81
- | The Story of the Three Little Pigs | 956 | Traditional |
82
- | The Little Red Hen | 1,295 | Traditional |
83
- | The Little Gingerbread Man | 1,823 | Traditional |
84
- | The Sleeping Beauty | 1,783 | Traditional |
85
- | The Adventures of Puss in Boots | 503 | Traditional (verse) |
86
-
87
- 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.
88
-
89
- ## Key Design Decisions
90
-
91
- - **All local inference** — voice, Q&A, and ASR run on the Space GPU. No external APIs.
92
- - **Interruptible chunked streaming** — paragraphs synthesized and played one at a time for fast start and clean pause/resume.
93
- - **Pre-generated Q&A** — anticipated questions are generated in the background during narration for sub-1s response on cache hits.
94
- - **Button-based interruption** — tap Ask to pause. No always-listening mic (privacy + complexity).
95
- - **Privacy-first** — no audio leaves the server, no user accounts, no database.
96
-
97
- ## Privacy
98
-
99
- 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.
100
-
101
- ## License
102
-
103
- Hackathon project. Stories are public domain.
 
1
+ ---
2
+ title: ReadBookMom
3
+ emoji: 📖
4
+ colorFrom: yellow
5
+ colorTo: green
6
+ sdk: gradio
7
+ sdk_version: 5.33.0
8
+ app_file: app.py
9
+ pinned: false
10
+ ---
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
SPEC.md ADDED
@@ -0,0 +1,103 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # ReadBookMom
2
+
3
+ **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.**
4
+
5
+ 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.
6
+
7
+ ## Demo
8
+
9
+ ```
10
+ 🎤 Record 15s of your voice → 📖 Pick a story → ▶️ Story plays in your voice
11
+ ↓
12
+ ❓ Child taps Ask → Story pauses
13
+ ↓
14
+ Child asks a question → Hears answer in your voice
15
+ ↓
16
+ ▶️ Story resumes
17
+ ```
18
+
19
+ ## How It Works
20
+
21
+ | Step | What Happens | Model |
22
+ |---|---|---|
23
+ | **Clone** | Parent records or uploads 15–30s of audio. Voice representation is computed and cached. | QWEN-TTS-0.6B |
24
+ | **Listen** | Story plays in the cloned voice as interruptible paragraph chunks. | QWEN-TTS-0.6B |
25
+ | **Ask** | Child taps Ask, narration pauses, child types or speaks a question. | Whisper-small (ASR, on-demand) |
26
+ | **Answer** | A short grounded answer is generated from the story context and spoken in the cloned voice. | Qwen2.5-3B-Instruct + QWEN-TTS-0.6B |
27
+ | **Resume** | Story continues from where it left off. | Cached chunks |
28
+
29
+ ## Models
30
+
31
+ | Model | Role | Size |
32
+ |---|---|---|
33
+ | [QWEN-TTS-0.6B](https://huggingface.co/Qwen/Qwen-TTS-0.6B) | Voice cloning + TTS | 0.6B params |
34
+ | [Qwen2.5-3B-Instruct](https://huggingface.co/Qwen/Qwen2.5-3B-Instruct) | Story Q&A | 3B params (4-bit on T4) |
35
+ | [Whisper-small](https://huggingface.co/openai/whisper-small) | Child speech-to-text | 244M params (loaded on demand) |
36
+
37
+ ## Tech Stack
38
+
39
+ - **UI:** Gradio 5.x + gr.Server (custom CSS/JS for Google Stitch-inspired design)
40
+ - **Runtime:** Single `app.py` process on HF Spaces (T4 or A10G GPU)
41
+ - **Stories:** 10 public domain `.txt` files (downloaded and cleaned from Project Gutenberg)
42
+ - **Storage:** In-memory session cache (no database)
43
+
44
+ ## Quick Start (Local Dev)
45
+
46
+ ```bash
47
+ git clone https://github.com/MomsVoiceAI/HuggingFace_Hack.git
48
+ cd HuggingFace_Hack
49
+ pip install gradio transformers torch accelerate bitsandbytes soundfile numpy
50
+ python app.py
51
+ # → http://localhost:7860
52
+ ```
53
+
54
+ ## Project Structure
55
+
56
+ ```
57
+ ├── app.py # Main Gradio app
58
+ ├── requirements.txt # Python deps
59
+ ├── stories/ # 10 cleaned public domain story texts (TTS-ready)
60
+ ├── story_downloader/ # Story acquisition & cleaning pipeline
61
+ │ ├── gutenberg_downloader.py # Reusable Project Gutenberg downloader/parser
62
+ │ ├── download_stories.py # Downloads 10 children's stories
63
+ │ └── clean_stories.py # Strips Gutenberg boilerplate for TTS
64
+ ├── static/ # Custom CSS/JS for Stitch-style UI
65
+ ├── assets/covers/ # Story cover images
66
+ ├── mission.md # Product vision
67
+ ├── sprint.md # 2-day hackathon sprint plan
68
+ ├── tech_stack.md # Technical architecture
69
+ └── future_mobile_app_considerations.md # Mobile deployment guidance
70
+ ```
71
+
72
+ ## Stories Included
73
+
74
+ | Story | Words | Source |
75
+ |---|---|---|
76
+ | The Tale of Peter Rabbit | 948 | Beatrix Potter |
77
+ | The Tale of Benjamin Bunny | 1,118 | Beatrix Potter |
78
+ | The Tale of Jemima Puddle-Duck | 1,245 | Beatrix Potter |
79
+ | The Tale of Tom Kitten | 691 | Beatrix Potter |
80
+ | The History of Tom Thumb | 2,912 | Traditional |
81
+ | The Story of the Three Little Pigs | 956 | Traditional |
82
+ | The Little Red Hen | 1,295 | Traditional |
83
+ | The Little Gingerbread Man | 1,823 | Traditional |
84
+ | The Sleeping Beauty | 1,783 | Traditional |
85
+ | The Adventures of Puss in Boots | 503 | Traditional (verse) |
86
+
87
+ 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.
88
+
89
+ ## Key Design Decisions
90
+
91
+ - **All local inference** — voice, Q&A, and ASR run on the Space GPU. No external APIs.
92
+ - **Interruptible chunked streaming** — paragraphs synthesized and played one at a time for fast start and clean pause/resume.
93
+ - **Pre-generated Q&A** — anticipated questions are generated in the background during narration for sub-1s response on cache hits.
94
+ - **Button-based interruption** — tap Ask to pause. No always-listening mic (privacy + complexity).
95
+ - **Privacy-first** — no audio leaves the server, no user accounts, no database.
96
+
97
+ ## Privacy
98
+
99
+ 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.
100
+
101
+ ## License
102
+
103
+ Hackathon project. Stories are public domain.