Skip to content
generated from antfu/starter-ts

A fully-typed client for Spotify API, compatible in a browser and node.

License

Notifications You must be signed in to change notification settings

noook/spotify-client

Repository files navigation

npm npm

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.

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

You can check for more advanced usage (OAuth, other methods...) in the playground directory

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

About

A fully-typed client for Spotify API, compatible in a browser and node.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published