ha-voice

Q: How do I install ha-voice?

Run npx skills add https://github.com/nodnarbnitram/claude-code-extensions --skill ha-voice in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/ha-voice/ (personal) or .claude/skills/ha-voice/ (project).

by nodnarbnitramMedia & Creative

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.

Installs: 218
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/nodnarbnitram/claude-code-extensions --skill ha-voice

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads ha-voice automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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

Go to Developer Tools → Assist
Enter test sentence: "turn on the bedroom light"
Check:
- ✅ Intent matched correctly
- ✅ Slots extracted properly
- ✅ Audio plays (if TTS configured)
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

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)

FAQ

What does the ha-voice skill do?

How do I install ha-voice?

Run npx skills add https://github.com/nodnarbnitram/claude-code-extensions --skill ha-voice in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/ha-voice/ (personal) or .claude/skills/ha-voice/ (project).

Which AI agents can use ha-voice?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is ha-voice safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains ha-voice?

It is published by nodnarbnitram in nodnarbnitram/claude-code-extensions. It has 218 recorded installs.