语音助手

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

NOTE

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

WARNING

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

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

如果您遇到崩溃，请参阅故障排除指南了解如何获取回溯信息。

voice_assistant:
  microphone: mic_id

配置变量

• microphone (*必需, 麦克风源配置)：用于输入的麦克风设置。

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

• speaker (可选, ID)：用于输出响应的扬声器。不能与下面的 media_player 同时使用。

• media_player (可选, ID)：用于输出响应的媒体播放器。不能与上面的 speaker 同时使用。

• use_wake_word (可选, 布尔值)：在 assist 管道上启用唤醒词。默认值为 false。

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

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

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

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

• on_listening (可选, 自动化)：语音助手麦克风开始监听时执行的自动化。

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

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

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

• on_stt_end (可选, 自动化)：语音助手完成语音转文字时执行的自动化。结果文本作为变量 x 可用于自动化。

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

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

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

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

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

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

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

• on_error (可选, 自动化)：语音助手遇到错误时执行的自动化。错误代码和消息作为变量 code 和 message 可用于自动化。

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

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

• noise_suppression_level (可选, 整数)：应用于 assist 管道的噪声抑制级别。范围 0 到 4（含）。默认值为 0（禁用）。

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

• volume_multiplier (可选, 浮点数)：应用于 assist 管道的音量倍数。必须大于 0。默认值为 1（禁用）。

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

• on_timer_finished (可选, 自动化)：语音助手计时器完成时执行的自动化。计时器作为 timer 变量可用，类型为 API Reference: voice_assistant::Timer。

• on_timer_cancelled (可选, 自动化)：语音助手计时器取消时执行的自动化。计时器作为 timer 变量可用，类型为 API Reference: voice_assistant::Timer。

• on_timer_updated (可选, 自动化)：语音助手计时器更新（暂停/恢复/持续时间更改）时执行的自动化。计时器作为 timer 变量可用，类型为 API Reference: voice_assistant::Timer。

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

动作

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

voice_assistant.start 动作

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

配置变量

• silence_detection (可选, 布尔值)：启用静音检测。默认值为 true。
• wake_word (可选, 字符串)：使用设备端唤醒词（如 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。

唤醒词检测

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

按键通话（Push to Talk）

以下是一个使用二进制传感器实现按键通话的示例。

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:

点击对话（Click to Converse）

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 Reference: voice_assistant.h