Speaker Source Media Player

The speaker_source media player platform orchestrates media source components that produce audio. When a media URL is received, the platform routes it to the appropriate source based on the URI prefix. For example, a URL starting with audio-file:// is handled by the Audio File media source.

It supports two independent audio pipelines: media and announcement. Each pipeline must output to a unique speaker. Use a mixer speaker component to create two different speakers that output to a single audio speaker.

Each pipeline maintains its own playlist with support for repeat (off, one, all) and shuffle modes. Volume and mute state are persisted to flash and restored on reboot.

This platform only works on ESP32-based chips using the ESP-IDF framework.

WARNING

Audio and voice components consume a significant amount of resources (RAM, CPU) on the device.

Crashes are likely to occur if you include too many additional components in your device’s configuration. In particular, Bluetooth/BLE components are known to cause issues when used in combination with Voice Assistant and/or other audio components.

# Example minimal configuration entry
audio_file:
  - id: alert_sound
    file: "sounds/alert.wav"

media_source:
  - platform: audio_file
    id: file_source

media_player:
  - platform: speaker_source
    media_pipeline:
      speaker: my_speaker_id
      sources:
        - file_source

Configuration variables

media_pipeline (Optional, Pipeline Schema): Configuration settings for the media pipeline. At least one of media_pipeline or announcement_pipeline is required.
- speaker (Required, ID): The speaker to output the audio.
- sources (Required, list of IDs): A list of media source component IDs to use for this pipeline. At least one source is required. When a media URL is received, the pipeline finds the first source that can handle the URI prefix. Each source can only belong to one pipeline; if both pipelines need the same type of source, configure separate instances.
- format (Optional, enum): The audio format Home Assistant will transcode audio to before sending it to the device. One of FLAC, MP3, OPUS, WAV, or NONE. NONE disables transcoding in Home Assistant; ESPHome will then compile support for all supported codecs (FLAC, MP3, OPUS, and WAV), which increases firmware size. To compile in additional codecs without setting this to NONE, use the Audio component. Defaults to FLAC.
- sample_rate (Optional, positive integer): Sample rate for the transcoded audio. Should be supported by the configured speaker component. Defaults to the speaker’s sample rate. The OPUS codec only supports a 48000 sample rate.
- num_channels (Optional, positive integer): Number of channels for the transcoded audio. Must be either 1 or 2. Defaults to the speaker’s number of channels.
- bitrate (Optional, positive integer): Constant bitrate in kbps that Home Assistant encodes MP3 at, one of 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160, 192, 224, 256 or 320. Only valid when format is MP3. When omitted, Home Assistant uses its default variable bitrate.
announcement_pipeline (Optional, Pipeline Schema): Configuration settings for the announcement pipeline. Same options as media_pipeline. Must use a different speaker than media_pipeline.
volume_increment (Optional, percentage): Increment amount that the media_player.volume_up and media_player.volume_down actions will increase or decrease volume by. Defaults to 5%.
volume_initial (Optional, percentage): The default volume used on first boot when no volume has been previously saved. Defaults to 50%.
volume_min (Optional, percentage): The minimum volume allowed. Defaults to 0%.
volume_max (Optional, percentage): The maximum volume allowed. Defaults to 100%.
announcement_volume (Optional, percentage): The volume for announcements that start while no media is playing. Scaled between volume_min and volume_max like the media player volume. Requires both announcement_pipeline and media_pipeline. If not set, announcements use the media player volume. See Announcement Volume.
on_mute (Optional, Automation): An automation to perform when muted.
on_unmute (Optional, Automation): An automation to perform when unmuted.
on_volume (Optional, Automation): An automation to perform when the volume is changed.
All other options from Media Player

Announcement Volume

When announcement_volume is set, an announcement that starts while nothing is playing uses that volume instead of the media player volume. Paused media counts as not playing. An announcement that starts while media is playing, or while another announcement plays at the media player volume, keeps the media player volume.

The media player volume is restored when the announcements finish or when media starts playing. Changing the volume during the announcement, for example with media_player.volume_set, ends the announcement volume and applies the new volume right away. The volume reported to Home Assistant and saved to flash is always the media player volume.

To change the announcement volume at runtime, use the speaker_source.set_announcement_volume action.

Example Configuration

This example configures a dual-pipeline setup using an I²S Audio Speaker with a mixer speaker to combine both pipelines and resampler speakers for sample rate matching. It uses Audio File media sources for both pipelines.

audio_file:
  - id: alert_sound
    file: "sounds/alert.wav"

media_source:
  - platform: audio_file
    id: announcement_file_source
  - platform: audio_file
    id: media_file_source

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_source
    name: "Speaker Source Media Player"
    id: speaker_source_media_player_id
    media_pipeline:
      speaker: media_spk_resampling_input
      format: FLAC
      num_channels: 2
      sources:
        - media_file_source
    announcement_pipeline:
      speaker: announcement_spk_resampling_input
      format: FLAC
      num_channels: 1
      sources:
        - announcement_file_source

Automations

`speaker_source.set_playlist_delay` Action

This action sets the delay between consecutive tracks in a pipeline’s playlist. This can be useful to add a pause between announcement files or between media tracks.

on_...:
  - speaker_source.set_playlist_delay:
      id: speaker_source_media_player_id
      pipeline: media
      delay: 500ms

Configuration variables:

id (Required, ID): The speaker source media player to control.
pipeline (Required, enum): Which pipeline to set the delay for. One of media or announcement.
delay (Required, Time, templatable): The delay between playlist tracks.

`speaker_source.set_announcement_volume` Action

This action sets the announcement volume. If an announcement is playing at the announcement volume, the new volume applies right away. The value is not saved; after a reboot the configured announcement_volume applies again. If announcement_volume is not configured, this action turns the announcement volume on, as long as both announcement_pipeline and media_pipeline are configured.

on_...:
  # Simple
  - speaker_source.set_announcement_volume: 70%

  # Full
  - speaker_source.set_announcement_volume:
      id: speaker_source_media_player_id
      volume: 70%

Configuration variables:

id (Optional, ID): The speaker source media player to control. Required if more than one is configured.
volume (Required, percentage, templatable): The announcement volume. A lambda returns a value between 0.0 and 1.0.

Base Media Player Actions

This platform supports all media player actions including play, pause, stop, toggle, volume_set, volume_up, volume_down, mute, unmute, next, previous, repeat_off, repeat_one, repeat_all, shuffle, unshuffle, and clear_playlist.

When using the media_player.play_media action, the media URL is routed to the first source in the pipeline that can handle the URI prefix. For example, a URL starting with audio-file:// is routed to an Audio File media source.