hivemind-audio-binary-protocol

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:

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:

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.

Related projects

• JarbasHiveMind/HiveMind-core — the hub this plugin extends
• JarbasHiveMind/hivemind-plugin-manager — loads this plugin by entry-point
• JarbasHiveMind/hivemind-mic-satellite — reference satellite client for the microphone stream mode

License

Apache License 2.0. See LICENSE.

Docs

• docs/audio_flow.md: detailed STT/TTS flow, FakeMicrophone, per-client listeners
• docs/configuration.md: full configuration reference
• docs/operations.md: plugin selection, satellite setup, authoring a binary plugin