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 aname
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.
Configuration variables:
id (Optional, ID): The media player to control. Defaults to the only one in YAML.
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.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.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.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:
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'