This is a React wrapper for Spotify Web Playback SDK.
By using this library, you can use declaratively handle the Spotify player.
Spotify Web Playback SDK will be not published in npm registory and downloaded from CDN. So when you use it, you must add a script tag. But it's not desirable. If you use this wrapper library, you don't have to add script tag to head of html.
The plain SDK does not have a declarative API. So, when you use it in your React app, you will probably find it hard to do. Using this library, you can handle the data provided by the SDK with custom hooks that you are used to.
npm install react-spotify-web-playback-sdk
Assume that you have the latest oauth token. Required scopes that the token have are "streaming", "user-read-email" and "user-read-private". You can also get an access token here.
WebPlaybackSDK component is a root of this library. So you must wrap any custom-hooks in this library with it.
import { WebPlaybackSDK } from "react-spotify-web-playback-sdk";
const AUTH_TOKEN = "your token here!";
const MySpotifyPlayer: React.VFC = () => {
const getOAuthToken = useCallback(callback => callback(AUTH_TOKEN), []);
return (
<WebPlaybackSDK
initialDeviceName="My awesome Spotify app"
getOAuthToken={getOAuthToken}
initialVolume={0.5}>
{/* `TogglePlay` and `SongTitle` will be defined later. */}
<TogglePlay />
<SongTitle />
</WebPlaybackSDK>
);
};props.initialDeviceName is a value that will be displayed in the official Spotify app as the device name.
props.getOAuthToken is a function that takes a callback function as an argument to receive the access token.
props.initialVolume is a value between 0 and 1. If not specified, it will be set to the default value of 1.
The props.initialVolume can be a value between 0 and 1. If not specified, 1 will be set as the default value.
Gets the playback status. For example, there are properties such as whether it is paused or not, and the playback position.
import { usePlaybackState } from "react-spotify-web-playback-sdk";
const SongTitle: React.VFC = () => {
const playbackState = usePlaybackState();
if (playbackState === null) return null;
return <p>Current song: {playbackState.track_window.current_track.name}</p>;
};If the connection with Spotify has not been established, it will be null, so perform a null check.
When you render MySpotifyPlayer in your React app, you will see My awesome Spotify app in Spotify Connect in your Spotify mobile app. Select it there and click the toggle play button to start playing.
This is a React component that wraps the SDK. This is not available in the React-Naitive environment.
The custom hooks included in the library will not work unless they are inside this component.
| prop name | type | default value | description |
|---|---|---|---|
initialDeviceName |
string | (required) | an initial value of Spotify Connect player name. |
getOAuthToken |
(callback: (token: string) => void) => void | (required) | a function called when player.connect() is called, or when the user's access token expires. |
initialVolume |
number | 1 | a initial value of volume. specified as a decimal number between 0 and 1. |
connectOnInitialized |
boolean | true | Whether to make a connection at the same time as initialization. |
const MyPlayer = () => {
const getOAuthToken = useCallback(callback => {
const token = fetchNewSpotifyToken();
callback(token);
}, []);
return (
<WebPlaybackSDK
initialDeviceName="My Spotify App"
getOAuthToken={getOAuthToken}
initialVolume={0.5}
connectOnInitialized={true}>
<SomeComponentsUsingCustomHook />
</WebPlaybackSDK>
);
};A custom hook that returns a boolean value whether the SDK has been downloaded and is ready or not.
function useWebPlaybackSDKReady(): boolean;const MyPlayer = () => {
const webPlaybackSDKReady = useWebPlaybackSDKReady();
if (!webPlaybackSDKReady) return <div>Loading...</div>;
return <div>Spotify App is ready!</div>;
};A custom hook that returns an object with functions to manipulate the player, such as resume() or seek(pos).
function useSpotifyPlayer(): Spotify.Player | null;const PauseResumeButton = () => {
const player = useSpotifyPlayer();
if (player === null) return null;
return (
<div>
<button onClick={() => player.pause()}>pause</button>
<button onClick={() => player.resume()}>resume</button>
</div>
);
};A custom hook to get an object representing the player's playback state. See the Spotify for Developers reference for more information on the properties that the object has.
If interval is true, state updates will occur during playback at the interval specified by durationMS. Even if it is false, state updates by SpotifyPlayer.pause and SpotifyPlayer.resume will occur.
function usePlaybackState(
interval?: boolean = false,
durationMS?: number = 1000,
): Spotify.PlaybackState | null;const SongTitle: React.VFC = () => {
const playbackState = usePlaybackState();
if (playbackState === null) return null;
return <p>Current song: {playbackState.track_window.current_track.name}</p>;
};A custom hook that retrieves an object that represents the state of the player device. According to the Spotify for Developers reference, it will be "not_ready" when there is no internet connection.
The device_id can be used as a parameter to, for example, the Spotify Web API's playback API (for reference).
type PlayerDevice = {
device_id: string;
status: "ready" | "not_ready";
};
function usePlayerDevice(): PlayerDevice | null;const SPOTIFY_URI = "spotify:track:7xGfFoTpQ2E7fRF5lN10tr";
const PlayCarlyRaeJepsen = () => {
const device = usePlayerDevice();
const playCarlyRaeJepsen = () => {
if (device === null) return;
fetch(
`https://api.spotify.com/v1/me/player/play?device_id=${device.device_id}`,
{
method: "PUT",
body: JSON.stringify({ uris: [SPOTIFY_URI] }),
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${AUTH_TOKEN}`,
},
},
);
};
if (device === null) return null;
return <button onClick={playCarlyRaeJepsen}>Play Carly Rae Jepsen</button>;
};If an error occurs, an object containing the message will be returned. Otherwise, null is returned.
type ErrorState = {
message: string;
type:
| "account_error"
| "authentication_error"
| "initialization_error"
| "playback_error";
};
function useErrorState(): ErrorState | null;const ErrorState = () => {
const errorState = useErrorState();
if (errorState === null) return null;
return <p>Error: {errorState.message}</p>;
};MIT
A minimal demo app:
https://react-spotify-web-playback-sdk.vercel.app/
A complete demo app: