Repository navigation
IPC Layer
The Electron IPC surface between the main process (services, WebSocket, audio adapters) and the renderer (React UI, microphone, speakers). Designed around three rules:
-
Sandboxed renderer. The renderer runs with
contextIsolation: trueandsandbox: true. The only API it sees is whatevercontextBridge.exposeInMainWorld('vg', api)exposes from the preload script — no directipcRenderer, no Node. -
Typed channels. Every channel name lives in
shared/constants.tsunder theIPCobject. The preload and the main process both import the same enum so a rename is a single edit. -
One direction per channel. A request/response uses
ipcMain.handle+ipcRenderer.invoke. A push-from-main useswebContents.send+ipcRenderer.on. We never overload a channel with both.
Source:
src/preload/index.ts (the contextBridge surface),
src/main/ipc-handlers.ts (the
request/response handlers), and
src/main/index.ts
(the push-from-main webContents.send calls).
flowchart LR
subgraph Renderer["Renderer (sandboxed)"]
React[React UI]
Hook[useConversation hook]
Settings[useSettings hook]
end
subgraph Preload["Preload (CJS, contextBridge)"]
Api[window.vg API]
end
subgraph Main["Main process (Node)"]
Handlers[ipc-handlers.ts]
Orch[Orchestrator]
Store[SettingsStore]
Stt[STT/TTS prepare]
end
React --> Hook --> Api
Api -- ipcRenderer.invoke --> Handlers
Api -- ipcRenderer.send --> Orch
Orch -- webContents.send --> Api
Store -- onChange<br>webContents.send --> Api
Stt -- send STT_STATUS / TTS_STATUS --> Api
Handlers --> Store
Handlers --> Orch
All channels are prefixed vg: for grep-ability.
| Channel | Kind | Direction | Payload | Purpose |
|---|---|---|---|---|
vg:ping |
invoke |
renderer → main | — | Returns 'pong'. Used by E2E to confirm the preload bridge is alive. |
| Channel | Kind | Direction | Payload |
|---|---|---|---|
vg:settings:get |
invoke |
renderer → main | → Settings
|
vg:settings:set |
invoke |
renderer → main |
Partial<Settings> → Settings
|
vg:settings:reset |
invoke |
renderer → main | → Settings
|
vg:settings:changed |
send |
main → renderer | Settings |
vg:settings:open-window |
send |
renderer → main | — |
vg:settings:changed is broadcast to every open BrowserWindow
(see registerIpcHandlers → settings.onChange). The main window AND
the Settings window both stay in sync with the persisted state.
| Channel | Kind | Direction | Payload |
|---|---|---|---|
vg:pair:test |
invoke |
renderer → main |
PairingInfo → PairTestResult
|
vg:pair:save |
invoke |
renderer → main |
PairingInfo → PairTestResult
|
The save variant tests first, persists on success. Errors map to
friendly Portuguese messages in
testPairing.
| Channel | Kind | Direction | Payload |
|---|---|---|---|
vg:connection:status |
send |
main → renderer | { status, latencyMs, lastError } |
Emitted on every 'status' event from
[[WebSocket-Client|HermesClient]] (connecting → connected → error etc).
Push-to-talk and command channels are send-only because they're intentionally fire-and-forget:
| Channel | Direction | Payload | Effect |
|---|---|---|---|
vg:conv:ptt:press |
renderer → main | — | orchestrator.pttPress() |
vg:conv:ptt:release |
renderer → main | — | orchestrator.pttRelease() |
vg:conv:audio-frame |
renderer → main | ArrayBuffer |
orchestrator.pushAudio(buf) |
vg:conv:cancel |
renderer → main | — | orchestrator.cancel() |
vg:conv:barge-in |
renderer → main | — | orchestrator.bargeIn() |
vg:conv:reset |
renderer → main | — | orchestrator.reset() |
Conversation events go the other way:
| Channel | Direction | Payload |
|---|---|---|
vg:conv:state |
main → renderer | ConversationContext |
vg:conv:transcript |
main → renderer | { text, turnId, role: 'user' | 'assistant' } |
vg:conv:response-text |
main → renderer | { text, final, turnId } |
vg:conv:tts-chunk |
main → renderer | { seq, format, turnId, data: base64 } |
vg:conv:error |
main → renderer | { code, message } |
vg:conv:warning |
main → renderer | { code, message } |
Why base64 for tts-chunk? webContents.send serialises payloads
with the structured clone algorithm, which supports ArrayBuffer
natively, but electron-store and the React DevTools both have trouble
displaying raw binary in transit. base64 trades 33% size for a sane
debug story — for a 30 ms PCM chunk at 22 050 Hz (~1.3 kB), the inflation
is negligible compared to the latency of going through React state.
| Channel | Kind | Payload |
|---|---|---|
vg:audio:mic-status |
invoke |
→ 'granted' | 'denied' | 'restricted' | 'not-determined' | 'unknown'
|
vg:audio:mic-request |
invoke |
→ boolean (true = user granted) |
vg:audio:open-mic-settings |
invoke |
→ boolean (true on macOS only) |
mic-status calls systemPreferences.getMediaAccessStatus('microphone')
on macOS, returns 'granted' everywhere else. open-mic-settings
shells out to
x-apple.systempreferences:com.apple.preference.security?Privacy_Microphone
so the user lands directly on the right pane.
| Channel | Kind | Direction | Payload |
|---|---|---|---|
vg:stt:status |
send |
main → renderer | { state: 'idle' | 'preparing' | 'ready' | 'error', progress?, message? } |
vg:stt:prepare |
invoke |
renderer → main | → { ok, message? } — force a re-check (e.g. user just brew install-d whisper) |
vg:tts:status |
send |
main → renderer | same shape as STT |
vg:tts:prepare |
invoke |
renderer → main | → { ok, message? }
|
vg:tts:list-voices |
invoke |
renderer → main |
{ provider: 'elevenlabs', apiKey } → { ok, voices, message? }
|
vg:tts:test |
invoke |
renderer → main |
TestVoiceRequest → { ok, message? } — used by the Settings → Voz "Test" button |
vg:audio:test-tts-chunk |
send |
main → renderer |
{ seq, format, data: base64, done? } — chunks from the test-voice call so the same playback layer plays |
| Channel | Kind | Direction | Payload |
|---|---|---|---|
vg:hotkey:trigger |
send |
main → renderer | 'press' | 'release' |
Emitted from globalShortcut in
src/main/global-shortcut.ts.
Today the renderer treats this purely as a UI flash hint (state-driven
buttons do the real work).
| Channel | Kind | Direction | Payload |
|---|---|---|---|
vg:wake:status |
send |
main → renderer |
{ running, models? } or { error }
|
vg:wake:detected |
send |
main → renderer | (reserved — used by the tray today) |
The preload script is the only code with both ipcRenderer access
and access to window. It exposes a typed vg namespace via
contextBridge.exposeInMainWorld:
// src/preload/index.ts (excerpt)
const api = {
settings: {
get: () => ipcRenderer.invoke(IPC.SETTINGS_GET),
set: (patch) => ipcRenderer.invoke(IPC.SETTINGS_SET, patch),
onChange: (cb) => on(IPC.SETTINGS_CHANGED, cb),
...
},
conversation: {
pttPress: () => ipcRenderer.send(IPC.CONV_PTT_PRESS),
pttRelease: () => ipcRenderer.send(IPC.CONV_PTT_RELEASE),
sendAudioFrame: (frame: ArrayBuffer) => ipcRenderer.send(IPC.CONV_AUDIO_FRAME, frame),
onTtsChunk: (cb) => on(IPC.CONV_TTS_CHUNK, cb),
...
},
...
};
contextBridge.exposeInMainWorld('vg', api);Notes:
-
on()is a tiny helper that wrapsipcRenderer.onand returns an unsubscribe function — the preload never lets the renderer touch the rawIpcRendererEvent(which leakssenderreferences). - The preload is CommonJS (
index.cjs). electron-vite bundles it withformat: 'cjs'because Electron's sandbox + ESM combination doesn't fully work yet — see Build-And-Packaging.
The Settings panel lives in a separate BrowserWindow. To keep both
windows in sync, the main process broadcasts events to every open
window via this helper:
function send(channel: string, payload: unknown): void {
for (const win of BrowserWindow.getAllWindows()) {
if (!win.isDestroyed()) win.webContents.send(channel, payload);
}
}That's why opening Settings while a turn is in flight doesn't lose
state — the freshly-opened window receives the next CONV_STATE,
STT_STATUS, TTS_STATUS tick like any other.
The Settings window also receives a one-shot snapshot on
ready-to-show so its UI never starts in a "preparing…" placeholder
state.
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