HiveMind Voice Relay
September 4, 2026 · View on GitHub
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
| Satellite | Mic | VAD | Wake word | STT | TTS | Connects to |
|---|---|---|---|---|---|---|
| HiveMind-cli | n/a | n/a | n/a | n/a | n/a | hivemind-core |
| hivemind-mic-satellite | local | local | server | server | server | core + audio-binary-protocol |
| HiveMind-voice-relay (this repo) | local | local | local | server | server | core + audio-binary-protocol |
| HiveMind-voice-sat | local | local | local | local | local | hivemind-core |
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-serverorovos-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-coreserver must have the hivemind-audio-binary-protocol binary plugin installed. Plainhivemind-coredoes not handle STT or TTS. Connecting to it results in silence: no transcription and no spoken response.Alternatively, run
hivemind-coretogether withovos-audioandovos-dinkum-listenerto 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).
| Plugin type | Config key | Default | Required |
|---|---|---|---|
| Microphone | microphone.module | ovos-microphone-plugin-alsa | Yes |
| VAD | listener.VAD.module | ovos-vad-plugin-silero | Yes |
| Wake word | listener.wake_word | hey_mycroft | Yes |
| G2P | tts.g2p_module | n/a | No |
| Media Playback | Audio.backends | n/a | No |
| OCP Plugins | n/a | n/a | No |
| Dialog Transformers | n/a | n/a | No (server-side only) |
| Audio Transformers | audio_transformers | n/a | No |
| Utterance Transformers | utterance_transformers | n/a | No |
| TTS Transformers | tts_transformers | n/a | No |
| STT transport | stt_transport | b64 | No |
| TTS transport | tts_transport | b64 | No |
| PHAL | n/a | n/a | No (auto-loaded if installed) |
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
| Project | Role |
|---|---|
| hivemind-audio-binary-protocol | Required hivemind-core plugin, provides server-side STT and TTS |
| hivemind-core | Base mesh node (no STT/TTS) |
| HiveMind-cli | Text-only satellite |
| hivemind-mic-satellite | Thinnest audio satellite (no local wakeword) |
| HiveMind-voice-sat | Full local stack satellite |
| hivemind-bus-client | HiveMind WebSocket client library |
| ovos-simple-listener | Lightweight listener library used internally |
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
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 asrecognizer_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.