> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuralcleave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wake Word

> Always-on wake word detection using OpenWakeWord — cross-platform, runs 100% locally.

NeuralCleave uses [OpenWakeWord](https://github.com/dscripka/openWakeWord) for wake word detection. OpenWakeWord runs on CPU, works on Windows, macOS, and Linux, and requires no cloud account.

## Configuration

```toml theme={null}
[voice]
wake_word = "alexa"               # alexa | hey_jarvis | custom
wake_word_threshold = 0.5         # 0.0–1.0; higher = fewer false positives
continuous_voice_enabled = true   # required — see "Handoff" below
```

`continuous_voice_enabled` isn't optional here even though it's a separate key: the wake-word detector only *fires*, it doesn't itself transcribe anything — the handoff to STT described below only happens when continuous listening is also enabled. Leaving it at its default (`false`) with only `wake_word` set produces a detector that logs a detection and does nothing else, with no error to indicate why.

## Built-in wake words

| Model name    | Phrase        |
| ------------- | ------------- |
| `alexa`       | "Alexa"       |
| `hey_jarvis`  | "Hey Jarvis"  |
| `hey_mycroft` | "Hey Mycroft" |

## Custom wake word

You can train a custom wake word model using OpenWakeWord's training tools:

1. Record 50–200 samples of your phrase.
2. Train with `openwakeword train`.
3. Place the `.tflite` model file in `~/.neuralcleave/wakewords/`.
4. Set `wake_word_model_path = "~/.neuralcleave/wakewords/my_phrase.tflite"` (takes precedence over `wake_word`). Keep `wake_word` set to any non-empty value too — it gates whether the detector is created at all.

## Status indicators

In the chat toolbar, the `VoiceStatusIndicator` shows an amber **Wake** badge when the detector is active. The `/voice` dashboard page shows a larger animated indicator.

## Tuning sensitivity

`wake_word_threshold` controls the detection threshold (0.0–1.0):

* **Lower** (e.g. 0.3): more responsive, more false positives
* **Higher** (e.g. 0.7): fewer false positives, may miss softer speech

Start at `0.5` and adjust based on your environment noise level.

## Handoff

Requires `continuous_voice_enabled = true` (see Configuration above) — without it, this handoff never happens.

When the wake word is detected:

1. The detector hands off to the VAD (Voice Activity Detection) layer.
2. VAD waits for a full utterance (silence after speech).
3. The audio chunk is passed to the STT backend.
4. The transcript enters the NeuralCleave pipeline.
5. The TTS reply plays back through the output device.

The `handoffActive` flag is visible in the `/voice` dashboard during a handoff.