Repository navigation
Glossary
Domain-specific terms you'll see across the wiki, in alphabetical order. Cross-linked back to the page where the concept is explained in depth.
The Node.js script at
build/after-pack.cjs
that runs after electron-builder packs the app and before it produces
the .dmg. Patches helper Info.plists and re-signs the bundle
ad-hoc — see Build-And-Packaging#macos-code-signing.
codesign --sign - — a code signature with no identity, so no Apple
Developer ID required. Provides a stable Designated Requirement
across rebuilds, which keeps macOS TCC permission grants alive. See
macOS-Permissions#ad-hoc-signing-and-the-tcc-cache.
When the user starts speaking while the assistant is still talking,
cancelling TTS playback and immediately opening the mic for a new
turn. Implemented as USER_INTERRUPT { reason: 'barge_in' } in the
State-Machine; the orchestrator's
Conversation-Orchestrator#barge-in
prevents a race with synchronous TTS adapters.
The Python aiohttp server at
server/hermes-voice-bridge/
that translates the desktop's WebSocket protocol to Hermes' HTTP API.
Full deep-dive at Hermes-Voice-Bridge.
The hello / welcome exchange where the client advertises features
it supports (barge_in, streaming_audio, etc) and the server replies
with its own capabilities. The intersection drives whether STT runs
client-side or server-side, for instance. See
Protocol#capability-negotiation.
A per-model dead-time (default 1.5 s) after a successful wake
detection during which subsequent triggers for the same model are
suppressed. Prevents one utterance from firing the detector five
times in a row. Implemented in
wake_word_runner.py.
A code-signing fingerprint that macOS' TCC uses to identify "the same app" across rebuilds. If the DR changes, granted permissions evaporate. We use ad-hoc signing to keep it stable. See macOS-Permissions.
Finite-State Machine. Voice Gateway's conversation logic is a pure
reducer over (state, event) → state'. Source at
src/shared/state-machine.ts,
documented at State-Machine.
The agent server at
https://hermes-agent.nousresearch.com/. The thing we're talking to.
The bridge POSTs to its /v1/chat/completions endpoint and forwards
the streamed reply back to the desktop.
Inter-Process Communication. Electron's mechanism for the renderer
process to call into the main process and vice versa. We use
ipcRenderer.invoke / ipcMain.handle for request/response and
webContents.send / ipcRenderer.on for push-only events. Full
channel map at IPC-Layer.
Per-user threshold for the minimum captured audio duration before we send to STT. Default 300 ms, configurable in Ativação. Filters accidental button taps. See Conversation-Orchestrator#audio-buffering-the-currentTurnAudio-deque.
The orchestrator-internal callback that forwards TTS chunks from the
local adapter to the renderer over vg:conv:tts-chunk. Guarded by
pendingTtsTurnId so chunks from a dying-process tail-fire are
dropped. See
conversation-orchestrator.ts.
The wake-word detection library by
dscripka. We run it inside
wake_word_runner.py.
See Wake-Word-Detection.
The (URL, token) pair that authenticates a desktop client to a
specific bridge. The token is a base64url 32-byte secret generated by
install.sh and stored in /etc/hermes-voice-bridge/config.toml on
the server and in electron-store on the client. See
Setup#step-3--first-run.
16-bit signed integer linear-PCM audio samples, the de-facto format for
Whisper and Piper. We carry it as pcm16_16khz (mic capture, STT
input) and pcm16_22050 (Piper output) / pcm16_24khz (server-side
TTS). See Audio-Pipeline.
A neural TTS that runs on CPU. The default local TTS provider.
Auto-installed via a Python venv at <userData>/piper/venv on first
use. See Text-To-Speech#piper-local-default.
The CommonJS bundle at out/preload/index.cjs that runs in a
privileged context between the main process and the sandboxed
renderer. The only place that can both require('electron') and call
contextBridge.exposeInMainWorld. See IPC-Layer#the-preload-contract.
Push-to-Talk. The default activation mode: the mic only opens while you hold the on-screen button or press the global hotkey. Configurable to wake-word mode in Ativação. See State-Machine#states.
A small object containing side-effectful helpers (like
newTurnId: () => crypto.randomUUID()) injected into the pure FSM
reducer. Tests pass a deterministic counter; production wires
defaultEnv. Keeps the reducer pure while still allowing for unique
turn IDs. See State-Machine#determinism-the-reducerenv.
The "no conversation in flight" state: IDLE in PTT mode,
LISTENING_WAKE in wake-word mode. Computed by restState(mode). See
State-Machine#states.
An Electron BrowserWindow with sandbox: true and
contextIsolation: true. The renderer can't require('node:...')
and can't access ipcRenderer directly — everything goes through
the preload's contextBridge surface.
Server-Sent Events. The format Hermes streams chat-completion deltas
in: data: {...}\n\n lines terminated by data: [DONE]\n\n. Parsed
by
_iter_sse_deltas
in the bridge. See Hermes-Voice-Bridge#the-sse-parser.
HermesClient.disconnect() sets explicitDisconnect = true which
short-circuits the reconnect loop. The next connect() call clears
the flag. See WebSocket-Client#lifecycle.
Transparency, Consent, and Control — macOS' framework for tracking which apps the user has granted access to mic, camera, etc. Permissions are bound to the bundle's Designated Requirement; an unsigned build "loses" permissions on every rebuild. See macOS-Permissions.
A UUID-shaped identifier minted by the FSM at the start of each
conversation turn (on PTT_PRESS / WAKE_DETECTED / barge_in).
Threaded through every message and event for the turn — makes
multi-turn debugging tractable. See State-Machine#context-shape.
The React hook in
src/renderer/hooks/useConversation.ts
that owns the call experience: state subscription, audio capture
lifecycle, playback wiring. Used by MainScreen. See
Renderer-UI#useconversation.
Voice Activity Detection. The mechanism that decides when the user
has stopped talking in wake-word mode. Currently a stub event
(VAD_SILENCE) in the FSM; not wired through to a real detector
yet. See State-Machine#events.
A discriminated union type in
shared/constants.ts
listing the openWakeWord model names we support (hey_jarvis,
alexa, hey_mycroft, hey_rhasspy, computer).
The first server-sent message after the WS upgrade, carrying
session_id, server_version, and capabilities. The desktop
client only marks itself "connected" once it receives this. See
Protocol#welcome.
The OpenAI speech-to-text model family. We support whisper.cpp
locally (tiny / base / small GGML models) and the hosted
OpenAI Whisper API. See Speech-To-Text.
Voice Gateway — VivaldiCode/voice-gateway. MIT licensed. Wiki sources live under docs/; run ./docs/sync-wiki.sh to publish.
Getting started
Architecture
- Architecture — system overview
- State-Machine — conversation FSM
- Conversation-Orchestrator — main glue
- WebSocket-Client — Hermes connection
- IPC-Layer — main ↔ renderer
- Settings-And-Storage — config persistence
Audio
- Audio-Pipeline — capture & playback
- Speech-To-Text — STT adapters
- Text-To-Speech — TTS adapters
- Wake-Word-Detection — openWakeWord
Server
- Hermes-Voice-Bridge — Python bridge
- Protocol — WebSocket spec
Platform
- Build-And-Packaging — electron-builder
- macOS-Permissions — TCC, signing
- Renderer-UI — React components
Project
- Testing-Guide — unit, integration, E2E
- Development-Guide — contributing
- Glossary — terms