HiveMind Voice Relay

Local wakeword detection. STT and TTS run remotely on hivemind-core with the hivemind-audio-binary-protocol plugin.

Voice Relay runs the microphone, VAD, and wakeword engine on-device. This keeps wake-word detection private and low-latency. It forwards audio to hivemind-core (running the hivemind-audio-binary-protocol plugin) for speech-to-text, and receives synthesised audio back for playback. No STT or TTS models run on the device.

Full documentation: docs/

Satellite spectrum

Voice Relay keeps wakeword detection on-device. No audio leaves the device until activation, and latency stays low. STT and TTS run on the hive instead. The point is not mainly resource savings. It is what it means for the hive to own speech services (see below).

Why voice-relay: HiveMind as a service

Voice-relay's real lesson is architectural. STT and TTS run inside the hive (the hivemind-audio-binary-protocol plugin on hivemind-core) and sit behind the same access-key authentication as the rest of the mesh. For a developer, the consequences matter more than the saved CPU:

• The hive owns STT/TTS. A voice-sat can point at any STT/TTS plugin it likes, including a public ovos-stt-plugin-server or ovos-tts-plugin-server. A relay cannot choose the engine, model, or voice. The hive operator decides, centrally and uniformly, for every relay that connects.
• Speech is authenticated. STT/TTS are not an open endpoint anyone can hit. Access is gated by the client's HiveMind credentials, exactly like every other message on the protocol.
• It is the reference for the b64 speech API. The relay sends audio for STT and receives speech for TTS as base64-encoded WAV over the HiveMessage bus (recognizer_loop:b64_transcribe, speak:b64_audio). This is the same work mic-satellite does over the binary protocol. Relay illustrates the b64 path. It could equally use binary.

Choose voice-relay when you want HiveMind to operate STT/TTS as a governed, authenticated service, uniform and centrally controlled, with wakeword kept local for latency and privacy. Lower device resource use is a consequence, not the goal.

Server requirements

Your hivemind-core server must have the hivemind-audio-binary-protocol binary plugin installed. Plain hivemind-core does not handle STT or TTS. Connecting to it results in silence: no transcription and no spoken response.

Alternatively, run hivemind-core together with ovos-audio and ovos-dinkum-listener to provide the same capabilities.

Install

pip install HiveMind-voice-relay

60-second quickstart

1. Configure identity (one-time):

hivemind-client set-identity --key YOUR_ACCESS_KEY --password YOUR_PASSWORD --host wss://your-hivemind-host

2. Run:

hivemind-voice-relay

3. Speak your wake word. The default wake word is hey mycroft (configured in ~/.config/mycroft/mycroft.conf).

CLI flags

Usage: hivemind-voice-relay [OPTIONS]

  connect to hivemind-core running the audio binary protocol

Options:
  --host TEXT      hivemind host (ws:// or wss://)
  --key TEXT       Access Key
  --password TEXT  Password for key derivation
  --port INTEGER   HiveMind port number (default: 5678)
  --selfsigned     Accept self-signed TLS certificates
  --siteid TEXT    Location identifier for message context
  --help           Show this message and exit.

All flags fall back to values stored by hivemind-client set-identity.

Configuration

Voice Relay reads ~/.config/mycroft/mycroft.conf (standard OVOS config).

See docs/configuration.md for full details and plugin swap instructions.

Features and limitations

Built on ovos-simple-listener. Compared to the full voice-satellite:

Present:

• Microphone capture, VAD, and wakeword detection, all local
• Audio forwarded to hivemind-core (hivemind-audio-binary-protocol plugin) for STT, over base64-encoded WAV or the binary protocol (configurable, see below)
• TTS audio synthesised server-side and streamed back for local playback, over the same choice of transports
• PHAL (platform hardware abstraction) auto-loaded if installed
• Standard OVOS plugin system for mic, VAD, and wakeword

Not supported (use HiveMind-voice-sat if you need these):

• Local STT / TTS plugins
• Continuous / Hybrid / Recording / Sleep listening modes
• Multiple wake words

Related

Development

Install from source with the end-to-end test extra, then run the suite:

uv pip install -e ".[e2e]"
pytest tests/

pyproject.toml is the single packaging source of truth. The E2E suite runs a real hivemind-core master in-process and the real relay client over a real HiveMessageBusClient, with the microphone/wakeword and the remote STT/TTS endpoints mocked. See docs/development.md.

License

Apache-2.0

Transformer pipelines

The relay can run OVOS transformer plugins on-device, configured in this device's mycroft.conf:

• audio_transformers — applied to captured speech before it is sent to the server for STT (e.g. denoise).
• utterance_transformers — applied to the transcript before it is emitted as recognizer_loop:utterance; a plugin cancellation (OVOS-TRANSFORM §8.1) drops the utterance.
• tts_transformers — applied to received TTS audio before playback (e.g. per-device sound effects).

STT and TTS transport

Each direction of audio hand-off between Voice Relay and hivemind-core has its own transport, set independently in mycroft.conf:

{
  "stt_transport": "b64",
  "tts_transport": "b64"
}

Both keys default to b64: the utterance recorded locally is sent as base64-encoded WAV over recognizer_loop:b64_transcribe, and synthesized speech comes back the same way over speak:b64_audio. This is the transport every prior release used, and it stays the default because it is the simplest to reason about and to reproduce in a demo — plain JSON, nothing binary to inspect.

Setting either key to binary switches that direction to the HiveMind binary protocol instead: raw PCM sent as a STT_AUDIO_TRANSCRIBE frame for STT, and the WAV file returned as a TTS_AUDIO frame for TTS. Binary transport skips the ~33% size increase base64 adds and the extra JSON framing, so prefer it on bandwidth-constrained links or when running many satellites against one hivemind-core instance. The two keys are independent — for example STT can stay on b64 while TTS moves to binary, or vice versa.

Loading is opt-in: a plugin only runs if named in its section. Avoid double-processing: if the HiveMind server or the OVOS agent behind it enables the same pipeline, data gets processed twice — enable each plugin on exactly one side.