README.md

metadata

title: 'WakeForge: GCP & Piper TTS Wake Word Dataset Creator'
emoji: 🔨
colorFrom: indigo
colorTo: purple
sdk: gradio
sdk_version: 6.19.0
app_file: app.py
pinned: false
license: cc-by-4.0

🔨 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:

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

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