WeKws: wake-up word detection that fits on an always-on device

A problem defined by a power budget

WeKws is described as a Production First and Production Ready End-to-End Keyword Spotting Toolkit, and the goal statement in the README is unusually concrete about the constraints.

Small footprint keyword spotting, or specifically wake-up word detection, is a typical and important module in internet of things devices, and it provides a way for users to control those devices hands-free. A wake-up word detection system usually runs locally and persistently on the device, which the README says requires low consumptional power, fewer model parameters, low computational complexity, and detection of a predefined keyword in a streaming way, which means low latency.

That is a different problem from speech recognition. You are not transcribing anything. You are answering one question, continuously, as cheaply as possible, and answering it with a latency low enough that a person experiences it as instant. Every design decision follows from that, and the references the project lists point the same way: max-pooling loss training of LSTM networks for small-footprint keyword spotting, a depthwise separable convolutional network for keyword spotting on an embedded system, Hello Edge for keyword spotting on microcontrollers, and mining effective negative training samples.

The audience is therefore device engineers, not application developers. The people who need this are working on a speaker, a headset or a sensor hub where the whole model has to fit in a few hundred kilobytes of memory and run on a microcontroller or a low power SoC without waking the main processor.

Four scenarios, from one keyword to a voiceprint

The README lists the typical applications the toolkit intends to support, and they are ordered by how much they demand of the model.

A single wake-up word is the simplest case and the one most consumer hardware needs. Multiple wake-up words covers a device that responds to more than one phrase, which complicates the false accept problem because the model now has more chances to fire by accident. A customizable wake-up word means the phrase is not fixed, which is a training problem rather than only a deployment problem, since the user needs a way to train or fine-tune on their own phrase.

The last one, a personalized wake-up word, is described as a combination of wake-up word detection and voiceprint. That is the interesting case for a research project, because it turns a keyword spotting model into a speaker recognition model, and the reference list includes work on mining effective negative training samples, which is exactly the problem of using other people's voices as negatives.

The order matters as a roadmap. Each step adds capability but also adds the training data and the model size a device must carry, so the practical question for an adopter is which of the four the hardware can actually afford, not which of the four is nicest.

Installing: conda, torch and a pinned WeNet dependency

The installation instructions are explicit and assume Conda rather than a bare virtual environment, with a Python version pinned for the environment.

The repository is cloned first:

git clone https://github.com/wenet-e2e/wekws.git

Then a Conda environment is created and the audio tooling is installed into it:

conda create -n wekws python=3.10
conda activate wekws
conda install conda-forge::sox

The torch pair comes next, and the README recommends torch 2.5.1 with CUDA 12.4, pointing at the PyTorch documentation for other CUDA versions:

pip install torch torchaudio

And the rest of the Python packages are installed from the requirements file, with a note that pre-commit is set up to keep the code clean and tidy:

pip install -r requirements.txt
pre-commit install  # for clean and tidy code

Two entries in that requirements file deserve a second look. The last line is a direct git dependency pinned to a commit of the WeNet repository, which means the install is not reproducible from PyPI alone and needs network access to that repository. The rest of the list is a research toolchain: tensorboard and tensorboardX for training, matplotlib for plots, onnx and onnxruntime for export and inference, lmdb for the dataset store, scipy, tqdm, langid and pypinyin for language handling, and a pinned set of flake8 plugins. The linting set is pinned to old versions, which is a detail that matters when the environment is rebuilt on a modern Python.

Datasets and the models the project plans to publish

The dataset section is a plan rather than a finished list, and the README says so: the project plans to support a variety of open source wake-up word datasets, including but not limited to several named ones.

Those are Hey Snips, the French wake-up word dataset, Google Speech Command, the broad set of short spoken commands, Hi Miya, a Chinese wake-up word set, and Hi Xiaowen, another Chinese set. The list is a good signal about the intended scope, since it spans a European wake-up phrase, a general command vocabulary and two Mandarin wake-up phrases, and the toolkit is a WeNet project, so the Chinese data is first class rather than an afterthought.

The claim attached to the datasets is that all the well-trained models on these datasets will be made public available. That is the part of the design that matters most for an adopter, because training a keyword spotting model is the expensive step and the datasets alone do not get you a running device.

The examples directory shows the shape of the work, with directories for hey_snips, hi_xiaowen and speechcommand_v1, so each supported dataset has a matching example rather than one example per feature.

A C++ runtime and four deployment targets

The runtime section states that the project plans to support a variety of hardware and platforms, and the four listed are a web browser, x86, Android and Raspberry Pi.

Those four are chosen to bracket the deployment space. A browser target means the model can be demonstrated or tested without a device, which is also how a model gets a second pair of eyes on its behaviour. x86 is the workstation case. Android is the phone case, where the same wake-up word feature appears in every assistant. Raspberry Pi is the general single board computer case, and it sits close to the microcontroller end of the range the references describe.

The repository layout shows how the two halves are separated. There is a wekws/ directory for the Python side, a runtime/ directory for the deployment side, and the runtime directory carries the C++ conventions with a .clang-format file and a CPPLINT.cfg, while the Python side has a .flake8 configuration. There is a tools/ directory and a docs/ directory.

The split is the right architecture for this problem, because the two halves have different constraints. The training side wants PyTorch, datasets and notebooks. The deployment side wants a small static library with no Python runtime, and it is the half that has to fit the memory and latency budget the README opened with.

Where WeKws is the wrong tool

Three cases point elsewhere.

The first is anything that is not keyword spotting. The toolkit is built to answer one narrow question continuously. If the requirement is to dictate a sentence, to transcribe a meeting, or to follow a voice command with a vocabulary of hundreds of words, this is the wrong shape of system, because the model that fits on a microcontroller and the model that recognises arbitrary speech are not the same project.

The second is a team that wants a commercial voice assistant stack. WeKws is a research toolkit from the WeNet community, with a roadmap, a paper and a set of references, and it publishes trained models rather than shipping a supported product with a service level agreement.

The third is a deployment where the compute budget is not actually the constraint. On a modern server or a recent phone, a small CPU or NPU accelerator is available and the power argument disappears, and then the toolkit's trade, a deliberately narrow keyword model, stops being an advantage and becomes a limitation.

There is also a question to ask about the models. The plan is to publish well-trained models per dataset, and each of those datasets has its own licence and its own recording conditions, so a model that recognises a wake-up word in a quiet office is a different proposition from the same model in a noisy kitchen. The README does not describe an evaluation protocol, so the accuracy numbers a team needs will have to come from testing on its own audio.

Editorial conclusion

Adopt WeKws if you are building a device that has to listen for a wake-up word continuously, under a power or memory budget that rules out a general speech stack, and if you are prepared to work with the C++ runtime and the pinned WeNet dependency. Do not adopt it for command line dictation, for offline transcription, or for a product that needs a broad vocabulary recognition rather than a small fixed keyword set. Verify three things first: the model and runtime pair you intend to ship, since the toolkit is built from the published references on small footprint keyword spotting; the accuracy of the keyword models on your own acoustic conditions, since the datasets listed are read and English, Chinese, and general command sets, and none of them is your microphone in your room; and the licence of the models you download, because the trained models on the datasets are what the toolkit plans to make available and each dataset carries its own terms. The licence is Apache-2.0, the last push was on 2026-07-23, and the repository publishes no GitHub releases.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. wenet-e2e/wekws on GitHub