pylav.nodes package

Subpackages

Submodules

pylav.nodes.manager module

class pylav.nodes.manager.NodeManager(client, external_host=None, external_password=None, external_port=None, external_ssl=False)[source]

Bases: object

Manages nodes and their connections to the client.

async add_node(*, host, port, password, unique_identifier, name, resume_timeout=60, reconnect_attempts=-1, ssl=False, search_only=False, disabled_sources=None, managed=False, yaml=None, extras=None, temporary=False)[source]

Adds a node to PyLav’s node manager.

Parameters:
  • 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.

  • resume_timeout (Optional[:class:`int]`) – How long the node should wait for a connection while disconnected before clearing all players. Defaults to 60.

  • name (str) – An identifier for the node that will show in logs. Defaults to None.

  • reconnect_attempts (Optional[:class:`int]`) – The amount of times connection with the node will be reattempted before giving up. Set to -1 for infinite. Defaults to 3.

  • ssl (Optional[:class:`bool]`) – Whether to use a ssl connection. Defaults to False.

  • search_only (bool) – Whether the node is search only. Defaults to False.

  • unique_identifier (Optional[:class:`str]`) – A unique identifier for the node. Defaults to None.

  • disabled_sources (Optional[:class:`list`[:class:`str]]`) – A list of sources to disable. Defaults to None.

  • managed (Optional[:class:`bool]`) – Whether the node is managed by the client. Defaults to False.

  • yaml (Optional[:class:`dict]`) – A dictionary of node settings. Defaults to None.

  • extras (Optional[:class:`dict]`) – A dictionary of extra settings. Defaults to {}.

  • temporary (bool) – Whether the node is temporary. Defaults to False. Temporary nodes are not added to the db.

Returns:

The node that was added.

Return type:

Node

property available_nodes

Returns a list of available nodes

property client

Returns the client

async close()[source]

Disconnects all nodes and closes the session.

async connect_to_all_nodes()[source]

Connects to all nodes.

async find_best_node(region=None, not_region=None, feature=None, already_attempted_regions=None, coordinates=None, wait=False, attempt=0, backoff=None)[source]

Finds the best (least used) node in the given region, if applicable. :param region: The region to use. :type region: str :param not_region: The region to exclude. :type not_region: str :param feature: The feature required. :type feature: str :param already_attempted_regions: A set of regions that have already been attempted. :type already_attempted_regions: set`[:class:`str] :param coordinates: The coordinates to use. :type coordinates: tuple`[:class:`float, float] :param wait: Whether to wait for a node to become available. :type wait: bool :param attempt: The current attempt number. :type attempt: int :param backoff: The backoff to use. :type backoff: ExponentialBackoffWithReset

Return type:

Optional[:class:`Node]`

get_closest_node(region)[source]

Returns the closest node to a given region. :param region: The region to use. :type region: str

Return type:

Node

get_node_by_id(unique_identifier)[source]

Returns a node by its unique identifier. :param unique_identifier: The unique identifier of the node. :type unique_identifier: int

Return type:

Optional[:class:`Node]`

get_region(endpoint)[source]

Returns a region from a Discord voice server address. :param endpoint: The address of the Discord voice server. :type endpoint: str

Return type:

Optional[:class:`str]`

property managed_nodes

Returns a list of nodes that are managed by the client

async node_connect(node)[source]

Called when a node is connected from Lavalink. :param node: The node that has just connected. :type node: Node

async node_disconnect(node, code, reason)[source]

Called when a node is disconnected from Lavalink. :param node: The node that has just connected. :type node: Node :param code: The code for why the node was disconnected. :type code: int :param reason: The reason why the node was disconnected. :type reason: str

property nodes

Returns a list of all nodes

property player_queue

Returns a list of players that are queued to be played

async remove_node(node)[source]

Removes a node. :param node: The node to remove from the list. :type node: Node

property search_only_nodes

Returns a list of nodes that are search only

property session

Returns the aiohttp session used by the client

async wait_until_ready(timeout=None)[source]

Wait until all nodes are ready.

pylav.nodes.node module

class pylav.nodes.node.Node(manager, host, password, resume_timeout, port=None, name=None, reconnect_attempts=-1, ssl=False, search_only=False, unique_identifier=None, disabled_sources=None, managed=False, extras=None, temporary=False)[source]

Bases: object

Represents a Node connection with Lavalink.

Note

Nodes are NOT meant to be added manually, but rather with Client.add_node().

property api_version

The API version of the node.

property available

Returns whether the node is available for requests

property base_api_url

Returns the base API URL of the target node.

property base_url

Returns the base URL of the target node.

property base_ws_url

Returns the base WebSocket URL of the target node.

property can_resume

Returns whether the node can be resumed

property capabilities

Returns the capabilities of the target node.

Returns:

The capabilities of the target node.

Return type:

set

async close()[source]

Closes the target node.

property config

The config of the node.

property connected_count

Returns the number of players on this node that are connected

property connected_players

Returns a list of all players on this node that are connected

property connection_protocol

The protocol used for the connection

property coordinates

The coordinates of the node.

Returns:

The coordinates of the node.

Return type:

tuple

property count

Returns the number of players on this node

async delete_session_player(guild_id)[source]

Deletes the player associated with the target node and the given guild ID.

async delete_session_player_sponsorblock_categories(guild_id)[source]

Deletes the sponsorblock categories for the player associated with the target node and the given guild ID.

property disabled_sources

Returns the disabled sources of the target node.

Returns:

The disabled sources of the target node.

Return type:

set

dispatch_event(event)[source]

Dispatches the given event to all registered hooks. :param event: The event to dispatch to the hooks. :type event: Event

down_unvote(player)[source]

Removes a down vote for this node

down_vote(player)[source]

Adds a down vote for this node

property down_votes

Returns the down votes for this node

async fetch_api_version()[source]

Fetches the API version response from the target node.

async fetch_current_lyrics(guild_id, skipTrackSource=False, raise_on_error=False)[source]

Fetches the lyrics for the current track from the target node.

async fetch_decodetrack(encoded_track, timeout=_SENTINEL.sentinel, raise_on_failure=True)[source]

Fetches the decodetrack response from the target node.

async fetch_info(raise_on_error=False)[source]

Fetches the info response from the target node.

async fetch_loadsearch(query)[source]
async fetch_loadtracks(query)[source]

Fetches the loadtracks response from the target node.

async fetch_lyrics(encodedTrack, skipTrackSource=False, raise_on_error=False)[source]

Fetches the lyrics for the specified track.

async fetch_node_version()[source]

Fetches the version response from the target node.

async fetch_routeplanner_status()[source]

Fetches the routeplanner status response from the target node.

async fetch_session_player(guild_id)[source]

Gets the player associated with the target node and the given guild ID.

async fetch_session_players()[source]

Gets all players associated with the target node.

Returns:

A list of all players associated with the target node.

Return type:

list[rest_api.LavalinkPlayer]

async fetch_stats(raise_on_error=False)[source]

Fetches the stats response from the target node.

async fetch_version(raise_on_error=False)[source]

Fetches the version response from the target node.

async filters(*, player, volume=None, equalizer=None, karaoke=None, timescale=None, tremolo=None, vibrato=None, rotation=None, distortion=None, low_pass=None, channel_mix=None, echo=None)[source]

Set the filters for a player.

get_endpoint_current_track_lyrics(guild_id)[source]

Get current playing track lyrics.

get_endpoint_decodetrack()[source]

Returns the decodetrack endpoint of the target node.

get_endpoint_decodetracks()[source]

Returns the decodetracks endpoint of the target node.

get_endpoint_info()[source]

Returns the info endpoint of the target node.

get_endpoint_loadseach()[source]

Returns the loadsearch endpoint of the target node.

get_endpoint_loadtracks()[source]

Returns the loadtracks endpoint of the target node.

get_endpoint_routeplanner_free_address()[source]

Returns the routeplanner free address endpoint of the target node.

get_endpoint_routeplanner_free_all()[source]

Returns the routeplanner free all endpoint of the target node.

get_endpoint_routeplanner_status()[source]

Returns the routeplanner status endpoint of the target node.

get_endpoint_session()[source]

Returns the session endpoint of the target node.

get_endpoint_session_player_by_guild_id(guild_id)[source]

Returns the session player endpoint of the target node for the given guild ID.

get_endpoint_session_player_sponsorblock_categories(guild_id)[source]

Returns the session player sponsorblock categories endpoint of the target node for the given guild ID.

get_endpoint_session_players()[source]

Returns the session players endpoint of the target node.

get_endpoint_stats()[source]

Returns the stats endpoint of the target node.

get_endpoint_version()[source]

Returns the version endpoint of the target node.

get_endpoint_websocket()[source]

Returns the WebSocket endpoint of the target node.

get_filter_payload(*, player, volume=None, equalizer=None, karaoke=None, timescale=None, tremolo=None, vibrato=None, rotation=None, distortion=None, low_pass=None, channel_mix=None, reset_no_set=False, reset=False, pluginFilters=None)[source]

Gets the filter payload.

async get_guild_player(guild_id)[source]

Fetches the player for the given guild ID.

async get_lavasearch(query, bypass_cache=False)[source]

Gets the query from LavaSearch. :param query: The query to search for. :type query: str :param bypass_cache: Whether to bypass the cache. :type bypass_cache: bool

Returns:

Lavalink LoadSearch Response Object

Return type:

LavalinkLoadSearchObjects

async get_lavasearch_collection(query, bypass_cache=False, sleep=False, filter=None)[source]

Gets all tracks associated with the given query.

Parameters:
  • query (Query) – The query to perform a search for.

  • filter (Optional[Literal[``”tracks”`` , "albums", "artists", "playlists"]]) – Whether to filter the response to a specific type.

  • bypass_cache (bool) – Whether to bypass the cache.

  • sleep (bool) – Whether to sleep for 1 second before returning the response.

Returns:

Lavalink LoadSearch Response object

Return type:

Optional[rest_api.LoadSearchResponses | list[PlaylistData] | list[Track]]

get_lyrics()[source]

Get lyrics of the specified track.

async get_query_localfiles(query, bypass_cache=True)[source]

Gets the query from Localfiles. :param query: The query to search for. :type query: str :param bypass_cache: Whether to bypass the cache. :type bypass_cache: bool

Returns:

Lavalink LoadTrack Response Object

Return type:

LavalinkLoadTrackObjects

async get_query_speak(query, bypass_cache=False)[source]

Gets the query for speak. :param query: The query to search for. :type query: str :param bypass_cache: Whether to bypass the cache. :type bypass_cache: bool

Returns:

Lavalink LoadTrack Response Object

Return type:

LavalinkLoadTrackObjects

async get_session_player_sponsorblock_categories(guild_id)[source]

Gets the sponsorblock categories for the player associated with the target node and the given guild ID.

async get_track(query, first=False, bypass_cache=False, sleep=False)[source]

Gets all tracks associated with the given query.

Parameters:
  • query (Query) – The query to perform a search for.

  • first (bool) – Whether to return the first result or all results.

  • bypass_cache (bool) – Whether to bypass the cache.

  • sleep (bool) – Whether to sleep for 1 second before returning the response.

Returns:

Lavalink LoadTrack Response object

Return type:

LavalinkLoadTrackObjects

async get_track_from_cache(query, first=False)[source]

Gets a query from the query cache.

async get_unsupported_features()[source]

Returns the unsupported features of the target node.

has_capability(source)

Checks if the target node has the specified source.

Parameters:

source (str) – The source to check.

Returns:

True if the target node has the specified source, False otherwise.

Return type:

bool

has_filter(filter_name)[source]

Checks if the target node has the specified filter.

Parameters:

filter_name (str) – The filter to check.

Returns:

True if the target node has the specified filter, False otherwise.

Return type:

bool

has_source(source)[source]

Checks if the target node has the specified source.

Parameters:

source (str) – The source to check.

Returns:

True if the target node has the specified source, False otherwise.

Return type:

bool

property host

The host of the node

property identifier

The identifier of the Node.

property is_ready

Whether the node is ready or not.

property managed

Whether the node is managed or not.

property name

The name of the node

property node_manager

The NodeManager this node belongs to

async node_monitor_task()[source]

Monitors the node for health and stability.

static parse_loadtrack_response(data)[source]
Parses the loadtrack response.
data: LoadTracksResponseT

The data to parse.

Returns
LavalinkLoadTrackObjects

Lavalink LoadTrack Response Object

property password

The password of the node

async patch_session(payload)[source]

Patches the session associated with the target node.

async patch_session_player(guild_id, no_replace=False, payload=None)[source]

Updates the player associated with the target node and the given guild ID.

property penalty

Returns the load-balancing penalty for this node

async penalty_with_region(region)[source]

The penalty for the node, with the region added in

property players

Returns a list of all players on this node

property playing_count

Returns the number of players on this node that are playing

property playing_players

Returns a list of all players on this node that are playing

property port

The port of the node

async post_decodetracks(encoded_tracks, raise_on_failure=False)[source]

Posts the decodetracks response from the target node.

async post_routeplanner_free_address(address)[source]

Frees the given address from the routeplanner.

async post_routeplanner_free_all()[source]

Frees all addresses from the routeplanner.

async put_session_player_sponsorblock_categories(guild_id, categories)[source]

Sets the sponsorblock categories for the player associated with the target node and the given guild ID.

property reconnect_attempts

The number of attempts to reconnect to the node

property region

The region of the node

async region_distance(region)[source]

Returns the numeric representation of the distance between the target node and the given region.

Parameters:

region (str) – The region to get the distance to.

Returns:

The numeric representation of the distance between the target node and the given region.

Return type:

float

property resume_timeout

The timeout to use for resuming

async search_apple_music(query, bypass_cache=False)[source]

Gets the query from Apple Music. :param query: The query to search for. :type query: str :param bypass_cache: Whether to bypass the cache. :type bypass_cache: bool

Returns:

Lavalink LoadTrack Response Object

Return type:

LavalinkLoadTrackObjects

async search_deezer(query, bypass_cache=False)[source]

Gets the query from Deezer. :param query: The query to search for. :type query: str :param bypass_cache: Whether to bypass the cache. :type bypass_cache: bool

Returns:

Lavalink LoadTrack Response Object

Return type:

LavalinkLoadTrackObjects

property search_only

Whether the node is search only or not.

async search_soundcloud(query, bypass_cache=False)[source]

Gets the query from Soundcloud. :param query: The query to search for. :type query: str :param bypass_cache: Whether to bypass the cache. :type bypass_cache: bool

Returns:

Lavalink LoadTrack Response Object

Return type:

LavalinkLoadTrackObjects

async search_spotify(query, bypass_cache=False)[source]

Gets the query from Spotify. :param query: The query to search for. :type query: str :param bypass_cache: Whether to bypass the cache. :type bypass_cache: bool

Returns:

Lavalink LoadTrack Response Object

Return type:

LavalinkLoadTrackObjects

async search_yandex(query, bypass_cache=False)[source]

Gets the query from Yandex Music. :param query: The query to search for. :type query: str :param bypass_cache: Whether to bypass the cache. :type bypass_cache: bool

Returns:

Lavalink LoadTrack Response Object

Return type:

LavalinkLoadTrackObjects

async search_youtube(query, bypass_cache=False)[source]

Gets the query from YouTube music. :param query: The query to search for. :type query: str :param bypass_cache: Whether to bypass the cache. :type bypass_cache: bool

Returns:

Lavalink LoadTrack Response Object

Return type:

LavalinkLoadTrackObjects

async search_youtube_music(query, bypass_cache=False)[source]

Gets the query from YouTube music. :param query: The query to search for. :type query: str :param bypass_cache: Whether to bypass the cache. :type bypass_cache: bool

Returns:

Lavalink LoadTrack Response Object

Return type:

LavalinkLoadTrackObjects

property server_connected_players

Returns the number of players on this node that are connected

property server_playing_players

Returns the number of players on this node that are playing

property session

The aiohttp session of the node

property session_id

Returns the session id of the node

property socket_protocol

The protocol used for the socket connection

property sources

Returns the sources of the target node.

Returns:

The sources of the target node.

Return type:

set

property ssl

Whether the node is using a ssl connection

property stats

The stats of the node

property supports_apple_music

Checks if the target node supports Apple Music.

Returns:

True if the target node supports Apple Music, False otherwise.

Return type:

bool

property supports_bandcamp

Checks if the target node supports Bandcamp.

Returns:

True if the target node supports Bandcamp, False otherwise.

Return type:

bool

property supports_clypit

Checks if the target node supports ClypIt.

Returns:

True if the target node supports ClypIt, False otherwise.

Return type:

bool

property supports_deezer

Checks if the target node supports Deezer.

Returns:

True if the target node supports Deezer, False otherwise.

Return type:

bool

property supports_getyarn

Checks if the target node supports GetYarn.

Returns:

True if the target node supports GetYarn, False otherwise.

Return type:

bool

property supports_http

Checks if the target node supports HTTP.

Returns:

True if the target node supports HTTP, False otherwise.

Return type:

bool

property supports_lavalyrics

Checks if the target node supports LavaLyrics.

Returns:

True if the target node supports LavaLyrics, False otherwise.

Return type:

bool

property supports_lavasearch

Checks if the target node supports LavaSearch.

Returns:

True if the target node supports LavaSearch, False otherwise.

Return type:

bool

property supports_local

Checks if the target node supports local files.

Returns:

True if the target node supports local files, False otherwise.

Return type:

bool

property supports_mixcloud

Checks if the target node supports Mixcloud.

Returns:

True if the target node supports Mixcloud, False otherwise.

Return type:

bool

property supports_ocremix

Checks if the target node supports OCRemix.

Returns:

True if the target node supports OCRemix, False otherwise.

Return type:

bool

property supports_pornhub

Checks if the target node supports PornHub.

Returns:

True if the target node supports PornHub, False otherwise.

Return type:

bool

property supports_reddit

Checks if the target node supports Reddit.

Returns:

True if the target node supports Reddit, False otherwise.

Return type:

bool

property supports_soundcloud

Checks if the target node supports SoundCloud.

Returns:

True if the target node supports SoundCloud, False otherwise.

Return type:

bool

property supports_soundgasm

Checks if the target node supports Soundgasm.

Returns:

True if the target node supports Soundgasm, False otherwise.

Return type:

bool

property supports_speak

Checks if the target node supports speak source.

Returns:

True if the target node supports speak, False otherwise.

Return type:

bool

property supports_sponsorblock

Checks if the target node supports SponsorBlock.

Returns:

True if the target node supports SponsorBlock, False otherwise.

Return type:

bool

property supports_spotify

Checks if the target node supports Spotify.

Returns:

True if the target node supports Spotify, False otherwise.

Return type:

bool

property supports_tiktok

Checks if the target node supports TikTok.

Returns:

True if the target node supports TikTok, False otherwise.

Return type:

bool

property supports_tts

Checks if the target node supports Google Cloud TTS.

Returns:

True if the target node supports Google Cloud TTS, False otherwise.

Return type:

bool

property supports_twitch

Checks if the target node supports Twitch.

Returns:

True if the target node supports Twitch, False otherwise.

Return type:

bool

property supports_vimeo

Checks if the target node supports Vimeo.

Returns:

True if the target node supports Vimeo, False otherwise.

Return type:

bool

property supports_yandex_music

Checks if the target node supports Yandex Music.

Returns:

True if the target node supports Yandex Music, False otherwise.

Return type:

bool

property supports_youtube

Checks if the target node supports YouTube.

Returns:

True if the target node supports YouTube, False otherwise.

Return type:

bool

property trace

Returns whether the node is being traced or not.

async update_disabled_sources(sources)[source]

Updates the disabled sources.

Return type:

None

async update_features()[source]

Updates the features of the target node.

property version

The version of the node.

voted(player)[source]

Returns whether a player has voted for this node

async wait_until_ready(timeout=None)[source]

Waits until the target node is ready.

property websocket

The websocket of the node

pylav.nodes.utils module

class pylav.nodes.utils.Penalty(stats)[source]

Bases: object

Represents the penalty of the stats of a Node

property cpu_penalty

The penalty of the cpu load of the node

property deficit_frame_penalty

The penalty of the deficit frames of the node

property null_frame_penalty

The penalty of the nulled frames of the node

property player_penalty

The penalty of the players playing on the node.

This is the number of players playing in the node.

property special_handling

The special handling penalty of the node.

property total

The total penalty of the node.

This is the sum of the penalties of the node.

class pylav.nodes.utils.Stats(node, data)[source]

Bases: object

Represents the stats of Lavalink node

property cpu_cores

The amount of cpu cores the system of the node has

property frames_deficit

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.

property frames_nulled

The number of frames that yielded null, rather than actual data

property frames_sent

The number of frames sent to Discord. .. warning:: Given that audio packets are sent via UDP, this number may not be 100% accurate due to dropped packets.

The CPU load generated by Lavalink

property memory_allocated

The amount of memory allocated to the node

property memory_free

The amount of memory free to the node

property memory_reservable

The amount of memory reservable to the node

property memory_used

The amount of memory that is used by the node

property penalty

The penalty for the node

property players

The amount of players connected to the node

property playing_players

The amount of players that are playing in the node

property system_load

The overall CPU load of the system

property uptime

How long the node has been running for in milliseconds

property uptime_seconds

How long the node has been running for in seconds

async pylav.nodes.utils.sort_key_nodes(node, region=None)[source]

The sort key for nodes.

pylav.nodes.websocket module

class pylav.nodes.websocket.WebSocket(*, node, host, port, password, resume_timeout, reconnect_attempts, ssl)[source]

Bases: object

Represents the WebSocket connection with Lavalink

property bot_id

Returns the bot’s ID

property can_resume

Returns whether the websocket can resume

property client

Returns the Client instance

async close()[source]

Closes the websocket connection.

async configure_resume_and_timeout()[source]

Configures the resume and timeout

async connect()[source]

Attempts to establish a connection to Lavalink

property connected

Returns whether the websocket is connected to Lavalink

property connecting

Returns whether the websocket is connecting to Lavalink

async handle_event(data)[source]

Handles the event message from Lavalink.

Parameters:

data (LavalinkEventT) – The data given from Lavalink.

async handle_message(data)[source]

Handles the response from the websocket.

Parameters:

data (LavalinkPlayerUpdateT|LavalinkEventT| LavalinkStatsT| LavalinkReadyT) – The data given from Lavalink.

async handle_player_update(data)[source]

Handles the player update message from the websocket.

Parameters:

data (LavalinkPlayerUpdateT) – The data given from Lavalink.

async handle_ready(data)[source]

Handles the ready message from the websocket.

Parameters:

data (LavalinkReadyT) – The data given from Lavalink.

async handle_stats(data)[source]

Handles the stats message from the websocket.

Parameters:

data (LavalinkStatsOpObject) – The data given from Lavalink.

property is_ready

Returns whether the websocket is ready

property lib_version

Returns the PyLav library version

async manual_closure(managed_node=False)[source]

Triggers a manual closure of the websocket connection.

async maybe_reconnect_player(player)[source]

Attempts to reconnect the player if it is not connected.

Parameters:

player (Player) – The player to reconnect.

property node

Returns the Node instance

async ping()[source]

Pings the websocket

ready
property resumed

Returns whether the websocket has resumed

async send(**data)[source]

Sends a payload to Lavalink.

Parameters:

data (dict) – The data sent to Lavalink.

property session_id

Returns the session ID

property socket_protocol

The protocol used for the socket connection

async wait_until_ready(timeout=None)[source]

Waits until the websocket is ready

Module contents