Nodes#

A Node is one lavalink instance.

Attributes

available
client
host
label
players
port
regions
secure
session_id
shard_ids
stats
version
weight

Methods

defadd_player
defcleanup
asyncclose
defconfigure_resuming
asyncconnect
asyncdecode_track
asyncdecode_tracks
defdestroy
asyncfetch_player
asyncfetch_plugins
asyncfetch_route_planner_status
asyncfetch_tracks
defget_player
defremove_player
asyncsync_players
asyncunmark_all_addresses
asyncunmark_failed_address
defupdate

class mafic.Node(*, host, port, label, password, client, secure=False, heartbeat=30, timeout=10, session=None, resume_key=None, regions=None, shard_ids=None, resuming_session_id=None)#

Bases: Generic[ClientT]

Represents a Lavalink node.

Warning

This class should not be instantiated manually. Instead, use NodePool.create_node().

Parameters:

host (str) – The host of the node, used to connect.
port (int) – The port of the node, used to connect.
label (str) – The label of the node, used to identify the node.
password (str) – The password of the node, used to authenticate the connection.
client (ClientT) – The client that the node is attached to.
secure (bool) – Whether the node is using a secure connection. This determines whether the node uses HTTP or HTTPS, WS or WSS.
heartbeat (int) – The interval at which the node will send a heartbeat to the client.
timeout (float) – The amount of time the node will wait for a response before raising a timeout error.
session (Optional[aiohttp.ClientSession]) – The session to use for the node. If not provided, a new session will be created.
resume_key (Optional[str]) –
The key to use when resuming the node. If not provided, the key will be generated from the host, port and label.

Warning

This is ignored in lavalink V4, use resuming_session_id instead.
regions (Optional[Sequence[Group | Region | VoiceRegion]]) – The voice regions that the node can be used in. This is used to determine when to use this node.
shard_ids (Optional[Sequence[int]]) – The shard IDs that the node can be used in. This is used to determine when to use this node.
resuming_session_id (Optional[str]) –
The session ID to use when resuming the node. If not provided, the node will not resume.

This should be stored from on_node_ready() with session_id to resume the session and gain control of the players. If the node is not resuming, players will be destroyed if Lavalink loses connection to us.

New in version 2.2.

regions#

The regions that the node can be used in. This is used to determine when to use this node.

Type:: Optional[list[VoiceRegion]]

shard_ids#

The shard IDs that the node can be used in. This is used to determine when to use this node.

Type:: Optional[list[int]]

add_player(guild_id, player)#

Add a player to the node.

Parameters:

guild_id (int) – The guild ID to add the player for.
player (Player[ClientT]) – The player to add.

Return type:

None

property available: bool#

Whether the node is available.

This is False if the node is not connected, or if it is not ready.

cleanup()#

Cleanup the node, as if it was never connected.

Return type:: None

property client: ClientT#: The client that the node is attached to.

await close()#

Close the node.

This will disconnect the websocket and close the session. :rtype: None

New in version 2.6.

configure_resuming()#

Configure the node to resume.

Return type:: Coro[None]

await connect(*, backoff=None, player_cls=None)#

Connect to the node.

Parameters:

backoff (ExponentialBackoff[Literal[False]] | None) – The backoff to use when reconnecting.
player_cls (type[Player[ClientT]] | None) –
The player class to use for the node when resuming.

New in version 2.8.

Raises:

NodeAlreadyConnected – If the node is already connected.
asyncio.TimeoutError – If the connection times out. You can change the timeout with the timeout parameter.

Return type:

None

await decode_track(track)#

Decode a track from the encoded base64 data.

Parameters:: track (str) – The encoded track data.
Returns:: The decoded track.
Return type:: Track

See also

decode_track()

destroy(guild_id)#

Destroy a player.

Parameters:: guild_id (int) – The guild ID to destroy the player for.
Return type:: Coro[None]

await fetch_player(guild_id)#

Fetch player data from the node.

Note

This is an API call. Usually you should use get_player() instead.

New in version 2.6.

Parameters:: guild_id (int) – The guild ID to fetch the player for.
Returns:: The player data for the guild.
Return type:: dict

await fetch_plugins()#

Fetch the plugins from the node.

Returns:: The plugins from the node.
Return type:: list[Plugin]

await fetch_route_planner_status()#

Fetch the route planner status from the node.

Returns:: The route planner status from the node.
Return type:: RoutePlannerStatus

await fetch_tracks(query, *, search_type)#

Fetch tracks from the node.

Parameters:

query (str) – The query to search for.
search_type (str) – The search type to use.

Return type:

UnionType[list[Track], Playlist, None]

Returns:

list[Track] – A list of tracks if the load type is TRACK_LOADED or SEARCH_RESULT.
Playlist – A playlist if the load type is PLAYLIST_LOADED.
None – If the load type is NO_MATCHES.

get_player(guild_id)#

Get a player from the node.

Parameters:: guild_id (int) – The guild ID to get the player for.
Returns:: The player for the guild, if found.
Return type:: Optional[Player]

property host: str#: The host of the node.

property label: str#: The label of the node.

property players: list[Player[ClientT]]#: The players connected to the node.

Changed in version 2.0: This is now a list.

property port: int#: The port of the node.

remove_player(guild_id)#

Remove a player from the node.

Note

This does not disconnect the player from the voice channel. This simply exists to remove the player from the node cache.

Parameters:: guild_id (int) – The guild ID to remove the player for.
Return type:: None

property secure: bool#: Whether the node is using a secure connection.

property session_id: str | None#

The session ID of the node.

This is None if the node is not connected.

New in version 2.2.

property stats: NodeStats | None#

The stats of the node.

This will be None if the node has not sent stats yet. This could be if it is not connected, or if stats sending is disabled on the node.

await sync_players(player_cls=None)#

Sync the players with the node.

Note

This method is called automatically when the client is ready. You should not need to call this method yourself.

Parameters:

player_cls (type[Player[ClientT]] | None) –

The class of the player to use.

New in version 2.8.

Return type:

None

await unmark_all_addresses()#

Unmark all failed addresses so they can be used again.

Return type:: None

await unmark_failed_address(address)#

Unmark a failed address so it can be used again.

Parameters:: address (str) – The address to unmark.
Return type:: None

update(*, guild_id, track=..., position=None, end_time=None, volume=None, no_replace=None, pause=None, filter=None)#

Update a player.

Parameters:

guild_id (int) – The guild ID to update the player for.
track (Track | str | None) –
The track to update the player with. This can be either a Track or an identifier. Setting this to None will clear the track.

Changed in version 2.4: The track can now be a str to play an identifier.
position (int | None) – The position to update the player with.
end_time (int | None) – The position in the track to stop playing.
volume (int | None) – The volume to set.
no_replace (bool | None) – Whether to replace the current track or leave it playing.
pause (bool | None) – Whether to pause the player.
filter (Filter | None) – The filter to apply to the player.

Return type:

Coro[PlayerPayload]

property version: int#

The major semver version of the node.

This is 3 if the node is not connected. This is mostly used in Player for version checks.

New in version 2.2.

property weight: float#

The weight of the node.

This is used to determine which node to use when multiple nodes are available.

Notes

The weight is calculated based on the following:

The number of players connected to the node.
The load of the node.
The number of UDP frames nulled.
The number of UDP frames that are lost.
If the node memory is very close to full.

If the node has not sent stats yet, then a high value will be returned. This is so that the node will be used if it is the only one available, or if stats sending is disabled on the node.