Pre-release

This release is a pre-release and may not be stable for production use.

OpenVoiceOS Dinkum Listener

ovos-dinkum-listener is the voice input daemon for OpenVoiceOS. It reads audio from the microphone, runs it through a wakeword, VAD, and STT pipeline, and emits the results on the message bus for the rest of OVOS to use.

Full documentation lives in the technical manual and in docs/.

Install

pip install ovos-dinkum-listener[extras] to install this package and the default plugins.

Without extras you will also need to manually install, and possibly configure STT, WW, and VAD modules as described below.

Configuration

you can set the Wakeword, VAD, STT and Microphone plugins

eg, to run under MacOS you should use https://github.com/OpenVoiceOS/ovos-microphone-plugin-sounddevice

non exhaustive list of config options

{
  "stt": {
    "module": "ovos-stt-plugin-server",
    "fallback_module": "",
    "ovos-stt-plugin-server": {"url": "https://stt.openvoiceos.com/stt"}
  },
  "listener": {
    // NOTE, multiple hotwords are supported, these fields define the main wake_word,
    // this is equivalent to setting "active": true in the "hotwords" section
    // see "hotwords" section at https://github.com/OpenVoiceOS/ovos-config/blob/dev/ovos_config/mycroft.conf
    "wake_word": "hey_mycroft",
    "stand_up_word": "wake_up",
    "microphone": {
      "module": "ovos-microphone-plugin-alsa"
    },
    // If enabled will only check for wakeword if VAD also detected speech
    // this should reduce false activations
    "vad_pre_wake_enabled": true,
    // Voice Activity Detection is used to determine when users are speaking
    VAD": {
     // recommended plugin: "ovos-vad-plugin-silero"
     "module": "ovos-vad-plugin-silero",
     "ovos-vad-plugin-silero": {"threshold": 0.2},
     "ovos-vad-plugin-webrtcvad": {"vad_mode": 3}
    },
    // Seconds of speech before voice command has begun
    "speech_begin": 0.1,
    // Seconds of silence before a voice command has finished
    "silence_end": 0.5,
    // Settings used by microphone to set recording timeout with and without speech detected
    "recording_timeout": 10.0,
    // Settings used by microphone to set recording timeout without speech detected.
    "recording_timeout_with_silence": 3.0,
    // max time allowed without user speaking before exiting RECORDING mode
    "recording_mode_max_silence_seconds": 30.0,
    // Setting to remove all silence/noise from start and end of recorded speech (only non-streaming)
    "remove_silence": true,
    // continuous listen is an experimental setting, it removes the need for
    // wake words and uses VAD only, a streaming STT is strongly recommended
    // NOTE: depending on hardware this may cause mycroft to hear its own TTS responses as questions
    "continuous_listen": false,

    // hybrid listen is an experimental setting,
    // it will not require a wake word for X seconds after a user interaction
    // this means you dont need to say "hey mycroft" for follow up questions
    "hybrid_listen": false,
    // number of seconds to wait for an interaction before requiring wake word again
    "listen_timeout": 45
  }
}

Open data uploads

ovos-dinkum-listener can optionally upload wake word and STT audio samples to an ovos-opendata-server instance, so users and developers can donate samples to help improve wake word and STT plugins.

This is exclusively opt-in and off by default. Nothing is ever uploaded unless you explicitly configure at least one ww_urls or stt_urls endpoint below - there is no default server. This pairs with the intent-match metrics upload already supported by ovos-core (open_data.intent_urls).

{
  "open_data": {
    "ww_urls": ["https://your-opendata-server.example/api/wake_word"],
    "stt_urls": ["https://your-opendata-server.example/api/stt"],
    "user_agent": "ovos-metrics",
    "api_key": null
  }
}

ww_urls - list of server URLs to POST wake word samples to (name, audio, model, lang, plugin, plugin_config). Leave unset/empty to disable wake word uploads.
stt_urls - list of server URLs to POST STT samples to (transcript, lang, audio, model, plugin, plugin_config). Leave unset/empty to disable STT uploads.
user_agent - User-Agent header sent with uploads, defaults to "ovos-metrics".
api_key - optional, sent as the X-API-Key header if set.

Uploads happen in a background thread and never block the listener; failures are logged and otherwise ignored.

Tips and tricks

Saving Transcriptions

You can enable saving of recordings to file, this should be your first step to diagnose problems, is the audio inteligible? is it being cropped? too noisy? low volume?

set "save_utterances": true in your listener config, recordings will be saved to ~/.local/share/mycroft/listener/utterances

If the recorded audio looks good to you, maybe you need to use a different STT plugin, maybe the one you are using does not like your microphone, or just isn't very good for your language

Wrong Transcriptions

If you consistently get specific words or utterances transcribed wrong, you can remedy around this to some extent by using the ovos-utterance-corrections-plugin

You can define replacements at word level ~/.local/share/mycroft/word_corrections.json

for example whisper STT often gets artist names wrong, this allows you to correct them

{
    "Jimmy Hendricks": "Jimi Hendrix",
    "Eric Klapptern": "Eric Clapton",
    "Eric Klappton": "Eric Clapton"
}

Silence Removal

By default OVOS applies VAD (Voice Activity Detection) to crop silence from the audio sent to STT, this helps in performance and in accuracy (reduces hallucinations in plugins like FasterWhisper)

Depending on your microphone/VAD plugin, this might be removing too much audio

set "remove_silence": false in your listener config, this will send the full audio recording to STT

Listen Sound

does your listen sound contain speech? some users replace the "ding" sound with words such as "yes?"

In this case the listen sound will be sent to STT and might negatively affect the transcription

set "instant_listen": false in your listener config, this will drop the listen sound audio from the STT audio buffer. You will need to wait for the listen sound to finish before speaking your command in this case

Wake Word Verifiers

After the wake-word engine fires, optional verifier plugins can inspect the raw audio and suppress false detections before any callback is triggered. Plugins that implement HotWordVerifier (from ovos-plugin-manager) are discovered automatically.

Example — enable the Silero-VAD verifier with a custom threshold:

{
  "listener": {
    "ww_verifiers": {
      "ovos-ww-verifier-silero": {"threshold": 0.1}
    }
  }
}

Fail-open behaviour: 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 specific verifier without removing it from config:

{
  "listener": {
    "ww_verifiers": {
      "ovos-ww-verifier-silero": {"enabled": false}
    }
  }
}

Note: enabling ovos-ww-verifier-silero and "vad_pre_wake_enabled": true at the same time applies Silero VAD twice. Use one or the other.

How to test

Install the package with test dependencies, then run the suite:

pip install -e ".[extras]"
pip install pytest pytest-timeout
pytest test/ --timeout=30 -q

Expected output (clean environment):

...
258 passed in ~30s

To exercise the verifier chain in isolation:

pytest test/unittests/test_hotwords.py::TestHotwordVerifierChain -v

Expected output:

PASSED test_verify_no_verifiers_returns_true
PASSED test_verify_single_verifier_accepts
PASSED test_verify_single_verifier_rejects
PASSED test_verify_multiple_all_accept
PASSED test_verify_first_verifier_rejects_short_circuits
PASSED test_verify_second_verifier_rejects
PASSED test_verify_raising_verifier_is_fail_open
PASSED test_verify_raising_verifier_followed_by_rejecting_verifier
PASSED test_verify_constructor_verifiers_param

9 passed

To test end-to-end with the Silero verifier plugin installed:

pip install ovos-ww-verifier-silero

Add to your OVOS config:

{
  "listener": {
    "ww_verifiers": {
      "ovos-ww-verifier-silero": {"threshold": 0.1}
    },
    "vad_pre_wake_enabled": false
  }
}

Then start the listener and observe logs — a detected wake word followed by "wake word verifier plugins discarded detection" means the verifier rejected the audio (expected on a non-speech trigger).

Related projects

OpenVoiceOS/ovos-core - the assistant core that runs this listener
OpenVoiceOS/ovos-plugin-manager - discovers and loads the STT, VAD, wakeword, and audio transformer plugins used here
OpenVoiceOS/ovos-utterance-corrections-plugin - fixes recurring STT transcription errors
OpenVoiceOS/ovos-microphone-plugin-sounddevice - microphone plugin for MacOS

Credits

Voice Loop state machine implementation by @Synesthesiam for mycroft-dinkum

License

Apache License 2.0. See LICENSE.

Metadata

Release files for ovos-dinkum-listener 0.10.0a1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ovos-dinkum-listener 0.10.0a1
File	Size	Uploaded
ovos_dinkum_listener-0.10.0a1.tar.gz	117.2 kB	Sep 1, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for ovos-dinkum-listener 0.10.0a1
File	Interpreter	ABI	Platform	Reset
ovos_dinkum_listener-0.10.0a1-py3-none-any.whl 116.0 kB Sep 1, 2026	Python 3	none	any	Details

Total release size: 233.2 kB

Release files / ovos_dinkum_listener-0.10.0a1.tar.gz

Download URL	ovos_dinkum_listener-0.10.0a1.tar.gz
Size	117.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`e9b0a00cf74c903402c8292ffddc06e2cdb6e90dd276eeac393a25776b3bf222`
BLAKE2b-256 checksum How to use checksums	`a1d058f7f1cf91eec601afedd5341fd7fd626d769cf461d6b43550acb9a92b89`
Upload date	Sep 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / ovos_dinkum_listener-0.10.0a1-py3-none-any.whl

Download URL	ovos_dinkum_listener-0.10.0a1-py3-none-any.whl
Size	116.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`50f4b33de3d33cb9468242b7b9be022d4ab9a0896881cb3e2fc9edb24e589e77`
BLAKE2b-256 checksum How to use checksums	`d0b15371cb44ad0e6c19456306620c21a5ce93841c9133de006bfa85e6c65b88`
Upload date	Sep 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`