语音助手

带有麦克风的 ESPHome 设备能够将音频流式传输到 Home Assistant，并由 assist 在那里进行处理。

NOTE

语音助手需要 Home Assistant 2023.5 或更高版本。

WARNING

音频和语音组件会在设备上消耗大量资源（RAM、CPU）。

如果在设备的 配置中包含太多附加组件，可能会发生崩溃。特别是，蓝牙/BLE 组件已知在与 语音助手和/或其他音频组件一起使用时会导致问题。

如果发生崩溃，请参见 故障排除 指南了解如何获取回溯。

voice_assistant:
  microphone: mic_id

配置变量

• microphone (可选, Microphone Source Configuration 或其列表 ): 用于输入的 麦克风 设置。可以直接提供单个来源， 或者可以提供最多两个来源作为列表。当配置了两个来源时，来自两者的音频都会流式传输 到 Home Assistant；请参见下面的 第二个麦克风通道。

• micro_wake_word (可选, ID): 用于唤醒词检测的 micro_wake_word 组件。配置此项后，Home Assistant 可以更改启用的唤醒词模型。

• speaker (可选, ID): 用于输出 响应的 speaker。不能与下面的 media_player 一起使用。

• media_player (可选, ID): 用于输出响应的 media_player。不能与上面的 speaker 一起使用。

• use_wake_word (可选, boolean): 在 assist 管道上启用唤醒词。默认为 false。

• conversation_timeout (可选, Time): 在重置发送到语音辅助管道的 conversation_id 之前等待多长时间， 它包含当前辅助管道的上下文。默认为 300s。

• on_intent_start (可选, Automation): 当意图处理开始时执行的自动化。

• on_intent_progress (可选, Automation): 当意图进展发生时执行的自动化。 变量 x 是非空字符串，仅当流式 TTS 响应 URL 被发送到媒体播放器时才包含该 URL。

• on_intent_end (可选, Automation): 当意图处理结束时执行的自动化。

• on_listening (可选, Automation): 当语音助手麦克风开始 倾听时要执行的自动化。

• on_start (可选, Automation): 当 assist 管道启动时执行的自动化。

• on_wake_word_detected (可选, Automation): 当 assist 管道 检测到唤醒词时执行的自动化。

• on_end (可选, Automation): 当语音助手 完成所有任务时执行的自动化。

• on_stt_end (可选, Automation): 当语音助手 完成语音转文字时执行的自动化。生成的文本可作为变量 x 供自动化使用。

• on_stt_vad_start (可选, Automation): 当语音活动 检测开始语音转文字处理时执行的自动化。

• on_stt_vad_end (可选, Automation): 当语音活动 检测结束语音转文字处理时执行的自动化。

• on_tts_start (可选, Automation): 当语音助手 开始文字转语音时执行的自动化。要朗读的文本可作为变量 x 供自动化使用。

• on_tts_end (可选, Automation): 当语音助手 完成文字转语音时执行的自动化。包含音频响应的 URL 可作为变量 x 供自动化使用。

• on_tts_stream_start (可选, Automation): 当音频流 （语音响应）播放开始时执行的自动化。需要配置 speaker。

• on_tts_stream_end (可选, Automation): 当音频流 （语音响应）播放结束时执行的自动化。需要配置 speaker。

• on_idle (可选, Automation): 当语音助手 处于空闲状态（没有其他操作/状态正在进行）时执行的自动化。

• on_error (可选, Automation): 当语音助手 遇到错误时执行的自动化。错误代码和消息分别可作为变量 code 和 message 供自动化使用。

• on_client_connected (可选, Automation): 当 Home Assistant 已连接并等待语音助手命令时执行的自动化。

• on_client_disconnected (可选, Automation): 当 Home Assistant 断开与语音助手的连接时执行的自动化。

• noise_suppression_level (可选, integer): 应用于辅助管道的噪声抑制级别。 范围为 0 到 4（含）。默认为 0（禁用）。

• auto_gain (可选, dBFS): 应用于辅助管道的自动增益级别。 范围为 0dBFS 到 31dBFS（含）。默认为 0（禁用）。

• volume_multiplier (可选, float): 应用于辅助管道的音量乘数。 必须大于 0。默认为 1（禁用）。

• on_timer_started (可选, Automation): 当语音助手 计时器启动时执行的自动化。计时器可作为 timer 使用，类型为 API 参考：voice_assistant::Timer。

• on_timer_finished (可选, Automation): 当语音助手 计时器结束时执行的自动化。计时器可作为 timer 使用，类型为 API 参考：voice_assistant::Timer。

• on_timer_cancelled (可选, Automation): 当语音助手 计时器被取消时执行的自动化。计时器可作为 timer 使用，类型为 API 参考：voice_assistant::Timer。

• on_timer_updated (可选, Automation): 当语音助手 计时器被更新（暂停/恢复/时长更改）时执行的自动化。计时器可作为 timer 使用，类型为 API 参考：voice_assistant::Timer。

• on_timer_tick (可选, Automation): 当语音助手计时器的 tick 触发时执行的自动化。 只要此设备上有计时器，此操作每 1 秒 调用一次。 计时器可作为 timers 使用，它是类型为 API 参考：voice_assistant::Timer 的 std::vector（数组）。

动作

以下动作可供在自动化中使用：

voice_assistant.start 动作

监听一条语音命令然后停止。

配置变量

• silence_detection (可选, boolean): 启用静音检测。默认为 true。
• wake_word (可选, string, 可模板化): 使用设备唤醒词（如 Micro Wake Word）时 用于触发语音助手的唤醒词。

如果 silence_detection 设置为 false，请调用 voice_assistant.stop 以发出语音命令结束的信号。

voice_assistant.start_continuous 动作

开始监听语音命令。在 响应音频播放结束后会再次开始监听。某些错误会停止循环。 调用 voice_assistant.stop 以停止循环。

voice_assistant.stop 动作

停止监听语音命令。

条件

以下条件可供在自动化中使用：

voice_assistant.is_running 条件

如果语音助手当前正在运行，则返回 true。

voice_assistant.connected 条件

如果语音助手当前已连接到 Home Assistant，则返回 true。

第二个麦克风通道

可以通过向 microphone 传递一个包含两个来源的列表来提供第二个麦克风来源。当配置了两个来源时， 来自两者的音频都会流式传输到 Home Assistant。第一个来源携带更多处理的音频（增益、 噪声抑制等），而第二个来源携带更少处理的音频。Home Assistant 在语音管道的每个阶段使用效果最佳的通道。

voice_assistant:
  id: va
  microphone:
    - microphone: i2s_mics
      channels: 0
    - microphone: i2s_mics
      channels: 1

NOTE

两个麦克风来源都必须使用 microphone 所需的相同音频格式（16 kHz，每样本 16 位， 单声道）。需要 Home Assistant 2026.6.0 或更高版本才能使用第二个通道；较旧版本将忽略它。

唤醒词检测

请查看我们 GitHub 上的示例 YAML 文件 了解连续唤醒词检测。

按键通话

以下是一个通过 二进制传感器 提供按键通话的示例。

voice_assistant:
  microphone:
    microphone: ...
    channels: 0
    gain_factor: 4
  speaker: ...

binary_sensor:
  - platform: gpio
    pin: ...
    on_press:
      - voice_assistant.start:
          silence_detection: false
    on_release:
      - voice_assistant.stop:

点击对话

voice_assistant:
  microphone:
    microphone: ...
    channels: 0
    gain_factor: 4
  speaker: ...

binary_sensor:
  - platform: gpio
    pin: ...
    on_click:
      - if:
          condition: voice_assistant.is_running
          then:
            - voice_assistant.stop:
          else:
            - voice_assistant.start_continuous:

参见

• 麦克风组件
• API 参考：voice_assistant.h