Skip to content

Glossary

voice-gateway-bot edited this page May 25, 2026 · 1 revision

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.

afterPack hook

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.

Ad-hoc signature

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.

Barge-in

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.

Bridge

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.

Capability negotiation

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.

Cooldown (wake word)

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.

Designated Requirement (DR)

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.

FSM

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.

Hermes

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.

IPC

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.

minAudioMs

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.

onTtsChunk

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.

openWakeWord

The wake-word detection library by dscripka. We run it inside wake_word_runner.py. See Wake-Word-Detection.

Pairing

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.

PCM16

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.

Piper

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.

Preload script

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.

PTT

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.

Reducer environment (ReducerEnv)

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.

Rest state

The "no conversation in flight" state: IDLE in PTT mode, LISTENING_WAKE in wake-word mode. Computed by restState(mode). See State-Machine#states.

Sandboxed renderer

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.

SSE

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.

Sticky disconnect

HermesClient.disconnect() sets explicitDisconnect = true which short-circuits the reconnect loop. The next connect() call clears the flag. See WebSocket-Client#lifecycle.

TCC

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.

Turn ID

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.

useConversation

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.

VAD

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.

WakeWord

A discriminated union type in shared/constants.ts listing the openWakeWord model names we support (hey_jarvis, alexa, hey_mycroft, hey_rhasspy, computer).

Welcome

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.

Whisper

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

Getting started

Architecture

Audio

Server

Platform

Project


Clone this wiki locally