Reference#

Pool#

class discord.ext.lava.Pool#

nodes: dict[str, discord.ext.lava.node.Node[Bot, Player]] = {}#: A mapping of node identifiers to nodes that are attached to this pool.

classmethod await create_node(*, bot: Bot, provider: Provider, identifier: str, host: Optional[str] = None, port: Optional[str] = None, ws_url: Optional[str] = None, ws_path: Optional[str] = None, rest_url: Optional[str] = None, password: Optional[str] = None, json_dumps: Optional[Callable[[...], str]] = None, json_loads: Optional[Callable[[...], dict[str, Any]]] = None, spotify_client_id: Optional[str] = None, spotify_client_secret: Optional[str] = None, session: Optional[ClientSession] = None) → Node[Bot, Player]#

Creates a new node, connects it to its provider server, and adds it to the pool.

Note

You must set either the host and port or ws_url and rest_url parameters.

Parameters:

bot – The bot instance that this node should be attached to.
provider – An enum representing which external application this node will use, such as obsidian or lavalink.
identifier – A unique identifier for this node.
host – The host that this node will use for WebSocket connections and HTTP requests. If you want to construct a ws_url and rest_url yourself, you can pass None for this parameter.
port – The port that this node will use for WebSocket connections and HTTP requests. If you want to construct a ws_url and rest_url yourself, you can pass None for this parameter.
ws_url – The url that will be used to connect to the websocket. Constructing this url manually is optional and will override the host and port parameters.
ws_path – The path that will be used to connect to the websocket. Optional, if None, the default path for the selected provider will be used.
rest_url – The url that will be used to make HTTP requests. Constructing this url manually is optional and will override the host and port parameters.
password – The password to use for connections with the provider server. Optional, if the provider does not require a password you can omit this parameter or pass None.
json_dumps – The callable that will be used to serialize JSON data. Optional, if None, the built-in json.dumps will be used.
json_loads – The callable that will be used to deserialize JSON data. Optional, if None, the built-in json.loads will be used.
spotify_client_id – The spotify client ID to use with the builtin spotify integration. Optional, if None, spotify support will be disabled.
spotify_client_secret – The spotify client secret to use with the builtin spotify integration. Optional, if None, spotify support will be disabled.
session – The aiohttp session to use for WebSocket connections and HTTP requests. Optional, if None, a new session will be created.

Raises:

ValueError – If you don’t provide either host and port or ws_url and rest_url.
NodeAlreadyExists – If a node with the given identifier already exists.
InvalidNodePassword – If the password provided did not match the password required by the provider server.
NodeConnectionError – If the node could not connect to the provider server.

Return type:

Node

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

Retrieves the node with the given identifier from the pool, or a random one if an identifier is not provided.

Parameters:

identifier – The identifier of the node to return. Optional, if None, a random node will be returned.

Raises:

NoNodesConnected – If there are no nodes attached to the pool.
NodeNotFound – If there are no nodes with the given identifier in the pool.

Return type:

Node

classmethod await remove_node(identifier: str) → None#

Removes the node with the given identifier from the pool. This also calls the nodes Node.disconnect() method which in turn calls each player’s Player.disconnect() method.

Parameters:: identifier – The identifier of the node to remove.

Node#

class discord.ext.lava.Node(*, bot: Bot, provider: Provider, identifier: str, host: Optional[str] = None, port: Optional[str] = None, ws_url: Optional[str] = None, ws_path: Optional[str] = None, rest_url: Optional[str] = None, password: Optional[str] = None, json_dumps: Optional[Callable[[...], str]] = None, json_loads: Optional[Callable[[...], dict[str, Any]]] = None, spotify_client_id: Optional[str] = None, spotify_client_secret: Optional[str] = None, session: Optional[ClientSession] = None)#

A Node handles the interactions between your bot and a provider server such as obsidian or lavalink. These interactions include connecting to the websocket, searching for tracks, and managing player state.

See Pool.create_node() for more information about creating a node.

property bot: Bot#: The bot instance that this node is attached to.

property provider: Provider#: An enum representing which external application this node is using, such as obsidian or lavalink.

property identifier: str#: This node’s unique identifier.

property players: dict[int, Player]#: A mapping of guild id to player instance that this node is managing.

is_connected() → bool#: Returns True if this node is connected to its websocket, False if it is not.

await connect() → None#: Connects this node to its provider server.

await disconnect() → None#: Disconnects this node from its provider server.

await search(search: str, /, *, source: Source = Source.NONE, **extras: Any) → Search#

Requests search results from this node’s provider server, or other services like spotify.

Parameters:

search (str) – The search query.
source (Source) – The source to request results from. Defaults to Source.NONE.

Raises:

NoResultsFound – If no results were found.
SearchFailed – If the search failed.
HTTPError – If the HTTP request failed.

Return type:

Search

Player#

class discord.ext.lava.Player(client: ~discord.ext.commands.Bot = <MISSING>, channel: ~discord.VoiceChannel | ~discord.StageChannel = <MISSING>, /, *, node: ~typing.Optional[~discord.ext.lava.node.Node[~discord.ext.commands.Bot, ~discord.ext.lava.Player]] = None)#

property bot: Bot#: The bot instance that this player is attached to.

property voice_channel: VoiceChannel | StageChannel#: The voice channel that this player is connected to.

property node: Node[Bot, Player]#: The node that this player is attached to.

property current_track_id: str | None#: The ID of the current track. This is None if no track is playing.

property current: discord.ext.lava.objects.track.Track | None#: The current track. This is None if no track is playing.

property paused: bool#: Whether the player is paused. True if paused, False if not.

property position: float#: The position of the player. Returns 0.0 if no track is playing.

property filter: discord.ext.lava.objects.filters.filter.Filter | None#: The players current filter. This is None if no filter has been set yet.

property listeners: list[discord.member.Member]#: Returns a list of non bot members in the players voice channel who are also not deafened.

is_connected() → bool#: Whether the player is connected to a voice channel. True if connected, False if not.

is_playing() → bool#: Whether the player is playing a track. True if playing, False otherwise.

is_paused() → bool#: Whether the player is paused. True if paused, False otherwise.

await connect(*, timeout: Optional[float] = None, reconnect: Optional[bool] = None, self_mute: bool = False, self_deaf: bool = True) → None#

Connects the player to its voice channel.

Parameters:

timeout – Unused parameter, does nothing.
reconnect – Unused parameter, does nothing.
self_mute – True if the player should be muted when connected. Defaults to False.
self_deaf – True if the player should be deafened when connected. Defaults to True.

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

Disconnects the player from its voice channel and removes it from the node.

Parameters:: force – True if the player should send a request to the provider server to stop the current track even if one is not playing. Defaults to False.

await play(track: Track, /, *, start_time: Optional[int] = None, end_time: Optional[int] = None, no_replace: bool = False) → None#

Plays the given track.

Parameters:

track – The track to play.
start_time – The start time of the track in milliseconds. Defaults to None.
end_time – The end time of the track in milliseconds. Defaults to None.
no_replace – True if this track should not replace the current track, if any. Defaults to False.

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

Stops the current track.

Parameters:: force – True if the player should send the stop track request to the provider server even if this player’s current attribute is None. Defaults to False.

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

Sets the players pause state.

Parameters:: pause – True if the player should be paused, False otherwise.

await set_filter(filter: Filter, /, *, set_position: bool = True) → None#

Sets the players filter.

Parameters:

filter – The filter to set.
set_position – True if the player should set its position to the current position which applies filters instantly. Defaults to True.

await set_position(position: float, /, *, force: bool = False) → None#

Sets the players position.

Parameters:

position – The position to set, in milliseconds.
force – True if the player should send the set position request to the provider server even if this player’s current attribute is None. Defaults to False.

Queue#

class discord.ext.lava.Queue#

property loop_mode: QueueLoopMode#: Returns the current queue loop mode.

set_loop_mode(mode: QueueLoopMode, /) → None#

Sets the queue loop mode.

Parameters:: mode – The loop mode to set.

property length: int#: Returns the amount of items in the queue.

is_empty() → bool#: Returns True if the queue is empty, False if not.

clear() → None#: Removes all items from the queue.

reverse() → None#: Reverses the order of the items in the queue.

shuffle() → None#: Shuffles the items in the queue.

reset() → None#: Clears the queue and resets it internal state.

get_from_front(*, put_into_history: bool = True) → Track#

Removes and returns the first item in the queue.

This method also:

Adds the item to the queue history if put_into_history is True.
Puts the item back into the queue at the front if Queue.loop_mode is QueueLoopMode.CURRENT.
Puts the item back into the queue at the end if Queue.loop_mode is QueueLoopMode.ALL.

Parameters:: put_into_history – Whether the item should be added to the queue history. Optional, defaults to True.
Raises:: IndexError – If the queue is empty.
Return type:: Track

get_from_position(position: int, /, *, put_into_history: bool = True) → Track#

Removes and returns an item at the given position from the queue.

The note from Queue.get_from_front() also applies here.

Parameters:

position – The position of the item to remove and return.
put_into_history – Whether the item should be added to the queue history. Optional, defaults to True.

Raises:

IndexError – If there is no item at the given position.

Return type:

Track

await wait_for_item(*, put_into_history: bool = True) → Track#

Waits until an item has been added to the queue and returns it.

Parameters:: put_into_history – Whether the item should be added to the queue history. Optional, defaults to True.

put_at_front(*, item: QueueItemT | None = None, items: list[QueueItemT] | None = None) → None#

Puts an item, or items, into the front of the queue.

Parameters:

item – The item to put into the queue.
items – The items to put into the queue.

Warning

Only one of item and items can be specified.

Raises:: ValueError – If both or none of item and items are specified.

put_at_position(position: int, /, *, item: QueueItemT | None = None, items: list[QueueItemT] | None = None) → None#

Puts an item, or items, into the queue at the given position.

Parameters:

position – The position to insert the item or items at.
item – The item to put into the queue.
items – The items to put into the queue.

Warning

Only one of item and items can be specified.

Raises:: ValueError – If both or none of item and items are specified.

put_at_end(*, item: QueueItemT | None = None, items: list[QueueItemT] | None = None) → None#

Puts an item (or items) at the end of the queue.

Parameters:

item – The item to put into the queue.
items – The items to put into the queue.

Warning

Only one of item and items can be specified.

Raises:: ValueError – If both or none of item and items are specified.

get_from_history(*, position: int) → Track#

Get the item at the given position from the queue history.

Parameters:: position – The position of the item to get from the queue history.
Raises:: IndexError – If there is no item at the given position.
Return type:: Track

pop_from_history(*, position: int) → Track#

Removes and returns the item at the given position from the queue history.

Parameters:: position – The position of the item to remove and return from the queue history.
Raises:: IndexError – If there is no item at the given position.
Return type:: Track

put_into_history(*, position: int | None = None, item: QueueItemT | None = None, items: list[QueueItemT] | None = None) → None#

Puts an item, or items, into the queue history at the given position.

Parameters:

position – The position to insert the item or items at. Optional, defaults to None which adds the item(s) to the end of the history. (which means they will be fetched first by Queue.get_from_history())
item – The item to put into the queue history.
items – The items to put into the queue history.

Warning

Only one of item and items can be specified.

Raises:: ValueError – If both or none of item and items are specified.

Objects#

Track#

class discord.ext.lava.Track(*, id: str, info: dict[str, Any], extras: Optional[dict[str, Any]] = None)#

id: str#

title: str#

author: str#

uri: str#

identifier: str#

length: int#

position: int#

source: Source#

isrc: str | None#

extras: dict[str, Any]#

property artwork_url: str | None#

is_stream() → bool#

is_seekable() → bool#

Collection#

class discord.ext.lava.Collection(*, info: dict[str, Any], tracks: list[dict[str, Any]], extras: Optional[dict[str, Any]] = None)#

property name: str#

property url: str#

property selected_track: discord.ext.lava.objects.track.Track | int | None#

property tracks: list[discord.ext.lava.objects.track.Track]#

property source: Source#

Search#

class discord.ext.lava.Search(*, source: Source, type: str, result: spotipy.objects.album.Album | spotipy.objects.playlist.Playlist | spotipy.objects.artist.Artist | spotipy.objects.track.Track | list[discord.ext.lava.objects.track.Track] | discord.ext.lava.objects.collection.Collection, tracks: list[discord.ext.lava.objects.track.Track])#

property source: Source#

property type: str#

property result: spotipy.objects.album.Album | spotipy.objects.playlist.Playlist | spotipy.objects.artist.Artist | spotipy.objects.track.Track | list[discord.ext.lava.objects.track.Track] | discord.ext.lava.objects.collection.Collection#

property tracks: list[discord.ext.lava.objects.track.Track]#

Events#

TrackStart#

class discord.ext.lava.TrackStart(data: dict[str, Any])#

property track_id: str#

TrackEnd#

class discord.ext.lava.TrackEnd(data: dict[str, Any])#

property track_id: str#

property reason: Literal['STOPPED', 'REPLACED', 'CLEANUP', 'LOAD_FAILED', 'FINISHED']#

TrackStuck#

class discord.ext.lava.TrackStuck(data: dict[str, Any])#

property track_id: str#

property threshold_ms: int#

TrackException#

class discord.ext.lava.TrackException(data: dict[str, Any])#

property track_id: str#

property message: str#

property cause: str#

property severity: Literal['COMMON', 'FAULT', 'SUSPICIOUS']#

WebsocketOpen#

class discord.ext.lava.WebsocketOpen(data: dict[str, Any])#

property target: str#

property ssrc: int#

WebsocketClosed#

class discord.ext.lava.WebsocketClosed(data: dict[str, Any])#

property code: int#

property reason: str#

property by_remote: bool#

Filters#

ChannelMix#

class discord.ext.lava.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)#

left_to_left: float#

left_to_right: float#

right_to_left: float#

right_to_right: float#

classmethod mono() → ChannelMix#

classmethod only_left() → ChannelMix#

classmethod full_left() → ChannelMix#

classmethod only_right() → ChannelMix#

classmethod full_right() → ChannelMix#

classmethod switch() → ChannelMix#

Distortion#

class discord.ext.lava.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)#

sin_offset: float#

sin_scale: float#

cos_offset: float#

cos_scale: float#

tan_offset: float#

tan_scale: float#

offset: float#

scale: float#

Equalizer#

class discord.ext.lava.Equalizer(*, name: str = 'CustomEqualizer', bands: list[tuple[int, float]])#

name: str#

bands: list[discord.ext.lava.objects.filters.equalizer.EqualizerBandData]#

Karaoke#

class discord.ext.lava.Karaoke(*, level: float = 1.0, mono_level: float = 1.0, band: float = 220.0, band_width: float = 100.0)#

level: float#

mono_level: float#

band: float#

band_width: float#

LowPass#

class discord.ext.lava.LowPass(*, smoothing: float = 20.0)#

smoothing: float#

Rotation#

class discord.ext.lava.Rotation(*, speed: float = 5.0)#

speed: float#

Timescale#

class discord.ext.lava.Timescale(*, pitch: float = 1.0, speed: float = 1.0, rate: float = 1.0)#

pitch: float#

speed: float#

rate: float#

Tremolo#

class discord.ext.lava.Tremolo(*, frequency: float = 2.0, depth: float = 0.5)#

frequency: float#

depth: float#

Vibrato#

class discord.ext.lava.Vibrato(*, frequency: float = 2.0, depth: float = 0.5)#

frequency: float#

depth: float#

Volume#

class discord.ext.lava.Volume(*, level: float = 100.0)#

level: float#

Filter#

class discord.ext.lava.Filter(filter: Optional[Filter] = None, channel_mix: Optional[ChannelMix] = None, distortion: Optional[Distortion] = None, equalizer: Optional[Equalizer] = None, karaoke: Optional[Karaoke] = None, low_pass: Optional[LowPass] = None, rotation: Optional[Rotation] = None, timescale: Optional[Timescale] = None, tremolo: Optional[Tremolo] = None, vibrato: Optional[Vibrato] = None, volume: Optional[Volume] = None)#

filter: discord.ext.lava.objects.filters.filter.Filter | None#

channel_mix: discord.ext.lava.objects.filters.channel_mix.ChannelMix | None#

distortion: discord.ext.lava.objects.filters.distortion.Distortion | None#

equalizer: discord.ext.lava.objects.filters.equalizer.Equalizer | None#

karaoke: discord.ext.lava.objects.filters.karaoke.Karaoke | None#

low_pass: discord.ext.lava.objects.filters.low_pass.LowPass | None#

rotation: discord.ext.lava.objects.filters.rotation.Rotation | None#

timescale: discord.ext.lava.objects.filters.timescale.Timescale | None#

tremolo: discord.ext.lava.objects.filters.tremolo.Tremolo | None#

vibrato: discord.ext.lava.objects.filters.vibrato.Vibrato | None#

volume: discord.ext.lava.objects.filters.volume.Volume | None#

Enums#

Provider#

class discord.ext.lava.Provider(value)#

An enumeration.

OBSIDIAN = 0#

LAVALINK = 1#

QueueLoopMode#

class discord.ext.lava.QueueLoopMode(value)#

An enumeration.

DISABLED = 0#

ALL = 1#

CURRENT = 2#

Source#

class discord.ext.lava.Source(value)#

An enumeration.

BANDCAMP = 'bandcamp'#

YARN = 'getyarn.io'#

HTTP = 'http'#

LOCAL = 'local'#

NICO = 'niconico'#

SOUNDCLOUD = 'soundcloud'#

TWITCH = 'twitch'#

VIMEO = 'vimeo'#

YOUTUBE = 'youtube'#

YOUTUBE_MUSIC = 'youtube_music'#

SPOTIFY = 'spotify'#

UNKNOWN = 'unknown'#

NONE = ''#

Exceptions#

LavaError#

exception discord.ext.lava.LavaError#

NodeAlreadyExists#

exception discord.ext.lava.NodeAlreadyExists#

NodeNotFound#

exception discord.ext.lava.NodeNotFound#

NoNodesConnected#

exception discord.ext.lava.NoNodesConnected#

NodeAlreadyConnected#

exception discord.ext.lava.NodeAlreadyConnected#

NodeConnectionError#

exception discord.ext.lava.NodeConnectionError#

InvalidPassword#

exception discord.ext.lava.InvalidPassword#

NodeNotConnected#

exception discord.ext.lava.NodeNotConnected#

HTTPError#

exception discord.ext.lava.HTTPError(response: ClientResponse, message: str)#

property response: ClientResponse#

property message: str#

NoResultsFound#

exception discord.ext.lava.NoResultsFound(*, search: str, source: Source, type: str)#

property search: str#

property source: Source#

property type: str#

SearchFailed#

exception discord.ext.lava.SearchFailed(data: dict[str, Any])#

property message: str#

property severity: Literal['COMMON', 'FAULT', 'SUSPICIOUS']#

Utils#

SPOTIFY_URL_REGEX#

discord.ext.lava.SPOTIFY_URL_REGEX#

A regex that matches spotify URLs for tracks, albums, playlists, and artists.

MISSING#

discord.ext.lava.MISSING#

A sentinel value that is used to indicate a missing value with distinction from None.