API Reference#
The wavelink API Reference.
This section outlines the API and all it’s components within wavelink.
Wavelink is a robust and powerful Lavalink wrapper for Discord.py. Featuring, a fully asynchronous API that’s intuitive and easy to use with built in Spotify Support, Node Pool Balancing, advanced Queues, autoplay feature and looping features built in.
Event Reference#
WaveLink Events are events dispatched when certain events happen in Lavalink and Wavelink. All events must be coroutines.
Events are dispatched via discord.py and as such can be used with listener syntax.
All Track Events receive the payloads.TrackEventPayload
payload.
For example:
An event listener in a cog…
@commands.Cog.listener()
async def on_wavelink_node_ready(node: Node) -> None:
print(f"Node {node.id} is ready!")
- wavelink.on_wavelink_node_ready(node: Node)#
Called when the Node you are connecting to has initialised and successfully connected to Lavalink.
- wavelink.on_wavelink_track_event(payload: TrackEventPayload)#
Called when any Track Event occurs.
- wavelink.on_wavelink_track_start(payload: TrackEventPayload)#
Called when a track starts playing.
- wavelink.on_wavelink_track_end(payload: TrackEventPayload)#
Called when the current track has finished playing.
- wavelink.on_wavelink_websocket_closed(payload: WebsocketClosedPayload)#
Called when the websocket to the voice server is closed.
Payloads#
- 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
- 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
- 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.
- player#
The player associated with this event.
- Type
Enums#
- class wavelink.NodeStatus(value: str)#
Enum representing the current status of a Node.
- DISCONNECTED#
0
- CONNECTING#
1
- CONNECTED#
2
- class wavelink.TrackSource(value: str)#
Enum representing the Track Source Type.
- YouTube#
0
- YouTubeMusic#
1
- SoundCloud#
2
- Local#
3
- Unknown#
4
- 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”
- class wavelink.TrackEventType(value: str)#
Enum representing the TrackEvent types.
- START#
“TrackStartEvent”
- END#
“TrackEndEvent”
- 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#
- class wavelink.tracks.Playable(data: TrackPayload)#
Base ABC Track used in all the Wavelink Track types.
- str(track)
Returns a string representing the tracks name.
- repr(track)
Returns an official string representation of this track.
- track == other_track
Check whether a track is equal to another. A track is equal when they have the same Base64 Encoding.
- source#
The source this Track was fetched from.
- Type
- classmethod await search(query: str, /, *, node: wavelink.node.Node | None = None) list[Self] #
- classmethod await search(query: str, /, *, node: wavelink.node.Node | None = None) YouTubePlaylist
- classmethod await search(query: str, /, *, node: wavelink.node.Node | None = None) SoundCloudPlaylist
Search and retrieve tracks for the given query.
- Parameters
query (str) – The query to search for.
node (Optional[
wavelink.Node
]) – The node to use when searching for tracks. If nowavelink.Node
is passed, one will be fetched via thewavelink.NodePool
.
- classmethod await convert(ctx: commands.Context, argument: str) Self #
Converter which searches for and returns the first track.
Used as a type hint in a discord.py command.
NodePool#
- clsNodePool.get_connected_node
- clsNodePool.get_node
- asyncconnect
- asyncget_playlist
- asyncget_tracks
- class wavelink.NodePool#
The Wavelink NodePool is responsible for keeping track of all
Node
.Warning
This class should never be initialised. All methods are class methods.
- classmethod await connect(*, client: discord.Client, nodes: list[Node], spotify: spotify_.SpotifyClient | None = None) dict[str, Node] #
This function is a coroutine.
Connect a list of Nodes.
- Parameters
client (
discord.Client
) – The discord Client or Bot used to connect the Nodes.nodes (list[
Node
]) – A list of Nodes to connect.spotify (Optional[
ext.spotify.SpotifyClient
]) – The spotify Client to use when searching for Spotify Tracks.
- Returns
- Return type
dict[str,
Node
]
- classmethod get_node(id: Optional[str] = None) Node #
Retrieve a
Node
with the given ID or best, if no ID was passed.
- classmethod get_connected_node() Node #
Get the best available connected
Node
.- Returns
The best available connected Node.
- Return type
- Raises
InvalidNode – No Nodes are currently in the connected state.
- classmethod await get_tracks(query: str, /, *, cls: type[PlayableT], node: Node | None = None) list[PlayableT] #
This function is a coroutine.
Helper method to retrieve tracks from the NodePool without fetching a
Node
.- Parameters
- Returns
A list of found tracks converted to the provided cls.
- Return type
list[PlayableT]
- classmethod await get_playlist(query: str, /, *, cls: Playlist, node: Node | None = None) Playlist #
This function is a coroutine.
Helper method to retrieve a playlist from the NodePool without fetching a
Node
.Warning
The only playlists currently supported are
tracks.YouTubePlaylist
andtracks.YouTubePlaylist
.- Parameters
- Returns
A Playlist with its tracks.
- Return type
Node#
- asyncbuild_track
- defget_player
- asyncget_playlist
- asyncget_tracks
- class wavelink.Node(*, id: Optional[str] = None, uri: str, password: str, secure: bool = False, use_http: bool = False, session: ClientSession = ..., heartbeat: float = 15.0, retries: Optional[int] = None)#
The base Wavelink Node.
The Node is responsible for keeping the Websocket alive, tracking the state of Players and fetching/decoding Tracks and Playlists.
Note
The Node class should only be created once per Lavalink connection. To retrieve a Node use the appropriate
NodePool
methods instead.Warning
The Node will not be connected until passed to
NodePool.connect()
.- repr(node)
Returns an official string representation of this Node.
- Parameters
id (Optional[str]) – The unique identifier for this Node. If not passed, one will be generated randomly.
uri (str) – The uri to connect to your Lavalink server. E.g
http://localhost:2333
.password (str) – The password used to connect to your Lavalink server.
secure (Optional[bool]) – Whether the connection should use https/wss.
use_http (Optional[bool]) – Whether to use http:// over ws:// when connecting to the Lavalink websocket. Defaults to False.
session (Optional[aiohttp.ClientSession]) – The session to use for this Node. If no session is passed a default will be used.
heartbeat (float) – The time in seconds to send a heartbeat ack. Defaults to 15.0.
retries (Optional[int]) – The amount of times this Node will try to reconnect after a disconnect. If not set the Node will try unlimited times.
- client#
The discord client used to connect this Node. Could be None if this Node has not been connected.
- Type
- property status: NodeStatus#
The connection status of this Node.
DISCONNECTED CONNECTING CONNECTED
- get_player(guild_id: int, /) Player | None #
Return the
player.Player
associated with the provided guild ID.If no
player.Player
is found, returns None.- Parameters
guild_id (int) – The Guild ID to return a Player for.
- Return type
Optional[
player.Player
]
- await get_tracks(cls: type[PlayableT], query: str) list[PlayableT] #
This function is a coroutine.
Search for and retrieve Tracks based on the query and cls provided.
Note
If the query is not a Local search or direct URL, you will need to provide a search prefix. E.g.
ytsearch:
for a YouTube search.
- await get_playlist(cls: Playlist, query: str)#
This function is a coroutine.
Search for and return a
tracks.Playlist
given an identifier.- Parameters
cls (Type[
tracks.Playlist
]) – The type of which playlist should be returned, this must subclasstracks.Playlist
.query (str) – The playlist’s identifier. This may be a YouTube playlist URL for example.
- Returns
The related wavelink track object or
None
if none was found.- Return type
Optional[
tracks.Playlist
]- Raises
ValueError – Loading the playlist failed.
WavelinkException – An unspecified error occurred when loading the playlist.
Tracks#
Tracks inherit from Playable
. Not all fields will be available for each track type.
GenericTrack#
- class wavelink.GenericTrack(data: TrackPayload)#
Generic Wavelink Track.
Use this track for searching for Local songs or direct URLs.
- classmethod await convert(ctx: commands.Context, argument: str) Self #
Converter which searches for and returns the first track.
Used as a type hint in a discord.py command.
- classmethod await search(query: str, /, *, node: Node | None = None) list[Self] #
Search and retrieve tracks for the given query.
- Parameters
query (str) – The query to search for.
node (Optional[
wavelink.Node
]) – The node to use when searching for tracks. If nowavelink.Node
is passed, one will be fetched via thewavelink.NodePool
.
YouTubeTrack#
- class wavelink.YouTubeTrack(data: TrackPayload)#
- property thumbnail: str#
The URL to the thumbnail of this video.
Note
Due to YouTube limitations this may not always return a valid thumbnail. Use
fetch_thumbnail()
to fallback.- Returns
The URL to the video thumbnail.
- Return type
- 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
- await fetch_thumbnail(*, node: Optional[Node] = None) str #
Fetch the max resolution thumbnail with a fallback if it does not exist.
This sets and overrides the default
thumbnail
andthumb
properties.Note
This method uses an API request to fetch the thumbnail.
- Returns
The URL to the video thumbnail.
- Return type
- classmethod await convert(ctx: commands.Context, argument: str) Self #
Converter which searches for and returns the first track.
Used as a type hint in a discord.py command.
- classmethod await search(query: str, /, *, node: Node | None = None) list[Self] #
Search and retrieve tracks for the given query.
- Parameters
query (str) – The query to search for.
node (Optional[
wavelink.Node
]) – The node to use when searching for tracks. If nowavelink.Node
is passed, one will be fetched via thewavelink.NodePool
.
YouTubeMusicTrack#
- class wavelink.YouTubeMusicTrack(data: TrackPayload)#
A track created using a search to YouTube Music.
- classmethod await convert(ctx: commands.Context, argument: str) Self #
Converter which searches for and returns the first track.
Used as a type hint in a discord.py command.
- await fetch_thumbnail(*, node: Optional[Node] = None) str #
Fetch the max resolution thumbnail with a fallback if it does not exist.
This sets and overrides the default
thumbnail
andthumb
properties.Note
This method uses an API request to fetch the thumbnail.
- Returns
The URL to the video thumbnail.
- Return type
- classmethod await search(query: str, /, *, node: Node | None = None) list[Self] #
Search and retrieve tracks for the given query.
- Parameters
query (str) – The query to search for.
node (Optional[
wavelink.Node
]) – The node to use when searching for tracks. If nowavelink.Node
is passed, one will be fetched via thewavelink.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
- 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
SoundCloudTrack#
- class wavelink.SoundCloudTrack(data: TrackPayload)#
A track created using a search to SoundCloud.
- classmethod await convert(ctx: commands.Context, argument: str) Self #
Converter which searches for and returns the first track.
Used as a type hint in a discord.py command.
- classmethod await search(query: str, /, *, node: Node | None = None) list[Self] #
Search and retrieve tracks for the given query.
- Parameters
query (str) – The query to search for.
node (Optional[
wavelink.Node
]) – The node to use when searching for tracks. If nowavelink.Node
is passed, one will be fetched via thewavelink.NodePool
.
YouTubePlaylist#
- class wavelink.YouTubePlaylist(data: dict)#
Represents a Lavalink YouTube playlist object.
- str(playlist)
Returns a string representing the playlists name.
- tracks#
The list of
YouTubeTrack
in the playlist.- Type
- classmethod await convert(ctx: commands.Context, argument: str) Self #
Converter which searches for and returns the first track.
Used as a type hint in a discord.py command.
- classmethod await search(query: str, /, *, node: Node | None = None) list[Self] #
Search and retrieve tracks for the given query.
- Parameters
query (str) – The query to search for.
node (Optional[
wavelink.Node
]) – The node to use when searching for tracks. If nowavelink.Node
is passed, one will be fetched via thewavelink.NodePool
.
Player#
- asyncconnect
- asyncdisconnect
- defis_connected
- defis_paused
- defis_playing
- asyncmove_to
- asyncon_voice_server_update
- asyncon_voice_state_update
- asyncpause
- asyncplay
- asyncresume
- asyncseek
- asyncset_filter
- asyncset_volume
- asyncstop
- class wavelink.Player(client: Client = ..., channel: Union[VoiceChannel, StageChannel] = ..., *, nodes: Optional[list[wavelink.node.Node]] = None, swap_node_on_disconnect: bool = True)#
Wavelink Player class.
This class is used as a
VoiceProtocol
and inherits all its members.You must pass this class to
discord.VoiceChannel.connect()
withcls=...
. This ensures the player is set up correctly and put into the discord.py voice client cache.You can make an instance of this class before passing it to
discord.VoiceChannel.connect()
withcls=...
, but you must still pass it.Once you have connected this class you do not need to store it anywhere as it will be stored on the
Node
and in the discord.py voice client cache. Meaning you can access this player where you have access to aNodePool
, the specificNode
or aGuild
including inContext
andInteraction
.Examples
# Connect the player... player: wavelink.Player = await ctx.author.voice.channel.connect(cls=wavelink.Player) # Retrieve the player later... player: wavelink.Player = ctx.guild.voice_client
Note
The Player class comes with an in-built queue. See
queue.Queue
for more information on how this queue works.- Parameters
- client#
The discord Client or Bot associated with this Player.
- Type
- channel#
The channel this player is currently connected to.
- Type
- 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
- auto_queue#
The built-in AutoPlay Queue. This queue keeps track of recommended songs only. When a song is retrieved from this queue in the AutoPlay event, it is added to the main
wavelink.Queue.history
queue.- Type
- property autoplay: bool#
Returns a
bool
indicating whether thePlayer
is in AutoPlay mode or not.This property can be set to
True
orFalse
.When
autoplay
isTrue
, the player will automatically handle fetching and playing the next track from the queue. It also searches tracks in theauto_queue
, a special queue populated with recommended tracks, from the Spotify API or YouTube Recommendations.Note
You can still use the
on_wavelink_track_end()
event whenautoplay
isTrue
, but it is recommended to not do any queue logic or invoking play from this event.Most users are able to use
autoplay
andon_wavelink_track_start()
together to handle their logic. E.g. sending a message when a track starts playing.Note
The
auto_queue
will be populated when you play aSpotifyTrack
orYouTubeTrack
, and have initially setpopulate
toTrue
inplay()
. Seeplay()
for more info.New in version: 2.0
Version changed: 2.6.0 - The autoplay event now populates the
auto_queue
when playingYouTubeTrack
orSpotifyTrack
.
- property guild: discord.guild.Guild | None#
The discord Guild associated with the Player.
- property current: wavelink.tracks.Playable | None#
The currently playing Track if there is one.
Could be
None
if no Track is playing.
- await on_voice_server_update(data: VoiceServerUpdate) None #
This function is a coroutine.
An abstract method that is called when initially connecting to voice. This corresponds to VOICE_SERVER_UPDATE.
Warning
Do not override this method.
- await on_voice_state_update(data: GuildVoiceState) None #
This function is a coroutine.
An abstract method that is called when the client’s voice state has changed. This corresponds to VOICE_STATE_UPDATE.
Warning
Do not override this method.
- await connect(*, timeout: float, reconnect: bool, **kwargs: Any) None #
This function is a coroutine.
An abstract method called when the client initiates the connection request.
When a connection is requested initially, the library calls the constructor under
__init__
and then callsconnect()
. Ifconnect()
fails at some point thendisconnect()
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()
andon_voice_state_update()
will be called. The order that these two are called is unspecified.
- await move_to(channel: VoiceChannel) None #
This function is a coroutine.
Moves the player to a different voice channel.
- Parameters
channel (
discord.VoiceChannel
) – The channel to move to. Must be a voice channel.
- await play(track: wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack, replace: bool = True, start: Optional[int] = None, end: Optional[int] = None, volume: Optional[int] = None, *, populate: bool = False) Playable #
This function is a coroutine.
Play a WaveLink Track.
- Parameters
track (
tracks.Playable
) – Thetracks.Playable
orSpotifyTrack
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
and1000
. Defaults toNone
which will not change the volume.populate (bool) –
Whether to populate the AutoPlay queue. Defaults to
False
.New in version: 2.0
- Returns
The track that is now playing.
- Return type
Note
If you pass a
YouTubeTrack
orSpotifyTrack
and setpopulate=True
, whileautoplay
is set toTrue
, this method will populate theauto_queue
with recommended songs. When theauto_queue
is low on tracks this method will automatically populate theauto_queue
with more tracks, and continue this cycle until either the player has been disconnected orautoplay
is set toFalse
.Example
tracks: list[wavelink.YouTubeTrack] = await wavelink.YouTubeTrack.search(...) if not tracks: # Do something as no tracks were found... return await player.queue.put_wait(tracks[0]) if not player.is_playing(): await player.play(player.queue.get(), populate=True)
Version changed: 2.6.0 - This method now accepts
YouTubeTrack
orSpotifyTrack
when populating theauto_queue
.
- await set_volume(value: int) None #
This function is a coroutine.
Set the Player volume.
- Parameters
value (int) – A volume value between 0 and 1000.
- await seek(position: int) None #
This function is a coroutine.
Seek to the provided position, in milliseconds.
- Parameters
position (int) – The position to seek to in milliseconds.
- await stop(*, force: bool = True) None #
This function is a coroutine.
Stops the currently playing Track.
- Parameters
force (Optional[bool]) – Whether to stop the currently playing track and proceed to the next regardless if
loop
isTrue
. Defaults toTrue
.
Version changed: 2.6 - Added the
force
keyword argument.
- await set_filter(_filter: Filter, /, *, seek: bool = False) None #
This function is a coroutine.
Set the player’s filter.
- Parameters
filter (
wavelink.Filter
) – The filter to apply to the player.seek (bool) – Whether to seek the player to its current position which will apply the filter immediately. Defaults to
False
.
Queues#
- defclear
- defcopy
- defextend
- deffind_position
- defget
- defpop
- defput
- defput_at_front
- defput_at_index
- defshuffle
- class wavelink.BaseQueue#
BaseQueue for wavelink.
All queues inherit from this queue.
See
Queue
for the defaultPlayer
queue. Internally this queue uses acollections.deque
.Warning
It is not advisable to edit the internal
collections.deque
directly.- str(queue)
Returns a string showing all Playable objects appearing as a list in the queue.
- repr(queue)
Returns an official string representation of this queue.
- if queue
Returns True if members are in the queue. False if the queue is empty.
- queue(track)
Adds a member to the queue.
- len(queue)
Returns an int with the count of members in this queue.
- queue[2]
Returns a member at the given position. Does not remove the item from queue.
- queue[4] = track
Inserts an item into the queue at the given position.
- del queue[1]
Deletes a member from the queue at the given position.
- for track in queue
Iterates over the queue. Does not remove items when iterating.
- reversed(queue)
Reverse a reversed version of the queue.
- if track in queue
Checks whether a track is in the queue.
- queue = queue + [track, track1, track2, ...]
Return a new queue containing all new and old members from the given iterable.
- queue += [track, track1, track2, ...]
Add items to queue from the given iterable.
- get() wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack #
Return next immediately available item in queue if any.
Raises
QueueEmpty
if no items in queue.
- pop() wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack #
Return item from the right end side of the queue.
Raises
QueueEmpty
if no items in queue.
- find_position(item: wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack) int #
Find the position a given item within the queue.
Raises
ValueError
if item is not in the queue.
- put(item: wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack) None #
Put the given item into the back of the queue.
If the provided
item
is aYouTubePlaylist
orSoundCloudPlaylist
, all tracks from this playlist will be put into the queue.Note
Inserting playlists is currently only supported via this method, which means you can only insert them into the back of the queue. Future versions of wavelink may add support for inserting playlists from a specific index, or at the front of the queue.
Version changed: 2.6.0 - Added support for directly adding a
YouTubePlaylist
to the queue.
- put_at_index(index: int, item: wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack) None #
Put the given item into the queue at the specified index.
- put_at_front(item: wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack) None #
Put the given item into the front of the queue.
- shuffle() None #
Shuffles the queue in place. This does not return anything.
Example
player.queue.shuffle() # Your queue has now been shuffled...
New in version: 2.5
- extend(iterable: Iterable[wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack], *, atomic: bool = True) None #
Add the members of the given iterable to the end of the queue.
If atomic is set to
True
, no tracks will be added upon any exceptions.If atomic is set to
False
, as many tracks will be added as possible.
- copy()#
Create a copy of the current queue including its members.
- class wavelink.Queue#
Main Queue class.
All
Player
have this queue assigned to them.Note
This queue inherits from
BaseQueue
but has access to special async methods and loop logic.- async for track in queue
Pops members as it iterates the queue asynchronously, waiting for new members when exhausted. Does remove items when iterating.
- history#
The history queue stores information about all previous played tracks for the
Player
’s session.- Type
- get() wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack #
Return next immediately available item in queue if any.
Raises
QueueEmpty
if no items in queue.
- await get_wait() wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack #
This function is a coroutine.
Return the next item in queue once available.
Note
This will wait until an item is available to be retrieved.
- await put_wait(item: wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack) None #
This function is a coroutine.
Put an item into the queue asynchronously using
await
.If the provided
item
is aYouTubePlaylist
orSoundCloudPlaylist
, all tracks from this playlist will be put into the queue.Note
Inserting playlists is currently only supported via this method, which means you can only insert them into the back of the queue. Future versions of wavelink may add support for inserting playlists from a specific index, or at the front of the queue.
Version changed: 2.6.0 - Added support for directly adding a
YouTubePlaylist
to the queue.
- put(item: wavelink.tracks.Playable | wavelink.ext.spotify.SpotifyTrack) None #
Put the given item into the back of the queue.
If the provided
item
is aYouTubePlaylist
, all tracks from this playlist will be put into the queue.Note
Inserting playlists is currently only supported via this method, which means you can only insert them into the back of the queue. Future versions of wavelink may add support for inserting playlists from a specific index, or at the front of the queue.
Version changed: 2.6.0 - Added support for directly adding a
YouTubePlaylist
to the queue.
- reset() None #
Clears the state of all queues, including the history queue.
sets loop and loop_all to
False
.removes all items from the queue and history queue.
cancels any waiting queues.
Filters#
- class wavelink.Filter(_filter: Optional[Filter] = None, /, *, equalizer: Optional[Equalizer] = None, karaoke: Optional[Karaoke] = None, timescale: Optional[Timescale] = None, tremolo: Optional[Tremolo] = None, vibrato: Optional[Vibrato] = None, rotation: Optional[Rotation] = None, distortion: Optional[Distortion] = None, channel_mix: Optional[ChannelMix] = None, low_pass: Optional[LowPass] = None)#
A filter that can be applied to a track.
This filter accepts an instance of itself as a parameter which allows you to keep previous filters while also applying new ones or overwriting old ones.
- repr(filter)
Returns an official string representation of this filter.
- Parameters
filter (wavelink.Filter) – An instance of this filter class.
equalizer (wavelink.Equalizer) – An equalizer to apply to the track.
karaoke (wavelink.Karaoke) – A karaoke filter to apply to the track.
timescale (wavelink.Timescale) – A timescale filter to apply to the track.
tremolo (wavelink.Tremolo) – A tremolo filter to apply to the track.
vibrato (wavelink.Vibrato) – A vibrato filter to apply to the track.
rotation (wavelink.Rotation) – A rotation filter to apply to the track.
distortion (wavelink.Distortion) – A distortion filter to apply to the track.
channel_mix (wavelink.ChannelMix) – A channel mix filter to apply to the track.
low_pass (wavelink.LowPass) – A low pass filter to apply to the track.
- clsEqualizer.boost
- clsEqualizer.flat
- clsEqualizer.metal
- clsEqualizer.piano
- class wavelink.Equalizer(name: str = 'CustomEqualizer', *, bands: list[tuple[int, float]])#
An equalizer filter.
- Parameters
- 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.
- 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
andrate
will play the track normally.
- 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
anddepth
will play the track normally.
- 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
anddepth
will play the track normally.
- class wavelink.Rotation(speed: float = 5)#
A rotation filter.
Rotates the audio around stereo channels which can be used to create a 3D effect.
The default value provided for
speed
will play the track normally.- Parameters
speed (float) – The speed at which the audio should rotate.
- class wavelink.Distortion(*, sin_offset: float = 0.0, sin_scale: float = 1.0, cos_offset: float = 0.0, cos_scale: float = 1.0, tan_offset: float = 0.0, tan_scale: float = 1.0, offset: float = 0.0, scale: float = 1.0)#
A distortion filter.
- class wavelink.ChannelMix(*, left_to_left: float = 1.0, left_to_right: float = 0.0, right_to_left: float = 0.0, right_to_right: float = 1.0)#
A channel mix filter.
Allows you to control what channel audio from the track is actually played on.
Setting left_to_left and right_to_right to 1.0 will result in no change. Setting all channels to 0.5 will result in all channels receiving the same audio.
The default values provided for all the parameters will play the track normally.
- Parameters
left_to_left (float) – The “percentage” of audio from the left channel that should actually get played on the left channel.
left_to_right (float) – The “percentage” of audio from the left channel that should play on the right channel.
right_to_left (float) – The “percentage” of audio from the right channel that should actually get played on the right channel.
right_to_right (float) – The “percentage” of audio from the right channel that should play on the left channel.
- classmethod mono() ChannelMix #
Returns a ChannelMix filter that will play the track in mono.
- classmethod only_left() ChannelMix #
Returns a ChannelMix filter that will only play the tracks left channel.
- classmethod full_left() ChannelMix #
Returns a ChannelMix filter that will play the tracks left and right channels together only on the left channel.
- classmethod only_right() ChannelMix #
Returns a ChannelMix filter that will only play the tracks right channel.
- classmethod full_right() ChannelMix #
Returns a ChannelMix filter that will play the tracks left and right channels together only on the right channel.
- classmethod switch() ChannelMix #
Returns a ChannelMix filter that will switch the tracks left and right channels.
- class wavelink.LowPass(*, smoothing: float = 20)#
A low pass filter.
Suppresses higher frequencies while allowing lower frequencies to pass through.
The default value provided for
smoothing
will play the track normally.- Parameters
smoothing (float) – The factor by which the filter will block higher frequencies.
Exceptions#
- exception wavelink.WavelinkException#
Base wavelink exception.
- exception wavelink.AuthorizationFailed#
Exception raised when password authorization failed for this Lavalink node.
- exception wavelink.InvalidNode#
- exception wavelink.InvalidLavalinkVersion#
Exception raised when you try to use wavelink 2 with a Lavalink version under 3.7.
- exception wavelink.InvalidLavalinkResponse#
Exception raised when wavelink receives an invalid response from Lavalink.
- status:
int
|None
The status code. Could be
None
.
- status:
- 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.