Intro#

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 wavelink.Node’s.

An example:

import discord
import wavelink
from discord.ext import commands
from wavelink.ext import spotify


class Bot(commands.Bot):

    def __init__(self) -> None:
        intents = discord.Intents.default()
        intents.message_content = True

        super().__init__(intents=intents, command_prefix='?')

    async def on_ready(self) -> None:
        print(f'Logged in {self.user} | {self.user.id}')

    async def setup_hook(self) -> None:
        sc = spotify.SpotifyClient(
            client_id='CLIENT_ID',
            client_secret='CLIENT_SECRET'
        )

        node: wavelink.Node = wavelink.Node(uri='http://127.0.0.1:2333', password='youshallnotpass')
        await wavelink.NodePool.connect(client=self, nodes=[node], spotify=sc)


bot = Bot()


@bot.command()
@commands.is_owner()
async def play(ctx: commands.Context, *, search: str) -> None:

    try:
        vc: wavelink.Player = await ctx.author.voice.channel.connect(cls=wavelink.Player)
    except discord.ClientException:
        vc: wavelink.Player = ctx.voice_client

    vc.autoplay = True

    track: spotify.SpotifyTrack = await spotify.SpotifyTrack.search(search)

    if not vc.is_playing():
        await vc.play(track, populate=True)
    else:
        await vc.queue.put_wait(track)

Helpers#

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"])

Client#

class wavelink.ext.spotify.SpotifyClient(*, client_id: str, client_secret: str)#

Spotify client passed to wavelink.Node for searching via Spotify.

Parameters

client_id (str) – Your spotify application client ID.
client_secret (str) – Your spotify application secret.

Enums#

Attributes

album
playlist
track
unusable

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#: Album search type.

playlist#: Playlist search type.

unusable#: Unusable type. This type is returned when Wavelink can not be used to play this track.

Spotify Tracks#

Attributes

album
artists
duration
genres
id
images
isrc
length
name
raw
title
uri

Methods

clsSpotifyTrack.convert
clsSpotifyTrack.iterator
asyncfulfill
asyncsearch

class wavelink.ext.spotify.SpotifyTrack(data: dict[str, Any])#

A track retrieved via Spotify.

raw#

The raw payload from Spotify for this track.

Type: dict[str, Any]

album#

The album name this track belongs to.

Type: str

images#

A list of URLs to images associated with this track.

Type: list[str]

artists#

A list of artists for this track.

Type: list[str]

genres#

A list of genres associated with this tracks artist.

Type: list[str]

name#

The track name.

Type: str

title#

An alias to name.

Type: str

uri#

The URI for this spotify track.

Type: str

id#

The spotify ID for this track.

Type: str

isrc#

The International Standard Recording Code associated with this track if given.

Type: str | None

length#

The track length in milliseconds.

Type: int

duration#

Alias to length.

Type: int

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.

coroutine fulfill(*, player: Player, cls: Playable, populate: bool) → Playable#

Used to fulfill the wavelink.Player Auto Play Queue.

Warning

Usually you would not call this directly. Instead you would set wavelink.Player.autoplay to true, and allow the player to fulfill this request automatically.

Parameters

player (wavelink.player.Player) – If wavelink.Player.autoplay is enabled, this search will fill the AutoPlay Queue with more tracks.
cls – The class to convert this Spotify Track to.

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

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[wavelink.Node]) – An optional node to use when querying for tracks. Defaults to the best available.

Examples

async for track in spotify.SpotifyTrack.iterator(query=..., type=spotify.SpotifySearchType.playlist):
    ...

Note

See decode_url() for gathering information about the supplied URL, including search type. Before using this method.

classmethod coroutine search(query: str, *, type: SpotifySearchType = SpotifySearchType.track, node: Optional[Node] = None, 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[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.

Return type

Union[Optional[SpotifyTrack], List[SpotifyTrack]]

Examples

Searching for a singular tack to play…

track: spotify.SpotifyTrack = await spotify.SpotifyTrack.search(query=SPOTIFY_URL)

Searching for all tracks in an album…

tracks: list[spotify.SpotifyTrack] =
await spotify.SpotifyTrack.search(query=SPOTIFY_URL, type=spotify.SpotifySearchType.album)

Note

See decode_url() for gathering information about the supplied URL, including search type. Before using this method.

Exceptions#

exception wavelink.ext.spotify.SpotifyRequestError#

Base error for Spotify requests.

status: int: The status code returned from the request.
reason: Optional[str]: The reason the request failed. Could be None.