ovos-ww-plugin-microwakeword

This plugin adds wake-word detection to OpenVoiceOS. It wraps microWakeWord TFLite streaming models from the ESPHome ecosystem.

Supported models

Models published at https://github.com/esphome/micro-wake-word-models:

The plugin also accepts any community .tflite model that follows the microWakeWord input convention (1x1x40 int8 log-mel features).

Installation

pip install ovos-ww-plugin-microwakeword

The package installs ai-edge-litert (on Linux x86_64) or tflite-runtime (on other platforms) as a runtime dependency, along with pymicro-features (the TFLite Micro audio frontend wrapper).

Usage

Add the plugin to the hotwords section of ~/.config/mycroft/mycroft.conf (or ovos.conf), under your chosen wake word:

{
  "hotwords": {
    "okay nabu": {
      "module": "ovos-ww-plugin-microwakeword",
      "model_name": "okay_nabu",
      "model_version": 1,
      "probability_cutoff": 0.5,
      "sliding_window_size": 10,
      "refractory_frames": 40
    }
  }
}

Configuration reference

Technical details

Audio pipeline

16 kHz int16 PCM  →  pymicro-features (TFLite Micro audio frontend)
                  →  40-dim log-mel feature slice per 10 ms frame
                  →  quantize to int8 (scale 0.102, zero-point −128)
                  →  TFLite interpreter (1×1×40 → 1×1 uint8)
                  →  dequantize → float probability
                  →  sliding window average ≥ cutoff → detection

Model input signature

Inspected from okay_nabu.tflite (v1):

Input  tensor: serving_default_input_audio:0  shape=[1, 1, 40]  dtype=int8
               quantization: scale=0.10196, zero_point=-128
Output tensor: StatefulPartitionedCall:0      shape=[1, 1]       dtype=uint8
               quantization: scale=0.00390625, zero_point=0

The model embeds its streaming RNN/convolution state as TFLite resource variables. Each sequential interpreter.invoke() call advances the internal state automatically, so the plugin does not manage an external state tensor. interpreter.allocate_tensors() resets the streaming state. The plugin calls it from reset().

ESPHome model compatibility notes

• v1 models use the original microWakeWord architecture, with quantized int8 input for the TFLite Micro audio frontend.
• v2 models use the same input convention. The plugin supports both transparently.
• A model must accept [1, 1, 40] int8 input. Any model with a different input shape raises ValueError at load time.
• The audio frontend (pymicro-features) is the same C implementation that ESPHome uses for on-device inference.

How to test

Unit tests (no model required)

pytest tests/test_unit.py -v

All 16 unit tests use a mocked interpreter and pass without network access.

End-to-end tests (downloads okay_nabu.tflite, requires edge-tts and ffmpeg)

pip install edge-tts
pytest tests/test_e2e.py -v -s

Expected output:

tests/test_e2e.py::TestE2EReal::test_negative_no_detection PASSED
[positive test] DETECTION FIRED on 'okay nabu' TTS audio.   ← or SKIPPED with max_prob info
tests/test_e2e.py::TestE2EReal::test_positive_detection PASSED

The positive test skips rather than fails when TTS audio does not trigger the model, because the model is trained on human voice. The negative test ("hello world") is a hard assertion.

Related projects

Other OpenVoiceOS wake-word plugins:

• ovos-ww-plugin-openWakeWord
• ovos-ww-plugin-precise-onnx
• ovos-ww-plugin-vosk
• ovos-ww-plugin-wakeforge
• ovos-ww-plugin-wakewordlab

Credits

Developed by TigreGótico for OpenVoiceOS.

This project was funded through the NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 101135429.

License

Apache-2.0