Web Playback SDK Reference

Important policy notes

Spotify.Player

`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	`void`

Code Example:


_10 window.onSpotifyWebPlaybackSDKReady = () => {
_10   const token = '[My Spotify Web API access token]';
_10   const player = new Spotify.Player({
_10     name: 'Web Playback SDK Quick Start Player',
_10     getOAuthToken: cb => { cb(token); }
_10   });
_10 }

Parameter Name	Type	Description	Required
`name`	String	The name of the Spotify Connect player. It will be visible in other Spotify apps	Required
`getOAuthToken`	Function	This will be called every time you run Spotify.Player#connect or when a user's access token has expired (maximum of 60 minutes). You will be provided with a `callback` parameter. You will need to execute this with a valid `access_token` string for a Spotify Premium user.	Required
`volume`	Float	The default volume of the player. Represented as a decimal between 0 and 1. Default value is 1.	Optional
`enableMediaSession`	Boolean	If set to true, the Media Session API will be set with metadata and action handlers. Default value is false.	Optional

`Spotify.Player#connect`


Description	Connect our Web Playback SDK instance to Spotify with the credentials provided during initialization.
Response	Returns a `Promise` containing a `Boolean` (either `true` or `false`) with the success of the connection.

Code Example:


_10player.connect().then(success => {
_10  if (success) {
_10    console.log('The Web Playback SDK successfully connected to Spotify!');
_10  }
_10})

`Spotify.Player#disconnect`


Description	Closes the current session our Web Playback SDK has with Spotify.
Response	`Void`

Code Example:


_10player.disconnect()

`Spotify.Player#addListener`


Description	Create a new event listener in the Web Playback SDK. Alias for Spotify.Player#on.
Response	Returns a `Boolean`. Returns `true` if the event listener for the `event_name` is unique. See #removeListener for removing existing listeners.

Code Example:


_10player.addListener('ready', ({ device_id }) => {
_10  console.log('The Web Playback SDK is ready to play music!');
_10  console.log('Device ID', device_id);
_10})

Parameter Name	Type	Description	Required
`event_name`	String	A valid event name. See Web Playback SDK Events.	Required
`callback`	Function	A callback function to be fired when the event has been executed.	Required

`Spotify.Player#removeListener`


Description	Remove an event listener in the Web Playback SDK.
Response	Returns a `Boolean`. Returns `true` if the event name is valid with registered callbacks from #addListener.

Code Example:


_10// Removes all "ready" events
_10player.removeListener('ready');
_10// Remove a specific "ready" listener
_10player.removeListener('ready', yourCallback)

Parameter Name	Type	Description	Required
`event_name`	String	A valid event name. See Web Playback SDK Events.	Required
`callback`	Function	The callback function you would like to remove from the listener. If not provided, it will remove all callbacks under the `event_name`.	Optional

`Spotify.Player#getCurrentState`


Description	Collect metadata on local playback.
Response	Returns a `Promise`. It will return either a WebPlaybackState object or null depending on if the user is successfully connected.

Code Example:


_12player.getCurrentState().then(state => {
_12  if (!state) {
_12    console.error('User is not playing music through the Web Playback SDK');
_12    return;
_12  }
_12
_12  var current_track = state.track_window.current_track;
_12  var next_track = state.track_window.next_tracks[0];
_12
_12  console.log('Currently Playing', current_track);
_12  console.log('Playing Next', next_track);
_12});

`Spotify.Player#setName`


Description	Rename the Spotify Player device. This is visible across all Spotify Connect devices.
Response	Returns a `Promise`.

Code Example:


_10player.setName("My New Player Name").then(() => {
_10  console.log('Player name updated!');
_10});

Parameter Name	Type	Description	Required
`name`	String	The new desired player name.	Required

`Spotify.Player#getVolume`


Description	Get the local volume currently set in the Web Playback SDK.
Response	Returns a `Promise` containing the local volume (as a `Float` between 0 and 1).

Code Example:


_10player.getVolume().then(volume => {
_10  let volume_percentage = volume * 100;
_10  console.log('The volume of the player is ${volume_percentage}%');
_10});

`Spotify.Player#setVolume`


Description	Set the local volume for the Web Playback SDK.
Response	Returns an empty `Promise`

Code Example:


_10player.setVolume(0.5).then(() => {
_10  console.log('Volume updated!');
_10});

Parameter Name	Type	Description	Required
`volume`	Float	The new desired volume for local playback. Between 0 and 1. Note: On iOS devices, the audio level is always under the user’s physical control. The volume property is not settable in JavaScript. Reading the volume property always returns 1. More details can be found in the iOS-specific Considerations documentation page by Apple.	Required

`Spotify.Player#pause`


Description	Pause the local playback.
Response	Returns an empty `Promise`

Code Example:


_10player.pause().then(() => {
_10  console.log('Paused!');
_10});

`Spotify.Player#resume`


Description	Resume the local playback.
Response	Returns an empty `Promise`

Code Example:


_10player.resume().then(() => {
_10  console.log('Resumed!');
_10});

`Spotify.Player#togglePlay`


Description	Resume/pause the local playback.
Response	Returns an empty `Promise`

Code Example:


_10player.togglePlay().then(() => {
_10  console.log('Toggled playback!');
_10});

`Spotify.Player#seek`


Description	Seek to a position in the current track in local playback.
Response	Returns an empty `Promise`

Code Example:


_10// Seek to a minute into the track
_10player.seek(60 * 1000).then(() => {
_10  console.log('Changed position!');
_10});

Parameter Name	Type	Description	Required
`position_ms`	Integer	The position in milliseconds to seek to.	Required

`Spotify.Player#previousTrack`


Description	Switch to the previous track in local playback.
Response	Returns an empty `Promise`

Code Example:


_10player.previousTrack().then(() => {
_10  console.log('Set to previous track!');
_10});

`Spotify.Player#nextTrack`


Description	Skip to the next track in local playback.
Response	Returns an empty `Promise`

Code Example:


_10player.nextTrack().then(() => {
_10  console.log('Skipped to next track!');
_10});

`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 `Promise`

Code Example:


_10myActivateElementButton.addEventListener('click', () => {
_10  // The player is activated. The player will keep the
_10  // playing state once the state is transferred from other
_10  // applications.
_10  player.activateElement();
_10});
_10// Transfer your currently playing track into your
_10// application through device picker in Spotify APP.

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 Example:


_10player.addListener('ready', ({ device_id }) => {
_10  console.log('Connected with Device ID', device_id);
_10});

`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 Example:


_10player.addListener('not_ready', ({ device_id }) => {
_10  console.log('Device ID is not ready for playback', device_id);
_10});

`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 WebPlaybackPlayer object.

Code Example:


_10player.addListener('player_state_changed', ({
_10  position,
_10  duration,
_10  track_window: { current_track }
_10}) => {
_10  console.log('Currently Playing', current_track);
_10  console.log('Position in Song', position);
_10  console.log('Duration of Song', duration);
_10});

`autoplay_failed`


Description	Emitted when playback is prohibited by the browser’s autoplay rules. Check Spotify.Player#activateElement for more information.
Response	Returns `null`

Code Example:


_10player.addListener('autoplay_failed', () => {
_10  console.log('Autoplay is not allowed by the browser autoplay rules');
_10});

Errors

`initialization_error`


Description	Emitted when the `Spotify.Player` fails to instantiate a player capable of playing content in the current environment. Most likely due to the browser not supporting EME protection.

Code Example:


_10player.on('initialization_error', ({ message }) => {
_10  console.error('Failed to initialize', message);
_10});

`authentication_error`


Description	Emitted when the `Spotify.Player` fails to instantiate a valid Spotify connection from the access token provided to `getOAuthToken`.

Code Example:


_10player.on('authentication_error', ({ message }) => {
_10  console.error('Failed to authenticate', message);
_10});

`account_error`


Description	Emitted when the user authenticated does not have a valid Spotify Premium subscription.

Code Example:


_10player.on('account_error', ({ message }) => {
_10  console.error('Failed to validate Spotify account', message);
_10});

`playback_error`


Description	Emitted when loading and/or playing back a track failed.

Code Example:


_10player.on('playback_error', ({ message }) => {
_10  console.error('Failed to perform playback', message);
_10});

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.


_10{ 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.


_26{
_26  context: {
_26    uri: 'spotify:album:xxx', // The URI of the context (can be null)
_26    metadata: {},             // Additional metadata for the context (can be null)
_26  },
_26  disallows: {                // A simplified set of restriction controls for
_26    pausing: false,           // The current track. By default, these fields
_26    peeking_next: false,      // will either be set to false or undefined, which
_26    peeking_prev: false,      // indicates that the particular operation is
_26    resuming: false,          // allowed. When the field is set to `true`, this
_26    seeking: false,           // means that the operation is not permitted. For
_26    skipping_next: false,     // example, `skipping_next`, `skipping_prev` and
_26    skipping_prev: false      // `seeking` will be set to `true` when playing an
_26                              // ad track.
_26  },
_26  paused: false,  // Whether the current track is paused.
_26  position: 0,    // The position_ms of the current track.
_26  repeat_mode: 0, // The repeat mode. No repeat mode is 0,
_26                  // repeat context is 1 and repeat track is 2.
_26  shuffle: false, // True if shuffled, false otherwise.
_26  track_window: {
_26    current_track: <WebPlaybackTrack>,                              // The track currently on local playback
_26    previous_tracks: [<WebPlaybackTrack>, <WebPlaybackTrack>, ...], // Previously played tracks. Number can vary.
_26    next_tracks: [<WebPlaybackTrack>, <WebPlaybackTrack>, ...]      // Tracks queued next. Number can vary.
_26  }
_26}

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.


_18{
_18  uri: "spotify:track:xxxx", // Spotify URI
_18  id: "xxxx",                // Spotify ID from URI (can be null)
_18  type: "track",             // Content type: can be "track", "episode" or "ad"
_18  media_type: "audio",       // Type of file: can be "audio" or "video"
_18  name: "Song Name",         // Name of content
_18  is_playable: true,         // Flag indicating whether it can be played
_18  album: {
_18    uri: 'spotify:album:xxxx', // Spotify Album URI
_18    name: 'Album Name',
_18    images: [
_18      { url: "https://image/xxxx" }
_18    ]
_18  },
_18  artists: [
_18    { uri: 'spotify:artist:xxxx', name: "Artist Name" }
_18  ]
_18}

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:


_10{ message: "This will contain a message explaining the error." }