Remote Controlling Spotify Using the Connect Web API

Controlling Premium Users’ Playback

Image for post

Spotify provides two ways for developers to stream music from a web app: the Web Playback SDK and the Connect Web API. The Web Playback SDK simply streams full tracks through your web app to an authenticated premium Spotify user. The Connect Web API acts more like a remote control, interacting with a copy of Spotify open on one the authenticated user’s devices. Of the two, I find myself using the Web Playback SDK most often in client projects because it is simple for a user to understand: login to stream. However, the Web Playback SDK has a major drawback in that it does not currently work from mobile devices.

While putting together a timed comments prototype for Spotify, I found myself taking a closer look at the Connect Web API again because I wanted the experiment to work from mobile devices. In this blog post, I’d like to share how you can integrate with this API to create a Spotify controller within your own web apps.

Authenticate User

There are many ways to authorize a Spotify user on your app but I prefer implementing auth entirely in the browser using their Implicit Grant Flow. Using this technique, we can simply popup the Spotify login dialog and obtain the user’s access token upon authorization. These tokens are short lived but should be fine for most web app implementations. Check out the following blog for more info on how I implement authentication in this way.

You’ll want to make sure to authorize both the user-modify-playback-state and user-read-playback-state scopes.

Get User’s Devices

Once the user is logged in, you should get a list of their devices by making a request to the /v1/me/player/devices endpoint.

{
"devices": [
{
"id": "b46689a4cd5",
"is_active": true,
"is_private_session": false,
"is_restricted": false,
"name": "Lee's iMac Pro",
"type": "Computer",
"volume_percent": 70
}
]
}

Each device is given a unique ID but it is not guaranteed to be persistent so make sure you handle your caching accordingly. In addition, you’ll see whether the device is currently active, part of a private session, or if controlling this device is restricted. In order to target a specific device which is not currently active, you should transfer a user’s playback to this device (if it isn’t restricted or private.) You can do this with the /v1/me/player endpoint.

On my timed comments prototype, I created a little panel where the user can switch between their non-restricted devices. This is very similar to the devices panel Spotify provides on their own apps. This is also a good place to encourage users to open Spotify on one of their devices if it isn’t already.

Spotify provides a list of reasons why devices may not be appearing on this list.

Get User’s Currently Playing Track

Now that we know our authenticated user has an open and active Spotify device, it might be helpful to check if the user is currently playing a track. To do this, we simply call the /v1/me/player/currently-playing endpoint. In addition to returning info about the track, this API will provide additional properties which may help you build out your controller interface. For example, you can use the progress_ms property to generate a progress bar which has elapsed to the appropriate point. In addition, you can check which actions on this track may be disallowed within the current context.

When no track is currently playing or the session is private, this endpoint will return an empty payload.

Starting, Pausing, and Resuming

And now you’ve made it to the core action of any player: playing (and pausing) a track. Playback is achieved by calling the /v1/me/player/play endpoint and providing a valid Spotify context in the body parameters. For example, to play “Moonlight” by Future Islands you would include the track uri as part of the uris array.

curl -X "PUT" "https://api.spotify.com/v1/me/player/play" --data "{\"uris\":[\"spotify:track:1qyKIq8hw9yWkuPJ9ZjuvK\"]}" -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

You can separately use the context_uri parameter in a similar manner to play albums, artists, and playlists. In order to pause the current track, you simply call the /v1/me/player/pause endpoint.

Most Connect Web API endpoints allow you to pass the device_id as a query parameter and while the API should use the currently active device, I find this helps reaffirm the action.

More Endpoints Please

This short tutorial should get you started experimenting with the Connect Web API but there are many more endpoints for you to explore. You could adjust the user’s queue and get their recently played tracks. You may want to set their device to repeat or shuffle the current context. How about seeking or skipping between tracks?

I look forward to seeing what you build with this API and if you want to see it in action, check out my timed comments prototype.

I develop websites for rock 'n' roll bands and get paid in sex and drugs. Previously Silva Artist Management, SoundCloud, and Songkick. Currently: Available

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store