Speaker Components

The speaker domain contains common functionality shared across the speaker platforms.

Base Speaker Configuration

speaker:
  - platform: ...

Configuration variables:

• audio_dac (Optional, ID or list of IDs): The audio DAC to use for volume control. Can also be a list of audio DAC IDs that all receive this speaker’s audio. Every audio DAC in the list gets the same volume and mute. Each audio DAC can only be listed once.

# Example: two amplifiers on one I²S output
speaker:
  - platform: i2s_audio
    # ...
    audio_dac: [front_amp, rear_amp]

NOTE

A list of audio DACs must be on the same I²S data line. ESPHome can’t detect this from the YAML, because it doesn’t know how I²S outputs are physically wired. An audio DAC connected to a different I²S output, or another speaker’s data line, would follow this speaker’s volume and mute instead of its own.

Speaker Actions

All speaker actions can be used without specifying an id if you have only one speaker in your configuration YAML.

speaker.play Action

This action will start playing raw audio data from the speaker.

on_...:
  # Static raw audio data
  - speaker.play: [...]

  # Templated, return type is `std::vector<uint8_t>`
  - speaker.play: !lambda return {...};

  # in case you need to specify the speaker id
  - speaker.play:
      id: my_speaker
      data: [...]

Configuration variables:

• id (Optional, ID): The speaker to control. Defaults to the only one in YAML.
• data (Required, list of bytes, templatable): The raw audio data to play.

speaker.stop Action

This action will stop playing audio data from the speaker and discard the unplayed data.

Configuration variables:

• id (Optional, ID): The speaker to control. Defaults to the only one in YAML.

speaker.finish Action

This action will stop playing audio data from the speaker after all data is played.

Configuration variables:

• id (Optional, ID): The speaker to control. Defaults to the only one in YAML.

speaker.mute_on Action

This action will mute the speaker.

Configuration variables:

• id (Optional, ID): The speaker to control. Defaults to the only one in YAML.

speaker.mute_off Action

This action will unmute the speaker.

Configuration variables:

• id (Optional, ID): The speaker to control. Defaults to the only one in YAML.

speaker.volume_set Action

This action will set the volume of the speaker.

on_...:
  # Simple
  - speaker.volume_set: 50%

  # Full
  - speaker.volume_set:
      id: speaker_id
      volume: 50%

  # Simple with lambda
  -  speaker.volume_set: !lambda "return 0.5;"

Configuration variables:

volume (Required, percentage): The volume to set the speaker to.

Speaker Conditions

All speaker conditions can be used without specifying an id if you have only one speaker in your configuration YAML.

speaker.is_playing Condition

This condition will check if the speaker is currently playing audio data.

Configuration variables:

• id (Optional, ID): The speaker to check. Defaults to the only one in YAML.

speaker.is_stopped Condition

This condition will check if the speaker is fully stopped audio data and is in idle mode.

.. note:

Between the time speaker.is_playing is false and speaker.is_stopped is true the ‘speaker’ component is closing down structures that where used to play the data correctly. It better to check if the speaker is stopped then that if it plays.

Configuration variables:

• id (Optional, ID): The speaker to check. Defaults to the only one in YAML.

Platforms

See Also

• Create audio clip files for use with I²S Speakers
• I²S Audio Speaker