Skip to content

Spotify Connect Brand Notes

Jump to bottom
Todd Lucas edited this page Nov 10, 2024 · 20 revisions

This document tries to explain why the SpotifyPlus integration can behave erratically for certain device manufacturers.

The SpotifyPlus integration utilizes the Spotify Web API to control the Spotify Connect Player transport, as well as obtain Player state information. The Spotify Web API is updated correctly with player status information when the player is controlled from the Spotify Desktop, Mobile, or Web Applications.

Most manufacturers adhere to this standard, and update the Spotify Web API status accordingly; however, there are some manufacturers that don't! The SpotifyPlus integration can exhibit problems when a manufacturer does not correctly update the Spotify Web API with current status / transport control information for their device(s).

With that said, let's break things down by manufacturer ...

Sonos

Sonos does not fully implement the Spotify Connect API correctly, in that the Sonos Desktop Application does NOT keep the Spotify Web API informed of status updates or transport status. This is why it is flagged as a restricted device when querying the player state via the Spotify Web API Get Playback State endpoint.

The integration utilizes the Sonos Controller (or SoCo) Python package to interface with the Sonos device. The SoCo package utilizes the Sonos Control API in its code to access the Sonos device.

Note that the SpotifyPlus integration ONLY processes information from the Sonos device when it is playing Spotify Music Service content. You will need to use the Sonos Music Player integration if you want to control / display content from other Sonos music services.

For best results, it is recommended that you use the HA SpotifyPlus integration or Spotify Desktop / Mobile / Web applications to control the Sonos device. Do not use the Sonos Desktop / Mobile applications, as they do not fully communicate status updates to the Spotify Web API.

And if you have not done so, make sure to check out the OAuth2 Token for TokenType=Authorization_Code Devices documentation for enabling better support of Spotify Connect functionality on Sonos devices.

Sonos Limitations

The following are known limitations when using the SpotifyPlus integration with Sonos devices:

  • Sonos can play most Spotify media content types via the media browser: playlists, tracks, albums, podcasts. It seems to have trouble playing Spotify artists and audiobook media content types. The SpotifyPlus integration handles the artists limitations by issuing a call to the Spotify Web API Get Artists Albums endpoint, and loading the results to a local queue on the Sonos device for play.

    Audiobooks cannot currently be played at this time.
    The Spotify DJ playlist does not seem to work correctly when play is transferred from a non-Sonos device to a Sonos device.

  • Sonos devices do not support the Spotify Web API Start/Resume Playback endpoint from commercial streaming applications. A 403 Forbidden, Restricted device error is generated by the Spotify Web API if Start/Resume Playback is issued to a Sonos device. Note that Spotify applications (e.g. Desktop / Mobile) do not have this limitation and can play tracks or contexts at will, as they are not considered "commercial" applications. The SpotifyPlus integration player_media_play_context and player_media_play_tracks custom services get around this limitation by building a local queue on the Sonos device and issuing a SoCo Play command to play the local queue. Note that Sonos playback control is transferred from the SPOTIFY_CONNECT music source to the Sonos device local queue when this happens; the Spotify Connect source is paused after control is transferred to the Sonos local queue. I should also note that nothing shows as playing on the Spotify applications (e.g. Desktop / Mobile), since the Sonos device is no longer connected to the SPOTIFY_CONNECT music source and is playing the track(s) from its local queue. The only way for Spotify Connect to regain control of the Sonos Device is via a Spotify application (e.g. Desktop / Mobile), as the SoCo API does not support switching the music source on the Sonos device.

  • Sonos devices do not support the Spotify Web API Transfer Playback endpoint from commercial streaming applications. A 403 Forbidden, Restricted device error is generated by the Spotify Web API if Transfer Playback is issued to a Sonos device. Note that Spotify applications (e.g. Desktop / Mobile) do not have this limitation and can transfer playback at will, as they are not considered "commercial" applications. The SpotifyPlus integration player_transfer_playback custom service gets around this limitation by connecting the device to Spotify Connect (if need be) and transferring play by issuing a play command via the SoCo API. If the Spotify Connect connection could not be established, then a local queue on the Sonos device is built from the Spotify Web API users queue a SoCo play command is issued to play the local queue. Note that Sonos playback control is transferred from the SPOTIFY_CONNECT music source to the Sonos device local queue when this happens; the Spotify Connect source is paused after control is transferred to the Sonos local queue. I should also note that nothing shows as playing on the Spotify applications (e.g. Desktop / Mobile), since the Sonos device is no longer connected to the SPOTIFY_CONNECT music source and is playing the track(s) from its local queue. The only way for Spotify Connect to regain control of the Sonos Device is via a Spotify application (e.g. Desktop / Mobile), as the SoCo API does not support switching the music source on the Sonos device.

Sonos Observations

The following are a few things I have noticed while testing the integration with a Sonos Symfonisk device using the Spotify Music Service.

Before

  • The HA media player UI for the SpotifyPlus integration reports the current status of the users Spotify player via the Spotify Web API Get Playback State endpoint. The Sonos device's music source must be set to Spotify in order to reflect the correct status of the Sonos device in the HA media player UI for the SpotifyPlus integration. If the Sonos device is playing a non-Spotify music source (e.g. local queue items, QPlay, etc), then the status of the Sonos device will not be reflected correctly in the HA media player UI for the SpotifyPlus integration. This is because the Sonos device is no longer providing updates to the Spotify Web API, as the Sonos device music source is not set to Spotify. This can be confusing, especially if a Sonos local queue is built from a Spotify queue or playlist; the Sonos device appears to be playing Spotify content, but it's really playing items from a local queue (that happen to be copied from a Spotify queue or playlist).

  • The Spotify Web API PlayerState values for Shuffle and Repeat can be different than what the Sonos Controller API (SoCo) report for the device. Sonos uses a PlayMode value, which is a combination of the Shuffle and Repeat settings. I would think that the Spotify Web API would report the same values as the Sonos Controller API for these settings, but that is not the case. I found that using the Spotify Web API values was more accurate than using the Sonos Controller API values.

Sonos Observations - Sonos Desktop Application

The following were observed when starting Spotify playback using the Sonos Desktop Application:

  • The current song status (e.g. artist / album / track title, cover image, duration, progress, etc) is correct.
  • Some Transport controls (pause, resume play, next track, previous track, seek, mute, volume up / down, etc) work correctly.
  • Some Transport controls (repeat, shuffle) do not work as expected. I think this has something to do with the way Sonos queues tracks for play on the device.

Sonos Observations - Spotify Desktop / Web / Mobile Application

The following were observed when starting Spotify playback using the Spotify Desktop Application:

  • The current song status (e.g. artist / album / track title, cover image, duration, progress, etc) is correct.
  • All Transport controls (pause, resume play, next track, previous track, seek, repeat, shuffle, mute, volume up / down, etc) work correctly.

Sonos Observations - Home Assistant UI

The following were observed when starting Spotify playback using the Home Assistant media player interface (specifically the Mini-Media Player):

  • The current song status (e.g. artist / album / track title, cover image, duration, progress, etc) is correct.
  • All Transport controls (pause, resume play, next track, previous track, seek, repeat, shuffle, mute, volume up / down, etc) work correctly when player is controlled by HA or any of the Spotify developed applications.

Sonos Observations - Resetting Transport Control

If you find yourself in the situation where the Sonos device cannot be controlled via the Home Assistant media player UI, you can do the following to "reset" Spotify on the Sonos device:

  • restart Home Assistant.
  • start the Sonos desktop application.
  • select a Spotify playlist and click on Play Now; this should start play on the Sonos device.
  • click the Clear Queue button to clear the Sonos queue; this should stop play on the Sonos device and clear the play queue.
  • shut down the Sonos desktop application.
  • start the Spotify desktop application (mobile application would probably work too).
  • select a Spotify playlist and click on Play; this should start play on the Sonos device.
  • from a desktop browser, browse to the Home Assistant page that is displaying the SpotifyPlus integration UI.
  • power on the SpotifyPlus media player.
  • verify that the SpotifyPlus media player UI is displaying the correct information for the content that is playing.
  • open the Spotify Developer Get Playback State web page in a new browser tab.
  • click on the Try It button to retrieve current Spotify Connect Player playback state.
  • verify that the result is displaying the correct information for the content that is playing.
Clone this wiki locally