Web Playback SDK Reference
The Spotify Web Playback SDK is a public JavaScript SDK that allows you to implement local streaming playback of Spotify content in their web applications.
SDK Reference
Initializing the SDK
In order to initialize the Web Playback SDK, you need to embed a single line of JavaScript inside of your application. It should belong inside the <body>
tag:
<script src="https://sdk.scdn.co/spotify-player.js"></script>
You are then required to define a window.onSpotifyWebPlaybackSDKReady
method immediately.
This will be executed once the Web Playback SDK has successfully loaded and the Spotify.Player is available to load the SDK.
<script>
window.onSpotifyWebPlaybackSDKReady = () => {
// You can now initialize Spotify.Player and use the SDK
};
</script>
Playing a Spotify URI
The Web Playback SDK is only designed to create a local Connect device in your browser. The Web API is for additional actions such as search or playing a Spotify URI on any of a user’s Connect devices.
Here’s a JavaScript code example of how to play a Spotify URI using the Web API:
const play = ({
spotify_uri,
playerInstance: {
_options: {
getOAuthToken
}
}
}) => {
getOAuthToken(access_token => {
fetch(`https://api.spotify.com/v1/me/player/play?device_id=${id}`, {
method: 'PUT',
body: JSON.stringify({ uris: [spotify_uri] }),
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${access_token}`
},
});
});
};
play({
playerInstance: new Spotify.Player({ name: "..." }),
spotify_uri: 'spotify:track:7xGfFoTpQ2E7fRF5lN10tr',
});
For more information, check out the Start/Resume a User’s Playback Web API endpoint.
API Reference
Spotify.Player
Description | The main constructor for initializing the Web Playback SDK. It should contain an object with the player name, volume and access token. |
||||||||||||||||
Response |
|
||||||||||||||||
Code Sample |
|
||||||||||||||||
|
Spotify.Player#connect
Description | Connect our Web Playback SDK instance to Spotify with the credentials provided during initialization. |
Response | Returns a |
Code Sample |
|
Spotify.Player#disconnect
Description | Closes the current session our Web Playback SDK has with Spotify. |
Response |
|
Code Sample |
|
Spotify.Player#addListener
Description | Create a new event listener in the Web Playback SDK. Alias for |
||||||||||||
Response | Returns a |
||||||||||||
Code Sample |
|
||||||||||||
|
Spotify.Player#removeListener
Description | Remove an event listener in the Web Playback SDK. |
||||||||||||
Response | Returns a |
||||||||||||
Code Sample |
|
||||||||||||
|
Spotify.Player#getCurrentState
Description | Collect metadata on local playback. |
Response | Returns a |
Code Sample |
|
Spotify.Player#setName
Description | Rename the Spotify Player device. This is visible across all Spotify Connect devices. |
||||||||
Response | Returns an empty |
||||||||
Code Sample |
|
||||||||
|
Spotify.Player#getVolume
Description | Get the local volume currently set in the Web Playback SDK. |
Response | Returns a |
Code Sample |
|
Spotify.Player#setVolume
Description | Set the local volume for the Web Playback SDK. |
||||||||
Response | Returns an empty |
||||||||
Code Sample |
|
||||||||
|
Spotify.Player#pause
Description | Pause the local playback. |
Response | Returns an empty |
Code Sample |
|
Spotify.Player#resume
Description | Resume the local playback. |
Response | Returns an empty |
Code Sample |
|
Spotify.Player#togglePlay
Description | Resume/pause the local playback. |
Response | Returns an empty |
Code Sample |
|
Spotify.Player#seek
Description | Seek to a position in the current track in local playback. |
||||||||
Response | Returns an empty |
||||||||
Code Sample |
|
||||||||
|
Spotify.Player#previousTrack
Description | Switch to the previous track in local playback. |
Response | Returns an empty |
Code Sample |
|
Spotify.Player#nextTrack
Description | Skip to the next track in local playback. |
Response | Returns an empty |
Code Sample |
|
Spotify.Player#activateElement
Description | Some browsers prevent autoplay of media by ensuring that all playback is triggered by synchronous event-paths originating from user interaction such as a click. > In the autoplay disabled browser, to be able to keep the playing state during transfer from other applications to yours, this function needs to be called in advance. Otherwise it will be in pause state once it’s transferred. |
Response | Returns an empty |
Code Sample |
|
Events
ready
Description | Emitted when the Web Playback SDK has successfully connected and is ready to stream content in the browser from Spotify. |
Response | Returns a WebPlaybackPlayer object. |
Code Sample |
|
not_ready
Description | Emitted when the Web Playback SDK is not ready to play content, typically due to no internet connection. |
Response | Returns a WebPlaybackPlayer object. |
Code Sample |
|
player_state_changed
Description | Emitted when the state of the local playback has changed. It may be also executed in random intervals. |
Response | Returns a WebPlaybackState object. |
Code Sample |
|
autoplay_failed
Description | Emitted when playback is prohibited by the browser’s autoplay rules. Check Spotify.Player#activateElement for more information. |
Response | Returns |
Code Sample |
|
Error Reference
initialization_error
Description | Emitted when the |
Code Sample |
|
authentication_error
Description | Emitted when the |
Code Sample |
|
account_error
Description | Emitted when the user authenticated does not have a valid Spotify Premium subscription. |
Code Sample |
|
playback_error
Description | Emitted when loading and/or playing back a track failed. |
Code Sample |
|
Objects
WebPlaybackPlayer Object
This is an object that is provided in the ready
event as an argument.
WebPlaybackPlayer objects contain information related to the current player instance of the Web Playback SDK.
{ device_id: "c349add90ccf047f4e737492b69ba912bdc55f6a" }
WebPlaybackState Object
This is an object that is provided every time Spotify.Player#getCurrentState
is called.
It contains information on context, permissions, playback state, the user’s session, and more.
{
context: {
uri: 'spotify:album:xxx', // The URI of the context (can be null)
metadata: {}, // Additional metadata for the context (can be null)
},
disallows: { // A simplified set of restriction controls for
pausing: false, // The current track. By default, these fields
peeking_next: false, // will either be set to false or undefined, which
peeking_prev: false, // indicates that the particular operation is
resuming: false, // allowed. When the field is set to `true`, this
seeking: false, // means that the operation is not permitted. For
skipping_next: false, // example, `skipping_next`, `skipping_prev` and
skipping_prev: false // `seeking` will be set to `true` when playing an
// ad track.
},
paused: false, // Whether the current track is paused.
position: 0, // The position_ms of the current track.
repeat_mode: 0, // The repeat mode. No repeat mode is 0,
// repeat context is 1 and repeat track is 2.
shuffle: false, // True if shuffled, false otherwise.
track_window: {
current_track: <WebPlaybackTrack>, // The track currently on local playback
previous_tracks: [<WebPlaybackTrack>, <WebPlaybackTrack>, ...], // Previously played tracks. Number can vary.
next_tracks: [<WebPlaybackTrack>, <WebPlaybackTrack>, ...] // Tracks queued next. Number can vary.
}
}
WebPlaybackTrack Object
This is an object that is provided inside track_window
from the WebPlaybackState Object.
Track objects are Spotify Web API compatible objects containing metadata on Spotify content.
{
uri: "spotify:track:xxxx", // Spotify URI
id: "xxxx", // Spotify ID from URI (can be null)
type: "track", // Content type: can be "track", "episode" or "ad"
media_type: "audio", // Type of file: can be "audio" or "video"
name: "Song Name", // Name of content
is_playable: true, // Flag indicating whether it can be played
album: {
uri: 'spotify:album:xxxx', // Spotify Album URI
name: 'Album Name',
images: [
{ url: "https://image/xxxx" }
]
},
artists: [
{ uri: 'spotify:artist:xxxx', name: "Artist Name" }
]
}
WebPlaybackError Object
This is an object that is provided in all error handlers from the Web Playback SDK.
It is referred to as e
and looks like this:
{ message: "This will contain a message explaining the error." }
Troubleshooting
This section explains some of the common issues that might arise when using the Web Playback SDK.
Audio not playing on iOS browsers
- For audio to play through the Web Playback SDK, the user is required to interact with the SDK. Media activation policies in iOS cause this, and the only solution is to introduce a button or a similar element that activates an event with the SDK. A recommended approach is to split the initialization of the SDK into two steps, where the first step is to connect, and the second step is for the user to click a button that transfers playback and toggle play or similar approaches.
Background play on iOS browsers
- Playing in the background is not supported for iOS based browsers.
Notes about iframes
- The Web Playback SDK require iframes to allow
encrypted-media
andautoplay
in cases of cross origin iframes. This currently affects Chrome browsers since they introduced Feature Policy which disallows features within iframes by default.
Browser Extensions
- Some users have reported issues when loading the SDK using certain browser extensions, specifically the ones related to privacy or 3rd party blockers. If you experience a similar behavior, try to temporarily disable those extensions.