From 17dc350a6b47b8844b014b9e2fa0812e295e3d45 Mon Sep 17 00:00:00 2001 From: Brooklyn Nicholson Date: Thu, 23 Jul 2026 01:48:25 -0500 Subject: [PATCH] docs(voice): document the wake word feature Adds the wake-word user guide (setup, config, per-engine phrase changes, requirements, limits) and links it from the features overview. --- website/docs/user-guide/features/overview.md | 1 + website/docs/user-guide/features/wake-word.md | 173 ++++++++++++++++++ 2 files changed, 174 insertions(+) create mode 100644 website/docs/user-guide/features/wake-word.md diff --git a/website/docs/user-guide/features/overview.md b/website/docs/user-guide/features/overview.md index 75f365b38924..cb3eef221099 100644 --- a/website/docs/user-guide/features/overview.md +++ b/website/docs/user-guide/features/overview.md @@ -32,6 +32,7 @@ Hermes Agent includes a rich set of capabilities that extend far beyond basic ch ## Media & Web - **[Voice Mode](voice-mode.md)** — Full voice interaction across CLI and messaging platforms. Talk to the agent using your microphone, hear spoken replies, and have live voice conversations in Discord voice channels. +- **[Wake Word](wake-word.md)** — Hands-free "Hey Hermes" trigger for the CLI. An on-device hotword listener starts a fresh voice session when you speak the wake phrase, the "Hey Siri" way. - **[Browser Automation](browser.md)** — Full browser automation with multiple backends: Browserbase cloud, Browser Use cloud, local Chrome/Brave/Chromium/Edge via CDP, or local Chromium. Navigate websites, fill forms, and extract information. - **[Vision & Image Paste](vision.md)** — Multimodal vision support. Paste images from your clipboard into the CLI and ask the agent to analyze, describe, or work with them using any vision-capable model. - **[Image Generation](image-generation.md)** — Generate images from text prompts using FAL.ai. Eleven models supported (FLUX 2 Klein/Pro, GPT-Image 1.5/2, Nano Banana Pro, Ideogram V3, Recraft V4 Pro, Qwen, Z-Image Turbo, Krea V2 Medium/Large); pick one via `hermes tools`. diff --git a/website/docs/user-guide/features/wake-word.md b/website/docs/user-guide/features/wake-word.md new file mode 100644 index 000000000000..f4a48c7bd3ed --- /dev/null +++ b/website/docs/user-guide/features/wake-word.md @@ -0,0 +1,173 @@ +--- +sidebar_position: 11 +title: "Wake Word" +description: "Hands-free 'Hey Hermes' wake word — start a voice session by speaking, the 'Hey Siri' way" +--- + +# Wake Word ("Hey Hermes") + +The wake word turns Hermes into a hands-free assistant across the CLI, TUI, and +desktop app: with one setting on, Hermes listens in the background for a spoken +trigger phrase. Say it, and Hermes starts a fresh session, opens the microphone, +captures your command via the normal [voice pipeline](/user-guide/features/voice-mode), +and answers — exactly like "Hey Siri" or "Alexa". Use `surface` to pick which +one listens. + +Detection runs **entirely on-device**. The always-on listener only watches for +the wake phrase; no audio leaves your machine until you actually speak a command +to the agent. + +## How it works + +1. With `wake_word.enabled: true` (or after `/wake on`), a lightweight hotword + detector listens on your default microphone. +2. When it hears the wake phrase it pauses itself (freeing the mic), starts a new + session, and records one utterance with voice mode's silence detection. +3. Your speech is transcribed and sent to the agent. After it replies, the + listener resumes automatically and waits for the next wake word. + +It is **off by default** — nothing listens until you turn it on. + +## Engines + +| Engine | Cost | API key | Notes | +|--------|------|---------|-------| +| **openWakeWord** (default) | Free | None | Local ONNX models. Ships a bundled **"hey hermes"** model (default); also supports `hey_jarvis`, `alexa`, `hey_mycroft`, … and custom models | +| **Porcupine** | Free tier / paid | `PORCUPINE_ACCESS_KEY` | Picovoice engine; built-in keywords + custom `.ppn` files | + +By default the phrase is **"hey hermes"** — a model for it ships with Hermes, so +it works out of the box with no training. (On first use, openWakeWord downloads +its shared feature-extraction models — a small one-time fetch.) + +Both are lazy-installed the first time you enable the wake word. To install ahead +of time: + +```bash +uv pip install 'hermes-agent[wake]' # or: pip install 'hermes-agent[wake]' +``` + +## Quick start + +```bash +# In an interactive `hermes` session: +/wake on # start listening (installs the engine on first use) +/wake status # show phrase, provider, and state +/wake off # stop listening +``` + +Or enable it permanently in `~/.hermes/config.yaml`: + +```yaml +wake_word: + enabled: true +``` + +## Configuration + +```yaml +wake_word: + enabled: false + surface: auto # which surface owns the listener: "auto" | "cli" | "tui" | "gui" + provider: openwakeword # "openwakeword" (free, local) | "porcupine" + phrase: "hey hermes" # cosmetic label only — detection is keyed by the model/keyword below + sensitivity: 0.5 # 0.0-1.0 — raise to reduce false triggers + start_new_session: true # start a fresh session on wake vs. continue the current one + openwakeword: + model: hey_hermes # bundled default; OR a built-in name OR a path to a custom .onnx/.tflite + inference_framework: onnx # "onnx" | "tflite" + porcupine: + keyword: jarvis # built-in keyword OR path to a custom .ppn +``` + +`sensitivity`, `phrase`, and `start_new_session` apply to both engines. The +`openwakeword` and `porcupine` blocks select the actual detection model. + +### Surfaces (CLI, TUI, GUI) + +The wake word works in all three Hermes surfaces, and `surface` picks which one +owns the listener and opens the new session when it fires: + +| `surface` | Behavior | +|-----------|----------| +| `auto` (default) | Whichever surface you launch arms the listener. | +| `cli` | Only the classic `hermes` CLI. | +| `tui` | Only `hermes --tui`. | +| `gui` | Only the desktop app. | + +The detector is on-device and single-mic, so only one surface listens at a time +— `surface` is how you pin it. The TUI and desktop GUI share the same Python +backend (`tui_gateway`), which runs the detector server-side and yields the mic +to voice capture while a command records. + +## Using a different phrase + +"Hey Hermes" works out of the box — the bundled openWakeWord model +(`model: hey_hermes`) is the default. To wake on something else, either name a +built-in openWakeWord model or supply your own. + +### Option A — openWakeWord (free) + +Use a built-in name, or train a custom model (≈75–90 min on a free/Colab GPU), +drop the `.onnx` somewhere, and point the config at it: + +```yaml +wake_word: + enabled: true + provider: openwakeword + phrase: "hey jarvis" # cosmetic label + openwakeword: + model: hey_jarvis # built-in name + # model: ~/.hermes/wakewords/my_phrase.onnx # …or a custom model path +``` + +Training references: + +- [openWakeWord](https://github.com/dscripka/openWakeWord) +- [2026 training Colab](https://github.com/alfiedennen/openwakeword-colab-2026) + +:::tip Pick a distinctive phrase +Wake phrases that don't collide with everyday speech generalize best. Two +syllables with an uncommon word ("hermes" qualifies) beat common words like +"hello" or "stop". +::: + +### Option B — Porcupine (custom keyword in seconds) + +Create a "Hey Hermes" keyword in the [Picovoice Console](https://console.picovoice.ai/), +download the `.ppn`, and: + +```yaml +wake_word: + enabled: true + provider: porcupine + phrase: "hey hermes" + porcupine: + keyword: ~/.hermes/wakewords/hey_hermes.ppn +``` + +Set your access key in `~/.hermes/.env`: + +```bash +PORCUPINE_ACCESS_KEY=your-key-here +``` + +## Requirements + +- A working microphone and the `sounddevice` + `numpy` audio stack (shared with + voice mode). +- An STT provider for transcribing the spoken command — local `faster-whisper` + works out of the box; see [Voice Mode](/user-guide/features/voice-mode) for the + full provider list. +- The wake engine deps (auto-installed, or `hermes-agent[wake]`). + +`/wake status` reports exactly what's missing if the listener won't start. + +## Notes & limits + +- **Local surfaces only.** The wake word runs in the CLI, TUI, and desktop GUI — + wherever a local microphone is available. It does not run in the messaging + gateway (Telegram, Discord, …), which has no mic. +- **One mic at a time.** The detector releases the microphone while a command is + recording and reclaims it once the turn ends, so it won't fight voice capture. +- **Privacy.** Hotword detection is local. Set `sensitivity` higher if you get + false triggers, lower if it misses you.