Intro#

The Spotify extension is a QoL extension that helps in searching for and queueing tracks from Spotify URLs. 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) → wavelink.ext.spotify.utils.SpotifyDecodePayload | None#

Check whether the given URL is a valid Spotify URL and return a SpotifyDecodePayload if this URL is valid, or None if this URL is invalid.

Parameters

url (str) – The URL to check.

Returns

The decode payload containing the Spotify SpotifySearchType and Spotify ID.

Could return None if the URL is invalid.

Return type

Optional[SpotifyDecodePayload]

Examples

from wavelink.ext import spotify

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

Version changed: 2.6.0 - This function now returns SpotifyDecodePayload. For backwards compatibility you can access this payload like a dictionary.

Payloads#

Attributes
class wavelink.ext.spotify.SpotifyDecodePayload(*, type_: SpotifySearchType, id_: str)#

The SpotifyDecodePayload received when using decode_url().

repr(payload)

Returns an official string representation of this payload.

payload['attr']

Allows this object to be accessed like a dictionary.

type#

Either track, album or playlist. If type is not track, album or playlist, a special unusable type is assigned.

Type

SpotifySearchType

id#

The Spotify ID associated with the decoded URL.

Type

str

Note

To keep backwards compatibility with previous versions of decode_url(), you can access this object like a dictionary.

Warning

You do not instantiate this object manually. Instead you receive it via decode_url().

New in version: 2.6.0

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
class wavelink.ext.spotify.SpotifySearchType(value)#

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

track#

Track search type.

album#

Album search type.

playlist#

Playlist search type.

unusable#

Unusable type. This type is assigned when Wavelink can not be used to play this track.

Spotify Tracks#

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

A track retrieved via Spotify.

str(track)

Returns a string representing this SpotifyTrack’s name and artists.

repr(track)

Returns an official string representation of this SpotifyTrack.

track == other_track

Check whether a track is equal to another. Tracks are equal if they both have the same Spotify ID.

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.

Type

str | None

length#

The track length in milliseconds.

Type

int

duration#

Alias to length.

Type

int

explicit#

Whether this track is explicit or not.

Type

bool

classmethod await search(query: str, *, node: Optional[Node] = None) → list['SpotifyTrack']#

This function is a coroutine.

Search for tracks with the given query.

Parameters

  • query (str) – The Spotify URL to query for.

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

Return type

List[SpotifyTrack]

Examples

Searching for a singular tack to play…

tracks: list[spotify.SpotifyTrack] = await spotify.SpotifyTrack.search(query=SPOTIFY_URL)
if not tracks:
    # No tracks found, do something?
    return

track: spotify.SpotifyTrack = tracks[0]

Searching for all tracks in an album…

tracks: list[spotify.SpotifyTrack] = await spotify.SpotifyTrack.search(query=SPOTIFY_URL)
if not tracks:
    # No tracks found, do something?
    return

Version changed: 2.6.0 - This method no longer takes in the type parameter. The query provided will be automatically decoded, if the type returned by decode_url() is unusable, this method will return an empty list

classmethod iterator(*, query: str, limit: Optional[int] = None, 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 to search for. Must be of type Playlist or Album.

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

  • 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=...):
    ...

Version changed: 2.6.0 - This method no longer takes in the type parameter. The query provided will be automatically decoded, if the type returned by decode_url() is not either album or playlist this method will raise a TypeError.

classmethod await 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.

await 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

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.