Sets up a logger to stdout. This solely exists to make things easier for end-users who want to debug issues with Lava.
Adds an event hook to be dispatched on an event.
hooks (function
) – The hooks to register for the given event type.
If event parameter is left empty, then it will run when any event is dispatched.
event (Event
) – The event the hook belongs to. This will dispatch when that specific event is
dispatched. Defaults to None which means the hook is dispatched on all events.
Represents a Lavalink client used to manage nodes and connections.
user_id (int
) – The user id of the bot.
player (Optional[BasePlayer
]) – The class that should be used for the player. Defaults to DefaultPlayer
.
Do not change this unless you know what you are doing!
regions (Optional[dict
]) – A dictionary representing region -> nextcord endpoint. You should only
change this if you know what you’re doing and want more control over
which regions handle specific locations. Defaults to None.
connect_back (Optional[bool
]) –
A boolean that determines if a player will connect back to the node it was originally connected to. This is not recommended to do since the player will most likely be performing better in the new node. Defaults to False.
Warning
If this option is enabled and the player’s node is changed through Player.change_node after the player was moved via the failover mechanism, the player will still move back to the original node when it becomes available. This behaviour can be avoided in custom player implementations by setting self._original_node to None in the change_node function.
Represents the node manager that contains all lavalink nodes.
Represents the player manager that contains all the players.
Adds a node to Lavalink’s node manager.
host (str
) – The address of the Lavalink node.
port (int
) – The port to use for websocket and REST connections.
password (str
) – The password used for authentication.
region (str
) – The region to assign this node to.
resume_key (Optional[str
]) – A resume key used for resuming a session upon re-establishing a WebSocket connection to Lavalink.
Defaults to None.
resume_timeout (Optional[int
]) – How long the node should wait for a connection while disconnected before clearing all players.
Defaults to 60.
name (Optional[str
]) – An identifier for the node that will show in logs. Defaults to None
reconnect_attempts (Optional[int
]) – The amount of times connection with the node will be reattempted before giving up.
Set to -1 for infinite. Defaults to 3.
This function is a coroutine. Gets all tracks associated with the given query.
query (str
) – The query to perform a search for.
node (Optional[Node
]) – The node to use for track lookup. Leave this blank to use a random node.
Defaults to None which is a random node.
A dict representing tracks.
dict
This function is a coroutine. Decodes a base64-encoded track string into a dict.
track (str
) – The base64-encoded track string.
node (Optional[Node
]) – The node to use for the query. Defaults to None which is a random node.
A dict representing the track’s information.
dict
This function is a coroutine. Decodes a list of base64-encoded track strings into a dict.
tracks (list[str
]) – A list of base64-encoded track strings.
node (Optional[Node
]) – The node to use for the query. Defaults to None which is a random node.
A list of dicts representing track information.
List[dict
]
This function is a coroutine. Gets the routeplanner status of the target node.
node (Node
) – The node to use for the query.
A dict representing the routeplanner information.
dict
This function is a coroutine. Gets the routeplanner status of the target node.
node (Node
) – The node to use for the query.
address (str
) – The address to free.
True if the address was freed, False otherwise.
bool
This function is a coroutine. Gets the routeplanner status of the target node.
node (Node
) – The node to use for the query.
True if all failing addresses were freed, False otherwise.
bool
This function is a coroutine. This function intercepts websocket data from your nextcord library and forwards the relevant information on to Lavalink, which is used to establish a websocket connection and send audio packets to nextcord.
Example
bot.add_listener(lavalink_client.voice_update_handler, 'on_socket_response')
data (dict
) – The payload received from nextcord.
All Events are derived from Event
The base for all Lavalink events.
This event is dispatched when the player starts to play a track.
The player that started to play a track.
The track that started playing.
This event is dispatched when the player finished playing a track.
The player that finished playing a track.
The track that finished playing.
The reason why the track stopped playing.
str
This event is dispatched when the currently playing track is stuck. This normally has something to do with the stream you are playing and not Lavalink itself.
The player that has the playing track being stuck.
The track is stuck from playing.
The amount of time the track had while being stuck.
int
This event is dispatched when an exception occurs while playing a track.
The player that had the exception occur while playing a track.
The track that had the exception while playing.
The type of exception that the track had while playing.
Exception
This event is dispatched when there are no more songs in the queue.
The player that has no more songs in queue.
This event is dispatched when Lavalink.py successfully connects to a node.
This event is dispatched when a player changes to another node. Keep in mind this event can be dispatched multiple times if a node disconnects and the load balancer moves players to a new node.
The player whose node was changed.
This event is dispatched when a node disconnects and becomes unavailable.
The status code of the event.
int
The reason of why the node was disconnected.
str
This event is dispatched when a audio websocket to nextcord is closed. This can happen happen for various reasons like an expired voice server update.
The player whose audio websocket was closed.
The node the player was moved from.
int
The node the player was moved to.
str
If the websocket was closed remotely.
bool
All custom players must derive from BasePlayer
Represents the AudioTrack sent to Lavalink.
data (dict
) – The data to initialise an AudioTrack from.
requester (any
) – The requester of the track.
extra (dict
) – Any extra information to store in this AudioTrack.
The base64-encoded string representing a Lavalink-readable AudioTrack.
str
The track’s id. For example, a youtube track’s identifier will look like dQw4w9WgXcQ.
str
Whether the track supports seeking.
bool
The track’s uploader.
str
The duration of the track, in milliseconds.
int
Whether the track is a live-stream.
bool
The title of the track.
str
The full URL of track.
str
Any extra properties given to this AudioTrack will be stored here.
dict
Represents the BasePlayer all players must be inherited from.
The guild id of the player.
str
The player that Lavalink.py defaults to use.
The guild id of the player.
int
Whether or not a player is paused.
bool
The position of how far a track has gone.
int
The volume at which the player is playing at.
int
Whether or not to mix the queue up in a random playing order.
bool
Whether or not to continuously to play a track.
bool
The changes to audio frequencies on tracks.
list
The order of which tracks are played.
list
The track that is playing currently.
Returns the player’s track state.
Returns whether the player is connected to a voicechannel or not.
Returns the position in the track, adjusted for Lavalink’s 5-second stats interval.
Stores custom user data.
key (object
) – The key of the object to store.
value (object
) – The object to associate with the key.
Retrieves the related value from the stored user data.
key (object
) – The key to fetch.
default (Optional[any
]) – The object that should be returned if the key doesn’t exist. Defaults to None.
any
Removes an item from the the stored user data.
key (object
) – The key to delete.
Adds a track to the queue.
requester (int
) – The ID of the user who requested the track.
track (Union[AudioTrack
, dict
]) – The track to add. Accepts either an AudioTrack or
a dict representing a track returned from Lavalink.
index (Optional[int
]) – The index at which to add the track.
If index is left unspecified, the default behaviour is to append the track. Defaults to None.
Plays the given track.
track (Optional[Union[AudioTrack
, dict
]]) – The track to play. If left unspecified, this will default
to the first track in the queue. Defaults to None so plays the next
song in queue. Accepts either an AudioTrack or a dict representing a track
returned from Lavalink.
start_time (Optional[int
]) – Setting that determines the number of milliseconds to offset the track by.
If left unspecified, it will start the track at its beginning. Defaults to 0,
which is the normal start time.
end_time (Optional[int
]) – Settings that determines the number of milliseconds the track will stop playing.
By default track plays until it ends as per encoded data. Defaults to 0, which is
the normal end time.
no_replace (Optional[bool
]) – If set to true, operation will be ignored if a track is already playing or paused.
Defaults to False
Stops the player.
Plays the next track in the queue, if any.
Sets the player’s repeat state.
:param repeat: Whether to repeat the player or not.
:type repeat: bool
Sets the player’s shuffle state.
:param shuffle: Whether to shuffle the player or not.
:type shuffle: bool
Sets the player’s paused state.
pause (bool
) – Whether to pause the player or not.
Sets the player’s volume
Note
A limit of 1000 is imposed by Lavalink.
vol (int
) – The new volume level.
Seeks to a given position in the track.
position (int
) – The new position to seek to in milliseconds.
Sets the equalizer band gain to the given amount.
band (int
) – Band number (0-14).
gain (Optional[float
]) – A float representing gain of a band (-0.25 to 1.00). Defaults to 0.0.
Modifies the player’s equalizer settings.
gain_list (any
) – A list of tuples denoting (band, gain).
Resets equalizer to default values.
Represents a Node connection with Lavalink.
Note
Nodes are NOT mean’t to be added manually, but rather with Client.add_node()
. Doing this can cause
invalid cache and much more problems.
The address of the Lavalink node.
str
The port to use for websocket and REST connections.
int
The password used for authentication.
str
The region to assign this node to.
str
Returns whether the node is available for requests.
Returns a list of all players on this node.
Returns the load-balancing penalty for this node.
This function is a coroutine. Gets all tracks associated with the given query.
query (str
) – The query to perform a search for.
A dict representing an AudioTrack.
dict
This function is a coroutine. Gets the routeplanner status of the target node.
A dict representing the routeplanner information.
dict
Represents the node manager that contains all lavalink nodes.
Returns an iterator of all the nodes cached.
Cache of all the nodes that Lavalink has created.
list
All the regions that nextcord supports.
dict
Returns a list of available nodes.
Adds a node to Lavalink’s node manager.
host (str
) – The address of the Lavalink node.
port (int
) – The port to use for websocket and REST connections.
password (str
) – The password used for authentication.
region (str
) – The region to assign this node to.
resume_key (Optional[str
]) – A resume key used for resuming a session upon re-establishing a WebSocket connection to Lavalink.
Defaults to None.
resume_timeout (Optional[int
]) – How long the node should wait for a connection while disconnected before clearing all players.
Defaults to 60.
name (Optional[str
]) – An identifier for the node that will show in logs. Defaults to None.
reconnect_attempts (Optional[int
]) – The amount of times connection with the node will be reattempted before giving up.
Set to -1 for infinite. Defaults to 3.
Removes a node.
node (Node
) – The node to remove from the list.
Returns a Lavalink.py-friendly region from a nextcord voice server address.
endpoint (str
) – The address of the nextcord voice server.
Optional[str
]
Represents the player manager that contains all the players.
Returns the total amount of cached players.
Returns an iterator of all the players cached.
Cache of all the players that Lavalink has created.
dict
The player that the player manager is initialized with.
Removes a player from cache, and also Lavalink if applicable. Ensure you have disconnected the given guild_id from the voicechannel first, if connected.
Warning
This should only be used if you know what you’re doing. Players should never be
destroyed unless they have been moved to another Node
.
guild_id (int) – The guild_id associated with the player to remove.
Returns an iterator that yields only values.
Returns a list of players that match the given predicate.
predicate (Optional[function
]) – A predicate to return specific players. Defaults to None.
List[DefaultPlayer
]
Removes a player from the internal cache.
guild_id (int
) – The player that will be removed.
Gets a player from cache.
guild_id (int
) – The guild_id associated with the player to get.
Optional[DefaultPlayer
]
Creates a player if one doesn’t exist with the given information.
If node is provided, a player will be created on that node. If region is provided, a player will be created on a node in the given region. If endpoint is provided, Lavalink.py will attempt to parse the region from the endpoint and return a node in the parsed region.
If node, region and endpoint are left unspecified, or region/endpoint selection fails, Lavalink.py will fall back to the node with the lowest penalty.
Region can be omitted if node is specified and vice-versa.
guild_id (int
) – The guild_id to associate with the player.
region (str
) – The region to use when selecting a Lavalink node. Defaults to eu.
endpoint (str
) – The address of the nextcord voice server. Defaults to None.
node (Node
) – The node to put the player on. Defaults to None and a node with the lowest penalty is chosen.
Represents the stats of Lavalink node.
How long the node has been running for in milliseconds.
int
The amount of players connected to the node.
int
The amount of players that are playing in the node.
int
The amount of memory free to the node.
int
The amount of memory that is used by the node.
int
The amount of memory allocated to the node.
int
The amount of memory reservable to the node.
int
The amount of cpu cores the system of the node has.
int
The overall CPU load of the system.
int
The CPU load generated by Lavalink.
int
The number of frames sent to nextcord.
Warning
Given that audio packets are sent via UDP, this number may not be 100% accurate due to dropped packets.
int
The number of frames that yielded null, rather than actual data.
int
The number of missing frames. Lavalink generates this figure by calculating how many packets to expect
per minute, and deducting frames_sent
. Deficit frames could mean the CPU is overloaded, and isn’t
generating frames as quickly as it should be.
int
Formats the given time into HH:MM:SS.
time (int
) – The time in milliseconds.
str
Parses the given time into days, hours, minutes and seconds. Useful for formatting time yourself.
time (int
) – The time in milliseconds.
Tuple[int
, int
, int
, int
]
Decodes a base64 track string into an AudioTrack object.
track (str
) – The base64 track string.
decode_errors (str
) – The action to take upon encountering erroneous characters within track titles.