onnx-wakeword — Offline Wake Word & Keyword Spotting Inference Engine
中文文档
KWS · Keyword Spotting · Wake Word · Custom Wake Word · ONNX · ESP32 · Android · Home Assistant · Wyoming · Offline · Privacy-First · Open Source
100% offline · No audio upload · Model < 130KB · ESP32 / Android / Python / Web
onnx-wakeword is an open-source, fully offline inference engine for wake-word detection and keyword spotting (KWS)
The complete runtime path — audio preprocessing, Mel feature extraction, model execution, matched-head evaluation, and wake-word detection logic:
Audio → Mel features → Keyword TCN model → Matched classification/prototype head → Detection logic → Result
Designed for keyword models built on a causal temporal convolutional network (Causal TCN) with a matched classification or prototype-based head. Training pipeline fully self-developed.
- ONNX runtimes for Python, Web, and Android, plus an optimized INT8 TFLite runtime for ESP32-S3
- Runs on browser, desktop (Linux / Windows / macOS), Android, ESP32, and Home Assistant (Raspberry Pi uses the same Python path — expected to work, not yet hardware-verified)
- 100% local inference — no audio is ever uploaded, no API calls, no telemetry
- Demo models in
models/ (7 languages) let you test the full pipeline at zero cost
How to Get a Wake Word / KWS Model
The fastest path is training online at voicute.com:
- Enter one or more keywords — training data is generated with TTS, no recordings required (~30 min per keyword); you get a single-keyword or multi-keyword model
- (Optional) Upload a few real recordings — improves generalization to real speakers
- (Optional) One-click auto hard-negative mining — the trained model finds its own false triggers in a negative corpus and retrains: −89% to −99% false triggers, recall preserved
- Download
model.zip — load it offline on any platform above
Supported languages: Chinese, English, German, French, Japanese, Spanish, and Hindi — more languages coming. No API calls, no subscription after download; see voicute.com for licensing.
Quick Links
| Platform | Directory | Entry Point |
|---|
| Web | web/ | wakeword.js → VoicuteWakeWord.create() |
| Python | python/ — Linux / Windows / macOS / Raspberry Pi | pip install onnx-wakeword → WakeWordEngine() |
| Android | android/ | WakeWordEngine.java |
| ESP32 | esp32/ | ESP-IDF component |
| Home Assistant | wyoming/ | wyoming_voicute.py → Wyoming protocol |
Training & Deployment
onnx-wakeword is a two-part system: custom keyword models trained online, then a fully offline runtime.
- Train your own keyword — enter any wake word (Chinese, English, Japanese, French, German, Spanish, or Hindi), platform generates TTS training data and trains the Causal TCN model (~30 min). Download the result.
- Download the resulting
model.zip, load it on any supported platform — browser, desktop, Android, ESP32, Home Assistant.
Your trained model runs completely offline from this point on — no API calls, no monthly fees, no telemetry. Your audio never leaves your device during inference. For testing before you generate a custom keyword, run the demo models included in models/ (中文 / English / Deutsch / Français / Español / हिन्दी) using the same pipeline at zero cost.
Features
- Sub-130KB models — 25K parameters, fits ESP32 INT8 flash
- Multi-keyword — detect 2–10+ keywords with a single model
- Multi-language — Chinese, English, Japanese, French, German, Spanish, and Hindi
- 5-layer anti-false-trigger — consecutive frames, peak/background ratio, cooldown, burst detection, energy jump
- ZIP packaging — distribute model + config as a single file
- Home Assistant — native Wyoming protocol service, Docker image, and HA add-on
Performance
Tested on v9.3 models.
| Metric | Value |
|---|
| ONNX size | ~128KB (FP32) / ~74KB (INT8) |
| Desktop inference | <5ms / frame |
| ESP32-S3 TFLite Invoke (included demo) | ~51ms / frame (live AFE demo) |
The isolated Invoke() baseline is about 39.5–40.2 ms; the published ~51 ms figure includes the live ESP-SR AFE pipeline and its scheduling/cache contention.
Recall
Held-out Azure TTS, 400 samples × varied speed/pitch/volume; sliding-window peak detection:
| Keyword | Language | Recall |
|---|
| 你好小娜 (optimized) | ZH | 100% |
| Hey Jarvis (optimized) | EN | 99.0% |
| Salut Nova (optimized) | FR | 100% |
| Apfelstrudel (optimized) | DE | 98.5% |
| みらい (optimized) | JA | 100% |
| 小娜 (optimized) | ZH | 98.3% |
| 豆包豆包 (optimized) | ZH | 100% |
| Hola Orion (optimized) | ES | 99.3% |
| हैलो तारक (optimized) | HI | 99.3% |
| Hey Robot | EN | 100% |
| サクラ (Sakura) | JA | 100% |
| Apfelstrudel (base) | DE | 99.4% |
| Monsieur Sadin | FR | 100% |
| Croissant | FR | 90.3% |
"(optimized)" rows are false-trigger optimized models (hard-negative mining retrain, see below); unmarked rows are base demo models.
Across 20 recently trained keywords (5 languages): recall 90.3%–100%, mean 98.8%, 20/20 ≥ 90%.
Real-voice recall reaches 90%+ with 5 user recordings added during training.
False trigger control
False-trigger optimization: before vs after (each keyword measured on its own held-out negative corpus — same-language Common Voice read speech + music + household noise/silence, held out from training; bare model, threshold 0.5, 40ms sliding window, counted per triggered file):
以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗
