API Reference

await lavalink.initialize(bot: Bot, *, host, password, port: int | None = None, timeout: float = 30, resume_key: str | None = None, resume_timeout: float = 60, secured: bool = False)

Initializes the websocket connection to the lavalink player.

Important

This function must only be called AFTER the bot has received its “on_ready” event!

Parameters:

• bot (Bot) – An instance of a discord.py Bot object.

• host (str) – The hostname or IP address of the Lavalink node.

• password (str) – The password of the Lavalink node.

• port (Optional[int]) – The websocket port on the Lavalink Node. If not provided, it will use 80 for unsecured connections and 443 for secured.

• timeout (float) – Amount of time to allow retries to occur, None is considered forever.

• resume_key (Optional[str]) – A resume key used for resuming a session upon re-establishing a WebSocket connection to Lavalink.

• resume_timeout (float) – How long the node should wait for a connection while disconnected before clearing all players.

• secured (bool) – Whether to use the wss:// and https:// protocol.

await lavalink.connect(channel: VoiceChannel, *, self_deaf: bool = False)

Connects to a discord voice channel.

This is the publicly exposed way to connect to a discord voice channel. The initialize() function must be called first!

Parameters:

• channel (discord.VoiceChannel) – The channel to connect to.

• self_deaf (bool) – Whether to deafen the bot user upon join.

Returns:

The created Player object.

Return type:

Player

Raises:

IndexError – If there are no available lavalink nodes ready to connect to discord.

lavalink.get_player(guild_id: int) → Player

lavalink.register_event_listener(coro)

Registers a coroutine to receive lavalink event information.

This coroutine will accept three arguments: Player, LavalinkEvents, and possibly an extra. The value of the extra depends on the value of the second argument.

If the second argument is LavalinkEvents.TRACK_END, the extra will be a TrackEndReason.

If the second argument is LavalinkEvents.TRACK_EXCEPTION, the extra will be a dictionary with message, cause, and severity keys.

If the second argument is LavalinkEvents.TRACK_STUCK, the extra will be the threshold milliseconds that the track has been stuck for.

If the second argument is LavalinkEvents.TRACK_START, the extra will be a track identifier string.

If the second argument is any other value, the third argument will not exist.

Parameters:

coro – A coroutine function that accepts the arguments listed above.

Raises:

TypeError – If coro is not a coroutine.

lavalink.register_update_listener(coro)

Registers a coroutine to receive lavalink player update information.

This coroutine will accept a two arguments: an instance of Player and an instance of PlayerState.

Parameters:

coro –

Raises:

TypeError – If coro is not a coroutine.

lavalink.register_stats_listener(coro)

Registers a coroutine to receive lavalink server stats information.

This coroutine will accept a single argument which will be an instance of Stats.

Parameters:

coro –

Raises:

TypeError – If coro is not a coroutine.

lavalink.unregister_event_listener(coro)

Unregisters coroutines from being event listeners.

Parameters:

coro –

lavalink.unregister_update_listener(coro)

Unregisters coroutines from being player update listeners.

Parameters:

coro –

lavalink.unregister_stats_listener(coro)

Unregisters coroutines from being server stats listeners.

Parameters:

coro –

await lavalink.close(bot)

Closes the lavalink connection completely.

lavalink.utils.format_time(time)

Formats the given time into HH:MM:SS

Enums

class lavalink.LavalinkEvents(value)

An enumeration of the Lavalink Track Events.

FORCED_DISCONNECT = 'ForcefulDisconnectEvent'

Connection has been disconnect, do not attempt to reconnect.

QUEUE_END = 'QueueEndEvent'

This is a custom event generated by this library to denote the end of all tracks in the queue.

TRACK_END = 'TrackEndEvent'

The track playback has ended.

TRACK_EXCEPTION = 'TrackExceptionEvent'

There was an exception during track playback.

TRACK_START = 'TrackStartEvent'

The track playback started.

TRACK_STUCK = 'TrackStuckEvent'

Track playback got stuck during playback.

WEBSOCKET_CLOSED = 'WebSocketClosedEvent'

Websocket has been closed.

class lavalink.TrackEndReason(value)

The reasons why track playback has ended.

CLEANUP = 'CLEANUP'

The track was stopped because the cleanup threshold for the audio player was reached.

FINISHED = 'FINISHED'

The track reached the end, or the track itself ended with an exception.

LOAD_FAILED = 'LOAD_FAILED'

The track failed to start, throwing an exception before providing any audio.

REPLACED = 'REPLACED'

The track stopped playing because a new track started playing.

STOPPED = 'STOPPED'

The track was stopped due to the player being stopped.

class lavalink.PlayerState(value)

An enumeration.

class lavalink.Stats(memory, players, active_players, cpu, uptime)

Player

class lavalink.Player(client: Client, channel: VoiceChannel | StageChannel)

The Player class represents the current state of playback. It also is used to control playback and queue tracks.

The existence of this object guarantees that the bot is connected to a voice channel.

channel

The channel the bot is connected to.

Type:

discord.VoiceChannel

queue

Type:

list of Track

position

The seeked position in the track of the current playback.

Type:

int

current

Type:

Track

repeat

Type:

bool

shuffle

Type:

bool

add(requester: User, track: Track) → None

Adds a track to the queue.

Parameters:

• requester (discord.User) – User who requested the track.

• track (Track) – Result from any of the lavalink track search methods.

cleanup() → None

This method must be called to ensure proper clean-up during a disconnect.

It is advisable to call this from within disconnect() when you are completely done with the voice protocol instance.

This method removes it from the internal state cache that keeps track of currently alive voice clients. Failure to clean-up will cause subsequent connections to report that it’s still connected.

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

Connects to the voice channel associated with this Player.

property connected: bool

Whether the player is ready to be used.

await disconnect(*, force: bool = False) → None

Disconnects this player from it’s voice channel.

fetch(key: Any, default: Any | None = None) → Any

Returns a stored metadata value.

Parameters:

• key – Key used to store metadata.

• default – Optional, used if the key doesn’t exist.

await get_tracks(query) → Tuple[Track, ...]

Gets tracks from lavalink.

Parameters:

query (str) –

Return type:

Tuple[Track, …]

await handle_event(event: node.LavalinkEvents, extra) → None

Handles various Lavalink Events.

If the event is TRACK END, extra will be TrackEndReason.

If the event is TRACK EXCEPTION, extra will be the string reason.

If the event is TRACK STUCK, extra will be the threshold ms.

Parameters:

• event (node.LavalinkEvents) –

• extra –

await handle_player_update(state: node.PositionTime) → None

Handles player updates from lavalink.

Parameters:

state (websocket.PlayerState) –

property is_auto_playing: bool

Current status of playback

property is_playing: bool

Current status of playback

await load_tracks(query) → LoadResult

Executes a loadtracks request. Only works on Lavalink V3.

Parameters:

query (str) –

Return type:

LoadResult

await move_to(channel: VoiceChannel, *, self_deaf: bool = False) → None

Moves this player to a voice channel.

Parameters:

• channel (discord.VoiceChannel) –

• self_deaf (bool) –

await on_voice_server_update(data: dict, /) → None

An abstract method that is called when initially connecting to voice. This corresponds to VOICE_SERVER_UPDATE.

Parameters:

data (dict) – The raw :ddocs:`voice server update payload <topics/gateway-events#voice-server-update>`.

await on_voice_state_update(data: dict, /) → None

An abstract method that is called when the client’s voice state has changed. This corresponds to VOICE_STATE_UPDATE.

Warning

This method is not the same as the event. See: on_voice_state_update()

Parameters:

data (dict) – The raw :ddocs:`voice state payload <resources/voice#voice-state-object>`.

await pause(pause: bool = True, *, timed: int | None = None) → None

Pauses the current song.

Parameters:

• pause (bool) – Set to False to resume.

• timed (Optional[int]) – If an int is given the op will be called after it.

property paused: bool

Player’s paused state.

await play() → None

Starts playback from lavalink.

property ready: bool

Whether the underlying node is ready for requests.

await search_sc(query) → LoadResult

Gets track results from SoundCloud from Lavalink.

Parameters:

query (str) –

Return type:

list of Track

await search_yt(query) → LoadResult

Gets track results from YouTube from Lavalink.

Parameters:

query (str) –

Return type:

list of Track

await seek(position: int) → None

If the track allows it, seeks to a position.

Parameters:

position (int) – Between 0 and track length.

await set_volume(volume: int) → None

Sets the volume of Lavalink.

Parameters:

volume (int) – Between 0 and 150

await skip() → None

Skips to the next song.

await stop() → None

Stops playback from lavalink.

Important

This method will clear the queue.

store(key: Any, value: Any) → None

Stores a metadata value by key.

property volume: int

The current volume.

await wait_until_ready(*, timeout: float | None = None, no_raise: bool = False) → bool

Waits for the underlying node to become ready.

If no_raise is set, returns false when a timeout occurs instead of propogating TimeoutError. A timeout of None means to wait indefinitely.

Node

class lavalink.Node(*, event_handler: Callable, host: str, password: str, user_id: int, num_shards: int, port: int | None = None, resume_key: str | None = None, resume_timeout: float = 60, bot: Bot | None = None, secured: bool = False)

await connect(timeout: float | None = None, *, shutdown: bool = False)

Connects to the Lavalink player event websocket.

Parameters:

• timeout (float) – Time after which to timeout on attempting to connect to the Lavalink websocket, None is considered never, but the underlying code may stop trying past a certain point.

• shutdown (bool) – Whether the node was told to shut down

Raises:

• asyncio.TimeoutError – If the websocket failed to connect after the given time.

• AbortingNodeConnection – If the connection attempt must be aborted during a reconnect attempt

await create_player(channel: VoiceChannel | StageChannel, *, self_deaf: bool = False) → Player

Connects to a discord voice channel.

This function is safe to repeatedly call as it will return an existing player if there is one.

Parameters:

• channel (VoiceChannel) –

• self_deaf (bool) –

Returns:

The created Player object.

Return type:

Player

await disconnect()

Shuts down and disconnects the websocket.

get_player(guild_id: int) → Player

Gets a Player object from a guild ID.

Parameters:

guild_id (int) – Discord guild ID.

Return type:

Player

Raises:

KeyError – If that guild does not have a Player, e.g. is not connected to any voice channel.

await listener()

Listener task for receiving ops from Lavalink.

property ready: bool

Whether the underlying node is ready for requests.

Data Classes

class lavalink.Track(data)

Information about a Lavalink track.

requester

The user who requested the track.

Type:

discord.User

track_identifier

Track identifier used by the Lavalink player to play tracks.

Type:

str

seekable

Boolean determining if seeking can be done on this track.

Type:

bool

author

The author of this track.

Type:

str

length

The length of this track in milliseconds.

Type:

int

is_stream

Determines whether Lavalink will stream this track.

Type:

bool

position

Current seeked position to begin playback.

Type:

int

title

Title of this track.

Type:

str

uri

The playback url of this track.

Type:

str

start_timestamp

The track start time in milliseconds as provided by the query.

Type:

int

property thumbnail

Returns a thumbnail URL for YouTube tracks.

Type:

Optional[str]