ha-voice

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Home Assistant Voice Control

Home Assistant语音控制

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

配置Assist流水线、自定义意图、唤醒词、语音处理和语音卫星，实现本地语音控制。

Quick Start

快速开始

Setting up Assist Pipeline

配置Assist流水线

yaml

undefined

yaml

undefined

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.


**重要性：** 流水线将所有组件（STT、TTS、意图、对话Agent）连接成一个完整的语音工作流。

Creating Custom Intents

创建自定义意图

yaml

undefined

yaml

undefined

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.

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"


**重要性：** 自定义语句模式可实现贴合家庭场景的自然语音指令。

Configuring Text-to-Speech (TTS)

配置文本转语音（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.

本地方案 - Piper：

yaml

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

云端方案 - OpenAI：

yaml

tts:
  - platform: tts
    service: google_translate_say  # or openai, google cloud
    language: en

重要性： TTS提供语音反馈；本地方案无需依赖云端服务。

Configuring Speech-to-Text (STT)

配置语音转文本（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.

本地方案 - Faster Whisper：

yaml

stt:
  - platform: faster_whisper
    language: en

云端方案 - Google Cloud Speech：

yaml

stt:
  - platform: google_cloud
    language_code: en-US

重要性： STT将语音指令转换为文本；本地方案可保障隐私。

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

✅ 使用
```
custom_sentences/
```
目录配置意图（已弃用的
```
sentences/
```
目录请勿使用）
✅ 部署前使用Assist开发者工具测试意图
✅ 使用
```
{name:list}
```
语法实现基于槽位的实体匹配
✅ 在同一流水线中配置STT和TTS引擎
✅ 在流水线中启用唤醒词前，确认唤醒词实体已存在
✅ 记录意图列表，确保语音指令可被识别

❌ 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

❌ 请勿在语句模式中硬编码实体ID（使用列表和槽位）
❌ 请勿在custom_sentences的YAML文件中遗漏
```
version: 1
```
❌ 请勿混合使用旧的
```
sentences/
```
目录和新的
```
custom_sentences/
```
目录（仅使用
```
custom_sentences/
```
）
❌ 请勿在磁盘空间不足时启用Piper TTS（模型大小超过100MB）
❌ 请勿为所有槽位使用通配符
```
{query}
```
（会导致意图模糊）
❌ 请勿跳过Assist开发者工具的测试环节

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.

❌ 错误示例 - 硬编码实体ID：

yaml

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

✅ 正确示例 - 使用槽位列表：

yaml

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

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

原因： 列表是动态的，可通过编程方式从Home Assistant实体生成。

Sentence Pattern Syntax

语句模式语法

Slots

槽位

Named slots match list values:

yaml

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

命名槽位匹配列表值：

yaml

sentences:
  - "turn on {name:list}"  # 匹配列表值，捕获为'name'槽位

Lists

列表

List matching provides slot values:

yaml

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

列表匹配提供槽位值：

yaml

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

Optional Groups

可选分组

Square brackets make words optional:

yaml

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

方括号标记可选词汇：

yaml

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

Wildcards

通配符

Wildcard slots capture any text:

yaml

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

通配符槽位捕获任意文本：

yaml

sentences:
  - "remind me {reminder:text}"  # 捕获任意文本作为'reminder'
  - "set a timer for {duration:text}"

Combined Pattern Example

组合模式示例

yaml

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.

yaml

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"

重要性： 灵活的模式支持自然表述，同时保持意图识别的准确性。

Built-In Intents Reference

内置意图参考

Home Assistant provides default intents:

Home Assistant提供默认意图：

Navigation Intents

导航意图

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

```
HassTurnOn
```
/
```
HassTurnOff
```
- 控制设备
```
HassToggle
```
- 切换开关/灯光
```
HassOpenCover
```
/
```
HassCloseCover
```
- 控制遮阳帘
```
HassSetClimate
```
- 控制温控（制热/制冷）

Information Intents

信息查询意图

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

```
HassGetState
```
- 获取实体状态
```
HassGetHistory
```
- 查询自动化历史

Home Control Intents

家居控制意图

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

```
HassArmAlarm
```
/
```
HassDisarmAlarm
```
- 布防/撤防警报
```
HassLockDoor
```
/
```
HassUnlockDoor
```
- 控制门锁

Custom Intents

自定义意图

You create additional intents in

custom_sentences/

by defining new intent blocks:

yaml

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

你可以在

custom_sentences/

中通过定义新的意图块创建额外意图：

yaml

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

Wake Word Configuration

唤醒词配置

openWakeWord (Local)

openWakeWord（本地）

yaml

conversation:
  engine: openai

yaml

conversation:
  engine: openai

Enable openWakeWord

启用openWakeWord

binary_sensor:

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

undefined

binary_sensor:

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

undefined

Porcupine (Local, Paid)

Porcupine（本地，付费）

yaml

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

yaml

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

麦克风： INMP441（I2S数字麦克风）或同类产品
扬声器： MAX98357A放大器或同类产品
开发板： ESP32-S3，推荐ESP32-S3-BOX-3
网络： 需要WiFi连接

ESPHome Voice Assistant Config

ESPHome Voice Assistant配置

yaml

undefined

yaml

undefined

ESPHome device

ESPHome设备

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.

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


**重要性：** 语音卫星可将Assist扩展到多个房间，实现本地处理。

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:

yaml

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

完全支持（20+种语言）： en、de、fr、it、es、nl、pl、pt、ru、sv、tr、uk、zh、ja、ko等

部分支持（40+种语言）： 区域变体及其他语言，STT/TTS可用性各异

社区支持（80+种语言）： 社区贡献的语句模板

语言配置：

yaml

assist_pipeline:
  pipelines:
    - language: de  # German
      name: Deutsche Pipeline
      tts_engine: tts.piper  # 按语言设置语音

Performance Tuning

性能调优

STT (Faster Whisper):

yaml

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

TTS (Piper):

yaml

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

STT（Faster Whisper）：

yaml

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

TTS（Piper）：

yaml

tts:
  - platform: piper
    voice: en_GB-jenny
    rate: 11025  # 音频采样率
    volume_normalize: true

Conversation Agent Integration

对话Agent集成

Built-in Agent:

yaml

conversation:
  engine: home_assistant

OpenAI Agent:

yaml

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

Custom Conversation Agent:

yaml

conversation:
  engine: custom
  module: custom_components.my_agent

内置Agent：

yaml

conversation:
  engine: home_assistant

OpenAI Agent：

yaml

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

自定义对话Agent：

yaml

conversation:
  engine: custom
  module: custom_components.my_agent

Common Intent Patterns

常见意图模式

Device Control Pattern

设备控制模式

yaml

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

yaml

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

Climate Control Pattern

温控模式

yaml

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

yaml

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

查询模式

yaml

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

yaml

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

进入开发者工具 → Assist
输入测试语句："turn on the bedroom light"
检查：
- ✅ 意图匹配正确
- ✅ 槽位提取无误
- ✅ 音频正常播放（若已配置TTS）
调试匹配失败问题的方法：
- 检查语句模式
- 核对列表值
- 验证槽位名称

Troubleshooting

故障排除

Intent Not Recognized

意图未被识别

Symptoms: Voice command doesn't match any intent

Solution:

yaml

undefined

症状： 语音指令未匹配到任何意图

解决方案：

yaml

undefined

Check custom_sentences directory structure

检查custom_sentences目录结构

ls -R config/custom_sentences/

Verify YAML syntax

验证YAML语法

cat config/custom_sentences/en/custom.yaml

Test in Assist Developer Tools with exact phrase

在Assist开发者工具中使用精确语句测试

Adjust sentence patterns to match expected phrasing

调整语句模式以匹配预期表述

undefined

undefined

TTS/STT Engine Not Working

TTS/STT引擎无法工作

Symptoms: "Engine not available" error in Assist

Solution:

yaml

undefined

症状： Assist中出现“引擎不可用”错误

解决方案：

yaml

undefined

Verify engine is configured

验证引擎已配置

service: tts.piper # Must exist

service: tts.piper # 必须存在

Check dependencies installed

检查依赖是否安装

pip install piper-tts # for Piper pip install faster-whisper # for Whisper

pip install piper-tts # 针对Piper pip install faster-whisper # 针对Whisper

Restart Home Assistant to load engines

重启Home Assistant以加载引擎

undefined

undefined

Wake Word Not Triggering

唤醒词无响应

Symptoms: Binary sensor stays off despite noise

Solution:

yaml

undefined

症状： 即使有声音，二进制传感器仍保持关闭状态

解决方案：

yaml

undefined

Verify entity_id is correct

验证entity_id是否正确

service: homeassistant.update_entity target: entity_id: binary_sensor.wake_word

Check binary sensor configuration

检查二进制传感器配置

Review noise levels and model sensitivity

查看噪音水平和模型灵敏度

Test microphone separately

单独测试麦克风

undefined

undefined

Voice Satellite Connection Issues

语音卫星连接问题

Symptoms: ESP32 disconnects from WiFi or Assist pipeline

Solution:

bash

undefined

症状： ESP32与WiFi或Assist流水线断开连接

解决方案：

bash

undefined

Check WiFi signal strength in ESPHome logs

在ESPHome日志中查看WiFi信号强度

Reduce WiFi distance or add access point

缩短WiFi距离或添加接入点

Update ESPHome firmware

更新ESPHome固件

esphome run voice_assistant.yaml --upload-speed 115200

undefined

esphome run voice_assistant.yaml --upload-speed 115200

undefined

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

组件	版本	用途
Home Assistant	2024.1+	Assist平台
Faster Whisper	0.5+	本地STT引擎
Piper TTS	1.0+	本地TTS引擎

Optional

可选依赖

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

组件	版本	用途
OpenWakeWord	0.3+	唤醒词检测
Porcupine	最新版	高级唤醒词
ESPHome	2024.1+	语音卫星设备

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)

使用语音指令前，请确认：

Assist流水线已配置STT、TTS和对话引擎
已创建
```
custom_sentences/en/
```
目录并定义意图
语句模式已在Assist开发者工具中测试
唤醒词实体已存在（若使用唤醒词）
麦克风和扬声器工作正常（通过开发者工具测试）
意图列表包含正确的实体别名
语言设置与配置一致
所有YAML语法有效（无制表符，缩进正确）