hivemind-audio-binary-protocol

August 10, 2026 · View on GitHub

Binary audio plugin for hivemind-core.

The plugin adds server-side WakeWord detection, VAD, STT, and TTS to a hivemind-core hub. Lightweight satellites, such as hivemind-mic-satellite, stream raw audio to the hub and receive transcriptions or synthesized speech. The satellites do not run those models locally.

Where it fits

hivemind-core
  └── hivemind-plugin-manager  (BinaryDataHandlerFactory loads plugins by entry-point)
        └── hivemind-audio-binary-protocol  ← this repo
              ├── ovos-simple-listener  (WakeWord + VAD + STT pipeline)
              └── OVOSTTSFactory / OVOSSTTFactory / OVOSVADFactory / OVOSWakeWordFactory

The plugin registers under the hivemind.binary.protocol entry-point group as hivemind-audio-binary-protocol-plugin.

Install

pip install hivemind-audio-binary-protocol

You also need OVOS STT, TTS, VAD, and WakeWord plugins. Install them as you would in a standard OVOS setup:

pip install ovos-stt-plugin-server ovos-tts-plugin-piper ovos-vad-plugin-silero \
            ovos-ww-plugin-precise-lite

Quickstart

Add the binary_protocol block to ~/.config/hivemind-core/server.json:

{
  "binary_protocol": {
    "module": "hivemind-audio-binary-protocol-plugin",
    "hivemind-audio-binary-protocol-plugin": {
      "stt": {
        "module": "ovos-stt-plugin-server",
        "ovos-stt-plugin-server": {"url": "https://stt.openvoiceos.org"}
      },
      "tts": {
        "module": "ovos-tts-plugin-piper",
        "ovos-tts-plugin-piper": {"voice": "en_US-lessac-medium"}
      },
      "vad": {
        "module": "ovos-vad-plugin-silero"
      },
      "wake_word": "hey_mycroft",
      "hotwords": {
        "hey_mycroft": {
          "module": "ovos-ww-plugin-precise-lite",
          "model": "https://github.com/OpenVoiceOS/precise-lite-models/raw/master/wakewords/en/hey_mycroft.tflite"
        }
      }
    }
  }
}

Then start hivemind-core with the listen subcommand:

hivemind-core listen

Audio streaming modes

This plugin handles three binary audio flows:

ModeClient sendsHub returnsUse case
Microphone streamRaw PCM audio chunksBus messages (wakeword/utterance events)Mic satellite. The hub runs the full pipeline.
STT transcriptionRaw PCM audiorecognizer_loop:transcribe.responseClient wants a transcription without triggering skills.
STT handleRaw PCM audioTriggers recognizer_loop:utterance on the busClient wants the hub to handle the utterance.

The bus triggers TTS (speak:synth or speak:b64_audio) and returns binary WAV audio or a Base64-encoded string to the client.

Configuration reference

The plugin's config block mirrors the OVOS plugin config convention. Each sub-plugin (stt, tts, vad) takes its standard OVOS config:

KeyDescription
sttSTT plugin config. module selects the OVOS STT plugin.
ttsTTS plugin config. module selects the OVOS TTS plugin.
vadVAD plugin config. module selects the OVOS VAD plugin.
wake_wordWakeWord name (key into hotwords).
hotwordsDict of wakeword configurations, keyed by wakeword name.
utterance_transformersList of OVOS utterance transformer plugin names.
dialog_transformersList of OVOS dialog transformer plugin names.
metadata_transformersList of OVOS metadata transformer plugin names.
audio_transformersList of OVOS audio transformer plugin names applied to raw audio before STT.
tts_transformersList of OVOS tts transformer plugin names applied to synthesized audio after TTS.

If the config block is omitted, the plugin falls back to reading mycroft.conf (the standard OVOS configuration file) to select plugins.

Access control

This plugin respects hivemind-core's per-client allowed_types whitelist. Clients must have the correct access to send binary audio or receive TTS output.

License

Apache License 2.0. See LICENSE.

Docs