Pre-requisites:

• A Premium Spotify Subscription
• Follow the Home Assistant Spotify instructions (https://www.home-assistant.io/integrations/spotify/) to get your Key and Secret

Optional pre-requisites:

• A MusixMatch API Key (free)
• Your playlist ID for Spotify that you'd like to add your listening history to (just the ID, not the full URI)

1. Make sure that Home Assistant Community Store (HACS) is setup.
2. Go to integrations in HACS
3. Click the 3 dots in the top right corner and choose Custom repositories
4. Paste the following into the repository input field https://github.com/hokiebrian/spotify_plus and choose category of Integration
5. Click add and restart HA to let the integration load
6. Go to settings and choose Devices & Services
7. Click Add Integration and search for Spotify Plus
8. Follow the instructions for Home Assistant Spotify (https://www.home-assistant.io/integrations/spotify/) to connect your Spotify account
9. Optionally add your MusixMatch API key and Spotify History Playlist
10. Restart Home Assistant

If the optional data is left blank, those features will not be called upon. You can simply enable those features by putting valid keys in the space provided.

This provides an enhanced experience for Spotify in your Home Assistant instance.

This platform is for Home Assistant users that want to leverage Home Assistant to be deeply integrated with their Spotify listening and want to be more adventurous in their music listening. Out of the box, it is a Spotify Media Player. What you do with it beyond that is entirely up to you. A tremendous amount of Spotify data is accessible through these services and some fun and exciting cards, automations, scripts and interfaces can be built on top of this data.

• Provides a playlist and queue creation utility that is highly customizable
• Provides a simple Media Player entity that updates every 3 seconds
• Provides various services to deeply interact with your Spotify Account
• A handy search feature that can perform Artist Profile lookups as well as a normal search
• Provides direct links to your Top Artist and Followed Artists Radio Stations and Playlists
• Analyzes your playlists (up to 100 tracks) for Spotify song parameters (e.g. Energy, Valence, etc.)
• Pull your queue and recent items

Optional Functions:

• Provides link to external Lyrics provider (MusixMatch)
• Add tracks to a spotify playlist of your choosing

Usage:

• All of the services are available to be called from the Home Assistant Frontend or via Automations and Scripts
• As a suggestion, add an automation that triggers when the Player attribute media_content_id changes and call the get_song_data and extras services
• Set your artists and playlists to refresh at whatever interval you choose. They do not poll at all unless called upon, but the data will survive restarts.
• Use auto-entities or Markdown cards to generate cards for your artists, playlists, search results, queue, recent items, etc.
• Use Song Info to visualize current track parameters (Energy, Valence, etc.)
• See EXAMPLES for interface examples

This service does the fun stuff. Select values for a playlist or queue of songs. All settings are optional.

Artist Driven: The service will leverage a selected set of artists (either your Top Artists - up to the top 100 - or the collective of your followed artists. Top Artists time range can be selected (1m, 6m, 1y+). Based on that info, a random selection of 10 artists will be selected as seeds for your playlist / queue, along with the song feature parameters you select. You can dump the recommendations to a playlist or have the selection be ephemeral and just get dropped into your queue. You can play immediately, or just create a playlist to consume later.

The track parameters you enter are passed to Spotify with a default range of +/- 20% around the entered values. If your value is 50%, the submitted ranged will be .30 - .70. The exceptions are hard pinned values for a few options, such as energy. If you pin energy to 100, the range will only br 90-100 instead of 80-100. If you simply drop it to 99, the range will be 79-100. This helps to get you a set of songs that really meet your needs if you want to go extreme on a setting.

If the pre-filtered recommended track list is small (<50), the service will perform an additional query for tracks based on your Top 50 tracks in an effort to boost the playlist size.

Manual Submission: The other way to use this service is to create playlist or queues based on specific artist(s), genre(s) or track(s). Passing a comma-separated list of seed_artists/genres/tracks IDs will override the library or top artist inputs. You can use any combination of the three seed values, but the TOTAL quantity cannot exceed 5. You should check this on the frontend prior to sending the seed values. There is not any logic to detect if too many values have been passed. The available seed genres are an attribute of sensor.spotify_plus. These are the only genres that can be passed. They do not match the genres that are assigned to albums or artists. I don't get it either.

The best way to consume this service is to try it out. It is very responsive and you'll get a 100 track playlist very quickly.

This service does a deep dive on the current track. Track name, album, album track number, track length, track audio features, boolean if you are following the arist/album/track, ISRC, link to MusixMatch Lyric (if you provided an API key), and more.

These services will add or remove the item to your library:

• spotify_plus.spotify_follow_artist
• spotify_plus.spotify_follow_album
• spotify_plus.spotify_follow_track
• spotify_plus.spotify_follow_playlist
• spotify_plus.spotify_unfollow_artist
• spotify_plus.spotify_unfollow_album
• spotify_plus.spotify_unfollow_track
• spotify_plus.spotify_unfollow_playlist

All of these services can accept the ID/URI for the artist/album/track/playlist as an optional argument. If no data is passed, it will assume the current artist/album/track/playlist that is currently playing

Extras pulls the current queue and recently played items, along with all the attributes of the tracks.

This service adds the currently playing track to the playlist ID you configured in the integration options. It will check if the item exists in the history playlist, remove it and re-add it to the top of the playlist. The goal here is to capture all of the unique tracks listened to.

This service takes the history playlist referenced above and analyzes the frequency of artists then sorts the list by frequency. That's it.

This service gathers data (Name, Image, Spotify URI) for all of your followed artists, along with their key playlists, such as "ARTIST Radio" and "This is ARTIST".

This service gathers data (Name, Image, Spotify URI) for your top 99 artists, along with their key playlists, such as "ARTIST Radio" and "This is ARTIST".

This service gathers data (Name, Image, Spotify URI, Average of Song Features (energy, valence, etc.), number of tracks) for all of your created or followed playlists.

Search Spotify... with a twist! There are two search methods, Artist Profile and General Search. Artist Profile will provide Artist details, such as albums (listed reverse chronologically), top tracks, playlists and Related Artists. The General Search is just that, with results broken into tracks, albums, playlists.

Pull up to 50 playlists for a specified category. The available categories for you are an attribute of the sensor.spotify_plus sensor.

• What's up with these recorder errors saying the attribute fields are too large? It is recommended to exclude an entity_glob from the recorder (exclude sensor.spotify_*). The secondary sensors that have large amounts of attribute data will survive a reboot, even if they are excluded from the recorder.
• I get "No Active Device" errors and nothing plays? This is a Spotify limitation. If the backend player has a state of Idle, you cannot pass a play command without passing a device_id along with it. Keep this in mind when calling services that use the service to trigger play events. You can pass the NAME of the device, the code handles the device_id lookup. The other option is to simply call media_player.select_source and activate the player. You'll see the status of the player go from 'idle' to 'paused'. You can always check this in your script or automation conditions.
• My playlists have almost no tracks - your parameters are too off balance, play with the values.
• Where is Tempo? Why can't I enter that? Tempo is a highly deceptive metric assigned by Spotify. It is all but guaranteed you'll be frustrated. I tried many different ways to make this work, but the metric just isn't a reliable one. I'd recommend using some other parameters, such as Dancability, to tweak your tracks.

• The Spotify API is typically very responsive and has few issues. There is always the random disconnect and other odd behaviors. This platform hits the API every 3 seconds with a light request and has proven reliable at that frequency. It was tested with a 1 second update interval and it worked great - but 86,400 requests per day seemed excessive, so it's 28,800.
• Please provide feedback and suggestions!