Media Player Components

The media_player domain includes all platforms that implement media player functionality.

NOTE

ESPHome media players require Home Assistant 2022.6 or newer.

Base Media Player Configuration

media_player:
  - platform: ...
    name: "Media Player Name"

Configuration variables:

• id (Optional, string): Manually specify the ID for code generation. At least one of id and name must be specified.
• name (Optional, string): The name of the media player. At least one of id and name must be specified.

NOTE

If you have a friendly_name set for your device and you want the media player to use that name, you can set name: None.

• icon (Optional, icon): Manually set the icon to use for the media player in the frontend.

• internal (Optional, boolean): Mark this component as internal. Internal components will not be exposed to the frontend (like Home Assistant). Only specifying an id without a name will implicitly set this to true.

• disabled_by_default (Optional, boolean): If true, then this entity should not be added to any client’s frontend, (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI). Defaults to false.

• entity_category (Optional, string): The category of the entity. See https://developers.home-assistant.io/docs/core/entity/#generic-properties for a list of available options. Set to "" to remove the default entity category.

Media Player Actions

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

NOTE

Not all actions are supported by every media player platform. The availability of an action depends on the specific platform and its implemented features.

Configuration variables:

id (Optional, ID): The media player to control. Defaults to the only one in YAML. announcement (Optional, boolean): Whether to target announcements or regular media files, if supported by the media player. Defaults to false. Available on all command actions.

media_player.play Action

This action will resume playing the media player.

media_player.play_media Action

This action will start playing the specified media.

on_...:
  # Simple
  - media_player.play_media: 'http://media-url/media.mp3'

  # Full
  - media_player.play_media:
      id: media_player_id
      media_url: 'http://media-url/media.mp3'

  # Simple with lambda
  - media_player.play_media: !lambda 'return "http://media-url/media.mp3";'

Configuration variables:

media_url (Required, string): The media url to play.

media_player.pause Action

This action pauses the current playback.

media_player.stop Action

This action stops the current playback.

media_player.toggle Action

This action will pause or resume the current playback.

media_player.turn_off Action

This action will turn off the media player.

media_player.turn_on Action

This action will turn on the media player.

media_player.volume_up Action

This action will increase the volume of the media player.

media_player.volume_down Action

This action will decrease the volume of the media player.

media_player.mute Action

This action will mute the media player.

media_player.unmute Action

This action will unmute the media player.

media_player.next Action

This action will skip to the next track.

media_player.previous Action

This action will skip to the previous track.

media_player.repeat_off Action

This action will turn off repeat mode.

media_player.repeat_one Action

This action will set the media player to repeat the current track.

media_player.repeat_all Action

This action will set the media player to repeat all tracks.

media_player.shuffle Action

This action will enable shuffle mode.

media_player.unshuffle Action

This action will disable shuffle mode.

media_player.group_join Action

This action will join the media player to a group.

media_player.clear_playlist Action

This action will clear the media player’s playlist.

media_player.volume_set Action

This action will set the volume of the media player.

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

  # Full
  - media_player.volume_set:
      id: media_player_id
      volume: 50%

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

Configuration variables:

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

media_player.on_state Trigger

This trigger is activated each time the state of the media player is updated (for example, if the player is stop playing audio or received some command).

media_player:
  - platform: i2s_audio  # or any other platform
    # ...
    on_state:
      - logger.log: "State updated!"

media_player.on_play Trigger

This trigger is activated each time then the media player is started playing.

media_player:
  - platform: i2s_audio  # or any other platform
    # ...
    on_play:
      - logger.log: "Playback started!"

media_player.on_pause Trigger

This trigger is activated every time the media player pauses playback.

media_player:
  - platform: i2s_audio  # or any other platform
    # ...
    on_pause:
      - logger.log: "Playback paused!"

media_player.on_idle Trigger

This trigger is activated every time the media player finishes playing.

media_player:
  - platform: i2s_audio  # or any other platform
    # ...
    on_idle:
      - logger.log: "Playback finished!"

media_player.on_announcement Trigger

This trigger is activated every time the media player plays an announcement.

media_player:
  - platform: i2s_audio  # or any other platform
    # ...
    on_announcement:
      - logger.log: "Announcing!"

media_player.on_turn_off Trigger

This trigger is activated every time the media player is turned off.

media_player:
  - platform: ...  # any platform implementing the `supports_turn_off_on` trait
    # ...
    on_turn_off:
      - logger.log: "Media Player is Turned Off"

media_player.on_turn_on Trigger

This trigger is activated every time the media player is turned on.

media_player:
  - platform: ...  # any platform implementing the `supports_turn_off_on` trait
    # ...
    on_turn_on:
      - logger.log: "Media Player is Turned On"

media_player.is_idle Condition

This condition checks if the media player is idle.

# In some trigger:
on_...:
  if:
    condition:
      media_player.is_idle:

media_player.is_playing Condition

This condition checks if the media player is playing media.

# In some trigger:
on_...:
  if:
    condition:
      media_player.is_playing:

media_player.is_paused Condition

This condition checks if the media player is paused.

# In some trigger:
on_...:
  if:
    condition:
      media_player.is_paused:

media_player.is_announcing Condition

This condition checks if the media player is playing an announcement.

# In some trigger:
on_...:
  if:
    condition:
      media_player.is_announcing:

media_player.is_off Condition

This condition checks if the media player is turned off.

# In some trigger:
on_...:
  if:
    condition:
      media_player.is_off:

media_player.is_on Condition

This condition checks if the media player is turned on.

# In some trigger:
on_...:
  if:
    condition:
      media_player.is_on:

media_player.is_muted Condition

This condition checks if the media player is muted.

# In some trigger:
on_...:
  if:
    condition:
      media_player.is_muted:

Play media in order

You can use wait automation to play files one after the other:

# In some trigger:
on_...:
  then:
    - media_player.play_media: 'http://media-url/one.mp3'
    - wait_until:
        media_player.is_idle:
    - media_player.play_media: 'http://media-url/two.mp3'