Spotify Extension#

The Spotify extension is a QoL extension that helps in searching for and queueing tracks from Spotify URL’s or ID’s. To get started create a SpotifyClient and pass in your credentials. You then pass this to your Node(s). An example:

import wavelink
from wavelink.ext import spotify


async def create_nodes(...):
    await wavelink.NodePool.create_node(...,
                                        spotify_client=spotify.SpotifyClient(client_id=..., client_secret=...))

Once your Node has a SpotifyClient attached, you can use await spotify.SpotifyTrack.search(query=SPOTIFY_URL) to search for an appropriate YouTube Track.

Recipes#

Searching for a singular track:

# If an ID is passed you must provide a spotify.SpotifySearchType
# In this case type=spotify.SpotifySearchType.track
# This is not needed with full URL's

track = await spotify.SpotifyTrack.search(query="SPOTIFY_TRACK_URL_OR_ID", return_first=True)

Searching for an album (Flattened to a list):

# If an ID is passed you must provide a spotify.SpotifySearchType
# In this case type=spotify.SpotifySearchType.album
# This is not needed with full URL's

tracks = await spotify.SpotifyTrack.search(query="SPOTIFY_ALBUM_URL_OR_ID")

Searching for an album (As an async iterator):

async for track in spotify.SpotifyTrack.iterator(query="SPOTIFY_ALBUM_URL_OR_ID", type=spotify.SpotifySearchType.album)
    print(track)

Searching for a playlist (With PartialTrack’s):

# Partial tracks makes queueing large playlists or albums super fast...
# Partial tracks only have limited information until they are played...

async for partial in spotify.SpotifyTrack.iterator(query="SPOTIFY_PLAYLIST_URL_OR_ID", partial_tracks=True):
    player.queue.put(partial)

Decoding a Spotify URL:

# Useful for determining the type of search and the ID...
# If the URL decoded is an unusable type e.g artist, spotify.SpotifySearchType.unusable will be returned...
# If the URL is not a valid Spotify URL, None is returned.

decoded = spotify.decode_url("SPOTIFY_URL")
if decoded is not None:
    print(decoded['type'], decoded['id'])

Reference#

wavelink.ext.spotify.decode_url(url: str) → Optional[dict]#

Check whether the given URL is a valid Spotify URL and return it’s type and ID.

Parameters

url (str) – The URL to check.

Returns

An mapping of SpotifySearchType and Spotify ID. Type will be either track, album or playlist. If type is not track, album or playlist, a special unusable type is returned.

Could return None if the URL is invalid.

Return type

Optional[dict]

Examples

from wavelink.ext import spotify

...

decoded = spotify.decode_url("https://open.spotify.com/track/6BDLcvvtyJD2vnXRDi1IjQ?si=e2e5bd7aaf3d4a2a")

if decoded and decoded['type'] is spotify.SpotifySearchType.track:
    track = await spotify.SpotifyTrack.search(query=decoded["id"], type=decoded["type"])
class wavelink.ext.spotify.SpotifyClient(*, client_id: str, client_secret: str)#

Spotify client passed to Nodes for searching via Spotify.

Parameters

  • client_id (str) – Your spotify application client ID.

  • client_secret (str) – Your spotify application secret.

class wavelink.ext.spotify.SpotifySearchType(value)#

An enum specifying which type to search for with a given Spotify ID.

track

Default search type. Unless specified otherwise this will always be the search type.

album

Search for an album.

playlist

Search for a playlist.

class wavelink.ext.spotify.SpotifyTrack(id: str, info: dict)#

A track retrieved via YouTube with a Spotify URL/ID.

classmethod coroutine convert(ctx: Context, argument: str) → ST#

Converter which searches for and returns the first track.

Used as a type hint in a discord.py command.

classmethod iterator(*, query: str, limit: Optional[int] = None, type: SpotifySearchType = SpotifySearchType.playlist, node: Optional[Node] = MISSING, partial_tracks: bool = False)#

An async iterator version of search.

This can be useful when searching for large playlists or albums with Spotify.

Parameters

  • query (str) – The Spotify URL or ID to search for. Must be of type Playlist or Album.

  • limit (Optional[int]) – Limit the amount of tracks returned.

  • type (SpotifySearchType) – The type of search. Must be either playlist or album. Defaults to playlist.

  • node (Optional[Node]) – An optional node to use when querying for tracks. Defaults to best available.

  • partial_tracks (Optional[bool]) – Whether or not to create wavelink.tracks.PartialTrack objects for search at playtime. This can make queuing large albums or playlists considerably faster, but with less information. Defaults to False.

Examples

async for track in spotify.SpotifyTrack.iterator(query=..., type=spotify.SpotifySearchType.playlist):
    ...
classmethod coroutine search(query: str, *, type: SpotifySearchType = SpotifySearchType.track, node: Node = MISSING, return_first: bool = False) → Union[ST, None, List[ST]]#

This function is a coroutine.

Search for tracks with the given query.

Parameters

  • query (str) – The song to search for.

  • type (Optional[spotify.SpotifySearchType]) – An optional enum value to use when searching with Spotify. Defaults to track.

  • node (Optional[wavelink.Node]) – An optional Node to use to make the search with.

  • return_first (Optional[bool]) – An optional bool which when set to True will return only the first track found. Defaults to False.

Returns

Return type

Union[Optional[Track], List[Track]]

exception wavelink.ext.spotify.SpotifyRequestError(status: int, reason: Optional[str] = None)#

Base error for Spotify requests.

status#

The status code returned from the request.

Type

int

reason#

The reason the request failed. Could be None.

Type

Optional[str]