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 new phrase. The assistant now wakes on it instead of "hey mycroft".

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 default OVOS plugin for hey_mycroft is ovos-ww-plugin-precise-onnx, falling back down this chain if a plugin further up is not installed:

ovos-ww-plugin-precise-onnx (default)
ovos-ww-plugin-precise-lite (TFLite, archived)
ovos-ww-plugin-precise (classic Precise, archived)
ovos-ww-plugin-vosk
ovos-ww-plugin-pocketsphinx

Everything in the Precise family except ovos-ww-plugin-precise-onnx is archived on GitHub. The chain keeps them as fallbacks purely for compatibility with older trained models (.tflite/legacy Precise formats); new setups only need ovos-ww-plugin-precise-onnx.

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

The default hey_mycroft engine ovos-ww-plugin-precise-onnx is rated Beta. Its fallback 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 legacy 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.1}
  }
}

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 a now-defunct upstream. Legacy: do not train new Precise models. The ONNX exports of the existing community models live on, and one of them is still the shipped hey_mycroft default, but the training tooling is deprecated and unmaintained. For a new phrase, train openWakeWord or microWakeWord instead. 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). The intended long-term replacement for the Precise training path; expect rough edges while it is alpha. 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	First fallback below the default: a trained Precise wake-word model exported to TFLite. Warning: archived, kept working as installed. `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	Default plugin for `hey_mycroft`: 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 yet 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 custom wake-word models trained with wakeforge: train a detector from a single phrase, export a two-file model.	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 yet — not on PyPI, and both repositories are still 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 default mycroft.conf ships it as hey_mycroft_tflite, the first fallback below the ONNX default.

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. It is the plugin the bundled default mycroft.conf ships 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_tflite"
   }
}

Donating wake word samples

The listener can save wake-word audio samples to local disk (listener.record_wake_words, off by default); an opt-in upload mechanism to an open-data server is proposed but not yet merged. See Privacy & Security.

Wake-word Plugins¶

Change your 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¶

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