microWakeWord trains a wake word detector, if you can live with the tuning

A wake word for a phrase no pretrained model covers

Voice assistants can only be woken by the phrase their vendor shipped. microWakeWord exists for the case where you want your own phrase, and it is aimed squarely at low power devices. The library description calls it an open source wake word library for detecting custom wake words on low power devices, and the models it produces are suitable for using TensorFlow Lite for Microcontrollers, with the claim that they are suitable for real-world usage with low false accept and false reject rates.

The audience is embedded developers. The projects that need this are a smart speaker, a bedside monitor, an offline voice terminal, a home automation hub: anything with a microphone and a microcontroller where you want a custom trigger word and cannot call a cloud service to do the recognition.

What the library is not is a runtime wake word engine. It is a training framework, and the README says so plainly in its warning banner: microWakeWord is currently available as an early release, and training new models is intended for advanced users. Training a model that works well is still very difficult, as it typically requires experimentation with hyperparameters and sample generation settings. The project is asking for insights to be shared, which tells you the expected workflow is iterative and collaborative rather than a one shot pipeline.

The primary language is Python, the licence is Apache-2.0, and the package requires Python 3.10 or later.

Two stages: a feature preprocessor, then a streaming model

The detection process has two stages and the design is worth understanding before you train anything.

The first stage processes raw monochannel audio at a 16 kHz sample rate through the micro_speech preprocessor from the TFLite Micro examples. That preprocessor generates 40 features over 30 ms of audio, the window duration, and generates them every 10 ms, the stride duration, so the first 20 ms of each window overlaps the previous one. The README notes the process is similar to computing a Mel spectrogram but includes noise suppression and automatic gain control, which is what makes it viable on devices with limited processing power. The linked example is where the full processing details live.

The second stage is the neural network. The streaming model takes the newest slice of feature data as input and returns the probability that the wake word was said. If the model predicts the wake word consistently across multiple windows, the library reports that the word was said, which is a simple temporal smoothing rule that suppresses single window false positives.

The architecture is a neural network using MixConv mixed depthwise convolutions suitable for streaming. The inference cadence is every 30 ms, where the initial convolution layer strides over three 10 ms slices of audio. The streaming model and the training code are based on heavily modified open source code from Google Research's kws_streaming project, associated with the paper Streaming Keyword Spotting on Mobile Devices.

The practical consequence of a fixed, small feature front end is that the model never sees raw audio. It sees 40 numbers per 10 ms, which is why the library can run on a microcontroller at all, and also why the preprocessor's noise suppression and gain control become part of your accuracy problem.

Training: non-streaming first, streaming afterwards

The training process in the README is a list of techniques, and two of them matter more than the rest.

The first is how the best weights are chosen, and it is a two step process. The top priority is minimising a specific metric, for example false accepts per hour on ambient background noise. Only if that target is met does the search then maximise a different metric, for example accuracy. This ordering is a deliberate statement about what matters in a wake word detector: a word that fires during a podcast is worse than a word that occasionally takes an extra repeat to hear.

The second is the model conversion. The model is trained in a non-streaming mode, on the entire spectrogram, and is then converted into a streaming model that updates on only the newest spectrogram features. Not padding the convolutions is what keeps the non-streaming and streaming models nearly identical in prediction behaviour, so the metric you measured during training carries over to the device.

The false accept estimate is a simulation. Long duration ambient clips are split into appropriately sized spectrograms with a 100 ms stride to imitate the streaming model, and the README is explicit that this is not a perfect estimate of real world false accepts per hour, though it is good enough for deciding which weights are best.

Data handling is also specified. Validation and test sets are split in two, one part containing the positive and negative generated samples, and one part, the validation_ambient and testing_ambient sets, consisting only of real world background sounds such as music, household noise and general speech. Generated spectrograms are stored as Ragged Mmap folders for fast loading from disk while training, and each feature set carries a sampling_weight controlling oversampling and a penalty_weight controlling the weight of incorrect predictions, with class weights adjustable through positive_class_weight and negative_class_weight. Raising the negative class weight is the documented way to reduce false acceptances.

Synthetic speech from Piper, plus a SpecAugment pass

Sample generation is where the difficulty sits, and the tooling is specific. Samples are generated using the Piper sample generator, which produces synthetic speech for the phrase you want. The generated samples are then augmented before or during training to increase variability, and the augmentation listed in the README is SpecAugment, which masks time and frequency features of the spectrogram.

The second source of material is curated negative data. Pre-generated spectrogram features for various negative datasets are published on Hugging Face, so you do not have to assemble your own background noise corpus before you can start.

There is a specific instruction that reads like a footnote and is probably the most valuable line in the training section: generate spectrogram features over a longer time period than needed for training the model. The reason given is that the preprocessor model applies PCAN and noise reduction, so generating over a longer period results in models that generalise better. It is the kind of detail that is easy to skip and expensive to discover on your own.

The last step is quantisation. The streaming models are quantised to increase performance on low power devices, and the README notes this carries a small performance penalty that varies from model to model, but that there is typically no reduction in accuracy.

Installing it and running the training notebook

There is no installer command in the README, because the project is consumed as a Python package. The manifest declares the package as microwakeword at version 0.1.0, with the dependencies declared dynamically and the build backend set to setuptools. The install requirements are listed in setup.py:

install_requires=[
        "audiomentations",
        "audio_metadata",
        "datasets",
        "mmap_ninja",
        "numpy>=2.0",
        "pymicro-features",
        "pyyaml",
        "tensorflow>=2.18",
        "webrtcvad-wheels",
        "ai-edge-litert",
]

The Python floor is declared in both manifests, with requires-python set to >=3.10 and python_requires matching it, and the black configuration targets py310, py311 and py312.

The first real use is the notebook, not the API. The README points at basic_training_notebook.ipynb to show how a model is trained, and immediately warns that the notebook will produce a model but that it will most likely not be usable, and that training a usable model requires a lot of experimentation. The notebook is meant to serve only as a starting point for advanced users.

So the expected workflow is: run the notebook, inspect the result, then work on the hyperparameters and the sample generation settings until the false accepts per hour target is met on your own ambient audio. The repository layout supports that loop. There is a notebooks/ directory, a microwakeword/ package, a benchmarks/ directory, a documentation/ directory and an etc/ directory that holds the logo and other assets.

Prebuilt models exist, and the README points you at them

If you are not trying to invent a new phrase, you do not have to train. The README states that the currently available models can be downloaded from the esphome/micro-wake-word-models repository, and that is where you should look first.

The listed releases in this repository give a sense of the model naming convention. They are not semantic versions but dated identifiers with descriptive names: Okay Nabu 20241226.3 from 2024-12-31, Okay Nabu 20241223.2 from 2024-12-26, and a New Beta V2 Models with Extra Key release from 2024-07-10. Nabu Casa and ESPHome appear among the organisations that gave feedback and development support, with the Open Home Foundation publishing the library badge.

That relationship explains the shape of the project. microWakeWord is a library from the Open Home Foundation, and the people thanked include individuals and organisations from the ESPHome and Nabu Casa ecosystem. The models are intended to be consumed by an embedded voice stack, and the model repository is separate from the training code so that a device can ship a model without shipping TensorFlow.

The difference in approach between the two paths is the whole trade. A downloaded model costs nothing and works on day one for a phrase that was trained once for everyone. A model you train yourself matches your phrase, your accent and your microphone, but it carries the whole cost of the experimentation loop.

Licence, maintenance and the cost of the tuning work

The licence is Apache-2.0, declared in the LICENSE file and in the package classifiers. For an embedded project that is one of the friendlier outcomes, since Apache-2.0 permits commercial use and modification with an explicit patent grant, and it places no copyleft obligation on a firmware image you ship.

On maintenance, the repository is not archived and the last push was on 2026-07-06. The listed releases, however, are all from 2024, with the most recent being Okay Nabu 20241226.3 on 2024-12-31. The package version in both manifests is 0.1.0, and the project describes itself as an early release. Those three facts together give a reasonable picture: the code is still being worked on, the shipped model artefacts are from a previous year, and the version number has not moved off 0.1.0.

The real cost of this project is not the licence and not the compute, it is the iteration loop. The README names the difficulty plainly: getting a model that works well typically requires experimentation with hyperparameters and sample generation settings, and the notebook alone is not enough. Add to that the fact that the false accept per hour metric is estimated rather than measured, and the ambient validation sets have to reflect your own environment, and the honest budget for a first successful model is several training runs rather than one.

If your device runs in a noisy home, your own ambient set is the part you cannot skip, and the two stage weight selection exists precisely so that the false accept target is met before accuracy is chased.

Editorial conclusion

Adopt microWakeWord if you need a wake word for a phrase no pretrained model covers, you can run a TensorFlow training pipeline on a workstation, and you are prepared to iterate on hyperparameters and sample generation until the false accept rate per hour is acceptable. Do not adopt it if you need a working detector today, because the project is an early release and its own documentation says the training notebook will most likely produce an unusable model. Verify the pipeline against your own ambient noise before shipping, expect the model to be quantised for the device, and note that the last push was on 2026-07-06 with the listed releases dating from 2024.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. OHF-Voice/micro-wake-word on GitHub
4. README
5. Releases