Skip to content

Voice Gateway 0.1.0 — first release

Choose a tag to compare

@VivaldiCode VivaldiCode released this 26 May 09:14
· 17 commits to main since this release
45eac57

First public release of Voice Gateway — a local-first desktop voice client for the Hermes agent. Push-to-talk or wake-word in, streaming text + speech out, with your choice of STT/TTS backends and no telemetry.

What's in this release

Core voice loop

  • Push-to-talk with a configurable global hotkey (default Cmd+Shift+H on macOS, Ctrl+Shift+H elsewhere)
  • Wake-word activation powered by openWakeWord — bundled "Hey Jarvis" model plus custom-phrase training via the Settings UI
  • Cancel mid-utterance — Escape or the visible cancel button stops capture and returns to IDLE
  • Barge-in — speaking over the bot interrupts TTS and starts a new turn

Conversation surface

  • Live transcript pane with user/assistant alternation, copy-to-clipboard, turn counter, export to file (Cmd+S), clear (Cmd+L), and persistence of the last 20 turns across restarts
  • State orb in the header reflects the FSM state (IDLE / CAPTURING / THINKING / SPEAKING / ERROR)
  • Minimalist mic + speaker pickers in the main header for quick device switching
  • Connection indicator with retry counter; click to reconnect immediately
  • Error toast with "Copy diagnostic" button, "Try again" action, auto-dismiss after 4 s
  • Tray menu with Show window / Open Settings / Quit

STT (speech-to-text) backends

  • Whisper local via whisper.cpp — auto-detects the whisper-cli binary on PATH, auto-downloads ggml-base.bin from Hugging Face on first use
  • OpenAI Whisper API — bring your own key
  • 30 s default transcription timeout (configurable)
  • Live-swap STT providers without restart

TTS (text-to-speech) backends

  • Piper local — auto-creates a Python venv on first use and pulls the piper-tts wheel
  • ElevenLabs API — bring your own key
  • 30 s / 60 s default synthesis timeouts (configurable)
  • Voice mute toggle in the header

Pairing & settings

  • Pairing wizard with 3 steps + back/cancel/step indicator, URL history (last 3), draft persistence, server-version probe, masked token field with whitespace-trim on paste
  • Five-tab Settings panel: Connection · Recognition · Voice · Activation · Advanced
  • Live updates — changing a setting in Settings reaches the orchestrator without a restart
  • Settings persistence + factory reset button in Advanced
  • Auto-launch on login toggle
  • Live log preview for debugging from inside Settings

Bridge / server side

  • Companion Python service at server/hermes-voice-bridge (aiohttp WebSocket bridge to a Hermes agent)
  • One-line install.sh for systemd setup
  • HTTP /healthz + bridge /ws endpoint
  • WebSocket reconnect with bounded exponential backoff (~16 s cap)
  • Auto-reconnect on window focus

macOS specifics

  • Apple Silicon arm64 DMG
  • Hardened runtime + ad-hoc codesign in afterPack — keeps the bundle's Designated Requirement stable across rebuilds so the user's microphone permission grant survives an update
  • NSMicrophoneUsageDescription injected into the helper bundles so getUserMedia actually surfaces a prompt
  • Resource-fork cleanup in the bundle (defends against ._* AppleDouble files breaking codesign)

Quality

  • Branch protection on main with required status checks (lint+typecheck, vitest matrix Node 20/22, Playwright E2E, Pytest, CodeQL) and enforce_admins: true
  • CodeQL scans on every PR + weekly
  • Dependabot weekly grouped updates for npm, pip, github-actions
  • SHA-pinned GitHub Actions
  • SECURITY.md with disclosure policy
  • Build doctor pre-flight (tools/build-doctor.cjs) — catches a corrupted-node_modules failure mode before electron-vite build wastes 6 s on a doomed run
  • vitest unit suite (incl. settings-store v1→v2 migration test, state-machine coverage, protocol fuzz, timeout helpers)
  • Playwright E2E suite covering: pairing, multi-turn, cancel, barge-in, reconnect, factory reset, hotkey rebind, settings live-update, output-device live-switch, backpressure under many audio chunks, capability negotiation, wake-word validation, and ~20 more
  • Pytest suite for the Python bridge + wake-word runner

Documentation

  • Full GitHub Wiki auto-synced from docs/ on every merge to main
  • Pages: Home, Architecture, Audio Pipeline, Build & Packaging, Conversation Orchestrator, Development Guide, Glossary, Hermes Voice Bridge, IPC Layer, Protocol, Renderer UI, Settings & Storage, Setup, Speech-To-Text, State Machine, Testing Guide, Text-To-Speech, Troubleshooting
  • GitHub Pages landing page

Install

  1. Download Voice Gateway-0.1.0-arm64.dmg from this release
  2. Open the DMG, drag Voice Gateway.app to Applications
  3. The DMG is ad-hoc signed (no Apple Developer ID). First launch needs the Gatekeeper override: right-click the app in Finder → Open → confirm
  4. Grant microphone permission when prompted (System Settings → Privacy → Microphone)
  5. Run the pairing wizard with your Hermes bridge URL + token

See docs/Setup.md for a fuller walkthrough.

Known limitations

  • macOS arm64 only in this release. Linux AppImage and Windows NSIS builds work from source (npm run build:linux / :win) but aren't published here yet — see issue #46 (React 19) and #45 (Vite 8 / Electron 39) for the upcoming coordinated upgrade work that will unlock the CI matrix.
  • No Apple Developer ID — the DMG is ad-hoc signed. Right-click → Open the first time.
  • Piper local TTS resources aren't bundled in the DMG. The app auto-installs them into <userData>/piper/venv on first Piper use, which needs Python 3.10+ on PATH. ElevenLabs works out of the box with an API key.
  • Whisper local STT binary isn't bundled either — brew install whisper-cpp or follow docs/Troubleshooting.md to point at a custom build. OpenAI Whisper API works out of the box with a key.

Verify the download

shasum -a 256 "Voice Gateway-0.1.0-arm64.dmg"
# Expected: cdb327dc5289a391679f0777cf0bf3aa2f97a5cc3c849d3ad00ba1a691ffa6b4

(If the upstream CI build replaces this asset, the SHA will differ — re-check against this release's checksum file once the workflow finishes.)

What's next

Tracked in open issues:

  • #45 — coordinated upgrade: Vite 8 + Electron 39 + @vitejs/plugin-react 6
  • #46 — React 19 migration
  • #47 — Dependabot config: skip majors on locked packages until #45 / #46 land
  • #48 — closed by the build-doctor change shipped in this release

Thanks for trying it. Bug reports + feature requests welcome via Issues.

— The Voice Gateway team