Media Player Service Enhancements - thlucas1/homeassistantcomponent_spotifyplus GitHub Wiki

The following enhancements were made to built-in services that are supported by the HA Media Player platform.

The integration also supports a number of custom services. Check out the Services Provided wiki document for a complete list.

The following HA media player standard features are supported by this integration:

  • BROWSE_MEDIA
  • MEDIA_ENQUEUE
  • NEXT_TRACK
  • PAUSE
  • PLAY
  • PLAY_MEDIA
  • PREVIOUS_TRACK
  • REPEAT_SET
  • SEEK
  • SELECT_SOUND_MODE
  • SELECT_SOURCE
  • SHUFFLE_SET
  • TURN_OFF
  • TURN_ON
  • VOLUME_MUTE
  • VOLUME_SET
  • VOLUME_STEP

SpotifyWebApiPython Library

The integration uses the SpotifyWebApiPython library to interface with the Spotify Web API for playback control and data gathering. The Spotipy library is no longer used.

Browse Media

It is suggested that you utilize the various custom services for browsing Spotify Catalog content, as they return much more detailed information. The browse_media service simply returns an HA Broswmedia object of basic data (e.g. Title, Id, and Image URL).

The following are some examples of broswing various Spotify content.

  • Album

    service: media_player.browse_media
data:
  entity_id: media_player.spotifyplus_john_s
  media_content_type: album
  media_content_id: spotify:album:0LhYYU14RU6IPQ9vVMu3Yk

  • Artist

    service: media_player.browse_media
data:
  entity_id: media_player.spotifyplus_john_s
  media_content_type: artist
  media_content_id: spotify:artist:6kFLnclYFc3gzpNt13wim5

  • Playlist

    service: media_player.browse_media
data:
  entity_id: media_player.spotifyplus_john_s
  media_content_type: playlist
  media_content_id: spotify:playlist:5v5ETK9WFXAnGQ3MRubKuE

  • Track

    service: media_player.browse_media
data:
  entity_id: media_player.spotifyplus_john_s
  media_content_type: track
  media_content_id: spotify:track:6zd8T1PBe9JFHmuVnurdRp

  • Show (aka. Podcast)

    service: media_player.browse_media
data:
  entity_id: media_player.spotifyplus_john_s
  media_content_type: show
  media_content_id: spotify:show:6kAsbP8pxwaU2kPibKTuHE

  • Episode (aka. Podcast Episode)

    service: media_player.browse_media
data:
  entity_id: media_player.spotifyplus_john_s
  media_content_type: episode
  media_content_id: spotify:episode:5h12bQsaYWkWP1ZBm05x6k

Example Response

A dictionary that contains an HA BrowseMedia object in dictionaty format.
This example is for a playlist request.

media_player.spotifyplus_john_s:
  title: Worship Playlist
  media_class: playlist
  media_content_type: playlist
  media_content_id: spotify:playlist:5v5ETK9WFXAnGQ3MRubKuE
  children_media_class: track
  can_play: true
  can_expand: true
  can_search: false
  thumbnail: >-
    https://image-cdn-fa.spotifycdn.com/image/ab67706c0000da842a1e8b013cde907c19a30af0
  not_shown: 0
  children:
    - title: Lovespeak
      media_class: track
      media_content_type: track
      media_content_id: spotify:track:5yIBlwkGBxySQjpBsgKh0X
      children_media_class: null
      can_play: true
      can_expand: false
      can_search: false
      thumbnail: https://i.scdn.co/image/ab67616d0000b273e7bb179e33dbec634ef30d83
    - title: I Need You
      media_class: track
      media_content_type: track
      media_content_id: spotify:track:6zd8T1PBe9JFHmuVnurdRp
      children_media_class: null
      can_play: true
      can_expand: false
      can_search: false
      thumbnail: https://i.scdn.co/image/ab67616d0000b2734bfd0e91bf806bc73d736cfd
    - title: The Flame Passes On
    ...

Player Status

With the release of v1.0.11, player status changes are detected in near real-time IF changes are made via Home Assistant (e.g. UI, service call, automation, etc).

This was accomplished by changing the integration SCAN_INTERVAL from 30 seconds to 1 second, but also adding logic to the update method to only call the underlying Spotify Web API at selected intervals:

  • call every 30 seconds if no user or track change activity.
  • call if a player command is issued: set_volume_level, media_play, media_pause, media_previous_track, media_next_track, media_seek, play_media, select_source, set_shuffle, and set_repeat.
  • call every second for 5 seconds after a player command is issued. This allows for extra time it may take for the Spotify Connect Player to update it's status after the command is processed.
  • call if the nowplaying track position has less than 5 seconds remaining. This is accomplished by subtracting the nowplaying DurationMS value (e.g. length of the track) from the nowPlaying track ProgressMS (e.g. current position of the track) value.

This logic adds a few more calls to the Spotify Web API, but not many. It's not perfect, but the acceptable trade-off is near real-time updates of Spotify Connect Player status.

Note that changes are NOT detected in near real-time if controlling the Spotify Connect Player from another non-HA device (e.g. Spotify Web App, Spotify Mobile App, etc). In this case, changes will be detected within 30 seconds by the HA state machine. For example, if you advance to the next track from the Spotify Web player, it will not show the change in HA for up to 30 seconds. This is a limitation of the Spotify Web API, in that Spotify does not offer a websockets API that informs clients of Spotify Connect Player status and relies on client polling.

Player Idling

If the integration is paused, the Spotify Connect Player service drops the connection to the player after about 10 minutes of inactivity. You will notice this, as the media information disappears (e.g. album / artist / track title, covert art image, etc) in the HA UI.

The integration will detect this scenario, and automatically issue a Spotify Web API Transfer Playback command to the default device to re-establish the connection to the Spotify Connect Player service when you resume play. This will also restore the media information (e.g. album / artist / track title, covert art image, etc). Note that it re-establishes the connection to the default device associated with the integration instance, so if you selected a different source for playback it will no longer be playing on that device. This is not a problem if you only have one device that you play Spotify content on.

Play should resume from where you left off, but to be honest I am not sure if that is always the case as it is controlled by the Spotify Connect Player service. Play was successfully resumed in all tests I have performed with my SoundTouch speaker devices.

Play Media (Enqueue)

The integration supports limited enqueue functions via the play_media service.

It's been my experience that the Spotify.com Queue display does not reflect the same contents as a call to the Spotify Web API Get Users Queue endpoint. Something to be aware of when you are trying to troubleshoot Player Queue issues.

The following enqueue commands are supported.

  • Play

    This example will start playing the specified content immediately.

    service: media_player.play_media
data:
  media_content_id: spotify:track:1nk99Y3YQlGOIf9xLiCZLP
  media_content_type: track
  enqueue: play
target:
  entity_id: media_player.spotifyplus_john_s

  • Play next

    This example will start playing the next item in the Spotify Player Queue. If there is no next item, then nothing is played. Note that the media_content_id uri value is not referenced, though it is required for the play_media service call.

    service: media_player.play_media
data:
  media_content_id: spotify:track:1nk99Y3YQlGOIf9xLiCZLP
  media_content_type: track
  enqueue: next
target:
  entity_id: media_player.spotifyplus_john_s

  • Add To Queue

    This example will append the media_content_id uri value to the Spotify Connect Player Queue. The currently playing media is not affected.

    service: media_player.play_media
data:
  media_content_id: spotify:track:1nk99Y3YQlGOIf9xLiCZLP
  media_content_type: track
  enqueue: next
target:
  entity_id: media_player.spotifyplus_john_s

  • Play Now and Clear Queue

    This example will start playing the specified content immediately. Note that it does not clear the queue, as there is no equivalent Spotify Web API function to clear the Spotify Connect Player Queue.

    service: media_player.play_media
data:
  media_content_id: spotify:track:1nk99Y3YQlGOIf9xLiCZLP
  media_content_type: track
  enqueue: replace
target:
  entity_id: media_player.spotifyplus_john_s

Play Media (Content Types)

The following are some examples of playing various Spotify content.

  • Album

    service: media_player.play_media
data:
  entity_id: media_player.spotifyplus_john_s
  media_content_type: album
  media_content_id: spotify:album:0LhYYU14RU6IPQ9vVMu3Yk

  • Artist

    service: media_player.play_media
data:
  entity_id: media_player.spotifyplus_john_s
  media_content_type: artist
  media_content_id: spotify:artist:6kFLnclYFc3gzpNt13wim5

  • Playlist

    service: media_player.play_media
data:
  entity_id: media_player.spotifyplus_john_s
  media_content_type: playlist
  media_content_id: spotify:playlist:5v5ETK9WFXAnGQ3MRubKuE

  • Track

    service: media_player.play_media
data:
  entity_id: media_player.spotifyplus_john_s
  media_content_type: track
  media_content_id: spotify:track:6zd8T1PBe9JFHmuVnurdRp

  • Show (aka. Podcast)

    service: media_player.play_media
data:
  entity_id: media_player.spotifyplus_john_s
  media_content_type: show
  media_content_id: spotify:show:6kAsbP8pxwaU2kPibKTuHE

  • Episode (aka. Podcast Episode)

    service: media_player.play_media
data:
  entity_id: media_player.spotifyplus_john_s
  media_content_type: episode
  media_content_id: spotify:episode:5h12bQsaYWkWP1ZBm05x6k

Search Media

It is suggested that you utilize the various search custom services for searching Spotify catalog content, as they return much more detailed information. The search_media service simply returns a list of HA Broswmedia objects of basic data (e.g. Title, Id, and Image URL).

Search results are limited to 10 matches per media type.

You can narrow down your search using field filters as part of the search_query argument. The available filters are album, artist, track, year, upc, tag:hipster, tag:new, isrc, and genre. Each field filter only applies to certain result types.

The artist and year filters can be used while searching albums, artists and tracks. You can filter on a single year or a range (e.g. 1955-1960).
The album filter can be used while searching albums and tracks.
The genre filter can be used while searching artists and tracks.
The isrc and track filters can be used while searching tracks.
The upc, tag:new and tag:hipster filters can only be used while searching albums. The tag:new filter will return albums released in the past two weeks and tag:hipster can be used to return only albums with the lowest 10% popularity.

See examples below for various search types.

Parameters

All parameters are required unless otherwise noted.

  • entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
  • search_query - Criteria used to search the Spotify catalog.
  • media_content_type (optional) - not used.
  • media_content_id (optional)- not used.
  • media_filter_classes - A dictionary of HA media classes to search for. note that Spotify only contains seven major media types that are searchable. The following HA MediaClass types are recognized by the integration (all others are ignored):
    • album - Spotify Album content.
    • artist - Spotify Artist content.
    • directory - Spotify Audiobook content.
    • episode - Spotify Episode content.
    • playlist - Spotify Playlist content.
    • podcast - Spotify Show content.
    • track - Spotify Track content.

The following are some examples of searching various Spotify content.

Search All Media Types

Search the Spotify catalog for all Albums, Artists, Audiobooks, Episodes, Playlists, Shows, and Tracks that contain the word "Love" in the title.

action: media_player.search_media
data:
  entity_id: media_player.spotifyplus_john_s
  search_query: Love
  media_filter_classes:
    - album
    - artist
    - directory
    - episode
    - playlist
    - podcast
    - track

Search Tracks by Artist

Search the Spotify catalog for Tracks that contain the word "Love" and were performed by Artist "MercyMe".

action: media_player.search_media
data:
  entity_id: media_player.spotifyplus_john_s
  search_query: "artist:MercyMe track:Love"
  media_filter_classes:
    - track

Search Tracks by Artist and Year

Search the Spotify catalog for Tracks that were released in 2025 by the Artist "MercyMe".

action: media_player.search_media
data:
  entity_id: media_player.spotifyplus_john_s
  search_query: "artist:MercyMe year:2025"
  media_filter_classes:
    - track

Search Playlists for Artist

Search the Spotify catalog for Playlists that contain content by the Artist "Seventh Day Slumber".

action: media_player.search_media
data:
  entity_id: media_player.spotifyplus_john_s
  search_query: "artist:Seventh Day Slumber"
  media_filter_classes:
    - playlist

Search for New Album Releases

Search the Spotify catalog for new album releases.

action: media_player.search_media
data:
  entity_id: media_player.spotifyplus_john_s
  search_query: "tag:new"
  media_filter_classes:
    - playlist

Search Response Example

A dictionary that contains a SearchMedia object, whose result argument contains a list of HA BrowseMedia objects in dictionary format.

media_player.spotifyplus_john_s:
  version: 1
  result:
    - title: Love
      media_class: album
      media_content_type: album
      media_content_id: spotify:album:29DUhof3Yr9NO5EdkzTNc4
      children_media_class: null
      can_play: true
      can_expand: true
      can_search: false
      thumbnail: https://i.scdn.co/image/ab67616d0000b2739f7d4096506c28d18f8f1750
      not_shown: 0
      children: []
      ...
    - title: Loverboy
      media_class: artist
      media_content_type: artist
      media_content_id: spotify:artist:2CLVPk9FcywjClBcTvWPkT
      children_media_class: null
      can_play: true
      can_expand: true
      can_search: false
      thumbnail: https://i.scdn.co/image/ab6761610000e5eb02a7fb52455eea92035311dc
      not_shown: 0
      children: []
      ...
    - title: "The 5 Love Languages: The Secret to Love that Lasts"
      media_class: directory
      media_content_type: audiobook
      media_content_id: spotify:show:3y5m3MDgcsEuilZL38d6Gz
      children_media_class: null
      can_play: true
      can_expand: true
      can_search: false
      thumbnail: https://i.scdn.co/image/ab676663000022a87ffc07bc3637148175a7dc67
      not_shown: 0
      children: []
      ...
    - title: "Huda: Love Island Tell All"
      media_class: episode
      media_content_type: episode
      media_content_id: spotify:episode:31WGkIPK4sY6NL94NeQpGG
      children_media_class: null
      can_play: true
      can_expand: false
      can_search: false
      thumbnail: https://i.scdn.co/image/ab6765630000ba8a11ac90f58651fe2084d3543b
      not_shown: 0
      children: []
      ...
    - title: Crazy Love Podcast
      media_class: podcast
      media_content_type: show
      media_content_id: spotify:show:34HxTaXogxr7FHDdkebrM9
      children_media_class: null
      can_play: true
      can_expand: true
      can_search: false
      thumbnail: https://i.scdn.co/image/ab6765630000ba8a82833496265c768994dd5481
      not_shown: 0
      children: []
      ...
    - title: Lovespeak
      media_class: track
      media_content_type: track
      media_content_id: spotify:track:5yIBlwkGBxySQjpBsgKh0X
      children_media_class: null
      can_play: true
      can_expand: false
      can_search: false
      thumbnail: https://i.scdn.co/image/ab67616d0000b273e7bb179e33dbec634ef30d83
      not_shown: 0
      children: []
      ...

Turn On / Turn Off

With the release of v1.0.12, the player supports the turn_on and turn_off media player services. Please refer to the Device Configuration Options - Integration Options wiki page for instructions on how to configure the power behavior.

Note

The Spotify Web API will not be queried when the media player is powered off - this is by design. It reduces traffic on your local network, as well as the extra load placed on Spotify Web API servers (and your Home Assistant instance) that service the request.

When powering on the integration, the previously selected source will resume play; if the previously selected source has been deactivated due to inactivity, then it will automatically be reactivated and play will resume. In the case of a Home Assistant restart, there is no previously selected source which will cause the configuration options Default Player Device ID to be selected if one was configured. If the Default Player Device ID option was not configured, then the player will be in an IDLE state with nothing playing.

You can transfer control to another Spotify Connect Device via the media player source list selection.

Spotify content can also be played via the HA media browser. The selected content will be played on the Spotify Connect Device that is selected in the media player source list. If the integration is powered off, then it will be powered on and the default device selected automatically.

Volume Set Step Level

Set level used for volume step services.

A system log warning is issued if specified level value is less than 0.01 or greater than 1.0, and the level is defaulted to 0.10.

Note that some devices require certain step / increment levels in volume adjustments. For example, the Bose SoundTouch devices require step increments of 10 percent and will raise exceptions if not specified in those increments. Consult your device manufacturer for their limitations and adjust accordingly.

Parameters

All parameters are required unless otherwise noted.

  • entity_id - Entity ID of the SpotifyPlus service that will process the request.
  • level - Level percentage to adjust the volume by. Default is 0.10 (e.g. 10 percent), range is 0.01 to 1.00 (e.g. 1 - 100 percent).

Example YAML

Set volume step level to 20 percent, and increase / decrease the volume.

action: spotifyplus.volume_set_step
data:
  entity_id: media_player.spotifyplus_john_s
  level: 0.20

action: media_player.volume_up
data:
  entity_id: media_player.spotifyplus_john_s

action: media_player.volume_down
data:
  entity_id: media_player.spotifyplus_john_s

State Custom Variables

The following custom state variables have been added (see Figure 1 below):

  • sp_artist_uri: Spotify Artist URI of the currently playing track; only populated if the type of item being played is a track, and at least one artist is returned in the track data from the current Spotify PlayerState.
  • sp_context_uri: Context URI
    Spotify uri for the currently playing context (e.g. "spotify:album:5ovMagVMhha9qq0OYDzXFm").
  • sp_device_id: Device ID
    Spotify device identifier that is currently active (e.g. "5d4931f9d0684b625d702eaa24137b2c1d99539c").
  • sp_device_name: Device Name
    Spotify device name that is currently active (e.g. "Bose-ST10-2"). This normally matches the source state attribute value, but can be different when the player is not playing active content.
  • sp_device_is_brand_sonos: Device Brand Sonos Indicator
    Denotes if the source device is a Sonos brand device (true) or not (false).
  • sp_device_is_chromecast: Device Brand Chromecast Indicator
    Denotes if the source device is a Google Chromecast device (true) or not (false).
  • sp_device_is_restricted: Device Restricted Indicator
    Denotes if the source device is considered a restricted device (true) or not (false) by the Spotify Web API.
  • sp_device_music_source: Device Music Source
    Music source currently selected on the source device; brand specific value.
  • sp_item_type: Item Type
    Denotes the type of item being played: track, podcast, or audiobook.
  • sp_play_time_remaining_est: Play Time Remaining Estimate Contains the estimated number of seconds remaining to be played in the currently playing track or episode, or null if nothing is playing. The value is only updated at every scan interval (e.g. 30 seconds) initially, but then reverts to updating every second for the final scan interval of the playing track. This allows you to create automations that can reliably detect when the track is nearing (within 30 seconds of) end of play. You should NOT check for specific seconds values, as sometimes it may skip a second or two depending on Spotify Web API response times during updates; always check for ranges (e.g. < 10, < 20 or > 10, etc).
  • sp_playing_type: Currently Playing Type
    The object type of the currently playing item, or null if nothing is playing. If not null, it can be one of track, episode, ad or unknown.
  • sp_playlist_name: Playlist Context Name
    Playlist name being played, if the current context is a playlist (e.g. "DJ"). Note that this value will not be returned if the context is a Spotify Algorithmic playlist (e.g. "Daily Mix 1", etc).
  • sp_playlist_uri: Playlist Context URI
    Playlist uri being played, if the current context is a playlist (e.g. "spotify:playlist:37i9dQZF1EYkqdzj48dyYq").
  • sp_source_list_hide: List of device names to hide from the source list (colon delimited).
  • sp_track_uri_origin: Currently playing track origin uri value resolved from playerstate linked_from data. This value contains the origin track uri value if track re-linking is in effect; otherwise, it contains the same value as the media_content_id value.
  • sp_track_is_explicit: Explicit Lyrics Indicator
    True if the track / episode has explicit content; otherwise, false.
  • sp_user_country: User Country Code / Market
    Country code for the active Spotify user account (e.g. "US").
  • sp_user_display_name: User Display Name
    Display name for the active Spotify user account (e.g. "Todd L").
  • sp_user_email: User EMail Address
    Email address for the active Spotify user account (e.g. "[email protected]").
  • sp_user_has_web_player_credentials: User Has Spotify Web player Credentials Indicator True if user has Spotify Web player Credentials configured for their Spotify user account; otherwise, false.
  • sp_user_id: User ID
    User-id for the active Spotify user account (e.g. "31l77y75hfnhk79f7gk6jkk878mg").
  • sp_user_product: User Product Level
    Product code for the active Spotify user account (e.g. "premium", "free", "unknown").
  • sp_user_uri: User URI
    Uri for the active Spotify user account (e.g. "spotify:user:31l77y75hfnhk79f7gk6jkk878mg").
  • volume_step: Volume Step Level Level percentage to adjust the volume by when using volume step services (e.g. 0.1). Default is 0.1, range is 0.1 to 1.0.

State Enhancement Screenshot

Figure 1 - Developer Tools, State Display
Unique values are hi-lited out for privacy.

⚠️ **GitHub.com Fallback** ⚠️