扬声器音频媒体播放器

speaker 媒体播放器平台允许您通过扬声器组件播放设备内和在线音频媒体。

此平台极大地受益于外部 PSRAM。有关详细信息，请参阅性能部分。

它原生支持解码 FLAC、MP3 和 WAV 音频文件。Home Assistant（自 2024.10 版本起）可以代理其发送的任何媒体，并将其转码为指定格式和采样率，以最大限度地减少设备的计算负载。

它支持两种不同的音频管道：公告和媒体。每个音频管道必须输出到唯一的扬声器。使用混音扬声器组件创建两个不同的扬声器，输出到单个音频扬声器。

直接内置到固件中的设备内文件可以在没有网络连接的情况下播放。使用配置的采样率、1 或 2 个通道以及每采样 16 位对设备内文件进行编码。

此平台仅适用于使用 ESP-IDF 框架的基于 ESP32 的芯片。

WARNING

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

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

# 示例最小配置条目
media_player:
  - platform: speaker
    announcement_pipeline:
      speaker: announcment_spk_id

配置变量

• announcement_pipeline (必需, 管道模式): 公告管道的配置设置。

  • speaker (必需, ID): 输出音频的扬声器。
  • format (可选, 枚举): Home Assistant 在将音频发送到设备之前将音频转码到的音频格式。可选 FLAC、MP3、WAV 或 NONE。NONE 禁用 Home Assistant 中的转码。默认为 FLAC。
  • sample_rate (可选, 正整数): 转码音频的采样率。应受配置的 speaker 组件支持。默认为扬声器的采样率。
  • num_channels (可选, 正整数): 转码音频的通道数。必须是 1 或 2。默认为扬声器的通道数。

• media_pipeline (可选, 管道模式): 媒体管道的配置设置。选项与 announcement_pipeline 相同。

• buffer_size (可选, 正整数): 每个管道的缓冲区大小（字节）。必须在 4000 到 4000000 之间。默认为 1000000。

• codec_support_enabled (可选, 布尔值): 启用 MP3 和 FLAC 解码器。默认为 true。

• task_stack_in_psram (可选, 布尔值): 在外部内存中运行音频任务。默认为 false。

• volume_increment (可选, 百分比): media_player.volume_up 和 media_player.volume_down 动作增加或减少音量的增量。默认为 5%。

• volume_initial (可选, 百分比): 媒体播放器首次启动时的默认音量（之前未保存音量时）。默认为 50%。

• volume_min (可选, 百分比): 允许的最小音量。默认为 0%。

• volume_max (可选, 百分比): 允许的最大音量。默认为 100%。

• files (可选, 列表): 构建到固件中用于设备内播放的媒体文件列表。

  • id (必需, ID): 文件的唯一 ID。
  • file (必需, 字符串): 音频文件的路径。可以是本地文件路径或 URL。

• on_mute (可选, 自动化): 静音时执行的自动化。

• on_unmute (可选, 自动化): 取消静音时执行的自动化。

• on_volume (可选, 自动化): 音量更改时执行的自动化。

• 媒体播放器的所有其他选项

配置示例

此示例将音频输出到配置为 48000 Hz 采样率的 I²S 音频扬声器。它使用 mixer 扬声器组件来处理合并两个不同的管道，并使用 resampler 扬声器组件确保源扬声器使用相同的采样率。

它添加了一个开关，用于播放设备内文件作为闹钟通知。当闹钟激活时，任何正在播放的媒体都会被降低音量。闹钟关闭后，媒体音量衰减将逐渐停止。

i2s_audio:
    i2s_lrclk_pin: GPIOXX
    i2s_bclk_pin: GPIOXX
    sample_rate: 48000
speaker:
  - platform: i2s_audio
    id: speaker_id
    dac_type: external
    i2s_dout_pin: GPIOXX
    sample_rate: 48000
  - platform: mixer
    id: mixer_speaker_id
    output_speaker: speaker_id
    source_speakers:
      - id: announcement_spk_mixer_input
      - id: media_spk_mixer_input
  - platform: resampler
    id: media_spk_resampling_input
    output_speaker: media_spk_mixer_input
  - platform: resampler
    id: announcement_spk_resampling_input
    output_speaker: announcement_spk_mixer_input
media_player:
  - platform: speaker
    name: "扬声器媒体播放器"
    id: speaker_media_player_id
    media_pipeline:
        speaker: media_spk_resampling_input
        num_channels: 2
    announcement_pipeline:
        speaker: announcement_spk_resampling_input
        num_channels: 1
    files:
      - id: alarm_sound
        file: alarm.flac # 放置在 yaml 目录中。应使用 48000 Hz 采样率、单声道或立体声音频以及每采样 16 位进行编码。
switch:
  - platform: template
    name: "响铃计时器"
    id: timer_ringing
    optimistic: true
    restore_mode: ALWAYS_OFF
    on_turn_off:
        # 停止播放闹钟
        - media_player.stop:
            announcement: true
        - mixer_speaker.apply_ducking:  # 在 2 秒内停止对媒体流的音量衰减
            id: media_spk_mixer_input
            decibel_reduction: 0
            duration: 2.0s
    on_turn_on:
        # 立即将媒体音频降低 20 分贝
        - mixer_speaker.apply_ducking:
            id: media_spk_mixer_input
            decibel_reduction: 20
            duration: 0.0s
        - while:
            condition:
                switch.is_on: timer_ringing
            then:
                # 将闹钟声音作为公告播放
                - media_player.speaker.play_on_device_media_file:
                    media_file: alarm_sound
                    announcement: true
                # 等待直到闹钟声音开始播放
                - wait_until:
                    media_player.is_announcing:
                # 等待直到闹钟声音停止播放
                - wait_until:
                    not:
                      media_player.is_announcing:

自动化

media_player.speaker.play_on_device_media_file 动作

此动作将播放设备内媒体文件。

on_...:
  # 简单形式
  - media_player.speaker.play_on_device_media_file: file_id

  # 完整形式
  - media_player.speaker.play_on_device_media_file:
      media_file: wake_word_trigger_sound
      announcement: true

配置变量：

• media_file (必需, ID): 媒体文件的 ID。
• announcement (可选, 布尔值): 是否将文件作为公告或媒体流播放。默认为 false。
• enqueue (可选, 布尔值): 是否将媒体文件添加到管道内部播放列表的末尾。默认为 false。

性能

解码音频文件是 CPU 和内存密集型操作。强烈建议使用 PSRAM 外部内存。要在内存受限的设备上使用此组件，请仅定义公告管道，减小缓冲区大小，将 codec_support_enabled 设置为 false，并将管道转码设置格式设置为 WAV，使用低采样率且仅 1 个通道。

网络优化

扬声器媒体播放器自动启用高性能网络以优化音频流。这会配置 WiFi 和 TCP/IP 设置以获得更好的吞吐量和更低的延迟。优化级别根据 PSRAM 情况调整：

• 保证有 PSRAM（Psram 配置为 ignore_not_found: false）：激进设置，512KB TCP 窗口和 512 个 WiFi RX 缓冲区
• 不保证有 PSRAM：保守优化设置，65KB TCP 窗口和 64 个 WiFi 缓冲区

如果您遇到内存不足问题，可以在 Network 组件配置中设置 enable_high_performance: false 来禁用这些优化。

音频编解码器性能

通常，解码 FLAC 的 CPU 使用率最低，但需要稳定的 WiFi 连接。解码 MP3 需要通过 WiFi 发送的数据较少，但解码时 CPU 占用更高。如果通过网络连接流式传输，仅建议在低采样率下解码 WAV。

增加缓冲区大小可以减少卡顿，但不要将其设置为外部内存的全部大小。每个管道都会分配配置的数量，此设置也不会考虑音频堆栈中分配的其他较小缓冲区。

仅当日志显示内存分配失败且配置了许多组件时，才将 task_stack_in_psram 设置为 true。它较慢，特别是如果您的 PSRAM 不支持 octal 模式。

故障排除

在故障排除时，请尽可能简化您的设置。仅配置 announcement_pipeline，不要使用 resampler 或 mixer 扬声器。

音频问题

如果听不到任何声音，请检查您的硬件是否需要将 GPIO 引脚设置为高电平或低电平才能启用扬声器。验证您是否配置了正确的扬声器通道：如果不确定哪些通道可用，请尝试将扬声器配置设置为立体声。

如果音频质量较差，请检查输出扬声器配置。尝试调整每采样位数、通道和采样率设置。通常，较高的采样率可以改善音频质量：尝试使用 44100 Hz 或 48000 Hz 而不是 16000 Hz。

如果暂停命令生效前有明显的延迟，请减小输出扬声器中的缓冲持续时间。如果使用了 mixer 扬声器组件，请务必同时调整硬件扬声器组件设置和 mixer 扬声器组件设置。

如果音频卡顿，且您的设备有 PSRAM，请添加（Psram 配置为 ignore_not_found: false），以便网络堆栈使用更高性能的优化设置。

另见

• 扬声器组件
• 混音扬声器
• 重采样扬声器
• 媒体播放器组件