Media player

Interacts with media players on your network.

Media player states

A media player can have the following states. Each item shows the label you see in the Home Assistant interface, followed by the state as Home Assistant stores it. If you write templates or edit automations in YAML, use the stored state.

• Off (off): The media player is turned off and is not accepting commands until turned on.
• On (on): The media player is turned on, but no details on its state are currently known.
• Idle (idle): The media player is turned on and accepting commands, but not playing any media. For example, it might show a home screen.
• Playing (playing): The media player is currently playing media.
• Paused (paused): The media player has media loaded and is paused.
• Buffering (buffering): The media player is preparing to start playback of media.
• Unavailable (unavailable): The entity is currently unavailable.
• Unknown (unknown): The state is not yet known.

List of triggers

The Media player integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following triggers. Each link below opens a dedicated page with examples, fields, and a step-by-step UI walkthrough.

• Media player muted (media_player.muted) Triggers when one or more media players are muted.

• Media player paused playing (media_player.paused_playing) Triggers when one or more media players pause playing.

• Media player started playing (media_player.started_playing) Triggers when one or more media players start playing.

• Media player stopped playing (media_player.stopped_playing) Triggers when one or more media players stop playing.

• Media player turned off (media_player.turned_off) Triggers when one or more media players turn off.

• Media player turned on (media_player.turned_on) Triggers when one or more media players turn on.

• Media player unmuted (media_player.unmuted) Triggers when one or more media players are unmuted.

• Media player volume changed (media_player.volume_changed) Triggers when the volume of one or more media players changes.

• Media player volume crossed threshold (media_player.volume_crossed_threshold) Triggers when the volume of one or more media players crosses a threshold.

For an overview of every trigger across all integrations, see the triggers reference.

List of conditions

The Media player integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following conditions. Each link below opens a dedicated page with examples, fields, and a step-by-step UI walkthrough.

• Media player is muted (media_player.is_muted) Tests if one or more media players are muted.

• Media player is not playing (media_player.is_not_playing) Tests if one or more media players are not playing.

• Media player is off (media_player.is_off) Tests if one or more media players are off.

• Media player is on (media_player.is_on) Tests if one or more media players are on.

• Media player is paused (media_player.is_paused) Tests if one or more media players are paused.

• Media player is playing (media_player.is_playing) Tests if one or more media players are playing.

• Media player is not muted (media_player.is_unmuted) Tests if one or more media players are not muted.

• Media player volume (media_player.is_volume) Tests the volume of one or more media players.

For an overview of every condition across all integrations, see the conditions reference.

List of actions

The Media player integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following actions. Each link below opens a dedicated page with examples, parameters, and a step-by-step UI walkthrough.

• Browse media (media_player.browse_media) Browses the media available on a media player.

• Clear media player playlist (media_player.clear_playlist) Removes all items from a media player’s playlist.

• Join media players (media_player.join) Groups media players together for synchronous playback.

• Next track (media_player.media_next_track) Selects the next track on a media player.

• Pause media (media_player.media_pause) Pauses playback on a media player.

• Play media (media_player.media_play) Starts playback on a media player.

• Play/Pause media (media_player.media_play_pause) Toggles play and pause on a media player.

• Previous track (media_player.media_previous_track) Selects the previous track on a media player.

• Seek media (media_player.media_seek) Jumps to a different position in the media currently playing.

• Stop media (media_player.media_stop) Stops playback on a media player.

• Play specified media (media_player.play_media) Plays specific media on a media player.

• Set media player repeat (media_player.repeat_set) Sets the repeat mode of a media player.

• Search media (media_player.search_media) Searches the media available on a media player.

• Select media player sound mode (media_player.select_sound_mode) Selects a sound mode of a media player.

• Select media player source (media_player.select_source) Changes the input source of a media player.

• Set media player shuffle (media_player.shuffle_set) Enables or disables shuffle mode on a media player.

• Toggle media player (media_player.toggle) Toggles a media player on or off.

• Turn off media player (media_player.turn_off) Turns off a media player.

• Turn on media player (media_player.turn_on) Turns on a media player.

• Unjoin media player (media_player.unjoin) Removes a media player from a group.

• Turn down media player volume (media_player.volume_down) Turns down the volume of a media player.

• Mute/unmute media player (media_player.volume_mute) Mutes or unmutes a media player.

• Set media player volume (media_player.volume_set) Sets the volume level of a media player.

• Turn up media player volume (media_player.volume_up) Turns up the volume of a media player.

For an overview of every action across all integrations, see the actions reference.

Media player automation examples

Here are a few examples of how you can use Media player triggers and conditions in automations.

Automation: dim the room when a movie starts

When the living room TV starts playing, dim the lights so the room is ready for watching.

• Trigger: Media player started playing
  • Target: Living room TV
• Action: Turn on light
  • Target: Living room lights

alias: "Dim the room when the TV starts playing"
triggers:
  - trigger: media_player.started_playing
    target:
      entity_id: media_player.living_room_tv
actions:
  - action: light.turn_on
    target:
      entity_id: light.living_room_lights
    data:
      brightness_pct: 25

Automation: send a bedtime reminder if audio is still playing

At bedtime, check whether the bedroom speaker is still playing, and send a notification if it is.

• Trigger: Time: 23:00
• Condition: Media player is playing
  • Target: Bedroom speaker
• Action: Send a notification message
  • Target: My Device (notify.my_device)

alias: "Remind me when audio is still playing at bedtime"
triggers:
  - trigger: time
    at: "23:00:00"
conditions:
  - condition: media_player.is_playing
    target:
      entity_id: media_player.bedroom_speaker
actions:
  - action: notify.send_message
    target:
      entity_id: notify.my_device
    data:
      message: >
        Bedroom audio is still playing.

Device class

The device class tells Home Assistant what kind of media player an entity is, such as a TV or a speaker. Home Assistant uses the device class to choose the icon. Google Assistant, Alexa, and Apple Home use the device class to decide what kind of device to show.

The integration that provides the media player sets the device class.

Device classes in automations and templates

• Automations: The device class doesn’t change how a media player works in automations.
• Templates: The device class is the device_class attribute of the entity. Use the stored value, such as tv. For example, you can find entities by device class.

List of available device classes

A media player without a device class is a generic media player and shows by default.

Each item shows the name you see in the Home Assistant interface, followed by the device class as Home Assistant stores it.

• TV (tv): A television.
• Speaker (speaker): A speaker.
• Receiver (receiver): A device that takes audio and video input and outputs it to speakers and displays.
• Projector (projector): A projector.