Spotify’s Player API: Your Toolkit for Controlling Spotify Programmatically
In 2017, we launched the Spotify Connect Web API, a set of tools that developers could use to programmatically start, stop, and manage Spotify audio playback from the web. This post presents an overview of what you can do with the API, now called the Player API, and some background information about how it came to exist.
Prior to shipping the Connect Web API, Spotify offered a public interface that allowed developers to connect to Spotify’s Mac desktop application from another app running on Mac OS X. Through AppleScript, third-party developers could start or stop the music that was playing from Spotify’s Mac app and observe the title of the track that was playing. Developers used this opportunity to extend the Spotify experience into a variety of creative apps for their own personal use, for friends, and for other Spotify users.
The Spotify Connect Web API extended these innovations to the web, and it now allows developers to control Spotify playback from any internet-connected device or app. The Player API has been used by thousands of developers to make third-party apps for home automation, social listening, music discovery, and much more.
In 2018, we enhanced the Player API further with the launch of our Web Playback SDK: a JavaScript SDK that enables developers to create and control a fully functional player in the browser. When paired with the Player API, our Web Playback SDK can be used to build a frontend application that contains a fully functional web player for Spotify Premium users.
In 2020, the Player API was further improved by the addition of an add-to-queue API — a new endpoint that developers can use to add tracks to the list of songs or podcast episodes that are playing next. We’re excited about what’s in store for the future of the Player API, and about the apps that developers are making with its functionality.
What can I do with it?
Issue commands
At its core, the Player API empowers your web application to tell Spotify what audio to play and where and how to play it. In order to make commands, your app will need an OAuth access token authorized with the user-modify-playback-state OAuth scope. After your app has been granted a token with this permission by a user, your app can use that token to send commands to the Spotify Web API from any device connected to the internet. Note that most commands will only work for users who have a Spotify Premium subscription.
Starting playback
PUT https://api.spotify.com/v1/me/player/play
The namesake feature of our Player API is the /v1/me/player/play endpoint — your tool for beginning or continuing the playback of music or podcasts on Spotify.
It’s more powerful than the play button that you see in Spotify’s mobile app. When you make a request to the /v1/me/player/play endpoint, your third-party app can specify tracks by ID, or pass a context that you’d like to play. Contexts can be a playlist, an album, or a collection, like your Liked Songs.
You can also tell Spotify which device you’d like to listen to by providing Spotify with a device identifier. The device can refer to a Web Playback SDK app, a running instance of a Spotify app, or one of your Spotify Connect-enabled speakers. You can find the device identifiers that are available to control through our Devices API. Note that some devices are not supported.
When you use the play endpoint, you can also tell Spotify how loud the music should be — a score from 0 to 100 — and you can also ask Spotify to offset playback by one or more playlist items. This could be useful if you want to start playback from the third song in a playlist, for example.
Stopping playback
PUT https://api.spotify.com/v1/me/player/pause
This endpoint is simple: it stops the audio that’s currently playing. After pausing playback with the pause endpoint, you can start it again by sending a request to /v1/me/player/play without any options.
Turning up (or down) the volume
PUT https://api.spotify.com/v1/me/player/volume
This command sets the volume between 0 and 100. Some apps use it to add a volume slider or switch into their user interface.
Adding songs to the queue
PUT https://api.spotify.com/v1/me/player/queue
You can use the Player API to add songs or podcast episodes to the “Up next” queue in your Spotify app. Use this endpoint carefully — there is no API yet for removing tracks from the queue, or for reading the contents of the queue.
Audio seeking
PUT https://api.spotify.com/v1/me/player/seek
Your app can use the seek endpoint to move the audio cursor to a given millisecond of the track or podcast episode that is currently playing. After the command is executed, Spotify will begin playback from that point in the song or episode. Some apps — like those using the Web Playback SDK — might use this endpoint to build an audio scrubbing interface.
Observe state
Issuing playback commands to Spotify would be hard without the ability to observe the state of the player and Connect environment. Luckily, the Player API includes methods you can use to do just that. You can find some of the more popular observation endpoints below. Calling these endpoints requires a token that’s been authorized with the user-read-playback-state OAuth scope.
List devices
GET https://api.spotify.com/v1/me/player/devices
You can use the devices API endpoint to fetch a list of active devices that you can target with playback commands. The list will include any open Web Playback SDK apps, many online Spotify Connect speakers, and Spotify-built apps that you may have open, like the web player.
See what’s playing
GET https://api.spotify.com/v1/me/player
Making a GET request to the player endpoint will provide you with basic information about the currently playing context, the device that’s streaming, and other information about the playback state like whether or not shuffle is enabled and if the songs will repeat or not.
What you can build with the Player API
Party apps and social listening experiences
Music fans commonly use Spotify Connect on social occasions to listen to music with friends and family. You can use the Player APIs to build an app that helps with your next house party or backyard barbeque.
For example, the Player API allows you to fetch information about the currently playing track. Your app can combine this information with the Audio Features API to learn about the estimated danceability or tempo of the currently playing song, and integrate this information with a programmable lighting system to match the mood.
Developers can also combine the Player APIs with our Web Playback SDK to make a virtual “listening party” experience. By tracking the current point in the song and using the seek API endpoint when necessary, your app can allow groups of Spotify users to log into a web app, listen to music at the same time and share control over which songs will be played next.
Home automation integrations
Many home automation systems are extensible or open source. Developers can use the Player APIs to connect Spotify with smart home systems and make audio a part of their routine. For example, you could use the /v1/me/player/play endpoint to begin streaming your favorite morning podcast at the same time as a programmable coffee machine starts to brew coffee.
Getting started
With some programming knowledge, any Spotify Premium user can set up a Player API app or develop one for their own use. You can connect with other developers who are using the API in the Spotify for Developers forum, or find examples of third-party apps in the Developer Showcase.
We hope you get creative with it and make inventions that add to the Spotify experience for yourself or for your friends. To get started, visit Spotify for Developers and log in with your Spotify account to register your first app. Happy coding!
Tags: backend
