Wake-word Plugins¶

In a nutshell

A wake word is the special phrase that gets your assistant's attention, like "Hey Mycroft". It only starts paying attention when you mean to talk to it, instead of listening all the time. Wake-word plugins are the different tools that listen for that phrase. Some are more accurate for a fixed phrase. Others let you pick your own wake word with less setup. See the Glossary and the listener service for related details.

Wake-word plugins let Open Voice OS detect specific words or sounds, typically the assistant's name (for example "Hey Mycroft"). You can customize them for other use cases. These plugins let the system listen for and react to activation commands or phrases.

Audio format contract

Wake-word plugins receive raw PCM from the microphone plugin: 16 kHz sample rate, 16-bit samples, mono, little-endian, delivered in 4096-byte chunks by default.

Change your wake word¶

Open ~/.config/mycroft/mycroft.conf (create it if it doesn't exist).

Add or edit the listener.wake_word key and a matching entry under hotwords:

{
  "listener": { "wake_word": "hey_computer" },
  "hotwords": {
    "hey_computer": { "module": "ovos-ww-plugin-vosk", "listen": true }
  }
}

Save the file. It is JSON (comments are allowed, mycroft.conf is parsed as JSONC).
Restart OVOS for the change to take effect:

How to restart your assistant

OVOS is not one program — it's several separate services (the listener, ovos-core, ovos-audio, the messagebus, and more) that need to pick up a config change together. How you restart them depends on how OVOS was installed:

systemd install (the ovos-installer or a RaspOVOS image): restart the whole stack with one command —
```
systemctl --user restart ovos.service
```
ovos.service is a --user target unit that the other services (ovos-messagebus.service, ovos-listener.service, ovos-audio.service, ovos-core.service, ovos-phal.service, and — if installed — ovos-gui.service) declare as PartOf=, so restarting it cascades to all of them. Restarting a single service instead (e.g. only the listener after a wake-word change) works the same way: systemctl --user restart ovos-listener.service.
Docker/container install: restart the equivalent service(s) in your compose file, e.g.
```
docker compose restart <service-name>
```
(or docker compose restart with no name to restart everything).
Manual/development run: stop the running ovos-core process (Ctrl-C) and start it again.

Say the phrase. The assistant wakes on it instead of "hey mycroft".

Pick any phrase, with no training

To use your own phrase without recording clips or training a model, see Change the Wake Word Without Training. You can try a phrase in the WakePhoneHuBERT Space first. To make the assistant answer only the people in your household, see Make OVOS Answer Only Your Voice.

Train your own wake word¶

The notebook kaggle_quickstart_ww trains a model for any phrase, for free on Kaggle or Colab. The model is for ovos-ww-plugin-wakeforge. Train a wake word explains how to use it on your device.

Available Plugins¶

OVOS supports different wake-word detection plugins, each with its own strengths and use cases. The full roster with descriptions and licenses lives in one place: the WW Plugins Reference table below.

The bundled mycroft.conf in ovos-config defines the hey_mycroft wake word as a chain of engines. If the engine at the top is not installed or fails to load, the listener uses the next engine in the chain. The chain is:

ovos-ww-plugin-precise-onnx with the hey_mycroft.onnx model
ovos-ww-plugin-wakeforge with the wakehubert_hey_mycroft_streaming ready model
ovos-ww-plugin-wakeforge with the wakehubert_hey_mycroft ready model
ovos-ww-plugin-vosk

The bundled mycroft.conf also uses WakeForge for two more words. wake_up uses the wakehubert_wake_up ready model. stop_recording uses the zero-shot engine ovos-ww-plugin-wakeforge-zeroshot with IPA phones, so it needs no trained model. Both words fall back to ovos-ww-plugin-vosk. See Ready WakeForge models.

Everything in the Precise family except ovos-ww-plugin-precise-onnx is archived on GitHub.

Vosk offers the fastest setup for an arbitrary wake phrase without model training.

ovos-ww-plugin-precise-onnx is rated Beta. ovos-ww-plugin-wakeforge is rated Alpha. ovos-ww-plugin-vosk is Stable, and ovos-ww-plugin-precise-lite is Deprecated. The default is chosen for accuracy. Per the Maturity Scale, maturity is separate from the recommendation.

Relative footprint

The default ovos-ww-plugin-precise-onnx models are small, purpose-built for a single wake phrase, and meant to run continuously on-device. They are much lighter than a general STT or TTS model. This is why wake-word detection is the one always-on inference step in the listener pipeline.

Specification: wake-word detection is one of the deployer-defined capture mechanisms that trigger the audio-input service (referenced in OVOS-AUDIO-IN-1 §5.1 as the source of a request_lang hint).

Alternative: openWakeWord

ovos-ww-plugin-openWakeWord runs open, pre-trained neural wake-word models and is a strong alternative when you want better accuracy than Vosk without touching the deprecated Precise training path.

Wake-word Configuration¶

Too many false alarms, or not hearing you at all? (Precise-family engines)

These two knobs apply to the Precise-family plugins (precise-onnx, precise-lite, classic precise) — the default setup. Other engines tune differently: Vosk ignores sensitivity/trigger_level entirely (it matches words, not model scores), so check your plugin's own entry in the reference table if you switched engines.

It wakes up on its own too often (false alarms)? Raise trigger_level. This gives fewer false positives, but needs a longer, more sustained match. Or lower sensitivity.
It doesn't hear you when you say the wake word? Raise sensitivity, so each chunk of audio is easier to trigger. Or lower trigger_level.

Both live under hotwords.<name> in mycroft.conf, next to each other. Nudge one at a time and test before changing the other. The full technical breakdown of what each number actually does is below.

The hotwords section in your mycroft.conf allows you to configure the wake-word detection parameters for each plugin. For instance:

"hotwords": {
  "hey_mycroft": {
    "module": "ovos-ww-plugin-precise-onnx",
    "model": "https://github.com/OpenVoiceOS/precise-lite-models/raw/master/wakewords/en/hey_mycroft.onnx",
    "trigger_level": 3,
    "sensitivity": 0.5,
    "listen": true
  }
}

See the full docs for the listener service

Wake-word entry types and keys¶

Each entry under hotwords is one of four types, set by a boolean key. active: null (the default) auto-enables the main wake word (listener.wake_word) and the stand-up word (listener.stand_up_word); every other entry stays disabled until you set active: true.

flowchart TD
    A["Wake-word entry in<br/>mycroft.conf"] --> B{"listen: true, or<br/>matches<br/>listener.wake_word?"}
    B -->|yes| C["Listen word: starts<br/>VAD/STT recording"]
    B -->|no| D{"wakeup: true, or<br/>matches<br/>listener.stand_up_word?"}
    D -->|yes| E["Wakeup word: exits<br/>sleep mode"]
    D -->|no| F{"stopword: true?"}
    F -->|yes| G["Stop word: ends free<br/>RECORDING mode"]
    F -->|no| H{"active: true?"}
    H -->|yes| I["Plain wake word: sound/<br/>bus event, no STT"]

Diagram: The flow starts at the wake-word entry in mycroft.conf and ends at one of four outcomes, and it branches in sequence through the listen, wakeup, stopword, and active checks to pick the matching wake-word type.

Type	Config key	Effect when detected
Listen word	`listen: true`, or matches `listener.wake_word`	Starts the VAD/STT recording pipeline
Wakeup word	`wakeup: true`, or matches `listener.stand_up_word`	Exits sleep mode
Stop word	`stopword: true`	Ends free `RECORDING` mode
Plain wake word	none of the above, `active: true`	Plays a sound and/or emits a bus event, without starting STT

Beyond module, active, listen, wakeup, stopword, and sensitivity/trigger_level, each entry accepts:

Key	Type	Description
`sound`	`str` \| `list`	Sound file played on detection.
`bus_event`	`str`	Bus message type emitted on detection.
`utterance`	`str`	Hard-coded utterance text, bypassing STT entirely for this entry.
`stt_lang`	`str`	Overrides the STT language for the command that follows this hotword.

"hotwords": {
  "hey_mycroft": {
    "module": "ovos-ww-plugin-precise-lite",
    "listen": true,
    "sound": "snd/start_listening.wav",
    "active": null
  },
  "wake_up": {
    "module": "ovos-ww-plugin-vosk",
    "wakeup": true,
    "active": null
  },
  "stop_recording": {
    "module": "ovos-ww-plugin-vosk",
    "stopword": true,
    "active": true
  },
  "hey_computer": {
    "module": "ovos-ww-plugin-precise-lite",
    "bus_event": "my.custom.event",
    "sound": "snd/ding.wav",
    "active": true
  },
  "hola_mycroft": {
    "module": "ovos-ww-plugin-precise-lite",
    "listen": true,
    "stt_lang": "es-es",
    "active": true
  }
}

Wake-word verifiers¶

After a wake-word engine fires, optional verifier plugins can inspect the raw wake word audio and suppress false detections before any callback runs. Verifiers implement the HotWordVerifier interface (from ovos-plugin-manager) and are configured under listener.ww_verifiers:

flowchart LR
    A[Wake-word engine fires] --> B["HotWordVerifier.<br/>verify()"]
    B -->|"False"| C[Detection suppressed]
    B -->|"True, or exception<br/>raised (fail open)"| D["Detection proceeds,<br/>callback runs"]

Diagram: The flow starts when the wake-word engine fires and ends with the detection either suppressed or proceeding to run the callback, and it branches on the HotWordVerifier.verify() result, failing open on exception.

"listener": {
  "ww_verifiers": {
    "ovos-ww-verifier-speaker": {"threshold": 0.45, "fail_open": false}
  }
}

The speaker verifier is set up step by step in Make OVOS Answer Only Your Voice.

Verifiers fail open: if a verifier plugin raises an unexpected exception, the exception is logged and the detection is not suppressed. Only an explicit False return from HotWordVerifier.verify() discards the wake. Disable a verifier without removing it from config with "enabled": false.

Double VAD if you use a Silero-based verifier

If your verifier plugin runs Silero VAD internally, enabling it together with "vad_pre_wake_enabled": true applies Silero VAD twice on the same audio. Use one or the other.

Choosing a wake-word engine¶

Where the authoritative detail lives, and the honest trade-offs:

Precise family (MycroftAI/mycroft-precise): a per-phrase GRU network from an unmaintained upstream. Do not train Precise models. The ONNX exports of the community models work, and one of them is the shipped hey_mycroft default, but the training tooling is deprecated and unmaintained. For a custom phrase, train openWakeWord, microWakeWord or WakeForge. sensitivity/trigger_level tuning of the existing models remains real work.
openWakeWord (dscripka/openWakeWord): a frozen speech-embedding backbone plus a small per-phrase classifier, trained entirely on synthetic TTS speech. Its self-reported targets are under 0.5 false accepts per hour and under 5% false rejects, with many models running concurrently on a Pi 3 core.
microWakeWord (kahrendt/microWakeWord): synthetic-sample training aimed at microcontrollers; the smallest-footprint neural option.
WakeForge (TigreGotico/wakeforge): the ecosystem's own training framework, in prerelease. Train a detector from a single typed phrase (synthetic data, no recording campaign) and run the exported two-file model with ovos-ww-plugin-wakeforge (alpha, on PyPI). Use it in place of the Precise training path. The repo's notebooks/ folder has worked Kaggle/Colab notebooks for hyperparameter search, tiered-scale training (micro/embedded/GPU), HuBERT distillation, and voice-conversion dataset bootstrapping. Dataset generation and augmentation for wake-word training also has a dedicated notebook, ww/tts2ww.ipynb in TigreGotico/ml-notebooks.
Vosk (project page): general ASR repurposed for keyword matching. Zero training for an arbitrary phrase, but heavier and worse at false-accept suppression than the dedicated nets; it ignores sensitivity entirely.
pocketsphinx (cmusphinx/pocketsphinx): decades-old HMM technology; upstream itself warns results "may not be wonderful". Last resort by design.

Tips and Caveats¶

Vosk Plugin: The Vosk plugin is useful when you need a simple setup that doesn't require training a wake-word model. It's great for quickly gathering data during the development stage.
Precision and Sensitivity: Adjust the sensitivity and trigger_level settings carefully. Too high a sensitivity can lead to false positives, while too low may miss detection.

`sensitivity` vs `trigger_level`: the technical breakdown¶

These two settings work together in the model-based Precise plugins (ovos-ww-plugin-precise-lite, ovos-ww-plugin-precise-onnx):

sensitivity (float, 0.0-1.0, default 0.5) sets how close a single audio chunk's model output has to be to "yes" before it counts as a match. A chunk counts as activated when its probability exceeds 1.0 - sensitivity. Raising sensitivity makes each individual chunk easier to trigger: more false positives, more sensitive to the word.
trigger_level (int, default 3) is a debounce counter. It is the number of consecutive activated chunks required before the wake word actually fires, so a single lucky chunk isn't enough. Raising trigger_level requires a longer sustained match: fewer false positives, but slower and stricter detection.

In short, sensitivity controls how easily one chunk counts as a hit. trigger_level controls how many hits in a row are needed to confirm the wake word.

Writing your own wake-word plugin

Building a wake-word engine instead of picking one from the roster? The HotWordEngine interface, its key methods, and a full step-by-step walkthrough live on the Wake-word Plugin Development page.

WW Plugins Reference¶

Code license is the SPDX license of the plugin's own repository. Where the plugin wraps a separately-licensed model, that is called out under "model".

Plugin	Description	License	Maturity
ovos-ww-plugin-precise-lite	A trained Precise wake-word model exported to TFLite. Warning: archived. `ovos-ww-plugin-precise-onnx` is the maintained successor.	Apache-2.0	Deprecated
ovos-ww-plugin-precise	Classic Precise wake-word plugin, the predecessor to the TFLite/ONNX rewrites. Warning: archived.	Apache-2.0	Deprecated
ovos-ww-plugin-pocketsphinx	Wake-word detection using CMU PocketSphinx. Not archived.	Apache-2.0	Stable
ovos-ww-plugin-openWakeWord	Wake-word detection using the open-source openWakeWord neural models.	Apache-2.0 (model: see model card)	Stable
ovos-ww-plugin-vosk	Mycroft wake-word plugin for Vosk	Apache-2.0 (model: see model card)	Stable
ovos-ww-plugin-precise-onnx	The first `hey_mycroft` engine in the bundled `mycroft.conf`: a Precise wake-word model exported to ONNX.	Apache-2.0	Beta
ovos-ww-plugin-wakewordlab	Compact (~240 KB) neural wake-word models with a Silero VAD pre-filter (`.wkw`/`.onnx`). Not on PyPI, install from source.	Apache-2.0	Alpha
ovos-ww-plugin-microwakeword	Runs microWakeWord streaming TFLite models (the ESPHome wake-word engine), `hey_mycroft` included. On PyPI as an alpha.	Apache-2.0	Alpha
ovos-ww-plugin-wakeforge	Runs ready WakeForge models, zero-shot wake words typed as IPA phones (`ovos-ww-plugin-wakeforge-zeroshot`), and custom models trained with wakeforge. A fallback for `hey_mycroft` in the bundled `mycroft.conf`.	Apache-2.0	Alpha
ovos-ww-plugin-server	Remote wake-word detection: streams audio to an `ovos-ww-server` instance (offload detection from a thin satellite). Not available: not on PyPI, and both repositories are private.	Apache-2.0	Alpha

Maturity reflects repository health (age, activity, open issues/PRs, in-repo docs), not version. See the Maturity Scale.

ovos-ww-plugin-precise-lite¶

GitHub: OpenVoiceOS/ovos-ww-plugin-precise-lite. Warning: archived.
Description: Trained Precise wake-word model exported to TFLite. The bundled mycroft.conf does not use it.

Default Configuration¶

"hotwords": {
  "hey_mycroft_tflite": {
    "module": "ovos-ww-plugin-precise-lite",
    "model": "https://github.com/OpenVoiceOS/precise-lite-models/raw/master/wakewords/en/hey_mycroft.tflite",
    "expected_duration": 3,
    "trigger_level": 3,
    "sensitivity": 0.5,
    "listen": true,
    "fallback_ww": "hey_mycroft_precise"
  }
}

ovos-ww-plugin-openWakeWord¶

GitHub: OpenVoiceOS/ovos-ww-plugin-openWakeWord
Description: Wake-word detection using the open-source openWakeWord neural models.

ovos-ww-plugin-vosk¶

GitHub: OpenVoiceOS/ovos-ww-plugin-vosk
Description: Mycroft wake-word plugin for Vosk

Example Configuration¶

  "listener": {
    "wake_word": "hey_computer"
  },
  "hotwords": {
    "hey_computer": {
        "module": "ovos-ww-plugin-vosk",
        "listen": true
    }
  }

hey_computer is a custom-wake-word example; the shipped config uses vosk only as the hey_mycroft_vosk fallback tier, not as the primary wake word.

ovos-ww-plugin-precise-onnx¶

GitHub: OpenVoiceOS/ovos-ww-plugin-precise-onnx
Description: Runs Precise wake-word models exported to ONNX. On the alpha channel, the bundled mycroft.conf uses it as the first engine for hey_mycroft.

Default Configuration¶

"listener": {
  "wake_word": "hey_mycroft"
},
"hotwords": {
  "hey_mycroft": {
    "module": "ovos-ww-plugin-precise-onnx",
    "model": "https://github.com/OpenVoiceOS/precise-lite-models/raw/master/wakewords/en/hey_mycroft.onnx",
    "trigger_level": 3,
    "sensitivity": 0.5,
    "listen": true,
    "fallback_ww": "hey_mycroft_wakehubert_streaming"
   }
}

Donating wake word samples

The listener can save wake-word audio samples to local disk (listener.record_wake_words, off by default). The listener has no mechanism to upload them. See Privacy & Security.

Ready WakeForge models¶

ovos-ww-plugin-wakeforge runs ready wake-word models with no training. The plugin downloads a model from Hugging Face the first time it uses it.

Alpha channel only

The ready models and the zero-shot engine are in the prerelease channel of the plugin only. Install it with pip install --pre ovos-ww-plugin-wakeforge.

To use a ready model, set model to its name:

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

Language	Ready model names
English	`wakehubert_alexa`, `wakehubert_android`, `wakehubert_computer`, `wakehubert_hello_nabu`, `wakehubert_hey_chatterbox`, `wakehubert_hey_computer`, `wakehubert_hey_floyd`, `wakehubert_hey_jarvis`, `wakehubert_hey_k9`, `wakehubert_hey_marvin`, `wakehubert_hey_mycroft`, `wakehubert_hey_potato`, `wakehubert_hey_rhasspy`, `wakehubert_hey_robin`, `wakehubert_hey_scout`, `wakehubert_hey_ziggy`, `wakehubert_home_assistant`, `wakehubert_jarvis`, `wakehubert_marvin`, `wakehubert_okay_nabu`, `wakehubert_sheila`, `wakehubert_stop`, `wakehubert_wake_up`
German	`wakehubert_aufwachen`
Spanish	`wakehubert_despierta`
Italian	`wakehubert_sveglia`
Dutch	`wakehubert_hey_stemcom`, `wakehubert_wakker_worden`

The model card gives the default threshold, the measured recall and the false activations per hour for each model. A model named wakehubert_<word>_streaming runs the featurizer in streaming mode and uses less CPU. Streaming models exist for alexa, hey_jarvis and hey_mycroft.

Wake words from IPA phones¶

ovos-ww-plugin-wakeforge-zeroshot detects a wake word from its IPA phones. It needs no recordings and no trained model. Get the phones with eSpeak NG:

espeak-ng -q --ipa -v en-us "hey jarvis"

eSpeak NG prints hˈeɪ dʒˈɑːɹvɪs. You can paste that output as it is. The plugin drops the stress marks, and spaces between phones are optional. Put the phones in the ipa key:

"hotwords": {
  "hey_jarvis": {
    "module": "ovos-ww-plugin-wakeforge-zeroshot",
    "ipa": "h eɪ dʒ ɑːɹ v ɪ s",
    "listen": true
  }
}

Use a phrase of six phones or more, ideally two words. Short single words are unreliable. For a short word, use a ready model or train one with wakeforge. The plugin README lists every configuration key.

Wake-word Plugins¶

Change your wake word¶

Train your own wake word¶

Available Plugins¶

Wake-word Configuration¶

Wake-word entry types and keys¶

Wake-word verifiers¶

Choosing a wake-word engine¶

Tips and Caveats¶

sensitivity vs trigger_level: the technical breakdown¶

WW Plugins Reference¶

ovos-ww-plugin-precise-lite¶

Default Configuration¶

ovos-ww-plugin-openWakeWord¶

ovos-ww-plugin-vosk¶

Example Configuration¶

ovos-ww-plugin-precise-onnx¶

Default Configuration¶

Ready WakeForge models¶

Wake words from IPA phones¶

`sensitivity` vs `trigger_level`: the technical breakdown¶