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.

For example:

An event listener in a cog…

@commands.Cog.listener()
async def on_wavelink_node_ready(node: Node):
    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_websocket_closed(player: Player, reason, code)#: Called when the Node websocket has been closed by Lavalink.

wavelink.on_wavelink_track_start(player: Player, track: Track)#: Called when a track starts playing.

wavelink.on_wavelink_track_end(player: player, track: Track, reason)#: Called when the current track has finished playing.

wavelink.on_wavelink_track_exception(player: Player, track: Track, error)#: Called when a TrackException occurs in Lavalink.

wavelink.on_wavelink_track_stuck(player: Player, track: Track, threshold)#: Called when a TrackStuck occurs in Lavalink.

Abstract Base Classes#

class wavelink.abc.Playable(id: str, info: Dict[str, Any])#

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

id#

The base64 identifier for this object.

Type: str

info#

The raw data supplied by Lavalink.

Type: Dict[str, Any]

length#: The duration of the track.

duration#: Alias to length.

class wavelink.abc.Searchable#

class wavelink.abc.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

nodes

Methods

clsNodePool.create_node
clsNodePool.get_node

class wavelink.NodePool#

Wavelink NodePool class.

This class holds all the Node objects created with create_node().

classmethod coroutine create_node(*, bot: discord.Client, host: str, port: int, password: str, https: bool = False, heartbeat: float = 30, region: Optional[discord.VoiceRegion] = None, spotify_client: Optional[spotify.SpotifyClient] = None, identifier: str = MISSING, dumps: Callable[[Any], str] = <function dumps>, resume_key: Optional[str] = None) → Node#

This function is a coroutine.

Classmethod that creates a Node object and stores it for use with WaveLink.

Parameters

bot (Union[discord.Client]) – The discord.py Bot or Client class.
host (str) – The lavalink host address.
port (int) – The lavalink port.
password (str) – The lavalink password for authentication.
https (bool) – Connect to lavalink over https. Defaults to False.
heartbeat (float) – The heartbeat in seconds for the node. Defaults to 30 seconds.
region (Optional[discord.VoiceRegion]) – The discord.py VoiceRegion to assign to the node. This is useful for node region balancing.
spotify_client (Optional[wavelink.ext.spotify.SpotifyClient]) – An optional SpotifyClient with credentials to use when searching for spotify tracks.
identifier (str) – The unique identifier for this Node. By default this will be generated for you.

Returns

The WaveLink Node object.

Return type

Node

classmethod get_node(*, identifier: str = MISSING, region: discord.VoiceRegion = MISSING) → Node#

Retrieve a Node from the NodePool.

Parameters

identifier (str) – If provided this method will attempt to return the Node with the provided identifier.
region (discord.VoiceRegion) – If provided this method will attempt to find the best Node with the provided region.

Returns

The WaveLink Node object.

Return type

Node

Raises

ZeroConnectedNodes – There are no currently connected Nodes on the pool with the provided options.
NoMatchingNode – No Node exists with the provided identifier.

property nodes: Dict[str, Node]#: A mapping of created Node objects.

Node#

Attributes

bot
host
identifier
penalty
players
port
region

Methods

asyncbuild_track
asyncdisconnect
defget_player
asyncget_playlist
asyncget_tracks
defis_connected

class wavelink.Node(bot: discord.Client, host: str, port: int, password: str, https: bool, heartbeat: float, region: Optional[discord.VoiceRegion], spotify: Optional[spotify.SpotifyClient], identifier: str, dumps: Callable[[Any], str], resume_key: Optional[str])#

WaveLink Node object.

bot#

The discord.py Bot object.

Type: discord.Client

Warning

This class should not be created manually. Please use NodePool.create_node() instead.

coroutine build_track(cls: Type[PT], identifier: str) → PT#

This function is a coroutine.

Build a track object with a valid track identifier.

Parameters

cls (Type[abc.Playable]) – The type of which track should be returned, this must subclass abc.Playable.
identifier (str) – The tracks unique Base64 encoded identifier. This is usually retrieved from various lavalink events.

Returns

The track built from a Base64 identifier.

Return type

abc.Playable

Raises

BuildTrackError – Decoding and building the track failed.

coroutine disconnect(*, force: bool = False) → None#

Disconnect this Node and remove it from the NodePool.

This is a graceful shutdown of the node.

get_player(guild: discord.Guild) → Optional[Player]#

Returns a Player object playing in a specific discord.Guild.

Parameters: guild (discord.Guild) – The Guild the player is in.
Returns
Return type: Optional[Player]

coroutine get_playlist(cls: Type[PLT], identifier: str) → Optional[PLT]#

This function is a coroutine.

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

Parameters

cls (Type[abc.Playlist]) – The type of which playlist should be returned, this must subclass abc.Playlist.
identifier (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[abc.Playlist]

Raises

LoadTrackError – Loading the playlist failed.
LavalinkException – An unspecified error occurred when loading the playlist.

coroutine get_tracks(cls: Type[PT], query: str) → List[PT]#

This function is a coroutine.

Search for and return a list of abc.Playable for a given query.

Parameters

cls (Type[abc.Playable]) – The type of which track should be returned, this must subclass abc.Playable.
query (str) – A query to use to search for tracks.

Returns

A list of wavelink track objects.

Return type

List[abc.Playable]

Raises

LoadTrackError – Loading the track failed.
LavalinkException – An unspecified error occurred when loading the track.

is_connected() → bool#: Bool indicating whether or not this Node is currently connected to Lavalink.

property host: str#: The host this node is connected to.

property identifier: str#: The Nodes unique identifier.

property penalty: float#: The load-balancing penalty for this node.

property players: List[Player]#: A list of currently connected Players.

property port: int#: The port this node is connected to.

property region: Optional[discord.VoiceRegion]#: The voice region of the Node.

Tracks#

Track#

Attributes

author
duration
id
identifier
info
length
title
uri

Methods

defis_stream

class wavelink.Track(id: str, info: dict)#

A Lavalink track object.

id#

The Base64 Track ID, can be used to rebuild track objects.

Type: str

info#

The raw track info.

Type: Dict[str, Any]

title#

The track title.

Type: str

identifier#

The tracks identifier. could be None depending on track type.

Type: Optional[str]

length#: The duration of the track in seconds.

duration#: Alias to length.

uri#

The tracks URI. Could be None.

Type: Optional[str]

author#

The author of the track. Could be None

Type: Optional[str]

is_stream() → bool#: Indicates whether the track is a stream or not.

SearchableTrack#

Methods

clsSearchableTrack.convert
clsSearchableTrack.search

class wavelink.SearchableTrack(id: str, info: dict)#

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 coroutine search(query: str, *, node: Node = MISSING, type: spotify.SpotifySearchType = None, return_first: Literal[False] = False) → List[ST]#

classmethod coroutine search(query: str, *, node: Node = MISSING, type: spotify.SpotifySearchType = None, return_first: Literal[True] = False) → Optional[ST]

classmethod coroutine search(query: str, *, node: Node = MISSING, return_first: Literal[False] = False) → List[ST]

classmethod coroutine search(query: str, *, node: Node = MISSING, return_first: Literal[True] = False) → Optional[ST]

This function is a coroutine.

Search for tracks with the given query.

Parameters

query (str) – The song to search for.
spotify_type (Optional[spotify.SpotifySearchType]) – An optional enum value to use when searching with Spotify.
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. Use this as True, when searching with LocalTrack.

Returns

Return type

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

YouTubeTrack#

Attributes

thumb
thumbnail

class wavelink.YouTubeTrack(id: str, info: dict)#

A track created using a search to YouTube.

property thumb: str#: The URL to the thumbnail of this video.

property thumbnail: str#: The URL to the thumbnail of this video.

YouTubeMusicTrack#

class wavelink.YouTubeMusicTrack(id: str, info: dict)#: A track created using a search to YouTube Music.

SoundCloudTrack#

class wavelink.SoundCloudTrack(id: str, info: dict)#: 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]

PartialTrack#

class wavelink.PartialTrack(*, query: str, node: ~typing.Optional[~wavelink.pool.Node] = MISSING, cls: ~typing.Optional[~wavelink.tracks.SearchableTrack] = <class 'wavelink.tracks.YouTubeTrack'>)#

A PartialTrack object that searches for the given query at playtime.

Parameters

query (str) – The query to search for at playtime.
node (Optional[wavelink.Node]) – An optional node to use when searching. Defaults to the best node.
cls (Optional[SearchableTrack]) – An optional Non-Partial Track object to use when searching.

Warning

This object will only search for the given query at playtime. Full track information will be missing until it has been searched.

LocalTrack#

class wavelink.LocalTrack(id: str, info: dict)#: Represents a Lavalinkl Local Track Object.

Player#

Attributes

guild
position
source
track
user

Methods

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

class wavelink.Player(client: Client = MISSING, channel: Union[VoiceChannel, StageChannel] = MISSING, *, node: Node = MISSING)#

WaveLink Player object.

This class subclasses discord.VoiceProtocol and such should be treated as one with additions.

Examples

@commands.command()
async def connect(self, channel: discord.VoiceChannel):

    voice_client = await channel.connect(cls=wavelink.Player)

Warning

This class should not be created manually but can be subclassed to add additional functionality. You should instead use discord.VoiceChannel.connect() and pass the player object to the cls kwarg.

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(*, force: bool = False) → None#

This function is a coroutine.

An abstract method called when the client terminates the connection.

See cleanup().

Parameters: force (bool) – Whether the disconnection was forced.

is_connected() → bool#: Indicates whether the player is connected to voice.

is_paused() → bool#: Indicates whether the currently playing track is paused.

is_playing() → bool#: Indicates whether a track is currently being played.

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: Dict[str, Any]) → 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: Dict[str, Any]) → 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 if it was playing.

coroutine play(source: Playable, replace: bool = True, start: Optional[int] = None, end: Optional[int] = None, volume: Optional[int] = None, pause: Optional[bool] = None)#

This function is a coroutine.

Play a WaveLink Track.

Parameters

source (abc.Playable) – The abc.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.
pause (bool) – Changes the players pause state. Defaults to None which will not change the pause state.

Returns

The track that is now playing.

Return type

wavelink.abc.Playable

coroutine resume() → None#

This function is a coroutine.

Resumes the player if it was paused.

coroutine seek(position: int = 0) → None#

This function is a coroutine.

Seek to the given position in the song.

Parameters: position (int) – The position as an int in milliseconds to seek to.

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_pause(pause: bool) → None#

This function is a coroutine.

Set the players paused state.

Parameters: pause (bool) – A bool indicating if the player’s paused state should be set to True or False.

coroutine set_volume(volume: int) → None#

This function is a coroutine.

Sets the player’s volume. Accepts an int between 0 and 1000 where 100 means 100% volume.

Parameters: volume (int) – The volume to set the player to.

coroutine stop() → None#

This function is a coroutine.

Stop the Player’s currently playing song.

property guild: Guild#: The discord.Guild this Player is in.

property position: float#: The current seek position of the playing source in seconds. If nothing is playing this defaults to 0.

property source: Optional[Playable]#: The currently playing audio source.

property track: Optional[Playable]#: The currently playing audio source.

property user: ClientUser#: The discord.ClientUser of the discord.Client

Queues#

Attributes

count
is_empty
is_full

Methods

defclear
defcopy
defextend
deffind_position
defget
defpop
defput
defput_at_front
defput_at_index

class wavelink.Queue(max_size: ~typing.Optional[int] = None, *, overflow: bool = True, queue_cls: ~typing.Type[~wavelink.queue.QT] = <class 'collections.deque'>)#

Basic Queue implementation for Playable objects.

Warning

This Queue class only accepts Playable objects. E.g YouTubeTrack, SoundCloudTrack.

Parameters: max_size (Optional[int]) – The maximum allowed tracks in the Queue. If None, no maximum is used. Defaults to None.

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

copy() → Queue#: Create a copy of the current queue including it’s members.

extend(iterable: Iterable[Playable], *, 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.

When overflow is enabled for the queue, atomic=True won’t prevent dropped items.

find_position(item: Playable) → int#

Find the position a given item within the queue.

Raises ValueError if item is not in queue.

get() → Playable#

Return next immediately available item in queue if any.

Raises QueueEmpty if no items in queue.

pop() → Playable#

Return item from the right end side of the queue.

Raises QueueEmpty if no items in queue.

put(item: Playable) → None#: Put the given item into the back of the queue.

put_at_front(item: Playable) → None#: Put the given item into the front of the queue.

put_at_index(index: int, item: Playable) → 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.

property is_full: bool#: Returns True if queue item count has reached max_size.

Attributes

history

Methods

asyncget_wait
asyncput_wait
defreset

class wavelink.WaitQueue(max_size: Optional[int] = None, history_max_size: Optional[int] = None, history_cls=wavelink.queue.Queue[~QT])#

Queue for Playable objects designed for Players that allow waiting for new items with get_wait.

Note

WaitQueue is the default Player queue.

history#

A history Queue of previously played tracks.

Type: Queue

coroutine get_wait() → Playable#

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: Playable) → None#

This function is a coroutine.

Put an item into the queue using await.

reset() → None#: Clears the state of all queues.

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.

Parameters

filter (wavelink.Filter) – An instance of this filter class.
equalizer (wavelink.Equalizer) – An equalizer to apply to the track.
karaoke (wavelink.Karaoke) – A karaoke filter to apply to the track.
timescale (wavelink.Timescale) – A timescale filter to apply to the track.
tremolo (wavelink.Tremolo) – A tremolo filter to apply to the track.
vibrato (wavelink.Vibrato) – A vibrato filter to apply to the track.
rotation (wavelink.Rotation) – A rotation filter to apply to the track.
distortion (wavelink.Distortion) – A distortion filter to apply to the track.
channel_mix (wavelink.ChannelMix) – A channel mix filter to apply to the track.
low_pass (wavelink.LowPass) – A low pass filter to apply to the track.

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 boost() → Equalizer#: A boost equalizer.

classmethod flat() → Equalizer#: A flat 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.

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 full_left() → ChannelMix#: Returns a ChannelMix filter that will play the tracks left and right channels together only on the left 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 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 only_right() → ChannelMix#: Returns a ChannelMix filter that will only play the tracks 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.WavelinkError#

exception wavelink.AuthorizationFailure#

exception wavelink.LavalinkException#

exception wavelink.LoadTrackError#

exception wavelink.BuildTrackError#

exception wavelink.NodeOccupied#

exception wavelink.InvalidIDProvided#

exception wavelink.ZeroConnectedNodes#

exception wavelink.NoMatchingNode#

exception wavelink.QueueException#

exception wavelink.QueueFull#

exception wavelink.QueueEmpty#