react-spotify-web-playback-sdk-headless

A headless react library for the Spotify web playback SDK. Quite a name

Why

This library was build for the Kokopelli project, since the regular Spotify SDK is not very user friendly. It does not support playing music directly and it cannot refresh access tokens. This library adds simple functions to do exactly that.

How to use

Usage is very simple, just add this to your project, preferably as high in the tree as possible (this is since re-renders can and will break the SDK)

import SpotifyWebPlayback from 'react-spotify-web-playback-sdk-headless'

const ACCESS_TOKEN="<access_token>"

const Index = () => {
  const player = useRef<SpotifyWebPlayback>(null)

  const playSong = () => {
    player.current?.play('spotify:track:4k1OADTXVmuABulPYY9IIu')
  }

  return <div>
    <button onClick={playSong}>
      Play a song
    </button>

    <SpotifyWebPlayback accessToken={ACCESS_TOKEN} name="cool player" volume={50}>
  </div>
}

The code above will initialize the player (if the token is valid) and pressing the button will play a song from the browser!

To access methods use the ref as seen above.

Props

No props are required, but the player will not play when some combinations are not present.

Prop	Value	Description
accessToken	string	The spotify access token to use, required the streaming scope.
refreshToken	string	The spotify refresh token to use, this is only used when refreshTokenAutomatically is present
name	string	Name for the player (as seen from Spotify)
volume	number	The volume of the player, from 1 to 100. This can be changed at all times
logging	boolean	To enable logging
debug	boolean	To enable debug logging, this is quite spammy
refreshTokenAutomatically	boolean	To automatically refresh the accessToken, this requires refreshTokenUrl and refreshToken
refreshTokenUrl	string	The URL running the token server, see below
getOAuthToken	(cb: (token: string) => void) => void	This function is called by the SDK when it needs a fresh token, this can be used to implement token refreshing manually

Listeners

The SDK has a lot of event you can listen to, so this is also exposed by this library. You can add a listener by passing it as a prop to the SpotifyWebPlayback object. For more information see the Spotify Developer Reference

Listener	Description
onReady	Is called when the player is ready
onNotReady	Is called when something went horribly wrong with initialization
onPlayerStateChanged	The most interesting event, is called when a song is started, paused, finished etc.
onInitializationError	Speaks for itself
onAuthenticationError	Speaks for itself
onAccountError	When a Spotify account doesnt have a premium subscription
onPlaybackError	Speaks for itself
onAutoplayFailed	Happens when the browser denies autoplay, this can be solved by adding a button that starts playback, or enabling autoplay
songFinished	New listener, is called when a song is finished with playing
onTokenRefresh	New listener, is called when a token is refreshed

Class methods

Most functions are from the SDK and docs for that can be found on the Spotify Developer Reference. But there are some new methods:

| Method | Type | Description | | setVolume | (volume: number) => void | Change the volume of the player | | play | (spotifyId: string) => void | Play a song on the player, takes a spotify id in the spotify:track:[id] format, or with just the id | | queueSongs | (spotifyIds: string[]) => void | Adds a list of songs to the current playback queue, same format as SpotifyWebPlayback#play |

Automatic Token Refreshing

Token refreshing has to be done by a server, which can be found here To use this you need to add some props to your object. If you use this then you cannot use getOAuthToken

<SpotifyWebPlayback accessToken="..." refreshToken="..." refreshTokenAutomatically refreshTokenUrl="<url_to_server>/spotify/auth/refresh" />

For an example of this check the 'test' story in the repo