Speaker Audio Media Player

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

此平台从外部 PSRAM 中受益匪浅。有关详情，请参见性能部分。

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

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

直接构建到固件中的设备文件可在无网络连接的情况下播放。设备文件应按照配置的采样率、1 或 2 个通道和每样本 16 位进行编码。

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

WARNING

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

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

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

配置变量

• announcement_pipeline（必需，Pipeline Schema）：公告流水线的配置设置。

  • speaker（必需，ID）：输出音频的扬声器。
  • format（可选，enum）：Home Assistant 在将音频发送到设备之前将其转码的音频格式。可选 FLAC、MP3、OPUS、WAV 或 NONE。NONE 将禁用 Home Assistant 中的转码；ESPHome 随后将为所有支持的编解码器（FLAC、MP3、OPUS 和 WAV）编译支持，这将增加固件大小。若要在不将此设置为 NONE 的情况下编译额外编解码器，请使用 Audio 组件。默认为 FLAC。
  • sample_rate（可选，positive integer）：转码音频的采样率。应被配置的 speaker 组件支持。默认为扬声器的采样率。OPUS 编解码器仅支持 48000 采样率。
  • num_channels（可选，positive integer）：转码音频的通道数。必须为 1 或 2。默认为扬声器的通道数。

• media_pipeline（可选，Pipeline Schema）：媒体流水线的配置设置。选项与 announcement_pipeline 相同。

• buffer_size（可选，positive integer）：每条流水线的缓冲区大小（以字节为单位）。必须在 4000 到 4000000 之间。默认为 1000000。

• task_stack_in_psram（可选，boolean）：在外部内存中运行音频任务。默认为 false。

• volume_increment（可选，percentage）：media_player.volume_up 和 media_player.volume_down 操作调高或调低音量的增量。默认为 5%。

• volume_initial（可选，percentage）：首次启动且之前未保存音量时，媒体播放器使用的默认音量。默认为 50%。

• volume_min（可选，percentage）：允许的最小音量。默认为 0%。

• volume_max（可选，percentage）：允许的最大音量。默认为 100%。

• files（可选，list）：要构建到固件中以用于设备上播放的媒体文件列表。

  • id（必需，ID）：文件的唯一 ID。
  • file（必需，string）：音频文件路径。可以是本地文件路径或 URL。

• on_mute（可选，Automation）：静音时执行的自动化。

• on_unmute（可选，Automation）：取消静音时执行的自动化。

• on_volume（可选，Automation）：音量更改时执行的自动化。

• on_turn_off（可选，Automation）：媒体播放器关闭时执行的自动化，实现了 supports_turn_off_on 特性。

• on_turn_on（可选，Automation）：媒体播放器打开时执行的自动化，实现了 supports_turn_off_on 特性。

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

示例配置

本示例将音频输出到以 48000 Hz 采样率配置的 I²S Audio 扬声器。它使用 mixer 扬声器组件来处理两条不同流水线的合并，并使用 resampler 扬声器组件确保源扬声器使用相同的采样率。

它添加了一个用于播放设备上的文件的开关以进行警报通知。在警报激活期间，任何正在播放的媒体都会被压声（ducking）。警报关闭后，媒体压声将逐渐停止。

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: "Speaker Media Player"
    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: "Ring Timer"
    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_...:
  # Simple
  - media_player.speaker.play_on_device_media_file: file_id

  # Full
  - media_player.speaker.play_on_device_media_file:
      media_file: wake_word_trigger_sound
      announcement: true

配置变量：

• media_file（必需，ID）：媒体文件的 ID。
• announcement（可选，boolean，templatable）：是否将文件作为公告或媒体流播放。默认为 false。
• enqueue（可选，boolean，templatable）：是否将媒体文件添加到流水线内部播放列表的末尾。默认为 false。

性能

解码音频文件对 CPU 和内存消耗很大。强烈建议使用外部 PSRAM。若要在内存受限的设备上使用此组件，请仅定义公告流水线，减小缓冲区大小，并将流水线转码设置格式设为 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 仅在通过网络连接以低采样率流式传输时推荐。

解码 OPUS 极其消耗 CPU 和内存，甚至可能无法在 ESP32 上实时解码。它仅适用于带有 PSRAM 的 ESP32-S3 设备。

如果在播放开始时（尤其是在原始 ESP32 上）遇到卡顿，可以通过 Audio 组件覆盖每个解码器库分配工作缓冲区的位置。

增加缓冲区大小可能减少卡顿，但不要将其设置为外部内存的整个大小。每条流水线分配配置的数量，且此设置也不考虑音频栈中分配的其他较小缓冲区。

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

故障排除

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

音频问题

如果听不到任何声音，请检查硬件是否需要将 GPIO 引脚设为高电平或低电平来启用扬声器。确认已正确配置扬声器通道：如果不清楚哪些通道可用，请尝试将扬声器配置设置为立体声。

如果音频质量差，请检查输出扬声器配置。尝试调整每样本位数、通道数和采样率设置。通常，更高的采样率会提升音频质量：尝试使用 44100 Hz 或 48000 Hz 而非 16000 Hz。

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

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

参见

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