ha-voice

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: ha-voice
description: "Configure Home Assistant Assist voice control with pipelines, intents, wake words, and speech processing. Use when setting up voice control, creating custom intents, configuring TTS/STT, or building voice satellites. Activates on keywords: Assist, voice control, wake word, intent, sentence, TTS, STT, Piper, Whisper, Wyoming."
---

# Home Assistant Voice Control

> Configure Assist pipelines, custom intents, wake words, speech processing, and voice satellites for local voice control.

## Quick Start

### Setting up Assist Pipeline

```yaml
# configuration.yaml
assist_pipeline:
  pipelines:
    - language: en
      name: Default Pipeline
      stt_engine: faster_whisper  # Local STT
      tts_engine: tts.piper       # Local TTS
      conversation_engine: conversation.home_assistant
      wake_word_entity: binary_sensor.wake_word
```

**Why this matters:** The pipeline connects all components (STT, TTS, intent, conversation agent) into a single voice workflow.

### Creating Custom Intents

```yaml
# custom_sentences/en/turn_on.yaml
language: en
version: 1

intents:
  TurnOn:
    data:
      - sentences:
          - "turn on the [area] {name:list}"
          - "turn on {name:list}"
          - "[please] activate {name:list}"
        lists:
          name: light_names

lists:
  light_names:
    - "bedroom light"
    - "kitchen overhead"
    - "living room"
```

**Why this matters:** Custom sentence patterns enable natural voice commands tailored to your home.

### Configuring Text-to-Speech (TTS)

**Local Option - Piper:**
```yaml
tts:
  - platform: piper
    language: en_GB
    voice: jenny_dioco
```

**Cloud Option - OpenAI:**
```yaml
tts:
  - platform: tts
    service: google_translate_say  # or openai, google cloud
    language: en
```

**Why this matters:** TTS gives voice feedback; local options require no cloud dependencies.

### Configuring Speech-to-Text (STT)

**Local Option - Faster Whisper:**
```yaml
stt:
  - platform: faster_whisper
    language: en
```

**Cloud Option - Google Cloud Speech:**
```yaml
stt:
  - platform: google_cloud
    language_code: en-US
```

**Why this matters:** STT converts spoken commands to text; local options provide privacy.

## Critical Rules

### ✅ Always Do

- ✅ Use `custom_sentences/` directory for intent configuration (not deprecated `sentences/`)
- ✅ Test intents with Assist Developer Tools before deploying
- ✅ Use `{name:list}` syntax for slot-based entity matching
- ✅ Configure both STT and TTS engines in the same pipeline
- ✅ Verify wake word entity exists before enabling in pipeline
- ✅ Document intent lists so voice commands are discoverable

### ❌ Never Do

- ❌ Don't hardcode entity IDs in sentence patterns (use lists and slots)
- ❌ Don't forget `version: 1` in custom_sentences YAML files
- ❌ Don't mix old `sentences/` directory with new `custom_sentences/` (use `custom_sentences/` only)
- ❌ Don't enable Piper TTS without adequate disk space (models are 100+ MB)
- ❌ Don't use wildcard `{query}` for every slot (makes intents ambiguous)
- ❌ Don't skip testing with Assist Developer Tools

### Common Mistakes

**❌ Wrong - Hardcoded entity IDs:**
```yaml
intents:
  TurnOn:
    data:
      - sentences:
          - "turn on light.bedroom"
          - "turn on light.kitchen"
```

**✅ Correct - Using slot lists:**
```yaml
intents:
  TurnOn:
    data:
      - sentences:
          - "turn on [the] {name:list}"
        lists:
          name: light_names

lists:
  light_names:
    - "bedroom"
    - "kitchen"
```

**Why:** Lists are dynamic and can be generated from Home Assistant entities programmatically.

## Sentence Pattern Syntax

### Slots

**Named slots** match list values:
```yaml
sentences:
  - "turn on {name:list}"  # Matches list value, captures as 'name' slot
```

### Lists

**List matching** provides slot values:
```yaml
lists:
  room:
    - "bedroom"
    - "kitchen"
    - "living room"
```

### Optional Groups

**Square brackets** make words option