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 ofwavelink.Player
that were connected on this Node and are now disconnected.
- wavelink.on_wavelink_extra_event(payload: wavelink.ExtraEventPayload)#
Called when an
Unknown
and/orUnhandled
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 specificPlayer
.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()
andPool.fetch_tracks()
Example:
tracks: wavelink.Search = await wavelink.Playable.search("Ocean Drive")
Payloads#
- class wavelink.NodeReadyEventPayload(node: Node, resumed: bool, session_id: str)#
Payload received in the
on_wavelink_node_ready()
event.
- class wavelink.TrackStartEventPayload(player: Player | None, track: Playable)#
Payload received in the
on_wavelink_track_start()
event.
- class wavelink.TrackEndEventPayload(player: Player | None, track: Playable, reason: str)#
Payload received in the
on_wavelink_track_end()
event.
- class wavelink.TrackExceptionEventPayload(player: Player | None, track: Playable, exception: TrackExceptionPayload)#
Payload received in the
on_wavelink_track_exception()
event.- exception#
The exception data received via Lavalink.
- Type
TrackExceptionPayload
- class wavelink.TrackStuckEventPayload(player: Player | None, track: Playable, threshold: int)#
Payload received in the
on_wavelink_track_stuck()
event.
- class wavelink.WebsocketClosedEventPayload(player: Player | None, code: int, reason: str, by_remote: bool)#
Payload received in the
on_wavelink_websocket_closed()
event.- code#
The close code enum value.
- class wavelink.PlayerUpdateEventPayload(player: Player | None, state: PlayerState)#
Payload received in the
on_wavelink_player_update()
event.
- class wavelink.StatsEventPayload(data: StatsOP)#
Payload received in the
on_wavelink_stats_update()
event.- memory#
See Also:
wavelink.StatsEventMemory
- cpu#
See Also:
wavelink.StatsEventCPU
- frames#
See Also:
wavelink.StatsEventFrames
. This could beNone
.- Type
wavelink.StatsEventFrames
| None
- class wavelink.StatsEventMemory(data: MemoryStats)#
Represents Memory Stats.
- class wavelink.StatsEventCPU(data: CPUStats)#
Represents CPU Stats.
- class wavelink.StatsEventFrames(data: FrameStats)#
Represents Frame Stats.
- class wavelink.StatsResponsePayload(data: StatsResponse)#
Payload received when using
fetch_stats()
- memory#
See Also:
wavelink.StatsEventMemory
- cpu#
See Also:
wavelink.StatsEventCPU
- frames#
See Also:
wavelink.StatsEventFrames
. This could beNone
.- Type
wavelink.StatsEventFrames
| None
- class wavelink.PlayerStatePayload(data: PlayerState)#
Represents the PlayerState information received via
fetch_player_info()
orfetch_players()
- class wavelink.VoiceStatePayload(data: VoiceStateResponse)#
Represents the VoiceState information received via
fetch_player_info()
orfetch_players()
. This is the voice state information received via Discord and sent to your Lavalink node.
- class wavelink.PlayerResponsePayload(data: PlayerResponse)#
Payload received when using
fetch_player_info()
orfetch_players()
- track#
The current track playing on Lavalink. Could be
None
if no track is playing.- Type
wavelink.Playable
| None
- state#
The current state of the player. See:
wavelink.PlayerStatePayload
.
- voice_state#
The voice state infomration received via Discord and sent to Lavalink. See:
wavelink.VoiceStatePayload
.
- filters#
The
wavelink.Filters
currently associated with this player.- Type
- class wavelink.GitResponsePayload(data: GitPayload)#
Represents Git information received via
wavelink.Node.fetch_info()
- commit_time#
The timestamp for when the commit was created.
- Type
- class wavelink.VersionResponsePayload(data: VersionPayload)#
Represents Version information received via
wavelink.Node.fetch_info()
- pre_release#
The pre-release version according to semver as a
.
separated list of identifiers.- Type
- class wavelink.PluginResponsePayload(data: PluginPayload)#
Represents Plugin information received via
wavelink.Node.fetch_info()
- class wavelink.InfoResponsePayload(data: InfoResponse)#
Payload received when using
fetch_info()
- version#
The version info payload for this Lavalink node in the
VersionResponsePayload
object.
- build_time#
The timestamp when this Lavalink jar was built.
- Type
- git#
The git info payload for this Lavalink node in the
GitResponsePayload
object.- Type
- plugins#
The enabled plugins for this node.
- Type
list[
PluginResponsePayload
]
- class wavelink.ExtraEventPayload(*, node: Node, player: Player | None, data: dict[str, Any])#
Payload received in the
on_wavelink_extra_event()
event.This payload is created when an
Unknown
andUnhandled
event is received from Lavalink, most likely via a plugin.Note
See the appropriate documentation of the plugin for the data sent with these events.
New in version: 3.1.0
Enums#
- 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.
- 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.
- 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
- 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.
- 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#
- 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: Optional[Client] = None, cache_capacity: Optional[int] = None) dict[str, wavelink.node.Node] #
Connect the provided Iterable[
Node
] to Lavalink.- Parameters
client (
discord.Client
| None) – Thediscord.Client
to use to connect theNode
. 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 toNone
.
- Returns
A mapping of
Node.identifier
toNode
associated with thePool
.- 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 thecache_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 thePool
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 thePool
.
Version changed: 3.0.0 - The
id
parameter was changed toidentifier
and is positional only.
- classmethod await fetch_tracks(query: str, /) list[wavelink.tracks.Playable] | wavelink.tracks.Playlist #
Search for a list of
Playable
or aPlaylist
, 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”
- Returns
A list of
Playable
or aPlaylist
based on your searchquery
. Could be an empty list, if no tracks were found.- Return type
- Raises
LavalinkLoadException – Exception raised when Lavalink fails to load results based on your query.
Node#
- asyncclose
- asyncfetch_info
- asyncfetch_player_info
- asyncfetch_players
- asyncfetch_stats
- asyncfetch_version
- defget_player
- asyncsend
- class wavelink.Node(*, identifier: Optional[str] = None, uri: str, password: str, session: Optional[ClientSession] = None, heartbeat: float = 15.0, retries: Optional[int] = None, client: Optional[Client] = None, resume_timeout: int = 60, inactive_player_timeout: int | None = 300)#
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 likehttps://lavalink.example.com
or a public IP address and port likehttp://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. IfNone
, one will be generated for you. Defaults toNone
.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 toNone
.client (
discord.Client
| None) – Thediscord.Client
or subclasses, E.g.commands.Bot
used to connect this Node. If this is not passed you must pass this towavelink.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 to60
.inactive_player_timeout (int | None) –
Set the default for
wavelink.Player.inactive_timeout
on every player that connects to this node. Defaults to300
.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 status: NodeStatus#
The current
Node
status.Refer to:
NodeStatus
- property players: dict[int, Player]#
A mapping of
discord.Guild.id
toPlayer
.Version changed: 3.1.1 - This property now returns a shallow copy of the internal mapping.
- property client: discord.client.Client | None#
Returns the
discord.Client
associated with thisNode
.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 toFalse
.
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
andPlayer
, 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 beNone
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
- 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
- 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
- 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 provideddiscord.Guild.id
.- Parameters
guild_id (int) – The
discord.Guild.id
to retrieve aPlayer
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
.
- class wavelink.Artist(*, data: dict[Any, Any])#
Container class representing Artist data received via Lavalink.
- class wavelink.Album(*, data: dict[Any, Any])#
Container class representing Album data received via Lavalink.
Playable#
- 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 identifier: str#
Property returning the identifier of this track from its source.
E.g. YouTube ID or Spotify ID.
- property position: int#
Property returning starting position of this track in milliseconds as an int.
- 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 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 beNone
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 thisPlayable
.You can set this property with a
dict
of validstr
keys to any validJSON
value, or aExtrasNamespace
.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 onExtrasNamespace
.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 viaLavalink
.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: wavelink.enums.TrackSource | str | None = TrackSource.YouTubeMusic) list[wavelink.tracks.Playable] | wavelink.tracks.Playlist #
Search for a list of
Playable
or aPlaylist
, 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 thesource
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, astr
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:”.
- Returns
A union of either list[
Playable
] orPlaylist
. Could return and empty list, if no tracks or playlist were found.- Return type
- 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 awavelink.Node
to use for searching as this method will now select the most appropriate node from thewavelink.Pool
.
Playlists#
- class wavelink.Playlist(data: PlaylistPayload)#
The wavelink Playlist container class.
This class is created and returned via both
Playable.search()
andwavelink.Pool.fetch_tracks()
.It contains various information about the playlist and a list of
Playable
that can be used directly inwavelink.Player.play()
. See below for various supported operations.Warning
You should not instantiate this class manually, use
Playable.search()
orwavelink.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 toPlayable
. When added, all tracks contained in this playlist, will be individually added to thewavelink.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.
- 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 thisPlaylist
.You can set this property with a
dict
of validstr
keys to any validJSON
value, or aExtrasNamespace
.If a dict is passed, it will be converted into an
ExtrasNamespace
, which can be converted back to a dict withdict(...)
. Additionally, you can also use list or tuple onExtrasNamespace
.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
- 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.- 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
Player#
- 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 yourdiscord.Client
to adiscord.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 variousvoice_client
attributes in discord.py, includingguild.voice_client
,ctx.voice_client
andinteraction.voice_client
.- auto_queue#
The auto_queue associated with this player. This queue holds tracks that are recommended by the AutoPlay feature.
- Type
- property inactive_timeout: int | None#
A property which returns the time as an
int
of seconds to wait before this player dispatches theon_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 theon_wavelink_inactive_player()
event orNone
to remove the timeout.Warning
Setting this to a value of
0
or below is the equivalent of setting this property toNone
.When this property is set, the timeout will reset, and all previously waiting countdowns are cancelled.
See:
Node
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 selectedNode
.Version changed: 3.0.0 - This property was previously known as
current_node
.
- property guild: discord.guild.Guild | None#
Returns the
Player
’s associateddiscord.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
.
- 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 return0
.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
tocls=
indiscord.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 orFalse
if they can not be determined.self_mute (bool | None) – Whether to self mute when moving. Defaults to
None
which keeps the current setting orFalse
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) 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
and1000
. Defaults toNone
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 toFalse
will resume the player if it is currently paused. Setting this parameter toNone
will not change the status of the player. Defaults toNone
.add_history (Optional[bool]) – If this argument is set to
True
, thePlayer
will add this track into thewavelink.Queue
history, if loading the track was successful. IfFalse
this track will not be added to your history. This does not directly affect theAutoPlay Queue
but will alter howAutoPlay
recommends songs in the future. Defaults toTrue
.filters (Optional[
Filters
]) – An Optional[Filters
] to apply when playing this track. Defaults toNone
. If this isNone
the currently set filters on the player will be applied.
- Returns
The track that began playing.
- Return type
Version changed: 3.0.0 - Added the
paused
parameter. Parametersreplace
,start
,end
,volume
andpaused
are now all keyword-only arguments. Added theadd_history
keyword-only argument. Added thefilters
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
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 aliasstop
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 toTrue
.- 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 asskip
. This method now returns thePlayable
that was skipped.
Queue#
- 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 viawavelink.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
- property mode: QueueMode#
Property which returns a
QueueMode
indicating which mode theQueue
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
New in version: 3.2.0
- property is_empty: bool#
Whether the queue has no members.
- Returns
Whether the queue is empty.
- Return type
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()
withforce=True
to skip the current track.Do NOT use this method to remove tracks from the queue, use either:
del queue[index]
- Returns
The track retrieved from the queue.
- Return type
- 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]
- Parameters
index (int) – The index of the track to get.
- Returns
The track retrieved from the queue.
- Return type
- 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
- 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 toTrue
.
- Returns
The number of tracks added to the queue.
- Return type
- 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
orwavelink.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 toTrue
.
- Returns
The number of tracks added to the queue.
- Return type
- 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
- 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
- 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
- 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
- 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 to1
.- 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 toNone
this will remove all instances of the item.
- Returns
The amount of times the item was removed from the queue.
- Return type
- 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 toNone
or by usingwavelink.Player.skip()
withforce=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
orNone
.
New in version: 3.2.0
Filters#
- 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
orreset
individually.Using
set
on an individual filter only updates anynew
values you pass. Usingreset
on an individual filter, resets it’s payload, and can be used beforeset
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 yourPlayer
. 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.reset (bool) – Whether to reset all filters that were not specified.
- reset() None #
Method which resets this object to an original state.
Using this method will clear all indivdual 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.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.
- class wavelink.Equalizer(payload: list[EqualizerPayload] | None = None)#
Equalizer Filter Class.
There are 15 bands
0
to14
that can be changed. Each band has again
which is the multiplier for the given band.gain
defaults to0
.Valid
gain
values range from-0.25
to1.0
, where-0.25
means the given band is completely muted, and0.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 alist
ofdict
containing the keysband
andgain
.band
can be anint
beteween0
and14
.gain
can be a float between-0.25
and1.0
, where-0.25
means the given band is completely muted, and0.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.
- 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
- reset() Self #
Reset this filter to its defaults.
- property payload: KaraokePayload#
The raw payload associated with this filter.
This property returns a copy.
- 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.
- reset() Self #
Reset this filter to its defaults.
- property payload: TimescalePayload#
The raw payload associated with this filter.
This property returns a copy.
- 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.
- reset() Self #
Reset this filter to its defaults.
- property payload: TremoloPayload#
The raw payload associated with this filter.
This property returns a copy.
- 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.
- reset() Self #
Reset this filter to its defaults.
- property payload: VibratoPayload#
The raw payload associated with this filter.
This property returns a copy.
- 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.
- 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.
- 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
and1.0
.left_to_right (Optional[float]) – The left to right channel mix factor. Between
0.0
and1.0
.right_to_left (Optional[float]) – The right to left channel mix factor. Between
0.0
and1.0
.right_to_right (Optional[float]) – The right to right channel mix factor. Between
0.0
and1.0
.
- reset() Self #
Reset this filter to its defaults.
- property payload: ChannelMixPayload#
The raw payload associated with this filter.
This property returns a copy.
- 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.
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#
- 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 awavelink.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 thePool
without existing, or thePool
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()
.