Home ▸ Integrations

Media player

Interacts with media players on your network.

Note

Building block integration

This media player is a building block integration that cannot be added to your Home Assistant directly but is used and provided by other integrations.

A building block integration differs from the typical integration that connects to a device or service. Instead, other integrations that do integrate a device or service into Home Assistant use this media player building block to provide entities, services, and other functionality that you can use in your automations or dashboards.

If one of your integrations features this building block, this page documents the functionality the media player building block offers.

The state of a media player

A media player can have the following states:

Off: The media player is turned off and is not accepting commands until turned on.
On: The media player is turned on, but no details on its state are currently known.
Idle: The media player is turned on and accepting commands, but currently not playing any media. Possibly at some idle home screen.
Playing: The media player is currently playing media.
Paused: The media player has an active media and is currently paused
Buffering: The media player is preparing to start playback of media.
Unavailable: The entity is currently unavailable.
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 after one or more media players are muted.
Media player paused playing (media_player.paused_playing) Triggers after one or more media players pause playing.
Media player started playing (media_player.started_playing) Triggers after one or more media players start playing.
Media player stopped playing (media_player.stopped_playing) Triggers after one or more media players stop playing.
Media player turned off (media_player.turned_off) Triggers after one or more media players turn off.
Media player turned on (media_player.turned_on) Triggers after one or more media players turn on.
Media player unmuted (media_player.unmuted) Triggers after one or more media players are unmuted.
Media player volume changed (media_player.volume_changed) Triggers after the volume of one or more media players changes.
Media player volume crossed threshold (media_player.volume_crossed_threshold) Triggers after 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.
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.

Actions

Media control actions

Available actions: turn_on, turn_off, toggle, volume_up, volume_down, volume_set, volume_mute, media_play_pause, media_play, media_pause, media_stop, media_next_track, media_previous_track, clear_playlist, shuffle_set, repeat_set, play_media, select_source, select_sound_mode, join, unjoin

Data attribute	Optional	Description
`entity_id`	yes	Target a specific media player. To target all media players, use `all`.

Action: Volume mute

The media_player.volume_mute action mutes or unmutes the volume of a media player.

Data attribute	Optional	Description
`entity_id`	yes	Target a specific media player. To target all media players, use `all`.
`is_volume_muted`	no	True/false for mute/unmute

Action: Volume set

The media_player.volume_set action sets the volume level of a media player.

Data attribute	Optional	Description
`entity_id`	yes	Target a specific media player. To target all media players, use `all`.
`volume_level`	no	Float for volume level. Range 0..1

Action: Media seek

The media_player.media_seek action seeks to a specific position in the currently playing media.

Data attribute	Optional	Description
`entity_id`	yes	Target a specific media player. To target all media players, use `all`.
`seek_position`	no	Position to seek to. The format is platform dependent.

Action: Play media

The media_player.play_media action plays media on a media player.

Data attribute	Optional	Description
`entity_id`	yes	Target a specific media player. To target all media players, use `all`.
`media_content_id`	no	A media identifier. The format of this is integration dependent. For example, you can provide URLs to Sonos and Cast but only a playlist ID to iTunes.
`media_content_type`	no	A media type. Must be one of `music`, `tvshow`, `video`, `episode`, `channel` or `playlist`. For example, to play music you would set `media_content_type` to `music`.
`enqueue`	yes	How the new media should interact with the queue. Must be one of `add`, `next`, `play`, `replace`. If the media player doesn’t support this feature, the new media will play and the `enqueue` directive is ignored.
`announce`	yes	Set to `true` to request the media player to temporarily stop playing media to announce this media and then resume. If the media player doesn’t support this feature, the announcement will play but the media player and will not resume playing the interrupted media once the announcement finishes.
`extra`	yes	Extra dictionary data to send, e.g., title, thumbnail. Possible values can be found below.

Extra dictionary data

Configuration Variables

Looking for your configuration file?

title string (Optional)

Title of the media.

thumb string (Optional)

Thumbnail image URL.

current_time float (Optional)

Seconds since the beginning of the content. If the content is live content, and the position is not specified, the stream will start at the live position.

autoplay boolean (Optional, default: true)

Whether the media will automatically play.

stream_type string (Optional)

Describes the type of media artifact as one of the following: NONE, BUFFERED, LIVE.

subtitles string (Optional)

URL of subtitle file to be shown on chromecast.

subtitles_lang string (Optional)

Language for subtitles.

subtitles_mime string (Optional)

Mimetype of subtitles.

subtitle_id integer (Optional)

ID of subtitle to be loaded.

enqueue boolean (Optional, default: false)

If True, enqueue the media instead of play it.

media_info map (Optional)

Additional MediaInformation attributes not explicitly listed.

metadata map (Optional)

Media metadata object, one of the following: GenericMediaMetadata, MovieMediaMetadata, TvShowMediaMetadata, MusicTrackMediaMetadata, PhotoMediaMetadata.

Documentation:

Example of calling media player action with title and image set:

action: media_player.play_media
target:
  entity_id: media_player.chromecast
data:
  media_content_type: music
  media_content_id: "https://fake-home-assistant.io.stream/aac"
  extra:
    thumb: "https://brands.home-assistant.io/_/homeassistant/logo.png"
    title: HomeAssistantRadio

Action: Select source

The media_player.select_source action selects an input source for a media player.

Data attribute	Optional	Description
`entity_id`	yes	Target a specific media player. To target all media players, use `all`.
`source`	no	Name of the source to switch to. Platform dependent.

Action: Select sound mode

The media_player.select_sound_mode action selects a sound mode for a media player.

Data attribute	Optional	Description
`entity_id`	yes	Target a specific media player. For example `media_player.marantz`
`sound_mode`	no	Name of the sound mode to switch to. Platform dependent.

Action: Shuffle set

The media_player.shuffle_set action enables or disables shuffle mode for a media player.

Data attribute	Optional	Description
`entity_id`	yes	Target a specific media player. For example `media_player.spotify`
`shuffle`	no	`true`/`false` for enabling/disabling shuffle

Action: Repeat set

The media_player.repeat_set action sets the repeat mode for a media player.

Data attribute	Optional	Description
`entity_id`	yes	Target a specific media player. For example `media_player.kitchen`
`repeat`	no	`off`/`all`/`one` for setting repeat mode

Action: Join

The media_player.join action groups media players together for synchronous playback. Only works on supported multiroom audio systems.

Data attribute	Optional	Description
`entity_id`	yes	The media player entity whose playback will be expanded to the players specified in `group_members`.
`group_members`	no	The player entities which will be synced with the playback from `entity_id`.

Action: Unjoin

The media_player.unjoin action unjoins a media player from any player groups.

Data attribute	Optional	Description
`entity_id`	yes	Unjoin this media player from any player groups.

Action: Browse media

The media_player.browse_media action provides access to browsing the media tree provided by the integration. Similar in functionality to browsing media through the media player UI. Common use cases include automations that need to navigate media libraries and find media by specific categories.

Data attribute	Optional	Description
`media_content_type`	yes	The type of media to browse such as music, playlist, and video. Integration specific.
`media_content_id`	yes	The content ID to browse. Integration specific. An empty content ID returns the top-level of the browse tree.

The action returns a media tree object that can be stored in a response variable for use in subsequent automation steps. The response includes:

Field	Description
`title`	Display name of the current level
`media_class`	Type of the current item (for example, directory, music, video)
`media_content_type`	Content type identifier
`media_content_id`	Integration specific content ID
`children_media_class`	Types of items in the children array
`children`	Array of child items with similar properties

Browse the root of the tree.

Note: The following example shows a response from a Sonos device. The structure and content types may vary between different media player integrations. Media content IDs are often URL-encoded.

  # Get the top of the browse tree
  - action: media_player.browse_media
    target:
      entity_id: media_player.living_room
    response_variable: top_level

# abbreviated Example response
media_player.living_room:
  title: Sonos
  media_class: directory
  media_content_type: root
  media_content_id: ""
  # children_media_class indicates that all items in the children array are directories  
  children_media_class: directory
  children:
    - title: Favorites
      media_class: directory
      media_content_type: favorites
      media_content_id: ""
    - title: Music Library
      media_class: directory
      media_content_type: library
      media_content_id: ""

Example of browsing a specific artist with the Sonos Integration:

Note: This example demonstrates browsing an artist’s albums. The format of media_content_id (A:ALBUMARTIST/artist_name) is specific to Sonos. Notice how special characters in album names are URL-encoded in the response (for example, %20 for spaces).

  - action: media_player.browse_media
    target:
      entity_id: media_player.living_room
    data:
      media_content_id: A:ALBUMARTIST/Beatles
      media_content_type: album
    response_variable: albums

# Abbreviated Example response
media_player.living_room:
  title: Beatles
  media_class: album
  media_content_type: album
  media_content_id: A:ALBUMARTIST/Beatles
  children_media_class: directory
  children:
    - title: A Hard Day's Night
      media_class: album
      media_content_type: album
      media_content_id: A:ALBUMARTIST/Beatles/A%20Hard%20Day's%20Night
    - title: Abbey Road
      media_class: album
      media_content_type: album
      media_content_id: A:ALBUMARTIST/Beatles/Abbey%20Road

Media player automation examples

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

Tip

You don’t need to edit YAML to use these examples. Copy a YAML snippet from this page, open the automation editor in Home Assistant, and press Ctrl+V (or Cmd+V on Mac). Home Assistant automatically converts the pasted YAML into the visual editor format, whether it’s a full automation, a single trigger, a condition, or an action.

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

YAML example for dimming the room when a movie starts

Automation

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)

YAML example for a bedtime playback reminder

Automation

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

A device class is a measurement categorization in Home Assistant. It influences how the entity is represented in the dashboard. This can be modified in the customize section. For example, different states may be represented by different icons, colors, or text.

The screenshot shows different icons representing device classes of the media player entity:

Screenshot showing different icons representing device classes of the media player entity Example of different icons representing device classes of the media player entity.

The following device classes are supported for media players:

tv: Device is a television type device.
speaker: Device is a speaker or stereo type device.
receiver: Device is an audio/video receiver type device taking audio and outputting to speakers and video to displays.

Help us improve our documentation

Suggest an edit to this page, or provide/view feedback for this page.

The state of a media player

List of triggers

List of conditions

Actions

Media control actions

Action: Volume mute

Action: Volume set

Action: Media seek

Action: Play media

Extra dictionary data

Configuration Variables

Action: Select source

Action: Select sound mode

Action: Shuffle set

Action: Repeat set

Action: Join

Action: Unjoin

Action: Browse media

Media player automation examples

Automation: dim the room when a movie starts

Automation: send a bedtime reminder if audio is still playing

Device class

Related topics

Help us improve our documentation