Metadata-Version: 2.4
Name: wakeforge
Version: 0.4.1a3
Summary: Full training and research suite for wake words — MFCC to HuBERT, all exported to ONNX
Author-email: JarbasAi <jarbasai@mailfence.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/TigreGotico/ww_trainer
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch
Requires-Dist: torchaudio
Requires-Dist: onnx>=1.17
Requires-Dist: onnxruntime>=1.20
Requires-Dist: numpy
Requires-Dist: soundfile
Requires-Dist: click
Requires-Dist: tqdm
Requires-Dist: scikit-learn
Requires-Dist: matplotlib
Requires-Dist: librosa
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: onnxscript; extra == "dev"
Requires-Dist: markovonnx; extra == "dev"
Requires-Dist: umap-learn; extra == "dev"
Requires-Dist: optuna; extra == "dev"
Requires-Dist: voiceclonnx; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: onnxscript; extra == "test"
Requires-Dist: markovonnx; extra == "test"
Requires-Dist: umap-learn; extra == "test"
Requires-Dist: optuna; extra == "test"
Requires-Dist: voiceclonnx; extra == "test"
Provides-Extra: torchcodec
Requires-Dist: torchcodec; extra == "torchcodec"
Provides-Extra: mlflow
Requires-Dist: mlflow; extra == "mlflow"
Provides-Extra: sweep
Requires-Dist: optuna; extra == "sweep"
Provides-Extra: ocsvm
Requires-Dist: scikit-learn>=1.3; extra == "ocsvm"
Provides-Extra: transformers
Requires-Dist: transformers; extra == "transformers"
Provides-Extra: markov
Requires-Dist: markovonnx; extra == "markov"
Provides-Extra: vc
Requires-Dist: voiceclonnx; extra == "vc"
Provides-Extra: vc-onnx
Requires-Dist: voiceclonnx; extra == "vc-onnx"
Provides-Extra: datagen
Requires-Dist: datasets; extra == "datagen"
Requires-Dist: ovos-plugin-manager; extra == "datagen"
Requires-Dist: ovos-tts-plugin-edge-tts; extra == "datagen"
Requires-Dist: vadonnx>=0.1.0; extra == "datagen"
Provides-Extra: mic
Requires-Dist: sounddevice; extra == "mic"
Provides-Extra: viz
Requires-Dist: umap-learn; extra == "viz"
Provides-Extra: notebooks
Requires-Dist: jupyter; extra == "notebooks"
Requires-Dist: nbconvert; extra == "notebooks"
Requires-Dist: ipykernel; extra == "notebooks"
Requires-Dist: datasets; extra == "notebooks"
Requires-Dist: ovos-plugin-manager; extra == "notebooks"
Requires-Dist: ovos-tts-plugin-edge-tts; extra == "notebooks"
Requires-Dist: vadonnx>=0.1.0; extra == "notebooks"
Dynamic: license-file

# Wake Word Trainer

A research-grade training suite for **wake-word detection** — the always-on
keyword spotter that wakes "Hey Siri", "OK Google", or your own custom phrase.
Train, evaluate, and ship lightweight on-device detectors that run anywhere
from an ESP32 to a GPU server. Every component exports to ONNX; production
inference requires only `onnxruntime` and `numpy` — no PyTorch at runtime.

## What is a wake word?

A short phrase ("hey jarvis", "computer", "alexa") that a device listens for
continuously. When detected, downstream STT/NLU runs. A useful detector must
run on tiny hardware (sub-100 KB, <10 % CPU, no internet), tolerate noise and
distance, almost never false-fire (< 1 FA / hour), and trigger reliably when
spoken (> 90 % recall at that operating point). ww-trainer is the toolchain
that builds such a detector from a single phrase — synthesise data, train,
evaluate, export, deploy.

## Who is this for?

| You are… | Start here |
|---|---|
| **Hobbyist** waking a Pi with your own phrase | [`docs/getting_started/quickstart.md`](docs/getting_started/quickstart.md) — ONNX in 5 minutes |
| **Embedded engineer** shipping to ESP32 / MCU | [`docs/guides/embedded.md`](docs/guides/embedded.md) |
| **Voice-assistant integrator** (OVOS, Rhasspy, …) | [`docs/guides/inference.md`](docs/guides/inference.md) |
| **ML researcher** comparing architectures / losses | [`docs/guides/search.md`](docs/guides/search.md), [`docs/reference/losses.md`](docs/reference/losses.md), [`docs/research/rppl.md`](docs/research/rppl.md) |
| **New to ML** entirely | [`docs/quickstart-kaggle.md`](docs/quickstart-kaggle.md) — step-by-step guide; runs free on Kaggle / Colab |

## Highlights

- **Single-string-to-ONNX** quickstart — `train_from_wakeword("hey jarvis", out)` produces a deployable model.
- **11 built-in featurizers (+ enrichment wrappers) × 15 classifier heads × 15 losses** — a real research surface.
- **Genetic + Bayesian HP search** with island-model parallelism, adaptive mutation, two-stage refinement.
- **Synthetic datagen** — TTS + pure-ONNX voice conversion ([voiceclonnx](https://github.com/TigreGotico/voiceclonnx)) to bootstrap a dataset from zero recordings.
- **Hard-negative mining** and **infinite training** for industrial-scale negative pools.
- **ONNX-first**: featurizer and head export cleanly; no CUDA-only kernels.
- **Hardware tiers** from `esp32_nano` (sub-1 KB int8) to `hubert_medium`.

### Honest trade-offs

- CPU training works for small tiers; a mid-range GPU is the best UX for larger ones.
- Synthetic data is great for smoke-testing — production still needs real far-field recordings.
- ONNX-export is mandatory; non-traceable components (custom CUDA kernels, dynamic control flow) are out of scope. See [`docs/internals/known_issues.md`](docs/internals/known_issues.md).
- SSL featurizers (HuBERT, Wav2Vec2-BERT) are used as pre-exported ONNX and held frozen during downstream training — guarantees train/inference parity but limits adaptation.

## Install

```bash
# Published package (import name stays ww_trainer):
pip install --pre "wakeforge[datagen,torchcodec]"
```

For development, clone the repo and install it editable instead:

```bash
# Core library + tests
uv pip install -e ".[dev]"

# Quickstart / datagen needs TTS plugins + HF datasets + an audio codec:
uv pip install -e ".[dev,datagen,torchcodec]"
```

Optional extras (`sweep`, `transformers`, `mlflow`, `datagen`, `vc`, `mic`,
`viz`, `markov`, `ocsvm`, `torchcodec`) — see
[`docs/faq.md`](docs/faq.md#2-install).

A default quickstart run needs **≈ 6–8 GB disk** and **~5 GB download**
(or ~1.5 GB with `--no-augmentation-data`). Voice cloning via `--vc-refs`
adds the per-engine ONNX weights downloaded on first use from the
HuggingFace Hub (size varies by `voiceclonnx` engine). Full per-dataset
budget: [`docs/getting_started/requirements.md`](docs/getting_started/requirements.md).
## 60-second quickstart

```bash
ww_trainer-quickstart --wake-word "hey jarvis" --output-dir ./hey_jarvis
```

Or in Python:

```python
from ww_trainer.quickstart import train_from_wakeword
result = train_from_wakeword("hey jarvis", "./hey_jarvis",
                             tier="small", epochs=50)
print(result.best_onnx_path, result.metrics)
```

Output: `best_f1_featurizer.onnx` + `best_f1.onnx` under
`./hey_jarvis/model/`. Load both with `OnnxWakeWordInferencer` —
[`docs/guides/inference.md`](docs/guides/inference.md).

## Documentation

Everything lives in [`docs/`](docs/index.md). Start with:

- [docs/learning_path.md](docs/learning_path.md) — **zero-to-hero curriculum** with literature anchors
- [docs/faq.md](docs/faq.md) — topic-ordered Q&A in 15 sections
- [docs/index.md](docs/index.md) — full documentation index
- [examples/README.md](examples/README.md) — 43 runnable examples

## Contributing

Issues and pull requests welcome on the `dev` branch. Tests live in `test/`;
run with `uv run pytest`.

## Citation

```bibtex
@software{ww_trainer,
  title  = {ww-trainer: a research suite for on-device wake-word detection},
  author = {TigreGotico contributors},
  year   = {2026},
  url    = {https://github.com/TigreGotico/ww-trainer},
  note   = {Funded by NGI0 Commons Fund / NLnet, grant 101135429}
}
```

---

## Credits

Developed by [TigreGótico](https://tigregotico.pt) for
[OpenVoiceOS](https://openvoiceos.org).

[![NGI0 Commons Fund](./ngi.png)](https://nlnet.nl/project/OpenVoiceOS)

This project was funded through the [NGI0 Commons Fund](https://nlnet.nl/commonsfund),
a fund established by [NLnet](https://nlnet.nl) with financial support from the
European Commission's [Next Generation Internet](https://ngi.eu) programme, under
the aegis of [DG Communications Networks, Content and Technology](https://commission.europa.eu/about-european-commission/departments-and-executive-agencies/communications-networks-content-and-technology_en)
under grant agreement No [101135429](https://cordis.europa.eu/project/id/101135429).

---

## License

Apache 2.0
