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

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