Upload folder using huggingface_hub

.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+env/
+output/
+hf_dataset/
+*.zip
+*.wav
+piper_voices/
+.DS_Store
+.gradio/

README.md

@@ -1,13 +1,112 @@
 ---
-title: Wakeforge
-emoji: 📈
-colorFrom: gray
-colorTo: red
+title: "WakeForge: GCP & Piper TTS Wake Word Dataset Creator"
+emoji: 🔨
+colorFrom: indigo
+colorTo: purple
 sdk: gradio
-sdk_version: 6.19.0
-python_version: '3.13'
+sdk_version: 4.44.0
 app_file: app.py
 pinned: false
+license: cc-by-4.0
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🔨 WakeForge
+### GCP & Piper TTS Wake Word Dataset Creator
+
+A Hugging Face Space that generates a synthetic **keyword-spotting / wake-word**
+dataset ready for **Hugging Face Datasets** and **Edge Impulse**.
+
+It uses **Google Cloud Text-to-Speech** when you provide an API key, and
+**automatically falls back to free, local Piper TTS** when you don't — so it
+always works, with or without a paid service.
+
+## Features
+
+- 🔀 **Automatic backend selection** — Google Cloud TTS (API key) with a free
+  Piper TTS fallback.
+- 🧱 **Three keyword-spotting classes** — `hey_android`, `unknown`,
+  `background_noise` (fully configurable phrases and labels).
+- 🎛️ **Local augmentation** — gain, time shift, additive noise, echo, plus
+  synthetic background-noise generation.
+- 📦 **Edge Impulse-ready** — `label.<id>.wav` filenames and `training` /
+  `testing` folders.
+- ⬆️ **One-click publishing** — push to a Hugging Face dataset repo and/or
+  **upload directly to your Edge Impulse project** with your own API key.
+
+## Using the Space
+
+1. Set the phrases, labels and dataset size.
+2. *(Optional)* Paste a **Google Cloud TTS API key**. Leave blank to use free
+   Piper TTS.
+3. *(Optional)* Tick **Push to Hugging Face** and provide a repo id + write token.
+4. *(Optional)* Tick **Upload to Edge Impulse** and paste your project API key
+   (Edge Impulse → your project → **Dashboard → Keys**).
+5. Click **Generate dataset** and download the resulting zip.
+
+### Space secrets (optional)
+
+Instead of typing keys into the UI, set them as Space secrets:
+
+| Secret | Purpose |
+|---|---|
+| `GCP_TTS_API_KEY` | Google Cloud TTS API key |
+| `HF_TOKEN` | Hugging Face write token for pushing datasets |
+| `EDGE_IMPULSE_API_KEY` | Edge Impulse project API key |
+
+## Command line
+
+The same pipeline runs locally without Gradio:
+
+```bash
+pip install -r requirements.txt
+
+# Free Piper TTS, prepare an HF folder locally
+python generate.py --out output --hf-out hf_dataset
+
+# Google Cloud TTS + push to HF + upload to Edge Impulse
+python generate.py \
+  --gcp-api-key "$GCP_TTS_API_KEY" \
+  --push-hf-repo "username/hey-android" --hf-token "$HF_TOKEN" \
+  --edge-impulse-api-key "$EDGE_IMPULSE_API_KEY"
+```
+
+## Output layout
+
+```text
+output/
+  edge_impulse_upload/
+    training/  hey_android.<id>.wav ...
+    testing/   hey_android.<id>.wav ...
+  by_label/
+    hey_android/ ...
+  metadata.csv
+  selected_voices.csv
+  dataset_summary.json
+
+hf_dataset/
+  audio/train/ ...
+  audio/test/ ...
+  README.md            # dataset card
+  hf_metadata.csv
+  metadata.csv
+```
+
+## Getting the keys
+
+- **Google Cloud TTS API key** — [Google Cloud Console](https://console.cloud.google.com/):
+  enable *Cloud Text-to-Speech API*, then **APIs & Services → Credentials →
+  Create credentials → API key**.
+- **Edge Impulse API key** — your project → **Dashboard → Keys**.
+- **Hugging Face token** — [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens)
+  (needs *write* access).
+
+## Notes & limitations
+
+Synthetic TTS audio is great for **bootstrapping** a wake-word model but is not
+a production benchmark. Before deploying, add real recordings from the target
+device and expected acoustic environments.
+
+## License
+
+CC BY 4.0. Verify that your use of generated synthetic speech complies with the
+terms of the voice models (Google Cloud TTS / Piper voices) you use.

packages.txt

@@ -0,0 +1 @@
+espeak-ng

requirements.txt

@@ -0,0 +1,5 @@
+gradio>=4.44.0
+numpy>=1.24
+requests>=2.31
+huggingface_hub>=0.24
+piper-tts>=1.2.0