Spotify-web-client NPM

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

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.

ofetch

@everything-registry/sub-chunk-2808

0.2.0

10 months ago

0.1.0

10 months ago