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

#python #machinelearning #opensource #softwaredevelopment

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

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%}'))