API Reference#

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

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.

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 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[wavelink.Node]) – The node to use when searching for tracks. If no wavelink.Node is passed, one will be fetched via the wavelink.NodePool.

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

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

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

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 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: bool = False, node: Node | None = None) → Self | list[Self]#

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[wavelink.Node]) – The node to use when searching for tracks. If no wavelink.Node is passed, one will be fetched via the wavelink.NodePool.

YouTubeTrack#

Attributes
Methods
class wavelink.YouTubeTrack(data: TrackPayload)#
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.

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

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

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[wavelink.Node]) – The node to use when searching for tracks. If no wavelink.Node is passed, one will be fetched via the wavelink.NodePool.

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#

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

A track created using a search to YouTube Music.

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.

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

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

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[wavelink.Node]) – The node to use when searching for tracks. If no wavelink.Node is passed, one will be fetched via the wavelink.NodePool.

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 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: bool = False, node: Node | None = None) → Self | list[Self]#

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[wavelink.Node]) – The node to use when searching for tracks. If no wavelink.Node is passed, one will be fetched via the wavelink.NodePool.

YouTubePlaylist#

Attributes
Methods
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]

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: bool = False, node: Node | None = None) → Self | list[Self]#

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[wavelink.Node]) – The node to use when searching for tracks. If no wavelink.Node is passed, one will be fetched via the wavelink.NodePool.

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.

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

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_connected() → bool#

Whether the player is connected to a voice channel.

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 voice server update payload.

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 voice state payload.

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

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

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