@hgahlla/spotifly

spotifly

Spotify with wings !

Spotify library in typescript without using the Spotify Web API.

• No authentication required.
• Super fast like the Web API.
• Lightweight with zero dependencies.
• Strongly typed API functions.
• Personalized fetching and automation using cookies.
• Automatic internal token refreshing.

...along with a Musixmatch API module. Works without any authentication too.

📦 Get Started

• Requirement

  node.js (>=17.5.0), bun or deno runtime.

• Installation

  npm i spotifly or bun i spotifly

• Usage

  import { Spotifly } from "spotifly";
  
  const sp = new Spotifly();
  const track = await sp.getTrack("abcdefghijk");
  console.log(track);

📖 Documentation

Functions marked with an asterisk (*) require your spotify cookies to work. How to get your Spotify cookies ?

• Spotifly module
  • getHomepage
  • getTrack
  • getTrackCredits
  • getRelatedTrackArtists
  • getArtist
  • getAlbum
  • getPlaylist
  • getPlaylistMetadata
  • getPlaylistContents
  • getUser
  • getSection
  • getPodcast
  • getPodcastEpisodes
  • getEpisode
  • searchAll
  • searchTracks
  • searchAlbums
  • searchPlaylists
  • searchArtists
  • searchUsers
  • searchPodcasts
  • getTrackLyrics
  • extractImageColors
  • *getMyProfile
  • *getMyLibrary
  • *getMyProductState
  • *getMyLikedSongs
  • *addToLikedSongs
  • *removeFromLikedSongs
  • *getTrackColorLyrics
• *SpotiflyPlaylist module
  • id
  • create
  • rename
  • changeDescription
  • fetchMetadata
  • fetchContents
  • add
  • remove
  • cloneFrom
  • delete
• Musixmatch module
  • search
  • getLyricsFromUrl
  • searchLyrics
• Parse module
  • urlToId
  • uriToId
  • urlToUri
  • uriToUrl
• How to get your Spotify cookies ?

Spotifly module

new Spotifly(cookie?: string)

The main module containing all the Spotify API functions.

• getHomepage(): Promise<SpotifyHome>

  Fetch the Spotify homepage data.

• getTrack(id: string): Promise<SpotifyTrack>

  Fetch the details of the provided track id.

• getTrackCredits(id: string): Promise<SpotifyTrackCredits>

  Fetch the credits of the provided track id.

• getRelatedTrackArtists(id: string): Promise<SpotifyRelatedTrackArtists>

  Fetch the related artists of the artist of the provided track id.

• getArtist(id: string): Promise<SpotifyArtist>

  Fetch the details of the provided artist id.

• getAlbum(id: string, limit?: number): Promise<SpotifyAlbum>

  Fetch the details of the provided album id, with optional limit for amount of tracks to fetch.

• getPlaylist(id: string, limit?: number, offset?: number): Promise<SpotifyPlaylist>

  Fetch all the details of the provided playlist id, with optional limit for amount of tracks to fetch.

• getPlaylistMetadata(id: string, limit?: number): Promise<SpotifyPlaylistMetadata>

  Fetch the metadata only of the provided playlist id, with optional limit for amount of tracks to fetch.

• getPlaylistContents(id: string, limit?: number): Promise<SpotifyPlaylistContents>

  Fetch the contents of the provided playlist id, with optional limit for amount of tracks to fetch.

• getUser(id: string, config?: { playlistLimit?: number, artistLimit?: number, episodeLimit?: number }): Promise<SpotifyUser>

  Fetch the details of the provided user id, with optional limit for amount of tracks to fetch.

• getSection(id: string): Promise<SpotifySection>

  Fetch the details of the provided section id.

• getPodcast(id: string): Promise<SpotifyPodcast>

  Fetch the details of the provided show id.

• getPodcastEpisodes(id: string, limit?: number): Promise<SpotifyPodcastEpisodes>

  Fetch the episodes of the provided show id, with optional limit for amount of episodes to fetch.

• getEpisode(id: string): Promise<SpotifyEpisode>

  Fetch the details of the provided episode id.

• searchAll(terms: string, limit?: number): Promise<SpotifySearchAll>

  Search the Spotify library with the terms provided, for all types of content, with optional limit for amount of search results to fetch.

• searchTracks(terms: string, limit?: number): Promise<SpotifySearchTracks>

  Search the Spotify library with the terms provided, for tracks, with optional limit for amount of search results to fetch.

• searchAlbums(terms: string, limit?: number): Promise<SpotifySearchAlbums>

  Search the Spotify library with the terms provided, for albums, with optional limit for amount of search results to fetch.

• searchPlaylists(terms: string, limit?: number): Promise<SpotifySearchPlaylists>

  Search the Spotify library with the terms provided, for playlists, with optional limit for amount of search results to fetch.

• searchArtists(terms: string, limit?: number): Promise<SpotifySearchArtists>

  Search the Spotify library with the terms provided, for artists, with optional limit for amount of search results to fetch.

• searchUsers(terms: string, limit?: number): Promise<SpotifySearchUsers>

  Search the Spotify library with the terms provided, for users, with optional limit for amount of search results to fetch.

• searchPodcasts(terms: string, limit?: number): Promise<SpotifySearchPodcasts>

  Search the Spotify library with the terms provided, for podcasts and shows, with optional limit for amount of search results to fetch.

• getTrackLyrics(id: string): Promise<string[]>

  Fetch the lyrics of the provided track id through the Musixmatch module.

  If you want to fetch lyrics directly from Spotify, see getTrackColorLyrics.

• extractImageColors(...urls: string[]): Promise<SpotifyExtractedColors>

  Extract raw, dark and light colors from the provided urls of images using Spotify API.

The following functions require cookies to work. How to get your Spotify cookies ?

• getMyProfile(): Promise<SpotifyMyProfile>

  Fetch the details of your Spotify profile.

• getMyLibrary(config?): Promise<SpotifyMyLibrary>

  Fetch your Spotify library.

  • config.filter?: [] | ["Playlists"] | ["Playlists", "By you"] | ["Artists"]
  • config.order?: "Recents" | "Recently Added" | "Alphabetical" | "Creator" | "Custom Order"
  • config.textFilter?: string
  • config.limit?: number

• getMyProductState(): Promise<SpotifyProductState>

  Fetch the details of your Spotify product state like premium plan, etc.

• getMyLikedSongs(): Promise<SpotifyLikedSongs>

  Fetch the songs you have liked from your Spotify library.

• addToLikedSongs(...trackUris: string[]): Promise<SpotifyLikedSongsAdd>

  Add the tracks to your liked songs library.

• removeFromLikedSongs(...trackUris: string[]): Promise<SpotifyLikedSongsRemove>

  Remove the tracks from your liked songs library.

• getTrackColorLyrics(id: string, imgUrl?: string): Promise<SpotifyColorLyrics>

  Fetch the track lyrics directly from Spotify's internal Musixmatch API with an optional image url to fetch the colors of that image.

SpotiflyPlaylist module

new SpotiflyPlaylist(cookie: string)

The module containing all the functions to interact with playlists in your Spotify library using the cookies provided. How to get your Spotify cookies ?

• id: string

  Property to get or set the playlist id with whom the following functions will be interacting.

• create(name: string)

  Create a new empty playlist with the provided name in your Spotify library and sets the id with the newly created one.

• rename(newName: string)

  Change the name of the playlist with the new name provided.

• changeDescription(newDescription: string)

  Change the description of the playlist with the new description provided.

• fetchMetadata(limit?: number)

  Fetch the metadata of the playlist.

• fetchContents(limit?: number)

  Fetch the contents of the playlist.

• add(...trackUris: string[])

  Add tracks to the playlist from the provided track uris.

• remove(...trackUris: string[])

  Remove tracks from the playlist from the provided track uris.

• cloneFrom(id: string, config?: { name?: string, description?: string, limit?: number; })

  Create a new playlist in your Spotify library by cloning from another playlist with optional config to change the data of the created playlist and sets the id with the newly created one.

• delete()

  Delete the playlist from your Spotify library.

Musixmatch module

The Musixmatch API module containing functions to search and fetch lyrics. No authentication needed.

• search(terms: string): Promise<MusixmatchSearch[]>

  Search the Musixmatch library with the terms provided.

• getLyricsFromUrl(url: string): string[]

  Fetch the lyrics from a Musixmatch lyrics url (i.e. musixmatch.com/lyrics/abc/xyz).

• searchLyrics(terms: string): string[]

  Fetch the lyrics of the top result after searching for the terms. Combination of the above two functions but faster.

Parse module

The parsing module containing few utility functions.

• urlToId(url: string): string

  Extract the id from an open.spotify.com url.

• uriToId(uri: string): string

  Extract the id from a Spotify uri (i.e. spotify:track:abcdefghijk).

• urlToUri(url: string): string

  Convert an open.spotify.com url to a Spotify uri (i.e. spotify:track:abcdefghijk).

• uriToUrl(uri: string): string

  Convert a Spotify uri (i.e. spotify:track:abcdefghijk) to an open.spotify.com url.

🍪 How to get your Spotify cookies ?

• Login to your Spotify account in your browser.
• Open Developer Tools of your browser and switch to Network tab.
• Go to https://open.spotify.com/.
• Find the request with the name open.spotify.com and open it.
• From the Headers tab, scroll to Request Headers section.
• Copy the contents of the Cookie header value.

The copied value is your Spotify cookies.

📜 License

This repository uses MIT License. See LICENSE for full license text.