Voice Relay

Runs microphone, VAD, and wakeword detection locally. Forwards audio to the hub after the wakeword triggers — STT and TTS synthesis run on the hub.

What runs locally: Microphone + VAD + Wakeword

What the hub provides: STT, TTS (requires hivemind-audio-binary-protocol on the hub)

When to use it

• Devices with enough CPU for a wakeword engine (Raspberry Pi 3/4, similar)
• Deployments where you want STT/TTS to be centrally governed (HiveMind as a service)
• Scenarios where audio should not leave the device until activation (latency + privacy)
• Multi-user or at-scale service deployments

The service model

Voice-relay's architecture has a specific meaning: STT and TTS run inside the hive (the hivemind-audio-binary-protocol plugin on hivemind-core) and are gated by the same access-key authentication as all other HiveMind messages. The hub operator chooses the STT engine, TTS engine, and voice. A relay satellite cannot override them.

This is the difference from voice-sat: a voice-sat can point at any STT/TTS plugin it likes. A relay cannot.

Install

pip install HiveMind-voice-relay

Hub requirements

The hub must have hivemind-audio-binary-protocol installed and configured. Alternatively, run hivemind-core together with ovos-audio and ovos-dinkum-listener to provide equivalent capabilities.

See Audio Binary Protocol.

Quickstart

1. On the hub — register a client:

hivemind-core add-client --name my-voice-relay

2. On the satellite — write the identity file:

hivemind-client set-identity \
  --key <access_key> \
  --password <password> \
  --host <hub_host>

3. Run:

hivemind-voice-relay

4. Say your wake word. Default is hey mycroft (configured in ~/.config/mycroft/mycroft.conf).

CLI flags

Usage: hivemind-voice-relay [OPTIONS]

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

Configuration

voice-relay reads ~/.config/mycroft/mycroft.conf.

Plugin type	Config key	Required
Microphone	listener.microphone.module	Yes
VAD	listener.VAD.module	Yes
Wakeword	listener.wake_word	Yes
G2P	g2p.module	No
Media playback	various	No
PHAL	PHAL.ovos-phal-...	No

How audio flows

[Microphone] → [VAD] → [Wakeword detector]
                              ↓ (after activation)
                    audio chunk → [HiveMind Hub]
                                       ↓
                             [hivemind-audio-binary-protocol]
                                       ↓
                               STT → IntentService
                                       ↓
                               TTS synthesis → audio
                                       ↓
                              [Satellite plays TTS audio]

After the wakeword triggers, audio is sent as base64-encoded audio via recognizer_loop:b64_transcribe. TTS audio comes back via speak:b64_audio.