Node¶

A Node represents a single Lavalink server connection managed by the Pool. Create Node instances and pass them to Pool.connect() — you do not connect them directly.

Guide

See the Node & Pool Guide for usage patterns and multi-node setup.

Node ¶

Node(
    *,
    identifier: str | None = None,
    uri: str,
    password: str,
    session: ClientSession | None = None,
    heartbeat: float = 15.0,
    retries: int | None = None,
    client: Client | None = None,
    resume_timeout: int = 60,
    inactive_player_timeout: int | None = 300,
    inactive_channel_tokens: int | None = 3,
    region: str | None = None,
)

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 :class:~revvlink.Player.

Supported operations

node == otherEquality check to determine whether this Node is equal to another reference of a Node.

repr(node)The official string representation of this Node.

Parameters:

Name	Type	Description	Default
`identifier`	`str \| None`	A unique identifier for this Node. Could be `None` to generate a random one on creation.	`None`
`uri`	`str`	`http://localhost:2333` which includes the port. But you could also provide a domain which won't require a port like `https://lavalink.example.com` or a public IP address and port like `http://111.333.444.55:2333`.	required
`password`	`str`	The password used to connect and authorize this Node.	required
`session`	`ClientSession \| None`	An optional :class:`aiohttp.ClientSession` used to connect this Node over websocket and REST. If `None`, one will be generated for you. Defaults to `None`.	`None`
`heartbeat`	`float`	A `float` in seconds to ping your websocket keep alive. Usually you would not change this.	`15.0`
`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 to `None`.	`None`
`client`	`Client \| None`	The :class:`discord.Client` or subclasses, E.g. `commands.Bot` used to connect this Node. If this is not passed you must pass this to :meth:`revvlink.Pool.connect`.	`None`
`resume_timeout`	`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 to `60`.	`60`
`inactive_player_timeout`	`int \| None`	Set the default for :attr:`revvlink.Player.inactive_timeout` on every player that connects to this node. Defaults to `300`.	`300`
`inactive_channel_tokens`	`int \| None`	Sets the default for :attr:`revvlink.Player.inactive_channel_tokens` on every player that connects to this node. Defaults to `3`.	`3`
`region`	`str \| None`	An optional string representing the node's region (e.g. "us", "eu", "asia"). Used for regional load balancing. Defaults to `None`. See also: :func:`on_revvlink_inactive_player`.	`None`

headers `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.

identifier `property` ¶

identifier: str

The unique identifier for this :class:Node.

uri `property` ¶

uri: str

The URI used to connect this :class:Node to Lavalink.

status `property` ¶

status: NodeStatus

The current :class:Node status.

Refer to: :class:~revvlink.NodeStatus

penalty `property` ¶

penalty: float

The composite load score for this node. Lower is better.

Used by :meth:Pool.get_node to rank nodes within a region or globally.

Components: - CPU system load (weighted exponentially) - Active player count (flat cost per player) - Frame deficit (huge penalty — indicates audio stuttering)

Returns:

Type	Description
`float`	The calculated penalty score.

players `property` ¶

players: dict[int, Player]

A mapping of :attr:discord.Guild.id to :class:~revvlink.Player.

Returns:

Type	Description
dict[int, :class:`~revvlink.Player`]	A shallow copy of the internal players mapping.

client `property` ¶

client: Client | None

The :class:discord.Client associated with this :class:Node.

Returns:

Type	Description
class:`discord.Client` \| None	The client instance, or `None` if it has not been set.

password `property` ¶

password: str

The password used to connect and authorize this :class:Node to Lavalink.

Returns:

Type	Description
`str`	The node password.

heartbeat `property` ¶

heartbeat: float

The duration in seconds between WebSocket heartbeat pings.

Returns:

Type	Description
`float`	The heartbeat interval in seconds.

session_id `property` ¶

session_id: str | None

The Lavalink session ID for this node connection.

Returns:

Type	Description
`str \| None`	The session ID, or `None` if the node is not connected.

info `property` ¶

info: NodeInfo | None

Returns the cached node info including source managers and plugins.

This property returns a :class:NodeInfo dataclass with convenience methods for checking available sources and plugins.

Could be None if the node has not fetched info yet. Use :meth:refresh_info to fetch the latest info.

Returns:

Type	Description
`NodeInfo \| None`	The node info, or None if not yet fetched.

refresh_info `async` ¶

refresh_info() -> NodeInfo

Fetch and cache the latest node info from Lavalink.

This method updates the cached info with the latest data from the Lavalink server, including available source managers and plugins.

Returns:

Type	Description
`NodeInfo`	The updated node info.

Raises:

Type	Description
`LavalinkException`	An error occurred while making this request to Lavalink.
`NodeException`	An error occurred while making this request to Lavalink, and Lavalink was unable to send any error information.

close `async` ¶

close(eject: bool = False, failover: bool = True) -> None

Method to close this Node and cleanup.

After this method has finished, the event on_revvlink_node_closed will be fired.

This method renders the Node websocket disconnected and disconnects all players.

Parameters:

Name	Type	Description	Default
`eject`	`bool`	If `True`, this will remove the Node from the Pool. Defaults to `False`.	`False`
`failover`	`bool`	If `True`, this will attempt to failover all players to another node. Defaults to `True`.	`True`

send `async` ¶

send(
    method: Method = "GET",
    *,
    path: str,
    data: Any | None = None,
    params: dict[str, Any] | None = 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 and Player, 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:

Name	Type	Description	Default
`method`	`Method`	The method to use when making this request. Available methods are "GET", "POST", "PATCH", "PUT", "DELETE" and "OPTIONS". Defaults to "GET".	`'GET'`
`path`	`str`	The path to make this request to. E.g. "/v4/stats".	required
`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.	`None`
`params`	`dict[str, Any] \| None`	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".	`None`

Returns:

Type	Description
`Any`	The response from Lavalink which will either be None, a str or JSON.

Raises:

Type	Description
`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.

fetch_players `async` ¶

fetch_players() -> list[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 revvlink.Player class. This is the data received from Lavalink about the players.

Returns:

Type	Description
list[:class:`PlayerResponsePayload`]	A list of :class:`PlayerResponsePayload` representing each player connected to this node.

Raises:

Type	Description
`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.

fetch_player_info `async` ¶

fetch_player_info(
    guild_id: int,
) -> PlayerResponsePayload | None

Method to fetch the player information Lavalink holds for the specific guild.

⚠Warning

This payload is not the same as the revvlink.Player class. This is the data received from Lavalink about the player. See: get_player

Parameters:

Name	Type	Description	Default
`guild_id`	`int`	The ID of the guild you want to fetch info for.	required

Returns:

Type	Description
class:`PlayerResponsePayload` \| None	The :class:`PlayerResponsePayload` representing the player info for the guild ID connected to this node. Could be `None` if no player is found with the given guild ID.

Raises:

Type	Description
`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.

decode_track `async` ¶

decode_track(encoded: str) -> Playable

Decode a single base64 encoded track string back into a :class:~revvlink.Playable.

Parameters:

Name	Type	Description	Default
`encoded`	`str`	The base64 encoded track string to decode.	required

Returns:

Type	Description
class:`~revvlink.Playable`	The decoded :class:`~revvlink.Playable`.

Raises:

Type	Description
`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.

decode_tracks `async` ¶

decode_tracks(encoded: list[str]) -> list[Playable]

Decode a list of base64 encoded track strings back into a list of :class:~revvlink.Playable.

Parameters:

Name	Type	Description	Default
`encoded`	`list[str]`	A list of base64 encoded track strings to decode.	required

Returns:

Type	Description
list[:class:`~revvlink.Playable`]	The decoded list of :class:`~revvlink.Playable`.

Raises:

Type	Description
`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.

get_routeplanner_status `async` ¶

get_routeplanner_status() -> dict[str, Any] | None

Fetch the RoutePlanner status for this Lavalink node.

Returns:

Type	Description
`dict[str, Any] \| None`	A dictionary containing the RoutePlanner status, or `None` if the RoutePlanner is not enabled on the server.

Raises:

Type	Description
`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.

unmark_failed_address `async` ¶

unmark_failed_address(address: str) -> None

Unmark a failed address in the RoutePlanner so it may be reused.

Parameters:

Name	Type	Description	Default
`address`	`str`	The IP address to unmark as failed.	required

Raises:

Type	Description
`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.

unmark_all_failed_addresses `async` ¶

unmark_all_failed_addresses() -> None

Unmark all failed addresses in the RoutePlanner so they may be reused.

Raises:

Type	Description
`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.

fetch_info `async` ¶

fetch_info() -> InfoResponsePayload

Method to fetch this Lavalink Nodes info response data.

Returns:

Type	Description
class:`InfoResponsePayload`	The :class:`InfoResponsePayload` associated with this Node.

Raises:

Type	Description
`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.

fetch_stats `async` ¶

fetch_stats() -> StatsResponsePayload

Method to fetch this Lavalink Nodes stats response data.

Returns:

Type	Description
class:`StatsResponsePayload`	The :class:`StatsResponsePayload` associated with this Node.

Raises:

Type	Description
`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.

fetch_version `async` ¶

fetch_version() -> str

Method to fetch this Lavalink version string.

Returns:

Type	Description
`str`	The version string associated with this Lavalink node.

Raises:

Type	Description
`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.

get_player ¶

get_player(guild_id: int) -> Player | None

Return a :class:~revvlink.Player associated with the provided :attr:discord.Guild.id.

Parameters:

Name	Type	Description	Default
`guild_id`	`int`	The :attr:`discord.Guild.id` to retrieve a :class:`~revvlink.Player` for.	required

Returns:

Type	Description
Optional[:class:`~revvlink.Player`]	The Player associated with this guild ID. Could be None if no :class:`~revvlink.Player` exists for this guild.

Node¶

Node ¶

headers property ¶

identifier property ¶

uri property ¶

status property ¶

penalty property ¶

players property ¶

client property ¶

password property ¶

heartbeat property ¶

session_id property ¶

info property ¶

refresh_info async ¶

close async ¶

send async ¶

fetch_players async ¶

fetch_player_info async ¶

decode_track async ¶

decode_tracks async ¶

get_routeplanner_status async ¶

unmark_failed_address async ¶

unmark_all_failed_addresses async ¶

fetch_info async ¶

fetch_stats async ¶

fetch_version async ¶

get_player ¶

headers `property` ¶

identifier `property` ¶

uri `property` ¶

status `property` ¶

penalty `property` ¶

players `property` ¶

client `property` ¶

password `property` ¶

heartbeat `property` ¶

session_id `property` ¶

info `property` ¶

refresh_info `async` ¶

close `async` ¶

send `async` ¶

fetch_players `async` ¶

fetch_player_info `async` ¶

decode_track `async` ¶

decode_tracks `async` ¶

get_routeplanner_status `async` ¶

unmark_failed_address `async` ¶

unmark_all_failed_addresses `async` ¶

fetch_info `async` ¶

fetch_stats `async` ¶

fetch_version `async` ¶