spotify-web-client

A fully typed client for node and browser environments.

🚀 Quick Start

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)
}

📦 Available APIs

• 🔒 Authentication
• 💿 Albums
• 🎤 Artists
• 📗 Audiobooks
• 🔖 Categories
• 🕮 Chapters
• 🎙️ Episodes
• 🪩 Genres
• 🌍 Markets
• ▶️ Player
• 🎧 Playlists
• 🔍 Search
• 🎙️ Shows
• 🎼 Tracks
• 👥 Users

🔒 Authentication

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 |

💿 Albums

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). |

🎤 Artists

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

📗 Audiobooks

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

🔖 Categories

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). |

🕮 Chapters

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

🎙️ Episodes

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

🪩 Genres

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

🌍 Markets

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

▶️ Player

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

🎧 Playlists

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

🔍 Search

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

🎙️ Shows

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

🎼 Tracks

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

👥 Users

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