ovos-ww-plugin-wakeforge

An OpenVoiceOS wake-word plugin that runs models made with wakeforge. It ships ready models for "hey mycroft", "alexa" and "wake up", together with the feature extractor they run on, so it works offline with nothing else to download. The runtime needs only onnxruntime and numpy.

This plugin only runs models. To train a model for your own wake word, use wakeforge, a wake-word research framework.

Install

pip install --pre ovos-ww-plugin-wakeforge

Try it on your laptop

You don't need OpenVoiceOS to try the models. The demo listens to your microphone and runs the ready model beside openWakeWord, microWakeWord and Precise, so you can compare them with your own voice:

pip install --pre "ovos-ww-plugin-wakeforge[demo]"
ovos-wakeforge-demo --wakeword hey_mycroft

Say the wake word. Each bar shows one engine's wake-word probability, and | marks where that engine triggers. See Compare against other engines for the options.

Use a ready model

Put this in mycroft.conf:

{
  "listener": {
    "wake_word": "hey_mycroft"
  },
  "hotwords": {
    "hey_mycroft": {
      "module": "ovos-ww-plugin-wakeforge",
      "model": "hey_mycroft",
      "listen": true
    }
  }
}

For the other ready models, set model to alexa, wake_up or hey_mycroft_synthetic, and name the hotword to match.

"hey mycroft" ships in two versions for comparison. hey_mycroft was trained on human recordings. hey_mycroft_synthetic was trained on synthetic speech only, the same way as alexa and wake_up, so it shows what a model for a word nobody has recorded can reach. The demo below runs both side by side.

Each ready model is a small classifier on features from WakeHuBERT tiny, a 0.64M-parameter speech feature extractor distilled from HuBERT-base. The score is a calibrated probability that the last 1.5 s holds the wake word. Each model fires at its own default trigger (0.965 for hey_mycroft, 0.998 for hey_mycroft_synthetic, 0.99 for alexa, 0.990 for wake_up), and after a detection it stays quiet for 2 s. Set "threshold" to change the trade-off: a lower value fires more readily and falsely more often. With a microphone whose gain is far too high or too low, "agc": true levels the audio before scoring. Model licences are listed in ovos_ww_plugin_wakeforge/models/NOTICE.

Use your own model

Point model at the classifier ONNX that wakeforge exported, and featurizer at its feature extractor. Both can be local paths or URLs. A model trained on a pretrained featurizer names that featurizer in its own metadata, so featurizer can be left out. A model whose metadata carries a calibrated default_threshold uses it, together with the ready-model smoothing.

{
  "listener": {
    "wake_word": "hey_jarvis"
  },
  "hotwords": {
    "hey_jarvis": {
      "module": "ovos-ww-plugin-wakeforge",
      "listen": true,
      "featurizer": "~/hey_jarvis/featurizer.onnx",
      "model": "~/hey_jarvis/model.onnx"
    }
  }
}

Config keys

URL models are cached under ${XDG_DATA_HOME}/wakeforge/.

Pretrained featurizers other than the bundled wakehubert and wakehubert-int8 are downloaded from the Hugging Face Hub on first use. A featurizer that depends on future audio, or on unbounded history, cannot run on a live stream and is refused at load time.

Compare against other engines

ovos-wakeforge-demo listens to the microphone and runs the ready model next to the other wake-word engines that have a model for the word, each fed the same 80 ms chunks:

pip install --pre "ovos-ww-plugin-wakeforge[demo]"
ovos-wakeforge-demo --wakeword hey_mycroft

openwakeword and microwakeword have no wake_up model either; running --wakeword wake_up shows those two (and precise-onnx) in the red "not loaded" row, with wakehubert the only bar on the panel.

Each engine has a row with a bar showing its wake-word probability and a | where it triggers. When a bar crosses its marker the row turns green with "WAKE WORD!", the detection is counted and logged under "recent detections", and that engine's detections are ignored for 2 s. A meter shows the microphone level and warns when the input clips. An engine that fails to load is listed in a red "not loaded" row with the reason, and an engine that fails while running shows the error in its own row.

Options: --wakeword alexa|hey_mycroft|wake_up, --threshold (WakeHuBERT trigger probability), --oww-threshold (default 0.5), --mww-cutoff (default: the model's shipped cutoff), --precise-sensitivity (default 0.5), --only wakehubert,openwakeword,..., --device (see python -m sounddevice), --agc (level each WakeHuBERT window) and --file clip.wav, which scores a 16 kHz recording instead of the microphone and prints each engine's detection times.

Related projects

• TigreGotico/wakeforge is the wake-word research framework that trains the models this plugin runs.
• OpenVoiceOS/ovos-plugin-manager loads this plugin alongside other speech-to-text, text-to-speech and wake-word plugins.
• OpenVoiceOS/ovos-ww-plugin-precise-onnx is a sibling wake-word plugin that runs Precise models through ONNX.

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