API Reference#

The wavelink API Reference.

This section outlines the API and all it’s components within wavelink.

Wavelink is a robust and powerful Lavalink wrapper for Discord.py. Featuring, a fully asynchronous API that’s intuitive and easy to use with built in Spotify Support, Node Pool Balancing, advanced Queues, autoplay feature and looping features built in.

Event Reference#

WaveLink Events are events dispatched when certain events happen in Lavalink and Wavelink. All events must be coroutines.

Events are dispatched via discord.py and as such can be used with listener syntax. All Track Events receive the payloads.TrackEventPayload payload.

For example:

An event listener in a cog…

@commands.Cog.listener()
async def on_wavelink_node_ready(node: Node) -> None:
    print(f"Node {node.id} is ready!")

Called when the Node you are connecting to has initialised and successfully connected to Lavalink.

Called when any Track Event occurs.

Called when a track starts playing.

Called when the current track has finished playing.

Called when the websocket to the voice server is closed.

Payloads#

Attributes
class wavelink.TrackEventPayload(*, data: EventOp, track: Playable, original: Playable | None, player: Player)#

The Wavelink Track Event Payload.

Warning

This class should not be created manually, instead you will receive it from the various wavelink track events.

event#

An enum of the type of event.

Type

TrackEventType

track#

The track associated with this event.

Type

Playable

original#

The original requested track before conversion. Could be None.

Type

Optional[Playable]

player#

The player associated with this event.

Type

player.Player

reason#

The reason this event was fired.

Type

Optional[str]

Attributes
class wavelink.WebsocketClosedPayload(*, data: dict[str, Any], player: Player)#

The Wavelink WebsocketClosed Event Payload.

Warning

This class should not be created manually, instead you will receive it from the wavelink on_wavelink_websocket_closed event.

code#

An Enum representing the close code from Discord.

Type

DiscordVoiceCloseType

reason#

The reason the Websocket was closed.

Type

Optional[str]

by_discord#

Whether the websocket was closed by Discord.

Type

bool

player#

The player associated with this event.

Type

player.Player

Enums#

Attributes
class wavelink.NodeStatus(value: str)#

Enum representing the current status of a Node.

DISCONNECTED#

0

CONNECTING#

1

CONNECTED#

2

Attributes
class wavelink.TrackSource(value: str)#

Enum representing the Track Source Type.

YouTube#

0

YouTubeMusic#

1

SoundCloud#

2

Local#

3

Unknown#

4

Attributes
class wavelink.LoadType(value: str)#

Enum representing the Tracks Load Type.

track_loaded#

“TRACK_LOADED”

playlist_loaded#

“PLAYLIST_LOADED”

search_result#

“SEARCH_RESULT”

no_matches#

“NO_MATCHES”

load_failed#

“LOAD_FAILED”

Attributes
class wavelink.TrackEventType(value: str)#

Enum representing the TrackEvent types.

START#

“TrackStartEvent”

END#

“TrackEndEvent”

Attributes
class wavelink.DiscordVoiceCloseType(value: str)#

Enum representing the various Discord Voice Websocket Close Codes.

CLOSE_NORMAL#

1000

UNKNOWN_OPCODE#

4001

FAILED_DECODE_PAYLOAD#

4002

NOT_AUTHENTICATED#

4003

AUTHENTICATION_FAILED#

4004

ALREADY_AUTHENTICATED#

4005

SESSION_INVALID#

4006

SESSION_TIMEOUT#

4009

SERVER_NOT_FOUND#

4011

UNKNOWN_PROTOCOL#

4012

DISCONNECTED#

4014

VOICE_SERVER_CRASHED#

4015

UNKNOWN_ENCRYPTION_MODE#

4016

Abstract Base Classes#

Attributes
Methods
class wavelink.tracks.Playable(data: TrackPayload)#

Base ABC Track used in all the Wavelink Track types.

str(track)

Returns a string representing the tracks name.

repr(track)

Returns an official string representation of this track.

track == other_track

Check whether a track is equal to another. A track is equal when they have the same Base64 Encoding.

data#

The raw data received via Lavalink.

Type

dict[str, Any]

encoded#

The encoded Track string.

Type

str

is_seekable#

Whether the Track is seekable.

Type

bool

is_stream#

Whether the Track is a stream.

Type

bool

length#

The length of the track in milliseconds.

Type

int

duration#

An alias for length.

Type

int

position#

The position the track will start in milliseconds. Defaults to 0.

Type

int

title#

The Track title.

Type

str

source#

The source this Track was fetched from.

Type

wavelink.TrackSource

uri#

The URI of this track. Could be None.

Type

Optional[str]

author#

The author of this track. Could be None.

Type

Optional[str]

identifier#

The Youtube/YoutubeMusic identifier for this track. Could be None.

Type

Optional[str]

classmethod await search(query: str, /, *, node: wavelink.node.Node | None = None) → list[Self]#
classmethod await search(query: str, /, *, node: wavelink.node.Node | None = None) → YouTubePlaylist
classmethod await search(query: str, /, *, node: wavelink.node.Node | None = None) → SoundCloudPlaylist

Search and retrieve tracks for the given query.

Parameters
classmethod await convert(ctx: commands.Context, argument: str) → Self#

Converter which searches for and returns the first track.

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

Attributes
class wavelink.tracks.Playlist(data: dict[str, Any])#

An ABC that defines the basic structure of a lavalink playlist resource.

data#

The raw data supplied by Lavalink.

Type

Dict[str, Any]

NodePool#

Attributes
Methods
class wavelink.NodePool#

The Wavelink NodePool is responsible for keeping track of all Node.

nodes#

A mapping of Node identifier to Node.

Type

dict[str, Node]

Warning

This class should never be initialised. All methods are class methods.

classmethod await connect(*, client: discord.Client, nodes: list[Node], spotify: spotify_.SpotifyClient | None = None) → dict[str, Node]#

This function is a coroutine.

Connect a list of Nodes.

Parameters

  • client (discord.Client) – The discord Client or Bot used to connect the Nodes.

  • nodes (list[Node]) – A list of Nodes to connect.

  • spotify (Optional[ext.spotify.SpotifyClient]) – The spotify Client to use when searching for Spotify Tracks.

Returns

A mapping of Node identifier to Node.

Return type

dict[str, Node]

classmethod get_node(id: Optional[str] = None) → Node#

Retrieve a Node with the given ID or best, if no ID was passed.

Parameters

id (Optional[str]) – The unique identifier of the Node to retrieve. If not passed the best Node will be fetched.

Return type

Node

Raises

InvalidNode – The given id does nto resolve to a Node or no Node has been connected.

classmethod get_connected_node() → Node#

Get the best available connected Node.

Returns

The best available connected Node.

Return type

Node

Raises

InvalidNode – No Nodes are currently in the connected state.

classmethod await get_tracks(query: str, /, *, cls: type[PlayableT], node: Node | None = None) → list[PlayableT]#

This function is a coroutine.

Helper method to retrieve tracks from the NodePool without fetching a Node.

Parameters

  • query (str) – The query to search for and return tracks.

  • cls (type[PlayableT]) – The type of Playable tracks that should be returned.

  • node (Optional[Node]) – The node to use for retrieving tracks. If not passed, the best Node will be used. Defaults to None.

Returns

A list of found tracks converted to the provided cls.

Return type

list[PlayableT]

classmethod await get_playlist(query: str, /, *, cls: Playlist, node: Node | None = None) → Playlist#

This function is a coroutine.

Helper method to retrieve a playlist from the NodePool without fetching a Node.

Warning

The only playlists currently supported are tracks.YouTubePlaylist and tracks.YouTubePlaylist.

Parameters

  • query (str) – The query to search for and return a playlist.

  • cls (type[PlayableT]) – The type of Playlist that should be returned.

  • node (Optional[Node]) – The node to use for retrieving tracks. If not passed, the best Node will be used. Defaults to None.

Returns

A Playlist with its tracks.

Return type

Playlist

Node#

Attributes
Methods
class wavelink.Node(*, id: Optional[str] = None, uri: str, password: str, secure: bool = False, use_http: bool = False, session: ClientSession = ..., heartbeat: float = 15.0, retries: Optional[int] = None)#

The base Wavelink Node.

The Node is responsible for keeping the Websocket alive, tracking the state of Players and fetching/decoding Tracks and Playlists.

Note

The Node class should only be created once per Lavalink connection. To retrieve a Node use the appropriate NodePool methods instead.

Warning

The Node will not be connected until passed to NodePool.connect().

repr(node)

Returns an official string representation of this Node.

Parameters

  • id (Optional[str]) – The unique identifier for this Node. If not passed, one will be generated randomly.

  • uri (str) – The uri to connect to your Lavalink server. E.g http://localhost:2333.

  • password (str) – The password used to connect to your Lavalink server.

  • secure (Optional[bool]) – Whether the connection should use https/wss.

  • use_http (Optional[bool]) – Whether to use http:// over ws:// when connecting to the Lavalink websocket. Defaults to False.

  • session (Optional[aiohttp.ClientSession]) – The session to use for this Node. If no session is passed a default will be used.

  • heartbeat (float) – The time in seconds to send a heartbeat ack. Defaults to 15.0.

  • retries (Optional[int]) – The amount of times this Node will try to reconnect after a disconnect. If not set the Node will try unlimited times.

heartbeat#

The time in seconds to send a heartbeat ack. Defaults to 15.0.

Type

float

client#

The discord client used to connect this Node. Could be None if this Node has not been connected.

Type

discord.Client

property id: str#

The Nodes unique identifier.

property uri: str#

The URI used to connect this Node to Lavalink.

property password: str#

The password used to connect this Node to Lavalink.

property players: dict[int, Player]#

A mapping of Guild ID to Player.

property status: NodeStatus#

The connection status of this Node.

DISCONNECTED CONNECTING CONNECTED

get_player(guild_id: int, /) → Player | None#

Return the player.Player associated with the provided guild ID.

If no player.Player is found, returns None.

Parameters

guild_id (int) – The Guild ID to return a Player for.

Return type

Optional[player.Player]

await get_tracks(cls: type[PlayableT], query: str) → list[PlayableT]#

This function is a coroutine.

Search for and retrieve Tracks based on the query and cls provided.

Note

If the query is not a Local search or direct URL, you will need to provide a search prefix. E.g. ytsearch: for a YouTube search.

Parameters

  • cls (type[PlayableT]) – The type of Playable tracks that should be returned.

  • query (str) – The query to search for and return tracks.

Returns

A list of found tracks converted to the provided cls.

Return type

list[PlayableT]

await get_playlist(cls: Playlist, query: str)#

This function is a coroutine.

Search for and return a tracks.Playlist given an identifier.

Parameters

  • cls (Type[tracks.Playlist]) – The type of which playlist should be returned, this must subclass tracks.Playlist.

  • query (str) – The playlist’s identifier. This may be a YouTube playlist URL for example.

Returns

The related wavelink track object or None if none was found.

Return type

Optional[tracks.Playlist]

Raises
await build_track(*, cls: type[PlayableT], encoded: str) → PlayableT#

This function is a coroutine.

Build a track from the provided encoded string with the given Track class.

Parameters

  • cls (type[PlayableT]) – The type of Playable track that should be returned.

  • encoded (str) – The Tracks unique encoded string.

Tracks#

Tracks inherit from Playable. Not all fields will be available for each track type.

GenericTrack#

Methods
class wavelink.GenericTrack(data: TrackPayload)#

Generic Wavelink Track.

Use this track for searching for Local songs or direct URLs.

classmethod await convert(ctx: commands.Context, argument: str) → Self#

Converter which searches for and returns the first track.

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

classmethod await search(query: str, /, *, node: Node | None = None) → list[Self]#

Search and retrieve tracks for the given query.

Parameters

YouTubeTrack#

Attributes
Methods
class wavelink.YouTubeTrack(data: TrackPayload)#
property thumbnail: str#

The URL to the thumbnail of this video.

Note

Due to YouTube limitations this may not always return a valid thumbnail. Use fetch_thumbnail() to fallback.

Returns

The URL to the video thumbnail.

Return type

str

property thumb: str#

The URL to the thumbnail of this video.

Note

Due to YouTube limitations this may not always return a valid thumbnail. Use fetch_thumbnail() to fallback.

Returns

The URL to the video thumbnail.

Return type

str

await fetch_thumbnail(*, node: Optional[Node] = None) → str#

Fetch the max resolution thumbnail with a fallback if it does not exist.

This sets and overrides the default thumbnail and thumb properties.

Note

This method uses an API request to fetch the thumbnail.

Returns

The URL to the video thumbnail.

Return type

str

classmethod await convert(ctx: commands.Context, argument: str) → Self#

Converter which searches for and returns the first track.

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

classmethod await search(query: str, /, *, node: Node | None = None) → list[Self]#

Search and retrieve tracks for the given query.

Parameters

YouTubeMusicTrack#

Attributes
Methods
class wavelink.YouTubeMusicTrack(data: TrackPayload)#

A track created using a search to YouTube Music.

classmethod await convert(ctx: commands.Context, argument: str) → Self#

Converter which searches for and returns the first track.

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

await fetch_thumbnail(*, node: Optional[Node] = None) → str#

Fetch the max resolution thumbnail with a fallback if it does not exist.

This sets and overrides the default thumbnail and thumb properties.

Note

This method uses an API request to fetch the thumbnail.

Returns

The URL to the video thumbnail.

Return type

str

classmethod await search(query: str, /, *, node: Node | None = None) → list[Self]#

Search and retrieve tracks for the given query.

Parameters
property thumb: str#

The URL to the thumbnail of this video.

Note

Due to YouTube limitations this may not always return a valid thumbnail. Use fetch_thumbnail() to fallback.

Returns

The URL to the video thumbnail.

Return type

str

property thumbnail: str#

The URL to the thumbnail of this video.

Note

Due to YouTube limitations this may not always return a valid thumbnail. Use fetch_thumbnail() to fallback.

Returns

The URL to the video thumbnail.

Return type

str

SoundCloudTrack#

Methods
class wavelink.SoundCloudTrack(data: TrackPayload)#

A track created using a search to SoundCloud.

classmethod await convert(ctx: commands.Context, argument: str) → Self#

Converter which searches for and returns the first track.

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

classmethod await search(query: str, /, *, node: Node | None = None) → list[Self]#

Search and retrieve tracks for the given query.

Parameters

YouTubePlaylist#

Attributes
Methods
class wavelink.YouTubePlaylist(data: dict)#

Represents a Lavalink YouTube playlist object.

str(playlist)

Returns a string representing the playlists name.

name#

The name of the playlist.

Type

str

tracks#

The list of YouTubeTrack in the playlist.

Type

YouTubeTrack

selected_track#

The selected video in the playlist. This could be None.

Type

Optional[int]

classmethod await convert(ctx: commands.Context, argument: str) → Self#

Converter which searches for and returns the first track.

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

classmethod await search(query: str, /, *, node: Node | None = None) → list[Self]#

Search and retrieve tracks for the given query.

Parameters

Player#

Attributes
Methods
class wavelink.Player(client: Client = ..., channel: Union[VoiceChannel, StageChannel] = ..., *, nodes: Optional[list[wavelink.node.Node]] = None, swap_node_on_disconnect: bool = True)#

Wavelink Player class.

This class is used as a VoiceProtocol and inherits all its members.

You must pass this class to discord.VoiceChannel.connect() with cls=.... This ensures the player is set up correctly and put into the discord.py voice client cache.

You can make an instance of this class before passing it to discord.VoiceChannel.connect() with cls=..., but you must still pass it.

Once you have connected this class you do not need to store it anywhere as it will be stored on the Node and in the discord.py voice client cache. Meaning you can access this player where you have access to a NodePool, the specific Node or a Guild including in Context and Interaction.

Examples

# Connect the player...
player: wavelink.Player = await ctx.author.voice.channel.connect(cls=wavelink.Player)

# Retrieve the player later...
player: wavelink.Player = ctx.guild.voice_client

Note

The Player class comes with an in-built queue. See queue.Queue for more information on how this queue works.

Parameters

  • nodes (Optional[list[node.Node]]) – An optional list of node.Node to use with this Player. If no Nodes are provided the best connected Node will be used.

  • swap_node_on_disconnect (bool) – If a list of node.Node is provided the Player will swap Nodes on Node disconnect. Defaults to True.

client#

The discord Client or Bot associated with this Player.

Type

discord.Client

channel#

The channel this player is currently connected to.

Type

discord.VoiceChannel

nodes#

The list of Nodes this player is currently using.

Type

list[node.Node]

current_node#

The Node this player is currently using.

Type

node.Node

queue#

The wavelink built in Queue. See queue.Queue. This queue always takes precedence over the auto_queue. Meaning any songs in this queue will be played before auto_queue songs.

Type

queue.Queue

auto_queue#

The built-in AutoPlay Queue. This queue keeps track of recommended songs only. When a song is retrieved from this queue in the AutoPlay event, it is added to the main wavelink.Queue.history queue.

Type

queue.Queue

property autoplay: bool#

Returns a bool indicating whether the Player is in AutoPlay mode or not.

This property can be set to True or False.

When autoplay is True, the player will automatically handle fetching and playing the next track from the queue. It also searches tracks in the auto_queue, a special queue populated with recommended tracks, from the Spotify API or YouTube Recommendations.

Note

You can still use the on_wavelink_track_end() event when autoplay is True, but it is recommended to not do any queue logic or invoking play from this event.

Most users are able to use autoplay and on_wavelink_track_start() together to handle their logic. E.g. sending a message when a track starts playing.

Note

The auto_queue will be populated when you play a SpotifyTrack or YouTubeTrack, and have initially set populate to True in play(). See play() for more info.

New in version: 2.0

Version changed: 2.6.0 - The autoplay event now populates the auto_queue when playing YouTubeTrack or SpotifyTrack.

is_connected() → bool#

Whether the player is connected to a voice channel.

is_playing() → bool#

Whether the Player is currently playing a track.

is_paused() → bool#

Whether the Player is currently paused.

property volume: int#

The current volume of the Player.

property guild: discord.guild.Guild | None#

The discord Guild associated with the Player.

property position: float#

The position of the currently playing track in milliseconds.

property ping: int#

The ping to the discord endpoint in milliseconds.

New in version: 2.0

property current: wavelink.tracks.Playable | None#

The currently playing Track if there is one.

Could be None if no Track is playing.

property filter: dict[str, Any]#

The currently applied filter.

await on_voice_server_update(data: VoiceServerUpdate) → None#

This function is a coroutine.

An abstract method that is called when initially connecting to voice. This corresponds to VOICE_SERVER_UPDATE.

Warning

Do not override this method.

await on_voice_state_update(data: GuildVoiceState) → None#

This function is a coroutine.

An abstract method that is called when the client’s voice state has changed. This corresponds to VOICE_STATE_UPDATE.

Warning

Do not override this method.

await connect(*, timeout: float, reconnect: bool, **kwargs: Any) → None#

This function is a coroutine.

An abstract method called when the client initiates the connection request.

When a connection is requested initially, the library calls the constructor under __init__ and then calls connect(). If connect() fails at some point then disconnect() is called.

Within this method, to start the voice connection flow it is recommended to use Guild.change_voice_state() to start the flow. After which, on_voice_server_update() and on_voice_state_update() will be called. The order that these two are called is unspecified.

Parameters

  • timeout (float) – The timeout for the connection.

  • reconnect (bool) – Whether reconnection is expected.

  • self_mute (bool) –

    Indicates if the client should be self-muted.

    New in version: 2.0

  • self_deaf (bool) –

    Indicates if the client should be self-deafened.

    New in version: 2.0

await move_to(channel: VoiceChannel) → None#

This function is a coroutine.

Moves the player to a different voice channel.

Parameters

channel (discord.VoiceChannel) – The channel to move to. Must be a voice channel.

await play(track: wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack, replace: bool = True, start: Optional[int] = None, end: Optional[int] = None, volume: Optional[int] = None, *, populate: bool = False) → Playable#

This function is a coroutine.

Play a WaveLink Track.

Parameters

  • track (tracks.Playable) – The tracks.Playable or SpotifyTrack track to start playing.

  • replace (bool) – Whether this track should replace the current track. Defaults to True.

  • start (Optional[int]) – The position to start the track at in milliseconds. Defaults to None which will start the track at the beginning.

  • end (Optional[int]) – The position to end the track at in milliseconds. Defaults to None which means it will play until the end.

  • volume (Optional[int]) – Sets the volume of the player. Must be between 0 and 1000. Defaults to None which will not change the volume.

  • populate (bool) –

    Whether to populate the AutoPlay queue. Defaults to False.

    New in version: 2.0

Returns

The track that is now playing.

Return type

Playable

Note

If you pass a YouTubeTrack or SpotifyTrack and set populate=True, while autoplay is set to True, this method will populate the auto_queue with recommended songs. When the auto_queue is low on tracks this method will automatically populate the auto_queue with more tracks, and continue this cycle until either the player has been disconnected or autoplay is set to False.

Example

tracks: list[wavelink.YouTubeTrack] = await wavelink.YouTubeTrack.search(...)
if not tracks:
    # Do something as no tracks were found...
    return

await player.queue.put_wait(tracks[0])

if not player.is_playing():
    await player.play(player.queue.get(), populate=True)

Version changed: 2.6.0 - This method now accepts YouTubeTrack or SpotifyTrack when populating the auto_queue.

await set_volume(value: int) → None#

This function is a coroutine.

Set the Player volume.

Parameters

value (int) – A volume value between 0 and 1000.

await seek(position: int) → None#

This function is a coroutine.

Seek to the provided position, in milliseconds.

Parameters

position (int) – The position to seek to in milliseconds.

await pause() → None#

This function is a coroutine.

Pauses the Player.

await resume() → None#

This function is a coroutine.

Resumes the Player.

await stop(*, force: bool = True) → None#

This function is a coroutine.

Stops the currently playing Track.

Parameters

force (Optional[bool]) – Whether to stop the currently playing track and proceed to the next regardless if loop is True. Defaults to True.

Version changed: 2.6 - Added the force keyword argument.

await set_filter(_filter: Filter, /, *, seek: bool = False) → None#

This function is a coroutine.

Set the player’s filter.

Parameters

  • filter (wavelink.Filter) – The filter to apply to the player.

  • seek (bool) – Whether to seek the player to its current position which will apply the filter immediately. Defaults to False.

await disconnect(**kwargs) → None#

This function is a coroutine.

Disconnect the Player from voice and cleanup the Player state.

Version changed: 2.5 - The discord.py Voice Client cache and Player are invalidated as soon as this is called.

Queues#

Attributes
Methods
class wavelink.BaseQueue#

BaseQueue for wavelink.

All queues inherit from this queue.

See Queue for the default Player queue. Internally this queue uses a collections.deque.

Warning

It is not advisable to edit the internal collections.deque directly.

str(queue)

Returns a string showing all Playable objects appearing as a list in the queue.

repr(queue)

Returns an official string representation of this queue.

if queue

Returns True if members are in the queue. False if the queue is empty.

queue(track)

Adds a member to the queue.

len(queue)

Returns an int with the count of members in this queue.

queue[2]

Returns a member at the given position. Does not remove the item from queue.

queue[4] = track

Inserts an item into the queue at the given position.

del queue[1]

Deletes a member from the queue at the given position.

for track in queue

Iterates over the queue. Does not remove items when iterating.

reversed(queue)

Reverse a reversed version of the queue.

if track in queue

Checks whether a track is in the queue.

queue = queue + [track, track1, track2, ...]

Return a new queue containing all new and old members from the given iterable.

queue += [track, track1, track2, ...]

Add items to queue from the given iterable.

property count: int#

Returns queue member count.

property is_empty: bool#

Returns True if queue has no members.

get() → wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack#

Return next immediately available item in queue if any.

Raises QueueEmpty if no items in queue.

pop() → wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack#

Return item from the right end side of the queue.

Raises QueueEmpty if no items in queue.

find_position(item: wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack) → int#

Find the position a given item within the queue.

Raises ValueError if item is not in the queue.

put(item: wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack) → None#

Put the given item into the back of the queue.

If the provided item is a YouTubePlaylist or SoundCloudPlaylist, all tracks from this playlist will be put into the queue.

Note

Inserting playlists is currently only supported via this method, which means you can only insert them into the back of the queue. Future versions of wavelink may add support for inserting playlists from a specific index, or at the front of the queue.

Version changed: 2.6.0 - Added support for directly adding a YouTubePlaylist to the queue.

put_at_index(index: int, item: wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack) → None#

Put the given item into the queue at the specified index.

put_at_front(item: wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack) → None#

Put the given item into the front of the queue.

shuffle() → None#

Shuffles the queue in place. This does not return anything.

Example

player.queue.shuffle()
# Your queue has now been shuffled...

New in version: 2.5

extend(iterable: Iterable[wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack], *, atomic: bool = True) → None#

Add the members of the given iterable to the end of the queue.

If atomic is set to True, no tracks will be added upon any exceptions.

If atomic is set to False, as many tracks will be added as possible.

copy()#

Create a copy of the current queue including its members.

clear() → None#

Remove all items from the queue.

Note

This does not reset the queue. See reset() for resetting the Queue assigned to the player.

Attributes
Methods
class wavelink.Queue#

Main Queue class.

All Player have this queue assigned to them.

Note

This queue inherits from BaseQueue but has access to special async methods and loop logic.

Warning

The history queue is a BaseQueue and has no access to async methods or loop logic.

async for track in queue

Pops members as it iterates the queue asynchronously, waiting for new members when exhausted. Does remove items when iterating.

history#

The history queue stores information about all previous played tracks for the Player’s session.

Type

BaseQueue

get() → wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack#

Return next immediately available item in queue if any.

Raises QueueEmpty if no items in queue.

await get_wait() → wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack#

This function is a coroutine.

Return the next item in queue once available.

Note

This will wait until an item is available to be retrieved.

await put_wait(item: wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack) → None#

This function is a coroutine.

Put an item into the queue asynchronously using await.

If the provided item is a YouTubePlaylist or SoundCloudPlaylist, all tracks from this playlist will be put into the queue.

Note

Inserting playlists is currently only supported via this method, which means you can only insert them into the back of the queue. Future versions of wavelink may add support for inserting playlists from a specific index, or at the front of the queue.

Version changed: 2.6.0 - Added support for directly adding a YouTubePlaylist to the queue.

put(item: wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack) → None#

Put the given item into the back of the queue.

If the provided item is a YouTubePlaylist, all tracks from this playlist will be put into the queue.

Note

Inserting playlists is currently only supported via this method, which means you can only insert them into the back of the queue. Future versions of wavelink may add support for inserting playlists from a specific index, or at the front of the queue.

Version changed: 2.6.0 - Added support for directly adding a YouTubePlaylist to the queue.

reset() → None#

Clears the state of all queues, including the history queue.

  • sets loop and loop_all to False.

  • removes all items from the queue and history queue.

  • cancels any waiting queues.

property loop: bool#

Whether the queue will loop the currently playing song.

Can be set to True or False. Defaults to False.

Return type

bool

New in version: 2.0

property loop_all: bool#

Whether the queue will loop all songs in the history queue.

Can be set to True or False. Defaults to False.

Note

If loop is set to True, this has no effect until loop is set to False.

Return type

bool

New in version: 2.0

Filters#

class wavelink.Filter(_filter: Optional[Filter] = None, /, *, equalizer: Optional[Equalizer] = None, karaoke: Optional[Karaoke] = None, timescale: Optional[Timescale] = None, tremolo: Optional[Tremolo] = None, vibrato: Optional[Vibrato] = None, rotation: Optional[Rotation] = None, distortion: Optional[Distortion] = None, channel_mix: Optional[ChannelMix] = None, low_pass: Optional[LowPass] = None)#

A filter that can be applied to a track.

This filter accepts an instance of itself as a parameter which allows you to keep previous filters while also applying new ones or overwriting old ones.

repr(filter)

Returns an official string representation of this filter.

Parameters
Methods
class wavelink.Equalizer(name: str = 'CustomEqualizer', *, bands: list[tuple[int, float]])#

An equalizer filter.

Parameters

  • name (str) – The name of this filter. Can be used to differentiate between equalizer filters.

  • bands (List[Dict[str, int]]) – A list of equalizer bands, each item is a dictionary with “band” and “gain” keys.

classmethod flat() → Equalizer#

A flat equalizer.

classmethod boost() → Equalizer#

A boost equalizer.

classmethod metal() → Equalizer#

A metal equalizer.

classmethod piano() → Equalizer#

A piano equalizer.

class wavelink.Karaoke(*, level: float = 1.0, mono_level: float = 1.0, filter_band: float = 220.0, filter_width: float = 100.0)#

A Karaoke filter.

The default values provided for all the parameters will play the track normally.

Parameters

  • level (float) – How much of an effect this filter should have.

  • mono_level (float) – How much of an effect this filter should have on mono tracks.

  • filter_band (float) – The band this filter should target.

  • filter_width (float) – The width of the band this filter should target.

class wavelink.Timescale(*, speed: float = 1.0, pitch: float = 1.0, rate: float = 1.0)#

A timescale filter.

Increases or decreases the speed, pitch, and/or rate of tracks.

The default values provided for speed, pitch and rate will play the track normally.

Parameters

  • speed (float) – A multiplier for the track playback speed. Should be more than or equal to 0.0.

  • pitch (float) – A multiplier for the track pitch. Should be more than or equal to 0.0.

  • rate (float) – A multiplier for the track rate (pitch + speed). Should be more than or equal to 0.0.

class wavelink.Tremolo(*, frequency: float = 2.0, depth: float = 0.5)#

A tremolo filter.

Creates a shuddering effect by quickly changing the volume.

The default values provided for frequency and depth will play the track normally.

Parameters

  • frequency (float) – How quickly the volume should change. Should be more than 0.0.

  • depth (float) – How much the volume should change. Should be more than 0.0 and less than or equal to 1.0.

class wavelink.Vibrato(*, frequency: float = 2.0, depth: float = 0.5)#

A vibrato filter.

Creates a vibrating effect by quickly changing the pitch.

The default values provided for frequency and depth will play the track normally.

Parameters

  • frequency (float) – How quickly the pitch should change. Should be more than 0.0 and less than or equal to 14.0.

  • depth (float) – How much the pitch should change. Should be more than 0.0 and less than or equal to 1.0.

class wavelink.Rotation(speed: float = 5)#

A rotation filter.

Rotates the audio around stereo channels which can be used to create a 3D effect.

The default value provided for speed will play the track normally.

Parameters

speed (float) – The speed at which the audio should rotate.

class wavelink.Distortion(*, sin_offset: float = 0.0, sin_scale: float = 1.0, cos_offset: float = 0.0, cos_scale: float = 1.0, tan_offset: float = 0.0, tan_scale: float = 1.0, offset: float = 0.0, scale: float = 1.0)#

A distortion filter.

Methods
class wavelink.ChannelMix(*, left_to_left: float = 1.0, left_to_right: float = 0.0, right_to_left: float = 0.0, right_to_right: float = 1.0)#

A channel mix filter.

Allows you to control what channel audio from the track is actually played on.

Setting left_to_left and right_to_right to 1.0 will result in no change. Setting all channels to 0.5 will result in all channels receiving the same audio.

The default values provided for all the parameters will play the track normally.

Parameters

  • left_to_left (float) – The “percentage” of audio from the left channel that should actually get played on the left channel.

  • left_to_right (float) – The “percentage” of audio from the left channel that should play on the right channel.

  • right_to_left (float) – The “percentage” of audio from the right channel that should actually get played on the right channel.

  • right_to_right (float) – The “percentage” of audio from the right channel that should play on the left channel.

classmethod mono() → ChannelMix#

Returns a ChannelMix filter that will play the track in mono.

classmethod only_left() → ChannelMix#

Returns a ChannelMix filter that will only play the tracks left channel.

classmethod full_left() → ChannelMix#

Returns a ChannelMix filter that will play the tracks left and right channels together only on the left channel.

classmethod only_right() → ChannelMix#

Returns a ChannelMix filter that will only play the tracks right channel.

classmethod full_right() → ChannelMix#

Returns a ChannelMix filter that will play the tracks left and right channels together only on the right channel.

classmethod switch() → ChannelMix#

Returns a ChannelMix filter that will switch the tracks left and right channels.

class wavelink.LowPass(*, smoothing: float = 20)#

A low pass filter.

Suppresses higher frequencies while allowing lower frequencies to pass through.

The default value provided for smoothing will play the track normally.

Parameters

smoothing (float) – The factor by which the filter will block higher frequencies.

Exceptions#

exception wavelink.WavelinkException#

Base wavelink exception.

exception wavelink.AuthorizationFailed#

Exception raised when password authorization failed for this Lavalink node.

exception wavelink.InvalidNode#
exception wavelink.InvalidLavalinkVersion#

Exception raised when you try to use wavelink 2 with a Lavalink version under 3.7.

exception wavelink.InvalidLavalinkResponse#

Exception raised when wavelink receives an invalid response from Lavalink.

status: int | None

The status code. Could be None.

exception wavelink.NoTracksError#

Exception raised when no tracks could be found.

exception wavelink.QueueEmpty#

Exception raised when you try to retrieve from an empty queue.

exception wavelink.InvalidChannelStateError#

Base exception raised when an error occurs trying to connect to a discord.VoiceChannel.

exception wavelink.InvalidChannelPermissions#

Exception raised when the client does not have correct permissions to join the channel.

Could also be raised when there are too many users already in a user limited channel.