Guide | Spotify for Developers

Spotify Connect is a feature on Spotify that allows you to use Spotify clients as a remote and cast content to different devices, such as smart speakers, game consoles, TVs, or wearables. The Web Playback SDK is a client-side JavaScript library that allows to create a new player instance in Spotify Connect and play audio from Spotify inside your application.

The following guide will lead you to step by step create a simple full-stack application to host the Spotify player to play music along with the rest of the devices from your home. By the end of the guide, you will have a fully working Spotify Player running on your browser similar to this one:

Spotify Connect

Let’s start coding!

Prerequisites

The Web Playback SDK requires Spotify Premium, so you’ll need a premium account to use it.

This guide assumes that you have some knowledge of JavaScript -both frontend using React and backend with Node.

Although not fully necessary, it is highly recommended to read the Quick Start Guide before this guide.

Source Code

The source code of the application can be found on the Spotifty GitHub repository. Feel free to fork it if you feel like it!

Set up your Account

Go to Spotify for Developers portal and log in using your Spotify credentials (You can find the login button under the Dashboard).

The dashboard is where we can create apps, control the API credentials bound to the app or just get some nice app usage statistics. Click on the Create an APP button and provide a name and a short description of your new application. Finally, accept the terms and conditions and click on Create. Your new application contains your Client ID and Client Secret needed to authorize the application we are about to code to use the Spotify resources.

Initializing the Project

The easiest way to start a project based on React is using the create-react-app tool. Open a terminal and run the tool using the npx command:

npx create-react-app spotify-web-player
cd spotify-web-player

npx is pre-bundled with npm since 5.2.0 version. The command creates a new folder called spotify-web-player that we will use as a template for our project, along with the package.json file which contains the project configuration.

Let’s install the dependencies and test the project by running:

npm install
npm run start

Go to your browser and open http://localhost:3000. If you see a spinning React logo, then the React project is ready.

Let’s create a server folder which will contain the implementation of the backend:

mkdir server

Finally, let’s add some extra commands to the package.json file to properly start the project. Open the package.json with your favorite editor and add the following entries inside the script section of the file:

  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "server": "node server",
    "dev": "run-p server start"
  },

Each entry corresponds with the following actions:

start starts an HTTP server on port 3000 to serve the React application.
build generates the static code ready to be deployed in production.
server executes the index.js file located on the server folder.
dev runs both client and server up using run-p tool to allow run multiple npm-scripts in parallel.

The run-p command belongs to the npm-run-all package. Let’s install the dependency by running the following command:

npm install npm-run-all --save-dev

Now that the project is ready, let’s move forward and start coding the backend’s authorization.

Authorization

Spotify allows developers to authenticate in several ways. Our project will implement the Authorization Code flow, which is very convenient for long-running apps, such as web apps, where the user grants permissions only once.

Rather than hard-coding the user credentials inside the source code of our application, we are going to use the dotenv package to store and read them from a hidden configuration file.

Install the dependency with the following command:

npm install dotenv --save-dev

Create a .env file in the root folder of the project and add the following variables using the NAME=VALUE format:

SPOTIFY_CLIENT_ID='my_spotify_client_id'
SPOTIFY_CLIENT_SECRET='my_spotify_client_secret'

The values are now accessible as environment variables and can be read using process.env:

var spotify_client_id = process.env.SPOTIFY_CLIENT_ID
var spotify_client_secret = process.env.SPOTIFY_CLIENT_SECRET

The idea behind the server is to export some basic endpoints to the frontend corresponding to the steps of the authorization flow:

/auth/login to request user authorization by getting an Authorization Code.
/auth/callback to request the Access Token using the Authorization Code requested in the previous step.

We will use Express to receive and handle all incoming requests to the server. Let’s start by installing the package dependency:

npm install express --save-dev

Create a new index.js file inside the server folder with the following content:

const express = require('express')
const dotenv = require('dotenv');

const port = 5000

dotenv.config()

var spotify_client_id = process.env.SPOTIFY_CLIENT_ID
var spotify_client_secret = process.env.SPOTIFY_CLIENT_SECRET

var app = express();

app.get('/auth/login', (req, res) => {
});

app.get('/auth/callback', (req, res) => {
});

app.listen(port, () => {
  console.log(`Listening at http://localhost:${port}`)
})

We can test the server with the following command:

npm run server

If everything goes fine, the server will start listening incoming requests on port 5000.

We are ready to start coding the authorization flow!

Request User Authorization

The first step is to redirect the user to a web page where they can choose to grant our application access to their premium account.

To do so, we need to send a GET request to the /authorize endpoint of the Spotify account service with the following parameters:

response_type, is the credential that will be returned. The value will always be code.
client_id, is the Client ID of the application we have just created on the portal dashboard.
scope, a space-separated list of actions that our app can be allowed to do on a user’s behalf. We need permission for streaming, user-read-email and user-read-private for the Web Player SDK.
redirect_uri is the URL that Spotify’s Authorization server will redirect once the access token is granted. Since we are running the project locally, our redirect URL will point to localhost:3000/auth/callback since all petitions are handled from the frontend.
state, a randomly generated string to protect against attacks such as cross-site request forgery.

Although state is not mandatory, is highly recommended including one. Here you have our proposal to generate randomly generated strings. Of course, feel free to implement something different:

var generateRandomString = function (length) {
  var text = '';
  var possible = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';

  for (var i = 0; i < length; i++) {
    text += possible.charAt(Math.floor(Math.random() * possible.length));
  }
  return text;
};

We have everything we need to implement the user authorization request. The following code implements the GET method, which performs the redirection to the Spotify login screen to allow users to grant permissions:

router.get('/auth/login', (req, res) => {

  var scope = "streaming \
               user-read-email \
               user-read-private"

  var state = generateRandomString(16);

  var auth_query_parameters = new URLSearchParams({
    response_type: "code",
    client_id: spotify_client_id,
    scope: scope,
    redirect_uri: "http://localhost:3000/auth/callback",
    state: state
  })

  res.redirect('https://accounts.spotify.com/authorize/?' + auth_query_parameters.toString());
})

Response

Once the user approves the application request, the user is redirected back to the application using the redirect_uri passed on the authorized request http://localhost:3000/auth/callback just described above.

The callback contains two query parameters:

An authorization code that will be exchanged for an access token.
The same state supplied in the request.

Before continuing with the second step, we need to go back to the portal to allow our application to perform callbacks to the redirect_uri we have supplied on the previous call:

Go to the Dashboard and select the application we created on the first step of the tutorial.
Click on Edit Settings and add the URL callback http://localhost:3000/auth/callback under the Redirect URIs field.

Remember to click save for the changes to take effect.

Request Access Token

Now that we have the authorization code, we must exchange it for tokens. Using the code from the previous step, we need to make a POST request to the /api/token endpoint.

The body of the request must be encoded in application/x-www-form-urlencoded with the following parameters:

grant_type, must always contain the value authorization_code.
code, is the authorization code returned on the previous step.
redirect_uri, must exactly match the same value sent on the user authorization request (previous step). This value is used for validation only since there is no actual redirection.

We must also include the following HTTP headers:

Authorization, is a base64 encoded string that contains the client ID and client secret keys. The field must have the format: Basic *<base64 encoded client_id:client_secret>*
Content-type, set with the value application/x-www-form-urlencoded to inform the server about the encoding of the body.

As the POST HTTP call will be made using the request library, we need to install the dependency:

npm install request --save-dev

We are now ready to implement the /auth/callback endpoint of our server:

app.get('/auth/callback', (req, res) => {

  var code = req.query.code;

  var authOptions = {
    url: 'https://accounts.spotify.com/api/token',
    form: {
      code: code,
      redirect_uri: "http://localhost:3000/auth/callback",
      grant_type: 'authorization_code'
    },
    headers: {
      'Authorization': 'Basic ' + (Buffer.from(spotify_client_id + ':' + spotify_client_secret).toString('base64')),
      'Content-Type' : 'application/x-www-form-urlencoded'
    },
    json: true
  };

  request.post(authOptions, function(error, response, body) {
    if (!error && response.statusCode === 200) {
      var access_token = body.access_token;
      res.redirect('/')
    }
  });
})

Note how the authentication ends with the access_token stored locally and redirection to /.

Response

If everything goes well, we will receive an HTTP 200 response with the access_token in the payload of the response:

{
   "access_token":"BQBZiiCqVjpZz9Boj1-8WirXFLgBpfZJwSR0Kw",
   "token_type":"Bearer",
   "expires_in":3600,
   "refresh_token":"AQC-JL7jaByIRKwZiFb29Tf_2AlF1qs",
   "scope":"streaming user-read-email user-read-private"
}

Return Access Token

The backend implements the /auth/token endpoint to return the access token in JSON format. The code looks like this:

app.get('/auth/token', (req, res) => {
  res.json(
     {
        access_token: access_token
     })
})

This access token will be used to instantiate the Web Playback SDK and, eventually, perform API calls using the Web APIs.

Proxying Backend Requests

During the development phase, our React app and backend will run on different hosts and ports:

The client runs on localhost:3000
The backend runs on localhost:5000

Thus, we need to tell our React app where to find the server when doing API calls such as /auth/login or /auth/token.

There are different approaches to do so:

Use the canonical URI on every API call.
Adding a proxy field to the package.json file: "proxy": "http://localhost:5000".
Set up our own proxy using the http-proxy-middleware package.

Let’s include the package in our project by doing:

npm install http-proxy-middleware --save-dev

Now, add a new file called setupProxy.js to the src folder with the following content:

module.exports = function (app) {
    app.use(proxy(`/auth/**`, { 
        target: 'http://localhost:5000' 
    }));
};

This way, all petitions with the /auth/** pattern will be redirected to the backend.

React Components

Let’s start by implementing a welcome screen with a nice Login in button to start the authorization flow we have just implemented on the backend side.

Open the src/App.js and replace the current implementation with this one:

import React, { useState, useEffect } from 'react';
import WebPlayback from './WebPlayback'
import Login from './Login'
import './App.css';

function App() {

  const [token, setToken] = useState('');

  useEffect(() => {

    async function getToken() {
      const response = await fetch('/auth/token');
      const json = await response.json();
      setToken(json.access_token);
    }

    getToken();

  }, []);

  return (
    <>
        { (token === '') ? <Login/> : <WebPlayback token={token} /> }
    </>
  );
}

export default App;

The component uses the useEffect hook to send a GET request to the /auth/token endpoint to check if we have a valid access_token already requested.

Once received, the access_token is stored using the setToken(), so the component will be rendered according to the following logic:

The Login component will be loaded in case the access_token is still empty.
If the access_token has been requested already (there is an active session ongoing), the WebPlaback component will load instead, receiving the access_token we have just requested.

Let’s take a look at the Login component:

import React from 'react';

function Login() {
    return (
        <div className="App">
            <header className="App-header">
                <a className="btn-spotify" href="/auth/login" >
                    Login with Spotify 
                </a>
            </header>
        </div>
    );
}

export default Login;

The login screen consists of one single button inviting users to log in. Once the user clicks on Login with Spotify, the component will perform a GET operation to /auth/login to start the authentication flow described on the previous section.

WebPlayback Component

Let’s create a new component to implement the web player. Create a new file called Webplayback.jsx and add a basic new React functional component as follows:

import React, { useState, useEffect } from 'react';

function WebPlayback(props) {

   return (
      <>
        <div className="container">
           <div className="main-wrapper">

            </div>
        </div>
      </>
    );
}

export default WebPlayback

Add the useEffect hook so the instance of the Web Playback SDK object is created right before we render the page for the first time:

useEffect(() => {

    const script = document.createElement("script");
    script.src = "https://sdk.scdn.co/spotify-player.js";
    script.async = true;

    document.body.appendChild(script);

    window.onSpotifyWebPlaybackSDKReady = () => {

        const player = new window.Spotify.Player({
            name: 'Web Playback SDK',
            getOAuthToken: cb => { cb(props.token); },
            volume: 0.5
        });

        setPlayer(player);

        player.addListener('ready', ({ device_id }) => {
            console.log('Ready with Device ID', device_id);
        });

        player.addListener('not_ready', ({ device_id }) => {
            console.log('Device ID has gone offline', device_id);
        });


        player.connect();

    };
}, []);

The first step to install the SDK is to load the library creating a new script tag within the DOM tree. As the onSpotifyWebPlaybackSDKReady method will be executed right after the Web Playback SDK has been successfully loaded, we create the Player instance inside the callback using the access_token supplied via React props

Once the Player object has been successfully created, we store the object using the userPlayer() hook, which has been defined as follows:

const [player, setPlayer] = useState(undefined);

The callback also connects the events emitted by the SDK using the addListener method of the player. You can find detailed information about the events supported by the SDK on the SDK reference page

The events we want to get notified are:

ready, emitted when the SDK is connected and ready to stream content.
not_ready, in case the connection is broken.
player_state_changed, emitted when the state of the local playback has changed (i.e., change of track).

Finally, the method calls to connect method to perform the connection of our new Spotify instance.

Running everything together

At this point we are ready to test the application:

Open a console and run the both client and server using the npm run dev command.
Open a browser and go to http://localhost:3000.
Click on the “Log in with Spotify” button.
Log in to Spotify using your credentials if you haven’t done it yet.
Open any Spotify client. You should be able to see a new Spotify instance in the Spotify connect button.
If you switch to the new instance, the music should start playing within the browser.

Congrats! The first step has been successfully accomplished! What about displaying some cool information about the stream currently playing, such as artist, track or album cover?

Playback Information Display

Let’s modify our WebPlayback component to store and display information about the track that is currently playing. Add the following hooks to the component:

const [is_paused, setPaused] = useState(false);
const [is_active, setActive] = useState(false);
const [current_track, setTrack] = useState(track);

is_paused is a boolean variable that indicates whether the current track is being played or not.
is_active to indicate whether the current playback has been transferred to this player or not.
current_track, an object to store the currently playing track.

Next step, we need to define the track JSON object. Add the following code outside the component implementation:

const track = {
    name: "",
    album: {
        images: [
            { url: "" }
        ]
    },
    artists: [
        { name: "" }
    ]
}

Extend the useEffect() hook by adding a new eventListener to, once the event is emitted, update the component with the current track

player.addListener('player_state_changed', ( state => {

    if (!state) {
        return;
    }

    setTrack(state.track_window.current_track);
    setPaused(state.paused);


    player.getCurrentState().then( state => { 
        (!state)? setActive(false) : setActive(true) 
    });

}));

Finally, let’s display information about the track the user is currently playing. Replace the render method with the following code:

return (
    <>
        <div className="container">
            <div className="main-wrapper">
                <img src={current_track.album.images[0].url} 
                     className="now-playing__cover" alt="" />

                <div className="now-playing__side">
                    <div className="now-playing__name">{
                                  current_track.name
                                  }</div>

                    <div className="now-playing__artist">{
                                  current_track.artists[0].name
                                  }</div>
                </div>
            </div>
        </div>
     </>
)

Playback Control

Once the playback is transferred to the browser, there is no way to modify the state of the playback, e.g. move to the next or previous tracks or pause/resume the playback.

Let’s add three new buttons to the WebPlayback component that will call to nextTrack(), previousTrack(), and togglePlay() methods from the SDK:

<button className="btn-spotify" onClick={() => { player.previousTrack() }} >
      &lt;&lt;
</button>

<button className="btn-spotify" onClick={() => { player.togglePlay() }} >
     { is_paused ? "PLAY" : "PAUSE" }
</button>

<button className="btn-spotify" onClick={() => { player.nextTrack() }} >
      &gt;&gt;
</button>

Preparing for Production

There are different approaches to roll out your React application in production along with the backend server. In this guide, we will cover the manual steps to build and place the code into one single folder.

Let’s start by generating the React app and all the static assets:

npm run build

If everything went fine, a new build folder will be generated containing all the generated files. You can check that the application works fine by using the serve HTTP server to serve the static files:

npm install -g serve
serve -s build

As we will be using the React server we have implemented through the guide, we need to extend the backend server to serve static files. Open the server/index.js file and add the following line:

app.use(express.static(path.join(__dirname, '../build')));

From now on, we can run the server and load files directly from the server, for example:

http://localhost:5000/index.html
http://localhost:5000/static/js/main.js

Next Steps

If you have reached this point, congratulations! Your first Spotify instance is up and running!

But this is just the beginning! What could we do next? Here you have some ideas to add to the prototype:

Use the refresh_token field from the Request Access Token response to request a new token once the current one expires.
Use the Search APIs to include search capabilities by artist, albums, or tracks.
Include a Transfer Playback button to transfer the current playback to another Spotify instance using the Player APIs.
Get, play and create new playlists using the Playlists APIs.

Prerequisites

Source Code

Set up your Account

Initializing the Project

Authorization

Request User Authorization

Response

Request Access Token

Response

Return Access Token

Proxying Backend Requests

React Components

Login Component

WebPlayback Component

Running everything together

Playback Information Display

Playback Control

Preparing for Production

Next Steps