ha-voice

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

# 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

# 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:

tts:
  - platform: piper
    language: en_GB
    voice: jenny_dioco

Cloud Option - OpenAI:

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:

stt:
  - platform: faster_whisper
    language: en

Cloud Option - Google Cloud Speech:

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:

intents:
  TurnOn:
    data:
      - sentences:
          - "turn on light.bedroom"
          - "turn on light.kitchen"

✅ Correct - Using slot lists:

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:

sentences:
  - "turn on {name:list}"  # Matches list value, captures as 'name' slot

Lists

List matching provides slot values:

lists:
  room:
    - "bedroom"
    - "kitchen"
    - "living room"

Optional Groups

Square brackets make words optional:

sentences:
  - "[please] turn on the {name:list}"
  - "activate [the] {device:list}"

Wildcards

Wildcard slots capture any text:

sentences:
  - "remind me {reminder:text}"  # Captures any text as 'reminder'
  - "set a timer for {duration:text}"

Combined Pattern Example

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

  Reminder:
    data:
      - sentences:
          - "remind me {reminder:text}"
          - "[please] [create | set] a reminder [for me] [to] {reminder:text}"

lists:
  light_names:
    - "bedroom light"
    - "kitchen overhead"
    - "living room lamps"
  room_names:
    - "bedroom"
    - "kitchen"
    - "living room"

Why this matters: Flexible patterns enable natural phrasing while maintaining intent recognition accuracy.

Built-In Intents Reference

Home Assistant provides default intents:

Navigation Intents

• HassTurnOn / HassTurnOff - Control devices
• HassToggle - Toggle switches/lights
• HassOpenCover / HassCloseCover - Control covers
• HassSetClimate - Control climate (heat/cool)

Information Intents

• HassGetState - Get entity state
• HassGetHistory - Query automation history

Home Control Intents

• HassArmAlarm / HassDisarmAlarm - Arm/disarm alarms
• HassLockDoor / HassUnlockDoor - Control locks

Custom Intents

You create additional intents in custom_sentences/ by defining new intent blocks:

intents:
  CustomIntentName:
    data:
      - sentences: [...]

Wake Word Configuration

openWakeWord (Local)

conversation:
  engine: openai

# Enable openWakeWord
binary_sensor:
  - platform: openwakeword
    models:
      - alexa    # "Alexa, help"
      - hey_google  # "Hey Google, ..."
      - hey_siri

Porcupine (Local, Paid)

binary_sensor:
  - platform: porcupine
    access_key: !secret porcupine_key
    keywords:
      - hey_home_assistant

Voice Satellite Setup

Hardware Requirements

• Microphone: INMP441 (I2S digital) or similar
• Speaker: MAX98357A amplifier or similar
• Board: ESP32-S3, ESP32-S3-BOX-3 preferred
• Connectivity: WiFi required

ESPHome Voice Assistant Config

# ESPHome device
packages:
  voice_assistant: !include packages/voice_assistant.yaml

# Or inline configuration:
i2s_audio:
  i2s_lrclk_pin: GPIO33
  i2s_bclk_pin: GPIO34
  i2s_mclk_pin: GPIO32

microphone:
  - platform: i2s_audio
    id: mic
    adc_type: external
    i2s_din_pin: GPIO35
    pdm: false

speaker:
  - platform: i2s_audio
    id: speaker
    dac_type: external
    i2s_dout_pin: GPIO36
    mode: mono

voice_assistant:
  microphone: mic
  speaker: speaker
  noise_suppression_level: 2
  auto_gain: 80dB
  volume_multiplier: 0.8

Why this matters: Voice satellites extend Assist to multiple rooms with local processing.

Speech Processing Configuration

Language Support

Full Support (20+ languages): en, de, fr, it, es, nl, pl, pt, ru, sv, tr, uk, zh, ja, ko, and more

Partial Support (40+ languages): Regional variants and additional languages with varying STT/TTS availability

Community Support (80+ languages): Community-contributed sentence templates

Language Config:

assist_pipeline:
  pipelines:
    - language: de  # German
      name: Deutsche Pipeline
      tts_engine: tts.piper  # Set voice per language

Performance Tuning

STT (Faster Whisper):

stt:
  - platform: faster_whisper
    language: en
    model: base  # tiny, base, small, medium, large
    acceleration: gpu  # CPU or GPU

TTS (Piper):

tts:
  - platform: piper
    voice: en_GB-jenny
    rate: 11025  # Audio sample rate
    volume_normalize: true

Conversation Agent Integration

Built-in Agent:

conversation:
  engine: home_assistant

OpenAI Agent:

conversation:
  engine: openai
  api_key: !secret openai_api_key
  model: gpt-4

Custom Conversation Agent:

conversation:
  engine: custom
  module: custom_components.my_agent

Common Intent Patterns

Device Control Pattern

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

Climate Control Pattern

intents:
  SetClimate:
    data:
      - sentences:
          - "set [the] {room:list} [thermostat] to {temp:number} degrees"
          - "make it {temp:number} in [the] {room:list}"
        lists:
          room: room_names

Query Pattern

intents:
  GetState:
    data:
      - sentences:
          - "what is the temperature [in the] {room:list}"
          - "is [the] {name:list} on"
        lists:
          room: room_names
          name: device_names

Testing with Developer Tools

1. Go to Developer Tools → Assist
2. Enter test sentence: "turn on the bedroom light"
3. Check:
   • ✅ Intent matched correctly
   • ✅ Slots extracted properly
   • ✅ Audio plays (if TTS configured)
4. Debug mismatches by:
   • Reviewing sentence patterns
   • Checking list values
   • Verifying slot names

Troubleshooting

Intent Not Recognized

Symptoms: Voice command doesn't match any intent

Solution:

# Check custom_sentences directory structure
ls -R config/custom_sentences/

# Verify YAML syntax
cat config/custom_sentences/en/custom.yaml

# Test in Assist Developer Tools with exact phrase
# Adjust sentence patterns to match expected phrasing

TTS/STT Engine Not Working

Symptoms: "Engine not available" error in Assist

Solution:

# Verify engine is configured
service: tts.piper  # Must exist

# Check dependencies installed
pip install piper-tts  # for Piper
pip install faster-whisper  # for Whisper

# Restart Home Assistant to load engines

Wake Word Not Triggering

Symptoms: Binary sensor stays off despite noise

Solution:

# Verify entity_id is correct
service: homeassistant.update_entity
target:
  entity_id: binary_sensor.wake_word

# Check binary sensor configuration
# Review noise levels and model sensitivity
# Test microphone separately

Voice Satellite Connection Issues

Symptoms: ESP32 disconnects from WiFi or Assist pipeline

Solution:

# Check WiFi signal strength in ESPHome logs
# Reduce WiFi distance or add access point
# Update ESPHome firmware
esphome run voice_assistant.yaml --upload-speed 115200

Dependencies

Required

Component	Version	Purpose
Home Assistant	2024.1+	Assist platform
Faster Whisper	0.5+	Local STT engine
Piper TTS	1.0+	Local TTS engine

Optional

Component	Version	Purpose
OpenWakeWord	0.3+	Wake word detection
Porcupine	Latest	Premium wake word
ESPHome	2024.1+	Voice satellite devices

Official Documentation

• Home Assistant Voice Control
• Assist Pipeline Configuration
• Intent Recognition Guide
• Conversation Integration

Setup Checklist

Before using voice commands, verify:

• Assist pipeline configured with STT, TTS, and conversation engine
• custom_sentences/en/ directory created with intent definitions
• Sentence patterns tested in Assist Developer Tools
• Wake word entity exists (if using wake word)
• Microphone and speaker working (test via Developer Tools)
• Intent lists contain correct entity aliases
• Language setting matches your configuration
• All YAML syntax is valid (no tabs, proper indentation)