I built a portable keyword spotting engine — started with Chinese, now supporting English

I built a portable keyword spotting engine — started with Chinese, now supporting English

I wanted offline voice commands for a few Python projects. Nothing fancy — just a single file I could drop in and run.

What it does

• One Python file — wakeword_engine.py, copy it into your project
• Small model — ~135KB for 3 keywords, <5ms inference
• Multi-keyword — one model detects 2-10 keywords in a single pass
• Fully offline — no cloud, no internet, ONNX Runtime under the hood
• 5-layer noise filtering — consecutive frame check, background suppression, cooldown, burst lock, energy jump detection

Why Chinese first

Most KWS engines optimize for English. I started with Chinese instead. It’s a tonal language with lots of single-syllable words — harder for keyword spotting. No pre-trained English embeddings to lean on either.

The upside: the architecture (causal TCN on mel spectrograms) doesn’t depend on any language-specific pretrained model. Once Chinese worked, English was almost free. Just needed the training data.

Usage

pip install onnxruntime numpy pyaudio

Enter fullscreen mode Exit fullscreen mode

from wakeword_engine import WakeWordEngine

engine = WakeWordEngine()
engine.load('model_info.json', 'melspectrogram.onnx')
engine.set_L1(True)
engine.start(lambda word, prob, info: print(f'{word} {prob:.0%}'))

Enter fullscreen mode Exit fullscreen mode

What’s working now

Platform Status Python ✅ mature Web (ONNX Runtime Web) ✅ working Android (Java) ✅ working ESP32 🚧 early

Next

Wyoming protocol integration for Home Assistant.

Repo: github.com/voicute/onnx-wakeword — MIT license.