mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-07-24 16:54:43 +00:00
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.
This commit is contained in:
Brooklyn Nicholson
parent
64686e6ec5
commit
17dc350a6b
2 changed files with 174 additions and 0 deletions
|
|
@ -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`.
|
||||
|
|
|
|||
173
website/docs/user-guide/features/wake-word.md
Normal file
173
website/docs/user-guide/features/wake-word.md
Normal file
|
|
@ -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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue