Note
This library was coded and released at the same time as https://github.com/spotify/spotify-web-api-ts-sdk/. Prefer their library as it is more complete.
A fully typed client for node and browser environments.
Install:
# npm
npm i spotify-web-client
# yarn
yarn add spotify-web-client
Import:
// ESM / Typescript
import { SpotifyClient } from 'spotify-web-client'
// CommonJS
const { SpotifyClient } = require('spotify-web-client')
Usage
const token = '...' // Generate an access token with OAuth
const client = new SpotifyClient().setAccessToken(token)
// Get currently played song
const playbackState = await client.player.getPlaybackState()
if (playbackState.item?.type === 'track') {
// playbackState.item narrowed to TrackObject
console.log(playbackState.item.name)
}
You can check for more advanced usage (OAuth, other methods...) in the playground directory
- 🔒 Authentication
- 💿 Albums
- 🎤 Artists
- 📗 Audiobooks
- 🔖 Categories
- 🕮 Chapters
- 🎙️ Episodes
- 🪩 Genres
- 🌍 Markets
▶️ Player- 🎧 Playlists
- 🔍 Search
- 🎙️ Shows
- 🎼 Tracks
- 👥 Users
These methods can be accessed directly through your SpotifyClient
instance.
Method | Description |
---|---|
setAccessToken |
Sets the access_token for the current instance of SpotifyClient |
setRefreshToken |
Sets the refresh_token for the current instance of SpotifyClient |
generateOAuthUrl |
Generates an OAuth link with the provided scope |
getAccessToken |
Exchanges an authorization code for an access_token and a refresh_token |
refreshToken |
Obtain a new access_token from a refresh token |
These methods can be accessed through the albums
key of your SpotifyClient
instance.
Method | Description |
---|---|
getAlbum |
Get Spotify catalog information for a single album. |
getAlbums |
Get Spotify catalog information for multiple albums identified by their Spotify IDs. |
getAlbumTracks |
Get Spotify catalog information about an album’s tracks. Optional parameters can be used to limit the number of tracks returned. |
getSavedAlbums |
Get a list of the albums saved in the current Spotify user's 'Your Music' library. |
saveAlbums |
Save one or more albums to the current user's 'Your Music' library. |
removeAlbums |
Remove one or more albums from the current user's 'Your Music' library. |
checkUserSavedAlbums |
Check if one or more albums is already saved in the current Spotify user's 'Your Music' library. |
getReleases |
Get a list of new album releases featured in Spotify (shown, for example, on a Spotify player’s “Browse” tab). |
These methods can be accessed through the artists
key of your SpotifyClient
instance.
Method | Description |
---|---|
getArtist |
Get Spotify catalog information for a single artist identified by their unique Spotify ID. |
getArtists |
Get Spotify catalog information for several artists based on their Spotify IDs. |
getArtistAlbums |
Get Spotify catalog information about an artist's albums. |
getArtistTopTracks |
Get Spotify catalog information about an artist's top tracks by country. |
getRelatedArtists |
Get Spotify catalog information about artists similar to a given artist. Similarity is based on analysis of the Spotify community's listening history. |
These methods can be accessed through the audiobooks
key of your SpotifyClient
instance.
Note: Audiobooks are only available for the US, UK, Ireland, New Zealand and Australia markets.
Method | Description |
---|---|
getAudiobook |
Get Spotify catalog information for a single audiobook. |
getAudiobooks |
Get Spotify catalog information for several audiobooks identified by their Spotify IDs. |
getAudiobookChapters |
Get Spotify catalog information about an audiobook's chapters. |
getSavedAudiobooks |
Get a list of the audiobooks saved in the current Spotify user's 'Your Music' library. |
saveAudiobooks |
Save one or more audiobooks to the current Spotify user's library. |
removeAudiobooks |
Remove one or more audiobooks from the Spotify user's library. |
checkUserSavedAudiobooks |
Check if one or more audiobooks are already saved in the current Spotify user's library. |
These methods can be accessed through the categories
key of your SpotifyClient
instance.
Method | Description |
---|---|
getCategories |
Get a list of categories used to tag items in Spotify (on, for example, the Spotify player’s “Browse” tab). |
getCategory |
Get a single category used to tag items in Spotify (on, for example, the Spotify player’s “Browse” tab). |
These methods can be accessed through the chapters
key of your SpotifyClient
instance.
Note: Chapters are only available for the US, UK, Ireland, New Zealand and Australia markets.
Method | Description |
---|---|
getChapter |
Get Spotify catalog information for a single chapter. |
getChapters |
Get Spotify catalog information for several chapters identified by their Spotify IDs. |
These methods can be accessed through the episodes
key of your SpotifyClient
instance.
Method | Description |
---|---|
getEpisode |
Get Spotify catalog information for a single episode identified by its unique Spotify ID. |
getEpisodes |
Get Spotify catalog information for several episodes based on their Spotify IDs. |
getSavedEpisodes |
Get a list of the episodes saved in the current Spotify user's library. |
saveEpisodes |
Save one or more episodes to the current user's library. |
removeEpisodes |
Remove one or more episodes from the current user's library. |
checkUserSavedEpisodes |
Check if one or more episodes is already saved in the current Spotify user's 'Your Episodes' library. |
These methods can be accessed through the genres
key of your SpotifyClient
instance.
Method | Description |
---|---|
getAvailableGenreSeeds |
Retrieve a list of available genres seed parameter values for recommendations. |
These methods can be accessed through the genres
key of your SpotifyClient
instance.
Method | Description |
---|---|
getMarkets |
Get the list of markets where Spotify is available. |
These methods can be accessed through the player
key of your SpotifyClient
instance.
Method | Description |
---|---|
getPlaybackState |
Get information about the user’s current playback state, including track or episode, progress, and active device. |
transferPlayback |
Transfer playback to a new device and determine if it should start playing. |
getAvailableDevices |
Get information about a user’s available devices. |
getCurrentlyPlayedTrack |
Get the object currently being played on the user's Spotify account. |
startPlayback |
Start a new context or resume current playback on the user's active device. |
pausePlayback |
Pause playback on the user's account. |
skipToNext |
Skips to next track in the user’s queue. |
skipToPrevious |
Skips to previous track in the user’s queue. |
seekToPosition |
Seeks to the given position in the user’s currently playing track. |
setRepeatMode |
Set the repeat mode for the user's playback. Options are repeat-track, repeat-context, and off. |
setPlaybackVolume |
Set the volume for the user’s current playback device. |
toggleShuffle |
Toggle shuffle on or off for user’s playback. |
getRecentlyPlayedTracks |
Get tracks from the current user's recently played tracks. |
getUserQueue |
Get the list of objects that make up the user's queue. |
addItemToQueue |
Add an item to the end of the user's current playback queue. |
These methods can be accessed through the playlists
key of your SpotifyClient
instance.
Method | Description |
---|---|
getPlaylist |
Get a playlist owned by a Spotify user. |
updatePlaylistDetails |
Change a playlist's name and public/private state. (The user must, of course, own the playlist.) |
getPlaylistItems |
Get full details of the items of a playlist owned by a Spotify user. |
updatePlaylistItems |
Either reorder or replace items in a playlist depending on the request's parameters. To reorder items, include range_start, insert_before, range_length and snapshot_id in the request's body. To replace items, include uris as either a query parameter or in the request's body. Replacing items in a playlist will overwrite its existing items. This operation can be used for replacing or clearing items in a playlist. |
addPlaylistItems |
Add one or more items to a user's playlist. |
removePlaylistItems |
Remove one or more items from a user's playlist. |
getCurrentUserPlaylists |
Get a list of the playlists owned or followed by the current Spotify user. |
getUserPlaylists |
Get a list of the playlists owned or followed by a Spotify user. |
createPlaylist |
Create a playlist for a Spotify user. (The playlist will be empty until you add tracks.) |
getFeaturedPlaylists |
Get a list of Spotify featured playlists (shown, for example, on a Spotify player's 'Browse' tab). |
getPlaylistsForCategory |
Get a list of Spotify playlists tagged with a particular category. |
getPlaylistCoverImage |
Get the current image associated with a specific playlist. |
addCustomPlaylistCoverImage |
Replace the image used to represent a specific playlist. |
These methods can be accessed through the search
key of your SpotifyClient
instance.
Note: Audiobooks are only available for the US, UK, Ireland, New Zealand and Australia markets.
Method | Description |
---|---|
search |
Get Spotify catalog information about albums, artists, playlists, tracks, shows, episodes or audiobooks that match a keyword string. |
These methods can be accessed through the shows
key of your SpotifyClient
instance.
Method | Description |
---|---|
getShow |
Get Spotify catalog information for a single show identified by its unique Spotify ID. |
getShows |
Get Spotify catalog information for several shows based on their Spotify IDs. |
getShowsEpisodes |
Get Spotify catalog information about an show’s episodes. Optional parameters can be used to limit the number of episodes returned. |
getSavedShows |
Get a list of shows saved in the current Spotify user's library. Optional parameters can be used to limit the number of shows returned. |
saveShows |
Save one or more shows to current Spotify user's library. |
removeShows |
Delete one or more shows from current Spotify user's library. |
checkUserSavedShows |
Check if one or more shows is already saved in the current Spotify user's library. |
These methods can be accessed through the tracks
key of your SpotifyClient
instance.
Method | Description |
---|---|
getTrack |
Get Spotify catalog information for a single track identified by its unique Spotify ID. |
getTracks |
Get Spotify catalog information for multiple tracks based on their Spotify IDs. |
getUserSavedTracks |
Get a list of the songs saved in the current Spotify user's 'Your Music' library. |
saveTracks |
Save one or more tracks to the current user's 'Your Music' library. |
removeSavedTracks |
Remove one or more tracks from the current user's 'Your Music' library. |
checkUserSavedTracks |
Check if one or more tracks is already saved in the current Spotify user's 'Your Music' library. |
getTracksAudioFeatures |
Get audio features for multiple tracks based on their Spotify IDs. |
getTrackAudioFeatures |
Get audio feature information for a single track identified by its unique Spotify ID. |
getTrackAudioAnalysis |
Get a low-level audio analysis for a track in the Spotify catalog. The audio analysis describes the track’s structure and musical content, including rhythm, pitch, and timbre. |
getRecommendations |
Recommendations are generated based on the available information for a given seed entity and matched against similar artists and tracks. If there is sufficient information about the provided seeds, a list of tracks will be returned together with pool size details. For artists and tracks that are very new or obscure there might not be enough data to generate a list of tracks. |
These methods can be accessed through the users
key of your SpotifyClient
instance.
Method | Description |
---|---|
getCurrentUserProfile |
Get detailed profile information about the current user (including the current user's username). |
getCurrentUserTopItems |
Get the current user's top artists or tracks based on calculated affinity. |
getUserProfile |
Get public profile information about a Spotify user. |
followPlaylist |
Add the current user as a follower of a playlist. |
unfollowPlaylist |
Remove the current user as a follower of a playlist. |
getFollowedArtists |
Get the current user's followed artists. |
follow |
Add the current user as a follower of one or more artists or other Spotify users. |
unfollow |
Remove the current user as a follower of one or more artists or other Spotify users. |
isFollowing |
Check to see if the current user is following one or more artists or other Spotify users. |
isFollowingPlaylist |
Check to see if one or more Spotify users are following a specified playlist. |