2024.12.5
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
  • Standby: The media player is in a low power state, accepting commands.
  • Buffering: The media player is preparing to start playback of media.
  • Unavailable: The entity is currently unavailable.
  • Unknown: The state is not yet known.

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 media_player.volume_mute

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 media_player.volume_set

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_player.media_seek

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 media_player.play_media

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 media_player.select_source

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 media_player.select_sound_mode

Currently only supported on Denon AVR and Songpal.

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 media_player.shuffle_set

Currently only supported on Sonos, Spotify, MPD, Kodi, Roon, OwnTone, Squeezebox and Universal.

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 media_player.repeat_set

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 media_player.join

Allows to group 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 media_player.unjoin

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

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.

Related topics