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

wavelink.on_wavelink_node_ready(node: Node)#: Called when the Node you are connecting to has initialised and successfully connected to Lavalink.

wavelink.on_wavelink_track_event(payload: TrackEventPayload)#: Called when any Track Event occurs.

wavelink.on_wavelink_track_start(payload: TrackEventPayload)#: Called when a track starts playing.

wavelink.on_wavelink_track_end(payload: TrackEventPayload)#: Called when the current track has finished playing.

Payloads#

Attributes

event
player
reason
track

class wavelink.TrackEventPayload(*, data: EventOp, track: Playable, 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

player#

The player associated with this event.

Type: player.Player

reason#

The reason this event was fired.

Type: Optional[str]

Abstract Base Classes#

Attributes

author
data
duration
encoded
identifier
is_seekable
is_stream
length
position
source
title
uri

Methods

clsPlayable.convert
clsPlayable.search

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

Base ABC Track used in all the Wavelink Track types.

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: 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 coroutine 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 coroutine search(query: str, /, *, return_first: Literal[False] = False, node: wavelink.node.Node | None = None) → list[Self]#

classmethod coroutine search(query: str, /, *, return_first: Literal[True] = False, node: wavelink.node.Node | None = None) → Self

classmethod coroutine search(query: str, /, *, return_first: bool = False, node: wavelink.node.Node | None = None) → Self | list[Self]

classmethod coroutine search(query: str, /, *, return_first: bool = False, node: wavelink.node.Node | None = None) → YouTubePlaylist

Search and retrieve tracks for the given query.

Parameters

query (str) – The query to search for.
return_first (Optional[bool]) – Whether to return the first track from the search results. Defaults to False.
node (Optional[Node]) – The node to use when searching for tracks. If no Node is passed, one will be fetched via the NodePool.

Attributes

data

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#

Methods

clsNodePool.get_connected_node
clsNodePool.get_node
asyncconnect
asyncget_playlist
asyncget_tracks

class wavelink.NodePool#

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

Warning

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

classmethod coroutine 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_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 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 coroutine 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 playlist currently supported is 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

classmethod coroutine 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]

Node#

Attributes

client
heartbeat
id
password
players
status
uri

Methods

asyncbuild_track
defget_player
asyncget_playlist
asyncget_tracks

class wavelink.Node(*, id: Optional[str] = None, uri: str, password: str, secure: 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().

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

coroutine 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.

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]

coroutine 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

ValueError – Loading the playlist failed.
WavelinkException – An unspecified error occurred when loading the playlist.

coroutine 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]

property id: str#: The Nodes unique identifier.

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

property uri: str#: The URI used to connect this Node to Lavalink.

Tracks#

GenericTrack#

class wavelink.GenericTrack(data: TrackPayload)#

Generic Wavelink Track.

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

YouTubeTrack#

Attributes

thumb
thumbnail

Methods

asyncfetch_thumbnail

class wavelink.YouTubeTrack(data: TrackPayload)#

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

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

Note

This method uses an API request to fetch the thumbnail.

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

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

YouTubeMusicTrack#

class wavelink.YouTubeMusicTrack(data: TrackPayload)#: A track created using a search to YouTube Music.

SoundCloudTrack#

class wavelink.SoundCloudTrack(data: TrackPayload)#: A track created using a search to SoundCloud.

YouTubePlaylist#

Attributes

name
selected_track
tracks

class wavelink.YouTubePlaylist(data: dict)#

Represents a Lavalink YouTube playlist object.

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]

Player#

Attributes

auto_queue
autoplay
channel
client
current
current_node
filter
guild
nodes
ping
position
queue
volume

Methods

asyncconnect
asyncdisconnect
defis_paused
defis_playing
asyncmove_to
asyncon_voice_server_update
asyncon_voice_state_update
asyncpause
asyncplay
asyncresume
asyncseek
asyncset_filter
asyncset_volume
asyncstop

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 discord.VoiceProtocol and inherits all its members.

Note

The Player class come with an in-built queue. See queue.Queue.

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: :class: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 Queue.history.

Type: queue.Queue

filter#

The current filters applied.

Type: dict[str, Any]

coroutine 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.

coroutine disconnect(**kwargs) → None#

This function is a coroutine.

Disconnect the Player from voice and cleanup the Player state.

is_paused() → bool#: Whether the Player is currently paused.

is_playing() → bool#: Whether the Player is currently playing a track.

coroutine 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.

coroutine 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.

Parameters: data (dict) – The raw :ddocs:`voice server update payload <topics/gateway#voice-server-update>`.

coroutine 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.

Parameters: data (dict) – The raw :ddocs:`voice state payload <resources/voice#voice-state-object>`.

coroutine pause() → None#

This function is a coroutine.

Pauses the Player.

coroutine play(track: Playable, 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 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. This is done automatically when AutoPlay is on. Defaults to False.

Returns

The track that is now playing.

Return type

tracks.Playable

coroutine resume() → None#

This function is a coroutine.

Resumes the Player.

coroutine 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.

coroutine 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.

coroutine set_volume(value: int) → None#

This function is a coroutine.

Set the Player volume.

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

coroutine stop() → None#

This function is a coroutine.

Stops the currently playing Track.

property autoplay: bool#

Bool whether the Player is in AutoPlay mode or not.

Can be set to True or False.

property current: wavelink.tracks.Playable | None#

The currently playing Track if there is one.

Could be None if no Track is playing.

property guild: discord.guild.Guild | None#: The discord Guild associated with the Player.

property ping: int#: The ping to the discord endpoint in milliseconds.

property position: float#: The position of the currently playing track in milliseconds.

property volume: int#: The current volume of the Player.

Queues#

Attributes

count
is_empty

Methods

defclear
defcopy
defextend
deffind_position
defget
defpop
defput
defput_at_front
defput_at_index

class wavelink.BaseQueue#

clear() → None#: Remove all items from the queue.

copy()#: Create a copy of the current queue including its members.

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.

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 queue.

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.

put(item: wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack) → None#: Put the given item into the back of the queue.

put_at_front(item: wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack) → None#: Put the given item into the front of 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.

property count: int#: Returns queue member count.

property is_empty: bool#: Returns True if queue has no members.

Attributes

loop
loop_all

Methods

defget
asyncget_wait
asyncput_wait
defreset

class wavelink.Queue#

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

Return next immediately available item in queue if any.

Raises QueueEmpty if no items in queue.

coroutine 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.

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

This function is a coroutine.

Put an item into the queue using await.

reset() → None#: Clears the state of all 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

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

Exceptions#

exception wavelink.WavelinkException#

exception wavelink.AuthorizationFailed#

exception wavelink.InvalidNode#

exception wavelink.InvalidLavalinkVersion#

exception wavelink.InvalidLavalinkResponse#

exception wavelink.NoTracksError#

exception wavelink.QueueEmpty#