Skip to content

Media Player Service Enhancements

Jump to bottom
Todd Lucas edited this page Dec 12, 2024 · 19 revisions

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.

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

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.

State Custom Variables

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

  • media_playlist_content_id: Playlist Context Content ID
    contains a Spotify URI value of the currently active playlist context if a playlist is active; otherwise, null.
  • spotifyplus_device_id: Device ID
    contains the Spotify Connect Player device id if one is active; otherwise no_device.
  • spotifyplus_device_name: true / false
    contains the Spotify Connect Player device name if one is active; otherwise no_device. This normally matches the source state attribute value, but can be different when the player is not playing active content.

State Enhancement Screenshot

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

Clone this wiki locally