API Reference#

The wavelink 3 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 discord.py listener syntax. All Track Events receive the appropriate payload.

For example:

An event listener in a cog.

@commands.Cog.listener()
async def on_wavelink_node_ready(self, payload: wavelink.NodeReadyEventPayload) -> None:
    print(f"Node {payload.node!r} is ready!")

wavelink.on_wavelink_node_ready(payload: wavelink.NodeReadyEventPayload)#: Called when the Node you are connecting to has initialised and successfully connected to Lavalink. This event can be called many times throughout your bots lifetime, as it will be called when Wavelink successfully reconnects to your node in the event of a disconnect.

wavelink.on_wavelink_stats_update(payload: wavelink.StatsEventPayload)#: Called when the stats OP is received by Lavalink.

wavelink.on_wavelink_player_update(payload: wavelink.PlayerUpdateEventPayload)#: Called when the playerUpdate OP is received from Lavalink. This event contains information about a specific connected player on the node.

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

Note

It is preferred to use this method when sending feedback about the now playing track etc.

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

Warning

If you are using AutoPlay, please make sure you take this into consideration when using this event. See: on_wavelink_track_start() for an event for performing logic when a new track starts playing.

wavelink.on_wavelink_track_exception(payload: wavelink.TrackExceptionEventPayload)#: Called when an exception occurs while playing a track.

wavelink.on_wavelink_track_stuck(payload: wavelink.TrackStuckEventPayload)#: Called when a track gets stuck while playing.

wavelink.on_wavelink_websocket_closed(payload: wavelink.WebsocketClosedEventPayload)#: Called when the websocket to the voice server is closed.

wavelink.on_wavelink_node_closed(node: wavelink.Node, disconnected: list[wavelink.Player])#: Called when a node has been closed and cleaned-up. The second parameter disconnected is a list of wavelink.Player that were connected on this Node and are now disconnected.

wavelink.on_wavelink_extra_event(payload: wavelink.ExtraEventPayload)#: Called when an Unknown and/or Unhandled event is recevied via Lavalink. This is most likely due to a plugin like SponsorBlock sending custom event data. The payload includes the raw data sent from Lavalink.

Note

Please see the documentation for your Lavalink plugins to determine what data they send.

New in version: 3.1.0

wavelink.on_wavelink_inactive_player(player: wavelink.Player)#

Triggered when the inactive_timeout countdown expires for the specific Player.

See: inactive_timeout
See: Node for setting a default on all players.

Examples#

Basic Usage:

@commands.Cog.listener()
async def on_wavelink_inactive_player(self, player: wavelink.Player) -> None:
    await player.channel.send(f"The player has been inactive for `{player.inactive_timeout}` seconds. Goodbye!")
    await player.disconnect()

New in version: 3.2.0

Types#

class wavelink.Search#

A type hint used when searching tracks. Used in Playable.search() and Pool.fetch_tracks()

Example:

tracks: wavelink.Search = await wavelink.Playable.search("Ocean Drive")

Payloads#

Attributes

node
resumed
session_id

class wavelink.NodeReadyEventPayload(node: Node, resumed: bool, session_id: str)#

Payload received in the on_wavelink_node_ready() event.

node#

The node that has connected or reconnected.

Type: Node

resumed#

Whether this node was successfully resumed.

Type: bool

session_id#

The session ID associated with this node.

Type: str

Attributes

original
player
track

class wavelink.TrackStartEventPayload(player: Player | None, track: Playable)#

Payload received in the on_wavelink_track_start() event.

player#

The player associated with this event. Could be None.

Type: Player | None

track#

The track received from Lavalink regarding this event.

Type: Playable

original#

The original track associated this event. E.g. the track that was passed to play() or inserted into the queue, with all your additional attributes assigned. Could be None.

Type: Playable | None

Attributes

original
player
reason
track

class wavelink.TrackEndEventPayload(player: Player | None, track: Playable, reason: str)#

Payload received in the on_wavelink_track_end() event.

player#

The player associated with this event. Could be None.

Type: Player | None

track#

The track received from Lavalink regarding this event.

Type: Playable

reason#

The reason Lavalink ended this track.

Type: str

original#

The original track associated this event. E.g. the track that was passed to play() or inserted into the queue, with all your additional attributes assigned. Could be None.

Type: Playable | None

Attributes

exception
player
track

class wavelink.TrackExceptionEventPayload(player: Player | None, track: Playable, exception: TrackExceptionPayload)#

Payload received in the on_wavelink_track_exception() event.

player#

The player associated with this event. Could be None.

Type: Player | None

track#

The track received from Lavalink regarding this event.

Type: Playable

exception#

The exception data received via Lavalink.

Type: TrackExceptionPayload

Attributes

player
threshold
track

class wavelink.TrackStuckEventPayload(player: Player | None, track: Playable, threshold: int)#

Payload received in the on_wavelink_track_stuck() event.

player#

The player associated with this event. Could be None.

Type: Player | None

track#

The track received from Lavalink regarding this event.

Type: Playable

threshold#

The Lavalink threshold associated with this event.

Type: int

Attributes

by_remote
code
player
reason

class wavelink.WebsocketClosedEventPayload(player: Player | None, code: int, reason: str, by_remote: bool)#

Payload received in the on_wavelink_websocket_closed() event.

player#

The player associated with this event. Could be None.

Type: Player | None

code#

The close code enum value.

Type: wavelink.DiscordVoiceCloseType

reason#

The reason the websocket was closed.

Type: str

by_remote#

True if discord closed the websocket. False otherwise.

Type: bool

Attributes

connected
ping
player
position
time

class wavelink.PlayerUpdateEventPayload(player: Player | None, state: PlayerState)#

Payload received in the on_wavelink_player_update() event.

player#

The player associated with this event. Could be None.

Type: Player | None

time#

Unix timestamp in milliseconds, when this event fired.

Type: int

position#

The position of the currently playing track in milliseconds.

Type: int

connected#

Whether Lavalink is connected to the voice gateway.

Type: bool

ping#

The ping of the node to the Discord voice server in milliseconds (-1 if not connected).

Type: int

Attributes

cpu
frames
memory
players
playing
uptime

class wavelink.StatsEventPayload(data: StatsOP)#

Payload received in the on_wavelink_stats_update() event.

players#

The amount of players connected to the node (Lavalink).

Type: int

playing#

The amount of players playing a track.

Type: int

uptime#

The uptime of the node in milliseconds.

Type: int

memory#

Enums#

Attributes

CONNECTED
CONNECTING
DISCONNECTED

class wavelink.NodeStatus(value)#

Enum representing the connection status of a Node.

DISCONNECTED#: The Node has been disconnected or has never been connected previously.

CONNECTING#: The Node is currently attempting to connect.

CONNECTED#: The Node is currently connected.

Attributes

SoundCloud
YouTube
YouTubeMusic

class wavelink.TrackSource(value)#

Enum representing a Playable source.

YouTube#: A source representing a track that comes from YouTube.

YouTubeMusic#: A source representing a track that comes from YouTube Music.

SoundCloud#: A source representing a track that comes from SoundCloud.

Attributes

ALREADY_AUTHENTICATED
AUTHENTICATION_FAILED
CLOSE_NORMAL
DISCONNECTED
FAILED_DECODE_PAYLOAD
NOT_AUTHENTICATED
SERVER_NOT_FOUND
SESSION_INVALID
SESSION_TIMEOUT
UNKNOWN_ENCRYPTION_MODE
UNKNOWN_OPCODE
UNKNOWN_PROTOCOL
VOICE_SERVER_CRASHED

class wavelink.DiscordVoiceCloseType(value)#

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

Attributes

disabled
enabled
partial

class wavelink.AutoPlayMode(value)#

Enum representing the various AutoPlay modes.

enabled#: When enabled, AutoPlay will work fully autonomously and fill the auto_queue with recommended tracks. If a song is put into a players standard queue, AutoPlay will use it as a priority.

partial#: When partial, AutoPlay will work fully autonomously but will not fill the auto_queue with recommended tracks.

disabled#: When disabled, AutoPlay will not do anything automatically.

Attributes

loop
loop_all
normal

class wavelink.QueueMode(value)#

Enum representing the various modes on wavelink.Queue

normal#: When set, the queue will not loop either track or history. This is the default.

loop#: When set, the track will continuously loop.

loop_all#: When set, the queue will continuously loop through all tracks.

Pool#

Methods

clsPool.close
clsPool.connect
clsPool.fetch_tracks
clsPool.get_node

class wavelink.Pool#

The wavelink Pool represents a collection of Node and helper methods for searching tracks.

To connect a Node please use this Pool.

Note

All methods and attributes on this class are class level, not instance. Do not create an instance of this class.

classmethod await connect(*, nodes: Iterable[Node], client: discord.Client | None = None, cache_capacity: int | None = None) → dict[str, Node]#

Connect the provided Iterable[Node] to Lavalink.

Parameters

nodes (Iterable[Node]) – The Node’s to connect to Lavalink.
client (discord.Client | None) – The discord.Client to use to connect the Node. If the Node already has a client set, this method will not override it. Defaults to None.
cache_capacity (int | None) – An optional integer of the amount of track searches to cache. This is an experimental mode. Passing None will disable this experiment. Defaults to None.

Returns

A mapping of Node.identifier to Node associated with the Pool.

Return type

dict[str, Node]

Raises

AuthorizationFailedException – The node password was incorrect.
InvalidClientException – The discord.Client passed was not valid.
NodeException – The node failed to connect properly. Please check that your Lavalink version is version 4.

Version changed: 3.0.0 - The client parameter is no longer required. Added the cache_capacity parameter.

classmethod await close() → None#

Close and clean up all Node on this Pool.

This calls wavelink.Node.close() on each node.

New in version: 3.0.0

classmethod get_node(identifier: Optional[str] = None, /) → Node#

Retrieve a Node from the Pool with the given identifier.

If no identifier is provided, this method returns the best node.

Parameters: identifier (str | None) – An optional identifier to retrieve a Node.
Raises: InvalidNodeException – Raised when a Node can not be found, or no Node exists on the Pool.

Version changed: 3.0.0 - The id parameter was changed to identifier and is positional only.

classmethod await fetch_tracks(query: str, /, *, node: Optional[Node] = None) → list[wavelink.tracks.Playable] | wavelink.tracks.Playlist#

Search for a list of Playable or a Playlist, with the given query.

Parameters

query (str) – The query to search tracks for. If this is not a URL based search you should provide the appropriate search prefix, e.g. “ytsearch:Rick Roll”
node (Node | None) – An optional Node to use when fetching tracks. Defaults to None, which selects the most appropriate Node automatically.

Returns

A list of Playable or a Playlist based on your search query. Could be an empty list, if no tracks were found.

Return type

list[Playable] | Playlist

Raises

LavalinkLoadException – Exception raised when Lavalink fails to load results based on your query.

Version changed: 3.0.0 - This method was previously known as both .get_tracks and .get_playlist. This method now searches for both Playable and Playlist and returns the appropriate type, or an empty list if no results were found. This method no longer accepts the cls parameter.

New in version: 3.4.0 - Added the node Keyword-Only argument.

Node#

Attributes

client
headers
heartbeat
identifier
password
players
session_id
status
uri

Methods

asyncclose
asyncfetch_info
asyncfetch_player_info
asyncfetch_players
asyncfetch_stats
asyncfetch_version
defget_player
asyncsend

class wavelink.Node(*, identifier: str | None = None, uri: str, password: str, session: aiohttp.ClientSession | None = None, heartbeat: float = 15.0, retries: int | None = None, client: discord.Client | None = None, resume_timeout: int = 60, inactive_player_timeout: int | None = 300, inactive_channel_tokens: int | None = 3)#

The Node represents a connection to Lavalink.

The Node is responsible for keeping the websocket alive, resuming session, sending API requests and keeping track of connected all Player.

node == other: Equality check to determine whether this Node is equal to another reference of a Node.

repr(node): The official string representation of this Node.

Parameters

identifier (str | None) – A unique identifier for this Node. Could be None to generate a random one on creation.
uri (str) – The URL/URI that wavelink will use to connect to Lavalink. Usually this is in the form of something like: http://localhost:2333 which includes the port. But you could also provide a domain which won’t require a port like https://lavalink.example.com or a public IP address and port like http://111.333.444.55:2333.
password (str) – The password used to connect and authorize this Node.
session (aiohttp.ClientSession | None) – An optional aiohttp.ClientSession used to connect this Node over websocket and REST. If None, one will be generated for you. Defaults to None.
heartbeat (Optional[float]) – A float in seconds to ping your websocket keep alive. Usually you would not change this.
retries (int | None) – A int of retries to attempt when connecting or reconnecting this Node. When the retries are exhausted the Node will be closed and cleaned-up. None will retry forever. Defaults to None.
client (discord.Client | None) – The discord.Client or subclasses, E.g. commands.Bot used to connect this Node. If this is not passed you must pass this to wavelink.Pool.connect().
resume_timeout (Optional[int]) – The seconds this Node should configure Lavalink for resuming its current session in case of network issues. If this is 0 or below, resuming will be disabled. Defaults to 60.
inactive_player_timeout (int | None) – Set the default for wavelink.Player.inactive_timeout on every player that connects to this node. Defaults to 300.
inactive_channel_tokens (int | None) –
Sets the default for wavelink.Player.inactive_channel_tokens on every player that connects to this node. Defaults to 3.

See also: on_wavelink_inactive_player().

property headers: dict[str, str]#: A property that returns the headers configured for sending API and websocket requests.

Warning

This includes your Node password. Please be vigilant when using this property.

property identifier: str#: The unique identifier for this Node.

Version changed: 3.0.0 - This property was previously known as id.

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

property status: NodeStatus#

The current Node status.

Refer to: NodeStatus

property players: dict[int, Player]#: A mapping of discord.Guild.id to Player.

Version changed: 3.1.1 - This property now returns a shallow copy of the internal mapping.

property client: discord.Client | None#

Returns the discord.Client associated with this Node.

Could be None if it has not been set yet.

New in version: 3.0.0

property password: str#: Returns the password used to connect this Node to Lavalink.

New in version: 3.0.0

property heartbeat: float#: Returns the duration in seconds that the Node websocket should send a heartbeat.

New in version: 3.0.0

property session_id: str | None#: Returns the Lavalink session ID. Could be None if this Node has not connected yet.

New in version: 3.0.0

await close(eject: bool = False) → None#

Method to close this Node and cleanup.

After this method has finished, the event on_wavelink_node_closed will be fired.

This method renders the Node websocket disconnected and disconnects all players.

Parameters: eject (bool) – If True, this will remove the Node from the Pool. Defaults to False.

Version changed: 3.2.1 - Added the eject parameter. Fixed a bug where the connected Players were not being disconnected.

await send(method: Literal['GET', 'POST', 'PATCH', 'DELETE', 'PUT', 'OPTIONS'] = 'GET', *, path: str, data: Optional[Any] = None, params: Optional[dict[str, Any]] = None) → Any#

Method for making requests to the Lavalink node.

Warning

Usually you wouldn’t use this method. Please use the built in methods of Node, Pool and Player, unless you need to send specific plugin data to Lavalink.

Using this method may have unwanted side effects on your players and/or nodes.

Parameters

method (Optional[str]) – The method to use when making this request. Available methods are “GET”, “POST”, “PATCH”, “PUT”, “DELETE” and “OPTIONS”. Defaults to “GET”.
path (str) – The path to make this request to. E.g. “/v4/stats”.
data (Any | None) – The optional JSON data to send along with your request to Lavalink. This should be a dict[str, Any] and able to be converted to JSON.
params (Optional[dict[str, Any]]) – An optional dict of query parameters to send with your request to Lavalink. If you include your query parameters in the path parameter, do not pass them here as well. E.g. {“thing”: 1, “other”: 2} would equate to “?thing=1&other=2”.

Returns

The response from Lavalink which will either be None, a str or JSON.

Return type

Any

Raises

LavalinkException – An error occurred while making this request to Lavalink.
NodeException – An error occured while making this request to Lavalink, and Lavalink was unable to send any error information.

New in version: 3.0.0

await fetch_players() → list[wavelink.payloads.PlayerResponsePayload]#

Method to fetch the player information Lavalink holds for every connected player on this node.

Warning

This payload is not the same as the wavelink.Player class. This is the data received from Lavalink about the players.

Returns

A list of PlayerResponsePayload representing each player connected to this node.

Return type

list[PlayerResponsePayload]

Raises

LavalinkException – An error occurred while making this request to Lavalink.
NodeException – An error occured while making this request to Lavalink, and Lavalink was unable to send any error information.

New in version: 3.1.0

await fetch_player_info(guild_id: int, /) → wavelink.payloads.PlayerResponsePayload | None#

Method to fetch the player information Lavalink holds for the specific guild.

Warning

This payload is not the same as the wavelink.Player class. This is the data received from Lavalink about the player. See: get_player()

Parameters

guild_id (int) – The ID of the guild you want to fetch info for.

Returns

The PlayerResponsePayload representing the player info for the guild ID connected to this node. Could be None if no player is found with the given guild ID.

Return type

PlayerResponsePayload | None

Raises

LavalinkException – An error occurred while making this request to Lavalink.
NodeException – An error occured while making this request to Lavalink, and Lavalink was unable to send any error information.

New in version: 3.1.0

await fetch_info() → InfoResponsePayload#

Method to fetch this Lavalink Nodes info response data.

Returns

The InfoResponsePayload associated with this Node.

Return type

InfoResponsePayload

Raises

LavalinkException – An error occurred while making this request to Lavalink.
NodeException – An error occured while making this request to Lavalink, and Lavalink was unable to send any error information.

New in version: 3.1.0

await fetch_stats() → StatsResponsePayload#

Method to fetch this Lavalink Nodes stats response data.

Returns

The StatsResponsePayload associated with this Node.

Return type

StatsResponsePayload

Raises

LavalinkException – An error occurred while making this request to Lavalink.
NodeException – An error occured while making this request to Lavalink, and Lavalink was unable to send any error information.

New in version: 3.1.0

await fetch_version() → str#

Method to fetch this Lavalink version string.

Returns

The version string associated with this Lavalink node.

Return type

str

Raises

LavalinkException – An error occurred while making this request to Lavalink.
NodeException – An error occured while making this request to Lavalink, and Lavalink was unable to send any error information.

New in version: 3.1.0

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

Return a Player associated with the provided discord.Guild.id.

Parameters: guild_id (int) – The discord.Guild.id to retrieve a Player for.
Returns: The Player associated with this guild ID. Could be None if no Player exists for this guild.
Return type: Optional[Player]

Tracks#

Tracks in wavelink 3 have been simplified. Please read the docs for Playable. Additionally the following data classes are provided on every Playable.

Attributes

artwork
url

class wavelink.Artist(*, data: dict[Any, Any])#

Container class representing Artist data received via Lavalink.

url#

The artist url. Could be None.

Type: str | None

artwork#

The artist artwork url. Could be None.

Type: str | None

Attributes

name
url

class wavelink.Album(*, data: dict[Any, Any])#

Container class representing Album data received via Lavalink.

name#

The album name. Could be None.

Type: str | None

url#

The album url. Could be None.

Type: str | None

Playable#

Attributes

album
artist
artwork
author
encoded
extras
identifier
is_preview
is_seekable
is_stream
isrc
length
playlist
position
preview_url
raw_data
recommended
source
title
uri

Methods

clsPlayable.search

class wavelink.Playable(data: TrackPayload, *, playlist: PlaylistInfo | None = None)#

The Wavelink Playable object which represents all tracks in Wavelink 3.

Note

You should not construct this class manually.

str(track): The title of this playable.

repr(track): The official string representation of this playable.

track == other: Whether this track is equal to another. Checks both the track encoding and identifier.

property encoded: str#: Property returning the encoded track string from Lavalink.

property identifier: str#

Property returning the identifier of this track from its source.

E.g. YouTube ID or Spotify ID.

property is_seekable: bool#: Property returning a bool whether this track can be used in seeking.

property author: str#: Property returning the name of the author of this track.

property length: int#: Property returning the tracks duration in milliseconds as an int.

property is_stream: bool#: Property returning a bool indicating whether this track is a stream.

property position: int#: Property returning starting position of this track in milliseconds as an int.

property title: str#: Property returning the title/name of this track.

property uri: str | None#: Property returning the URL to this track. Could be None.

property artwork: str | None#: Property returning the URL of the artwork of this track. Could be None.

property isrc: str | None#: Property returning the ISRC (International Standard Recording Code) of this track. Could be None.

property source: str#

Property returning the source of this track as a str.

E.g. “spotify” or “youtube”.

property album: Album#: Property returning album data for this track.

property artist: Artist#: Property returning artist data for this track.

property preview_url: str | None#: Property returning the preview URL for this track. Could be None.

property is_preview: bool | None#: Property returning a bool indicating if this track is a preview. Could be None if unknown.

property playlist: wavelink.tracks.PlaylistInfo | None#: Property returning a wavelink.PlaylistInfo. Could be None if this track is not a part of a playlist.

property recommended: bool#: Property returning a bool indicating whether this track was recommended via AutoPlay.

property extras: ExtrasNamespace#

Property returning a ExtrasNamespace of extras for this Playable.

You can set this property with a dict of valid str keys to any valid JSON value, or a ExtrasNamespace.

If a dict is passed, it will be converted into an ExtrasNamespace, which can be converted back to a dict with dict(…). Additionally, you can also use list or tuple on ExtrasNamespace.

The extras dict will be sent to Lavalink as the userData field.

Warning

This is only available when using Lavalink 4+ (Non BETA) versions.

Examples

track: wavelink.Playable = wavelink.Playable.search("QUERY")
track.extras = {"requester_id": 1234567890}

# later...
print(track.extras.requester_id)
# or
print(dict(track.extras)["requester_id"])

New in version: 3.1.0

property raw_data: TrackPayload#

The raw data for this Playable received via Lavalink.

You can use this data to reconstruct this Playable object.

Examples

# For example purposes...
old_data = track.raw_data

# Later...
track: wavelink.Playable = wavelink.Playable(old_data)

New in version: 3.2.0

classmethod await search(query: str, /, *, source: TrackSource | str | None = TrackSource.YouTubeMusic, node: Node | None = None) → Search#

Search for a list of Playable or a Playlist, with the given query.

Note

This method differs from wavelink.Pool.fetch_tracks() in that it will apply a relevant search prefix for you when a URL is not provided. This prefix can be controlled via the source keyword argument.

Note

This method of searching is preferred over, wavelink.Pool.fetch_tracks().

Parameters

query (str) –
The query to search tracks for. If this is not a URL based search this method will provide an appropriate search prefix based on what is provided to the source keyword only parameter, or it’s default.

If this query is a URL, a search prefix will not be used.
source (TrackSource | str | None) –
This parameter determines which search prefix to use when searching for tracks. If None is provided, no prefix will be used, however this behaviour is default regardless of what is provided when a URL is found.

For basic searches, E.g. YouTube, YouTubeMusic and SoundCloud, see: wavelink.TrackSource. Otherwise, a str may be provided for plugin based searches, E.g. “spsearch:” for the LavaSrc Spotify based search.

Defaults to wavelink.TrackSource.YouTubeMusic which is equivalent to “ytmsearch:”.
node (Node | None) – An optional Node to use when searching for tracks. Defaults to None, which uses the Pool’s automatic node selection.

Returns

A union of either list[Playable] or Playlist. Could return and empty list, if no tracks or playlist were found.

Return type

wavelink.Search

Raises

LavalinkLoadException – Exception raised when Lavalink fails to load results based on your query.

Examples

# Search for tracks, with the default "ytsearch:" prefix.
tracks: wavelink.Search = await wavelink.Playable.search("Ocean Drive")
if not tracks:
    # No tracks were found...
    ...

# Search for tracks, with a URL.
tracks: wavelink.Search = await wavelink.Playable.search("https://www.youtube.com/watch?v=KDxJlW6cxRk")
...

# Search for tracks, using Spotify and the LavaSrc Plugin.
tracks: wavelink.Search = await wavelink.Playable.search("4b93D55xv3YCH5mT4p6HPn", source="spsearch")
...

# Search for tracks, using Spotify and the LavaSrc Plugin, with a URL.
tracks: wavelink.Search = await wavelink.Playable.search("https://open.spotify.com/track/4b93D55xv3YCH5mT4p6HPn")
...

# Search for a playlist, using Spotify and the LavaSrc Plugin.
# or alternatively any other playlist URL from another source like YouTube.
tracks: wavelink.Search = await wavelink.Playable.search("https://open.spotify.com/playlist/37i9dQZF1DWXRqgorJj26U")
...

Version changed: 3.0.0 - This method has been changed significantly in version 3.0.0. This method has been simplified to provide an easier interface for searching tracks. See the above documentation and examples. You can no longer provide a wavelink.Node to use for searching as this method will now select the most appropriate node from the wavelink.Pool.

Playlists#

Attributes

artwork
author
extras
name
selected
tracks
type
url

Methods

deftrack_extras

class wavelink.Playlist(data: PlaylistPayload)#

The wavelink Playlist container class.

This class is created and returned via both Playable.search() and wavelink.Pool.fetch_tracks().

It contains various information about the playlist and a list of Playable that can be used directly in wavelink.Player.play(). See below for various supported operations.

Warning

You should not instantiate this class manually, use Playable.search() or wavelink.Pool.fetch_tracks() instead.

Warning

You can not use .search directly on this class, see: Playable.search().

Note

This class can be directly added to wavelink.Queue identical to Playable. When added, all tracks contained in this playlist, will be individually added to the wavelink.Queue.

str(x): Return the name associated with this playlist.

repr(x): Return the official string representation of this playlist.

x == y: Compare the equality of playlist.

len(x): Return an integer representing the amount of tracks contained in this playlist.

x[0]: Return a track contained in this playlist with the given index.

x[0:2]: Return a slice of tracks contained in this playlist.

for x in y: Iterate over the tracks contained in this playlist.

reversed(x): Reverse the tracks contained in this playlist.

x in y: Check if a Playable is contained in this playlist.

name#

The name of this playlist.

Type: str

selected#

The index of the selected track from Lavalink.

Type: int

tracks#

A list of Playable contained in this playlist.

Type: list[Playable]

type#

An optional str identifying the type of playlist this is. Only available when a plugin is used.

Type: str | None

url#

An optional str to the URL of this playlist. Only available when a plugin is used.

Type: str | None

artwork#

An optional str to the artwork of this playlist. Only available when a plugin is used.

Type: str | None

author#

An optional str of the author of this playlist. Only available when a plugin is used.

Type: str | None

track_extras(**attrs: object) → None#

Method which sets attributes to all Playable in this playlist, with the provided keyword arguments.

This is useful when you need to attach state to your Playable, E.g. create a requester attribute.

Warning

If you try to override any existing property of Playable this method will fail.

Parameters: **attrs – The keyword arguments to set as attribute name=value on each Playable.

Examples

playlist.track_extras(requester=ctx.author)

track: wavelink.Playable = playlist[0]
print(track.requester)

property extras: ExtrasNamespace#

Property returning a ExtrasNamespace of extras for this Playlist.

You can set this property with a dict of valid str keys to any valid JSON value, or a ExtrasNamespace.

If a dict is passed, it will be converted into an ExtrasNamespace, which can be converted back to a dict with dict(...). Additionally, you can also use list or tuple on ExtrasNamespace.

The extras dict will be sent to Lavalink as the userData field for each track in the playlist.

Warning

This is only available when using Lavalink 4+ (Non BETA) versions.

Examples

playlist: wavelink.Search = wavelink.Playable.search("QUERY")
playlist.extras = {"requester_id": 1234567890}

# later...
print(track.extras.requester_id)
# or
print(dict(track.extras)["requester_id"])

New in version: 3.2.0

Attributes

artwork
author
name
selected
tracks
type
url

class wavelink.PlaylistInfo(data: PlaylistPayload)#

The wavelink PlaylistInfo container class.

It contains various information about the playlist but does not contain the tracks associated with this playlist.

This class is used to provided information about the original wavelink.Playlist on tracks.

name#

The name of this playlist.

Type: str

selected#

The index of the selected track from Lavalink.

Type: int

tracks#

The amount of tracks this playlist originally contained.

Type: int

type#

An optional str identifying the type of playlist this is. Only available when a plugin is used.

Type: str | None

url#

An optional str to the URL of this playlist. Only available when a plugin is used.

Type: str | None

artwork#

An optional str to the artwork of this playlist. Only available when a plugin is used.

Type: str | None

author#

An optional str of the author of this playlist. Only available when a plugin is used.

Type: str | None

Player#

Attributes

auto_queue
autoplay
connected
current
filters
guild
inactive_channel_tokens
inactive_timeout
node
paused
ping
playing
position
queue
volume

Methods

asyncconnect
asyncdisconnect
asyncmove_to
asyncpause
asyncplay
asyncseek
asyncset_filters
asyncset_volume
asyncskip
asyncstop

class wavelink.Player(client: discord.Client = ..., channel: Connectable = ..., *, nodes: list[Node] | None = None)#

The Player is a discord.VoiceProtocol used to connect your discord.Client to a discord.VoiceChannel.

The player controls the music elements of the bot including playing tracks, the queue, connecting etc. See Also: The various methods available.

Note

Since the Player is a discord.VoiceProtocol, it is attached to the various voice_client attributes in discord.py, including guild.voice_client, ctx.voice_client and interaction.voice_client.

queue#

The queue associated with this player.

Type: Queue

auto_queue#

The auto_queue associated with this player. This queue holds tracks that are recommended by the AutoPlay feature.

Type: Queue

property inactive_channel_tokens: int | None#

A settable property which returns the token limit as an int of the amount of tracks to play before firing the on_wavelink_inactive_player() event when a channel is inactive.

This property could return None if the check has been disabled.

A channel is considered inactive when no real members (Members other than bots) are in the connected voice channel. On each consecutive track played without a real member in the channel, this token bucket will reduce by 1. After hitting 0, the on_wavelink_inactive_player() event will be fired and the token bucket will reset to the set value. The default value for this property is 3.

This property can be set with any valid int or None. If this property is set to <= 0 or None, the check will be disabled.

Setting this property to 1 will fire the on_wavelink_inactive_player() event at the end of every track if no real members are in the channel and you have not disconnected the player.

If this check successfully fires the on_wavelink_inactive_player() event, it will cancel any waiting inactive_timeout checks until a new track is played.

The default for every player can be set on Node.

See: Node
See: on_wavelink_inactive_player()

Warning

Setting this property will reset the bucket.

New in version: 3.4.0

property inactive_timeout: int | None#

A property which returns the time as an int of seconds to wait before this player dispatches the on_wavelink_inactive_player() event.

This property could return None if no time has been set.

An inactive player is a player that has not been playing anything for the specified amount of seconds.

Pausing the player while a song is playing will not activate this countdown.
The countdown starts when a track ends and cancels when a track starts.
The countdown will not trigger until a song is played for the first time or this property is reset.
The default countdown for all players is set on Node.

This property can be set with a valid int of seconds to wait before dispatching the on_wavelink_inactive_player() event or None to remove the timeout.

Warning

Setting this to a value of 0 or below is the equivalent of setting this property to None.

When this property is set, the timeout will reset, and all previously waiting countdowns are cancelled.

See: Node
See: on_wavelink_inactive_player()

New in version: 3.2.0

property autoplay: AutoPlayMode#

A property which returns the wavelink.AutoPlayMode the player is currently in.

This property can be set with any wavelink.AutoPlayMode enum value.

Version changed: 3.0.0 - This property now accepts and returns a wavelink.AutoPlayMode enum value.

property node: Node#: The Player’s currently selected Node.

Version changed: 3.0.0 - This property was previously known as current_node.

property guild: discord.guild.Guild | None#

Returns the Player’s associated discord.Guild.

Could be None if this Player has not been connected.

property connected: bool#: Returns a bool indicating if the player is currently connected to a voice channel.

Version changed: 3.0.0 - This property was previously known as is_connected.

property current: wavelink.tracks.Playable | None#: Returns the currently playing Playable or None if no track is playing.

property volume: int#

Returns an int representing the currently set volume, as a percentage.

See: set_volume() for setting the volume.

property filters: Filters#

Property which returns the Filters currently assigned to the Player.

See: set_filters() for setting the players filters.

Version changed: 3.0.0 - This property was previously known as filter.

property paused: bool#

Returns the paused status of the player. A currently paused player will return True.

See: pause() and play() for setting the paused status.

property ping: int#

Returns the ping in milliseconds as int between your connected Lavalink Node and Discord (Players Channel).

Returns -1 if no player update event has been received or the player is not connected.

property playing: bool#

Returns whether the Player is currently playing a track and is connected.

Due to relying on validation from Lavalink, this property may in some cases return True directly after skipping/stopping a track, although this is not the case when disconnecting the player.

This property will return True in cases where the player is paused and has a track loaded.

Version changed: 3.0.0 - This property used to be known as the is_playing() method.

property position: int#

Returns the position of the currently playing Playable in milliseconds.

This property relies on information updates from Lavalink.

In cases there is no Playable loaded or the player is not connected, this property will return 0.

This property will return 0 if no update has been received from Lavalink.

Version changed: 3.0.0 - This property now uses a monotonic clock.

await connect(*, timeout: float = 10.0, reconnect: bool, self_deaf: bool = False, self_mute: bool = False) → None#

Warning

Do not use this method directly on the player. See: discord.VoiceChannel.connect() for more details.

Pass the wavelink.Player to cls= in discord.VoiceChannel.connect().

Raises

ChannelTimeoutException – Connecting to the voice channel timed out.
InvalidChannelStateException – You tried to connect this player without an appropriate voice channel.

await move_to(channel: VocalGuildChannel | None, *, timeout: float = 10.0, self_deaf: bool | None = None, self_mute: bool | None = None) → None#

Method to move the player to another channel.

Parameters

channel (discord.VoiceChannel | discord.StageChannel) – The new channel to move to.
timeout (float) – The timeout in seconds before raising. Defaults to 10.0.
self_deaf (bool | None) – Whether to deafen when moving. Defaults to None which keeps the current setting or False if they can not be determined.
self_mute (bool | None) – Whether to self mute when moving. Defaults to None which keeps the current setting or False if they can not be determined.

Raises

ChannelTimeoutException – Connecting to the voice channel timed out.
InvalidChannelStateException – You tried to connect this player without an appropriate guild.

await play(track: Playable, *, replace: bool = True, start: int = 0, end: Optional[int] = None, volume: Optional[int] = None, paused: Optional[bool] = None, add_history: bool = True, filters: Optional[Filters] = None, populate: bool = False, max_populate: int = 5) → Playable#

Play the provided Playable.

Parameters

track (Playable) – The track to being playing.
replace (bool) – Whether this track should replace the currently playing track, if there is one. Defaults to True.
start (int) – The position to start playing the track at in milliseconds. Defaults to 0 which will start the track from the beginning.
end (Optional[int]) – The position to end the track at in milliseconds. Defaults to None which means this track will play until the very end.
volume (Optional[int]) – Sets the volume of the player. Must be between 0 and 1000. Defaults to None which will not change the current volume. See Also: set_volume()
paused (bool | None) – Whether the player should be paused, resumed or retain current status when playing this track. Setting this parameter to True will pause the player. Setting this parameter to False will resume the player if it is currently paused. Setting this parameter to None will not change the status of the player. Defaults to None.
add_history (Optional[bool]) – If this argument is set to True, the Player will add this track into the wavelink.Queue history, if loading the track was successful. If False this track will not be added to your history. This does not directly affect the AutoPlay Queue but will alter how AutoPlay recommends songs in the future. Defaults to True.
filters (Optional[Filters]) – An Optional[Filters] to apply when playing this track. Defaults to None. If this is None the currently set filters on the player will be applied.
populate (bool) –
Whether the player should find and fill AutoQueue with recommended tracks based on the track provided. Defaults to False.

Populate will only search for recommended tracks when the current tracks has been accepted by Lavalink. E.g. if this method does not raise an error.

You should consider when you use the populate keyword argument as populating the AutoQueue on every request could potentially lead to a large amount of tracks being populated.
max_populate (int) –
The maximum amount of tracks that should be added to the AutoQueue when the populate keyword argument is set to True. This is NOT the exact amount of tracks that will be added. You should set this to a lower amount to avoid the AutoQueue from being overfilled.

This argument has no effect when populate is set to False.

Defaults to 5.

Returns

The track that began playing.

Return type

Playable

Version changed: 3.0.0 - Added the paused parameter. Parameters replace, start, end, volume and paused are now all keyword-only arguments. Added the add_history keyword-only argument. Added the filters keyword-only argument.

Version changed: 3.3.0 - Added the populate keyword-only argument.

await pause(value: bool, /) → None#

Set the paused or resume state of the player.

Parameters: value (bool) – A bool indicating whether the player should be paused or resumed. True indicates that the player should be paused. False will resume the player if it is currently paused.

Version changed: 3.0.0 - This method now expects a positional-only bool value. The resume method has been removed.

await seek(position: int = 0, /) → None#

Seek to the provided position in the currently playing track, in milliseconds.

Parameters: position (int) – The position to seek to in milliseconds. To restart the song from the beginning, you can disregard this parameter or set position to 0.

Version changed: 3.0.0 - The position parameter is now positional-only, and has a default of 0.

await set_filters(filters: Optional[Filters] = None, /, *, seek: bool = False) → None#

Set the wavelink.Filters on the player.

Parameters

filters (Optional[Filters]) – The filters to set on the player. Could be None to reset the currently applied filters. Defaults to None.
seek (bool) – Whether to seek immediately when applying these filters. Seeking uses more resources, but applies the filters immediately. Defaults to False.

Version changed: 3.0.0 - This method now accepts a positional-only argument of filters, which now defaults to None. Filters were redesigned in this version, see: wavelink.Filters.

Version changed: 3.0.0 - This method was previously known as set_filter.

await set_volume(value: int = 100, /) → None#

Set the Player volume, as a percentage, between 0 and 1000.

By default, every player is set to 100 on creation. If a value outside 0 to 1000 is provided it will be clamped.

Parameters: value (int) – A volume value between 0 and 1000. To reset the player to 100, you can disregard this parameter.

Version changed: 3.0.0 - The value parameter is now positional-only, and has a default of 100.

await disconnect(**kwargs: Any) → None#

Disconnect the player from the current voice channel and remove it from the Node.

This method will cause any playing track to stop and potentially trigger the following events:

on_wavelink_track_end

on_wavelink_websocket_closed

Warning

Please do not re-use a Player instance that has been disconnected, unwanted side effects are possible.

await stop(*, force: bool = True) → wavelink.tracks.Playable | None#

An alias to skip().

See Also: skip() for more information.

Version changed: 3.0.0 - This method is now known as skip, but the alias stop has been kept for backwards compatibility.

await skip(*, force: bool = True) → wavelink.tracks.Playable | None#

Stop playing the currently playing track.

Parameters: force (bool) – Whether the track should skip looping, if wavelink.Queue has been set to loop. Defaults to True.
Returns: The currently playing track that was skipped, or None if no track was playing.
Return type: Playable | None

Version changed: 3.0.0 - This method was previously known as stop. To avoid confusion this method is now known as skip. This method now returns the Playable that was skipped.

Queue#

Attributes

count
history
is_empty
loaded
mode

Methods

defclear
defcopy
defdelete
defget
defget_at
asyncget_wait
defindex
defpeek
defput
defput_at
asyncput_wait
defremove
defreset
defshuffle
defswap

class wavelink.Queue(*, history: bool = True)#

The default custom wavelink Queue designed specifically for wavelink.Player.

Note

Player implements this queue by default. You can access it via wavelink.Player.queue.

str(queue): A string representation of this queue.

repr(queue): The official string representation of this queue.

if queue: Bool check whether this queue has items or not.

queue(track): Put a track in the queue.

len(queue): The amount of tracks in the queue.

queue[1]: Peek at an item in the queue. Does not change the queue.

for item in queue: Iterate over the queue.

if item in queue: Check whether a specific track is in the queue.

queue[1] = track: Set a track in the queue at a specific index.

del queue[1]: Delete a track from the queue at a specific index.

reversed(queue): Return a reversed iterator of the queue.

history#

A queue of tracks that have been added to history. Tracks are added to history when they are played.

Type: wavelink.Queue

property mode: QueueMode#

Property which returns a QueueMode indicating which mode the Queue is in.

This property can be set with any QueueMode.

New in version: 3.0.0

property count: int#

The queue member count.

Returns: The amount of tracks in the queue.
Return type: int

New in version: 3.2.0

property is_empty: bool#

Whether the queue has no members.

Returns: Whether the queue is empty.
Return type: bool

New in version: 3.2.0

get() → Playable#

Retrieve a track from the left side of the queue. E.g. the first.

This method does not block.

Warning

Due to the way the queue loop works, this method will return the same track if the queue is in loop mode. You can use wavelink.Player.skip() with force=True to skip the current track.

Do NOT use this method to remove tracks from the queue, use either:

del queue[index]
wavelink.Queue.remove()
wavelink.Queue.delete()

Returns: The track retrieved from the queue.
Return type: wavelink.Playable
Raises: QueueEmpty – The queue was empty when retrieving a track.

get_at(index: int, /) → Playable#

Retrieve a track from the queue at a given index.

Warning

Due to the way the queue loop works, this method will load the retrieved track for looping.

Do NOT use this method to remove tracks from the queue, use either:

del queue[index]
wavelink.Queue.remove()
wavelink.Queue.delete()

Parameters

index (int) – The index of the track to get.

Returns

The track retrieved from the queue.

Return type

wavelink.Playable

Raises

QueueEmpty – The queue was empty when retrieving a track.
IndexError – The index was out of range for the current queue.

New in version: 3.2.0

put_at(index: int, value: Playable, /) → None#

Put a track into the queue at a given index.

Note

This method doesn’t replace the track at the index but rather inserts one there, similar to a list.

Parameters

index (int) – The index to put the track at.
value (wavelink.Playable) – The track to put.

Raises

TypeError – The track was not a wavelink.Playable.

New in version: 3.2.0

await get_wait() → Playable#

This method returns the first wavelink.Playable if one is present or waits indefinitely until one is.

This method is asynchronous.

Returns: The track retrieved from the queue.
Return type: wavelink.Playable

put(item: list[wavelink.tracks.Playable] | wavelink.tracks.Playable | wavelink.tracks.Playlist, /, *, atomic: bool = True) → int#

Put an item into the end of the queue.

Accepts a wavelink.Playable, wavelink.Playlist or list[wavelink.Playble].

Parameters

item (wavelink.Playable | wavelink.Playlist | list[wavelink.Playble]) – The item to enter into the queue.
atomic (bool) – Whether the items should be inserted atomically. If set to True this method won’t enter any tracks if it encounters an error. Defaults to True.

Returns

The number of tracks added to the queue.

Return type

int

await put_wait(item: list[wavelink.tracks.Playable] | wavelink.tracks.Playable | wavelink.tracks.Playlist, /, *, atomic: bool = True) → int#

Put an item or items into the end of the queue asynchronously.

Accepts a wavelink.Playable or wavelink.Playlist or list[wavelink.Playable].

Note

This method implements a lock to preserve insert order.

Parameters

item (wavelink.Playable | wavelink.Playlist | list[wavelink.Playable]) – The item or items to enter into the queue.
atomic (bool) – Whether the items should be inserted atomically. If set to True this method won’t enter any tracks if it encounters an error. Defaults to True.

Returns

The number of tracks added to the queue.

Return type

int

delete(index: int, /) → None#

Method to delete an item in the queue by index.

Raises: IndexError – No track exists at this index.

Examples

# Deletes the track at index 1 (The second track).
queue.delete(1)

Version changed: 3.2.0 - The method is no longer a coroutine.

peek(index: int = 0, /) → Playable#

Method to peek at an item in the queue by index.

Note

This does not change the queue or remove the item.

Parameters

index (int) – The index to peek at. Defaults to 0 which is the next item in the queue.

Returns

The track at the given index.

Return type

wavelink.Playable

Raises

QueueEmpty – There are no items currently in this queue.
IndexError – No track exists at the given index.

New in version: 3.2.0

swap(first: int, second: int, /) → None#

Swap two items in the queue by index.

Parameters

first (int) – The first index to swap with.
second (int) – The second index to swap with.

Return type

None

Raises

IndexError – No track exists at the given index.

Example

# Swap the first and second tracks in the queue.
queue.swap(0, 1)

New in version: 3.2.0

index(item: Playable, /) → int#

Return the index of the first occurence of a wavelink.Playable in the queue.

Parameters: item (wavelink.Playable) – The item to search the index for.
Returns: The index of the item in the queue.
Return type: int
Raises: ValueError – The item was not found in the queue.

New in version: 3.2.0

shuffle() → None#

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

Example

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

Return type: None

clear() → None#

Remove all items from the queue.

Note

This does not reset the queue or clear history. Use this method on queue.history to clear history.

Example

player.queue.clear()
# Your queue is now empty...

Return type: None

copy() → Queue#

Create a shallow copy of the queue.

Returns: A shallow copy of the queue.
Return type: wavelink.Queue

reset() → None#

Reset the queue to its default state. This will clear the queue and history.

Note

This will cancel any waiting futures on the queue. E.g. wavelink.Queue.get_wait().

Return type: None

remove(item: Playable, /, count: int | None = 1) → int#

Remove a specific track from the queue up to a given count or all instances.

Note

This method starts from the left hand side of the queue E.g. the beginning.

Warning

Setting count to <= 0 is equivalent to setting it to 1.

Parameters

item (wavelink.Playable) – The item to remove from the queue.
count (int) – The amount of times to remove the item from the queue. Defaults to 1. If set to None this will remove all instances of the item.

Returns

The amount of times the item was removed from the queue.

Return type

int

Raises

ValueError – The item was not found in the queue.

New in version: 3.2.0

property loaded: wavelink.tracks.Playable | None#

The currently loaded track that will repeat when the queue is set to wavelink.QueueMode.loop.

This track will be retrieved when using wavelink.Queue.get() if the queue is in loop mode. You can unload the track by setting this property to None or by using wavelink.Player.skip() with force=True.

Setting this property to a new wavelink.Playable will replace the currently loaded track, but will not add it to the queue; or history until the track is played.

Returns: The currently loaded track or None if there is no track ready to repeat.
Return type: wavelink.Playable | None
Raises: TypeError – The track was not a wavelink.Playable or None.

New in version: 3.2.0

Filters#

Attributes

channel_mix
distortion
equalizer
karaoke
low_pass
plugin_filters
rotation
timescale
tremolo
vibrato
volume

Methods

clsFilters.from_filters
defreset
defset_filters

class wavelink.Filters(*, data: FilterPayload | None = None)#

The wavelink Filters class.

This class contains the information associated with each of Lavalinks filter objects, as Python classes. Each filter can be set or reset individually.

Using set on an individual filter only updates any new values you pass. Using reset on an individual filter, resets it’s payload, and can be used before set when you want a clean state for that filter.

See: reset() to reset every individual filter.

This class is already applied an instantiated on all new Player.

See: set_filters() for information on applying this class to your Player. See: filters for retrieving the applied filters.

To retrieve the payload for this Filters class, you can call an instance of this class.

Examples

import wavelink

# Create a brand new Filters and apply it...
# You can use player.set_filters() for an easier way to reset.
filters: wavelink.Filters = wavelink.Filters()
await player.set_filters(filters)

# Retrieve the payload of any Filters instance...
filters: wavelink.Filters = player.filters
print(filters())


# Set some filters...
# You can set and reset individual filters at the same time...
filters: wavelink.Filters = player.filters
filters.timescale.set(pitch=1.2, speed=1.1, rate=1)
filters.rotation.set(rotation_hz=0.2)
filters.equalizer.reset()

await player.set_filters(filters)


# Reset a filter...
filters: wavelink.Filters = player.filters
filters.timescale.reset()

await player.set_filters(filters)


# Reset all filters...
filters: wavelink.Filters = player.filters
filters.reset()

await player.set_filters(filters)


# Reset and apply filters easier method...
await player.set_filters()

set_filters(**filters: Unpack[FiltersOptions]) → None#

Set multiple filters at once to a standalone Filter object. To set the filters to the player directly see wavelink.Player.set_filters()

Parameters

volume (float) – The Volume filter to apply to the player.
equalizer (wavelink.Equalizer) – The Equalizer filter to apply to the player.
karaoke (wavelink.Karaoke) – The Karaoke filter to apply to the player.
timescale (wavelink.Timescale) – The Timescale filter to apply to the player.
tremolo (wavelink.Tremolo) – The Tremolo filter to apply to the player.
vibrato (wavelink.Vibrato) – The Vibrato filter to apply to the player.
rotation (wavelink.Rotation) – The Rotation filter to apply to the player.
distortion (wavelink.Distortion) – The Distortion filter to apply to the player.
channel_mix (wavelink.ChannelMix) – The ChannelMix filter to apply to the player.
low_pass (wavelink.LowPass) – The LowPass filter to apply to the player.
plugin_filters (wavelink.PluginFilters) – The extra Plugin Filters to apply to the player. See PluginFilters for more details.
reset (bool) – Whether to reset all filters that were not specified.

reset() → None#

Method which resets this object to an original state.

This method will clear all individual filters, and assign the wavelink default classes.

classmethod from_filters(**filters: Unpack[FiltersOptions]) → Self#

Creates a Filters object with specified filters.

Parameters

volume (float) – The Volume filter to apply to the player.
equalizer (wavelink.Equalizer) – The Equalizer filter to apply to the player.
karaoke (wavelink.Karaoke) – The Karaoke filter to apply to the player.
timescale (wavelink.Timescale) – The Timescale filter to apply to the player.
tremolo (wavelink.Tremolo) – The Tremolo filter to apply to the player.
vibrato (wavelink.Vibrato) – The Vibrato filter to apply to the player.
rotation (wavelink.Rotation) – The Rotation filter to apply to the player.
distortion (wavelink.Distortion) – The Distortion filter to apply to the player.
channel_mix (wavelink.ChannelMix) – The ChannelMix filter to apply to the player.
low_pass (wavelink.LowPass) – The LowPass filter to apply to the player.
plugin_filters (wavelink.PluginFilters) – The extra Plugin Filters to apply to the player. See PluginFilters for more details.
reset (bool) – Whether to reset all filters that were not specified.

property volume: float | None#

Property which returns the volume float associated with this Filters payload.

Adjusts the player volume from 0.0 to 5.0, where 1.0 is 100%. Values >1.0 may cause clipping.

property equalizer: Equalizer#: Property which returns the Equalizer filter associated with this Filters payload.

property karaoke: Karaoke#: Property which returns the Karaoke filter associated with this Filters payload.

property timescale: Timescale#: Property which returns the Timescale filter associated with this Filters payload.

property tremolo: Tremolo#: Property which returns the Tremolo filter associated with this Filters payload.

property vibrato: Vibrato#: Property which returns the Vibrato filter associated with this Filters payload.

property rotation: Rotation#: Property which returns the Rotation filter associated with this Filters payload.

property distortion: Distortion#: Property which returns the Distortion filter associated with this Filters payload.

property channel_mix: ChannelMix#: Property which returns the ChannelMix filter associated with this Filters payload.

property low_pass: LowPass#: Property which returns the LowPass filter associated with this Filters payload.

property plugin_filters: PluginFilters#: Property which returns the PluginFilters filters associated with this Filters payload.

Attributes

payload

Methods

defreset
defset

class wavelink.Equalizer(payload: list[EqualizerPayload] | None = None)#

Equalizer Filter Class.

There are 15 bands 0 to 14 that can be changed. Each band has a gain which is the multiplier for the given band. gain defaults to 0.

Valid gain values range from -0.25 to 1.0, where -0.25 means the given band is completely muted, and 0.25 means it will be doubled.

Modifying the gain could also change the volume of the output.

set(**options: Unpack[EqualizerOptions]) → Self#

Set the bands of the Equalizer class.

Accepts a keyword argument bands which is a list of dict containing the keys band and gain.

band can be an int beteween 0 and 14. gain can be a float between -0.25 and 1.0, where -0.25 means the given band is completely muted, and 0.25 means it will be doubled.

Using this method changes all bands, resetting any bands not provided. To change specific bands, consider accessing payload first.

reset() → Self#: Reset this filter to its defaults.

property payload: dict[int, EqualizerPayload]#

The raw payload associated with this filter.

This property returns a copy.

Attributes

payload

Methods

defreset
defset

class wavelink.Karaoke(payload: KaraokePayload)#

Karaoke Filter class.

Uses equalization to eliminate part of a band, usually targeting vocals.

set(**options: Unpack[KaraokeOptions]) → Self#

Set the properties of the this filter.

This method accepts keyword argument pairs. This method does not override existing settings if they are not provided.

Parameters

level (Optional[float]) – The level 0 to 1.0 where 0.0 is no effect and 1.0 is full effect.
mono_level (Optional[float]) – The mono level 0 to 1.0 where 0.0 is no effect and 1.0 is full effect.
filter_band (Optional[float]) – The filter band in Hz.
filter_width (Optional[float]) – The filter width.

reset() → Self#: Reset this filter to its defaults.

property payload: KaraokePayload#

The raw payload associated with this filter.

This property returns a copy.

Attributes

payload

Methods

defreset
defset

class wavelink.Timescale(payload: TimescalePayload)#

Timescale Filter class.

Changes the speed, pitch, and rate.

set(**options: Unpack[TimescalePayload]) → Self#

Set the properties of the this filter.

This method accepts keyword argument pairs. This method does not override existing settings if they are not provided.

Parameters

speed (Optional[float]) – The playback speed.
pitch (Optional[float]) – The pitch.
rate (Optional[float]) – The rate.

reset() → Self#: Reset this filter to its defaults.

property payload: TimescalePayload#

The raw payload associated with this filter.

This property returns a copy.

Attributes

payload

Methods

defreset
defset

class wavelink.Tremolo(payload: TremoloPayload)#

The Tremolo Filter class.

Uses amplification to create a shuddering effect, where the volume quickly oscillates. Demo: https://en.wikipedia.org/wiki/File:Fuse_Electronics_Tremolo_MK-III_Quick_Demo.ogv

set(**options: Unpack[TremoloPayload]) → Self#

Set the properties of the this filter.

This method accepts keyword argument pairs. This method does not override existing settings if they are not provided.

Parameters

frequency (Optional[float]) – The frequency.
depth (Optional[float]) – The tremolo depth.

reset() → Self#: Reset this filter to its defaults.

property payload: TremoloPayload#

The raw payload associated with this filter.

This property returns a copy.

Attributes

payload

Methods

defreset
defset

class wavelink.Vibrato(payload: VibratoPayload)#

The Vibrato Filter class.

Similar to tremolo. While tremolo oscillates the volume, vibrato oscillates the pitch.

set(**options: Unpack[VibratoPayload]) → Self#

Set the properties of the this filter.

This method accepts keyword argument pairs. This method does not override existing settings if they are not provided.

Parameters

frequency (Optional[float]) – The frequency.
depth (Optional[float]) – The vibrato depth.

reset() → Self#: Reset this filter to its defaults.

property payload: VibratoPayload#

The raw payload associated with this filter.

This property returns a copy.

Attributes

payload

Methods

defreset
defset

class wavelink.Rotation(payload: RotationPayload)#

The Rotation Filter class.

Rotates the sound around the stereo channels/user headphones (aka Audio Panning). It can produce an effect similar to https://youtu.be/QB9EB8mTKcc (without the reverb).

set(**options: Unpack[RotationOptions]) → Self#

Set the properties of the this filter.

This method accepts keyword argument pairs. This method does not override existing settings if they are not provided.

Parameters: rotation_hz (Optional[float]) – The frequency of the audio rotating around the listener in Hz. 0.2 is similar to the example video.

reset() → Self#: Reset this filter to its defaults.

property payload: RotationPayload#

The raw payload associated with this filter.

This property returns a copy.

Attributes

payload

Methods

defreset
defset

class wavelink.Distortion(payload: DistortionPayload)#

The Distortion Filter class.

According to Lavalink “It can generate some pretty unique audio effects.”

set(**options: Unpack[DistortionOptions]) → Self#

Set the properties of the this filter.

This method accepts keyword argument pairs. This method does not override existing settings if they are not provided.

Parameters

sin_offset (Optional[float]) – The sin offset.
sin_scale (Optional[float]) – The sin scale.
cos_offset (Optional[float]) – The cos offset.
cos_scale (Optional[float]) – The cos scale.
tan_offset (Optional[float]) – The tan offset.
tan_scale (Optional[float]) – The tan scale.
offset (Optional[float]) – The offset.
scale (Optional[float]) – The scale.

reset() → Self#: Reset this filter to its defaults.

property payload: DistortionPayload#

The raw payload associated with this filter.

This property returns a copy.

Attributes

payload

Methods

defreset
defset

class wavelink.ChannelMix(payload: ChannelMixPayload)#

The ChannelMix Filter class.

Mixes both channels (left and right), with a configurable factor on how much each channel affects the other. With the defaults, both channels are kept independent of each other.

Setting all factors to 0.5 means both channels get the same audio.

set(**options: Unpack[ChannelMixOptions]) → Self#

Set the properties of the this filter.

This method accepts keyword argument pairs. This method does not override existing settings if they are not provided.

Parameters

left_to_left (Optional[float]) – The left to left channel mix factor. Between 0.0 and 1.0.
left_to_right (Optional[float]) – The left to right channel mix factor. Between 0.0 and 1.0.
right_to_left (Optional[float]) – The right to left channel mix factor. Between 0.0 and 1.0.
right_to_right (Optional[float]) – The right to right channel mix factor. Between 0.0 and 1.0.

reset() → Self#: Reset this filter to its defaults.

property payload: ChannelMixPayload#

The raw payload associated with this filter.

This property returns a copy.

Attributes

payload

Methods

defreset
defset

class wavelink.LowPass(payload: LowPassPayload)#

The LowPass Filter class.

Higher frequencies get suppressed, while lower frequencies pass through this filter, thus the name low pass. Any smoothing values equal to or less than 1.0 will disable the filter.

set(**options: Unpack[LowPassPayload]) → Self#

Set the properties of the this filter.

This method accepts keyword argument pairs. This method does not override existing settings if they are not provided.

Parameters: smoothing (Optional[float]) – The smoothing factor.

reset() → Self#: Reset this filter to its defaults.

property payload: LowPassPayload#

The raw payload associated with this filter.

This property returns a copy.

Attributes

payload

Methods

defreset
defset

class wavelink.PluginFilters(payload: dict[str, Any])#

The PluginFilters class.

This class handles setting filters on plugins that support setting filter values. See the documentation of the Lavalink Plugin for more information on the values that can be set.

This class takes in a dict[str, Any] usually in the form of:

{"pluginName": {"filterKey": "filterValue"}, ...}

Warning

Do NOT include the "pluginFilters" top level key when setting your values for this class.

set(**options: dict[str, Any]) → Self#

Set the properties of this filter.

This method accepts keyword argument pairs OR you can alternatively unpack a dictionary. See the documentation of the Lavalink Plugin for more information on the values that can be set.

Examples

plugin_filters: PluginFilters = PluginFilters()
plugin_filters.set(pluginName={"filterKey": "filterValue", ...})

# OR...

plugin_filters.set(**{"pluginName": {"filterKey": "filterValue", ...}})

reset() → Self#: Reset this filter to its defaults.

property payload: dict[str, Any]#

The raw payload associated with this filter.

This property returns a copy.

Utils#

class wavelink.ExtrasNamespace(_ExtrasNamespace__dict: dict[str, Any] = {}, /, **kwargs: Any)#

A subclass of types.SimpleNameSpace.

You can construct this namespace with a dict of str keys and Any value, or with keyword pairs or with a mix of both.

You can access a dict version of this namespace by calling dict() on an instance.

Examples

ns: ExtrasNamespace = ExtrasNamespace({"hello": "world!"}, stuff=1)

# Later...
print(ns.hello)
print(ns.stuff)
print(dict(ns))

Exceptions#

WavelinkException

exception wavelink.WavelinkException#: Base wavelink Exception class. All wavelink exceptions derive from this exception.

exception wavelink.NodeException#: Error raised when an Unknown or Generic error occurs on a Node.

exception wavelink.InvalidClientException#: Exception raised when an invalid discord.Client is provided while connecting a wavelink.Node.

exception wavelink.AuthorizationFailedException#: Exception raised when Lavalink fails to authenticate a Node, with the provided password.

exception wavelink.InvalidNodeException#: Exception raised when a Node is tried to be retrieved from the Pool without existing, or the Pool is empty.

exception wavelink.LavalinkException#

Exception raised when Lavalink returns an invalid response.

Attributes#

status: int: The response status code.
reason: str | None: The response reason. Could be None if no reason was provided.

exception wavelink.LavalinkLoadException#: Exception raised when loading tracks failed via Lavalink.

exception wavelink.InvalidChannelStateException#: Exception raised when a Player tries to connect to an invalid channel or has invalid permissions to use this channel.

exception wavelink.ChannelTimeoutException#: Exception raised when connecting to a voice channel times out.

exception wavelink.QueueEmpty#: Exception raised when you try to retrieve from an empty queue via .get().