lavasnek_rs.lavasnek_rs

Cheat Sheet:

Functions that return a Result<T, E> mean that it can raise an exception. T is the type they return normally, and E is a list of possible exceptions that can raise.
Functions that return an Option<T> mean that the value returned can be None, where T would be the type of the returned value if not None.
If something returns a Future<T>, it means that it returns this, and that function should be awaited to work.
/ on arguments means the end of positional arguments.
Self (with a capital S) means the type of self.
A type prefixed with impl means it's a Class that implements that Trait type.

# def rust_sleep(seconds, /):

Test function, do not use.

# def log_something():

Test function, do not use.

# class Lavalink:

# Lavalink()

# def start_discord_gateway(self, /, wait_time):

Start the discord gateway, if it has stopped, or it never started because the client builder was configured that way.

If wait_time is passed, it will override the previosuly configured wait time.

Positional Arguments:

wait_time : Optional Unsigned 64 bit integer -- seconds

Returns: Future<None>

# def join(self, guild_id, channel_id, /):

Joins a guild's voice channel using the lavalink-rs discord gateway.

Returns information about the gateway connection, which can be used with create_session() to connect lavalink to that voice connection.

lavalink: lavasnek_rs.Lavalink = ...

connection_info = await lavalink.join(guild_id, voice_channel_id)
await lavalink.create_session(connection_info)

await send_message(f"Joined <#{voice_channel_id}>")

Timing out means that there's either no permission to join the voice channel, or 5 seconds have happened since the function was called.

Positional Arguments:

guild_id : Unsigned 64 bit integer
channel_id : Unsigned 64 bit integer

Returns: Future<Result<ConnectionInfo, builtins.TimeoutError>>

# def leave(self, guild_id, /):

Leaves the current guild's voice channel using the lavalink-rs discord gateway.

Lavalink.destroy() should be ran as well before this, to safely stop the lavalink session.

lavalink: lavasnek_rs.Lavalink = ...

await lavalink.destroy(guild_id)
await lavalink.leave(guild_id)

await send_message("Left voice channel")

Timing out means that 5 seconds have happened since the function was called.

Positional Arguments:

guild_id : Unsigned 64 bit integer

Returns: Future<Result<None, builtins.TimeoutError>>

# def create_session(self, connection_info, /):

Creates a session in Lavalink with a voice connection. This also creates a Node and inserts it. The node is not added to the loops unless PlayBuilder.queue() is ran.

This can raise a TypeError if a necessary field of ConnectionInfo is missing.

Positional Arguments:

connection_info : ConnectionInfo (obtained from Lavalink.join())

Returns: Future<Result<None, builtins.TypeError>>

# def destroy(self, guild_id, /):

Stops the session in Lavalink of the guild. This also creates a Node and inserts it.

This method does not remove the guild from the running event loops, nor does it clear the Node, this allows for reconnecting without losing data. If you are having issues with disconnecting and reconnecting the bot to a voice channel, remove the guild from the running event loops and reset the nodes.

lavalink.remove_guild_node(guild_id)
lavalink.remove_guild_from_loops(guild_id)

This can raise an exception if a network error happens.

Positional Arguments:

guild_id : Unsigned 64 bit integer

Returns: Future<Result<None, lavasnek_rs.NetworkError>>

# def play(self, guild_id, track, /):

Returns the Play builder.

lavalink: lavasnek_rs.Lavalink = ...

query_information = await lavalink.auto_search_tracks(search_query_or_url)

if not query_information["tracks"]: # tracks is empty
    await send_message("Could not find any video of the search query.")
    return

try:
    await lavalink.play(
        guild_id, query_information["tracks"][0]
    ).requester(author_id).queue()
except lavasnek_rs.NoSessionPresent:
    await send_message(f"Use `{PREFIX}join` first")
    return

Positional Arguments:

guild_id : Unsigned 64 bit integer
track : Track - From the track search methods, it's a value from the "tracks" field.

Returns: PlayBuilder

# def get_tracks(self, query, /):

Returns the tracks from the URL or query provided.

This can raise an exception if a network error happens.

Positional Arguments:

query : String

Returns: Future<Result<Tracks, lavasnek_rs.NetworkError>>

# def auto_search_tracks(self, query, /):

Will automatically search the query on youtube if it's not a valid URL.

This can raise an exception if a network error happens.

Positional Arguments:

query : String

Returns: Future<Result<Tracks, lavasnek_rs.NetworkError>>

# def search_tracks(self, query, /):

Returns tracks from the search query. Uses youtube to search.

This can raise an exception if a network error happens.

Positional Arguments:

query : String

Returns: Future<Result<Tracks, lavasnek_rs.NetworkError>>

# def decode_track(self, track, /):

Returns information from a track.

This can raise an exception if a network error happens.

Positional Arguments:

track : String -- base 64

Returns: Future<Result<Info, lavasnek_rs.NetworkError>>

# def stop(self, guild_id, /):

Stops the current player.

This can raise an exception if a network error happens.

Positional Arguments:

guild_id : Unsigned 64 bit integer

Returns: Future<Result<None, lavasnek_rs.NetworkError>>

# def skip(self, guild_id, /):

Skips the current playing track to the next item on the queue.

If nothing is in the queue, the currently playing track will keep playing. Check if the queue is empty and run stop() if that's the case.

lavalink: lavasnek_rs.Lavalink = ...

skip = await lavalink.skip(guild_id)
node = await lavalink.get_guild_node(guild_id)

if not skip:
    await send_message("Nothing to skip")
else:
    if not node["queue"] and not node["now_playing"]:
        await lavalink.stop(guild_id)

    await send_message(f"Skipped: {skip['track']['info']['title']}"

This can raise an exception if a network error happens.

Positional Arguments:

guild_id : Unsigned 64 bit integer

Returns: Future<Option<TrackQueue>>

# def set_pause(self, guild_id, pause, /):

Sets the pause status.

This can raise an exception if a network error happens.

Positional Arguments:

guild_id : Unsigned 64 bit integer
pause : bool

Returns: Future<Result<None, lavasnek_rs.NetworkError>>

# def pause(self, guild_id, /):

Sets pause status to True

# def resume(self, guild_id, /):

Sets pause status to False

# def seek_secs(self, guild_id, time, /):

Jumps to a specific time in the currently playing track.

This can raise an exception if a network error happens.

Positional Arguments:

guild_id : Unsigned 64 bit integer
time : Unsigned 64 bit integer

Returns: Future<Result<None, lavasnek_rs.NetworkError>>

# def jump_to_time_secs(self, guild_id, time, /):

Alias to seek_secs()

# def scrub_secs(self, guild_id, time, /):

Alias to seek_secs()

# def seek_millis(self, guild_id, time, /):

Jumps to a specific time in the currently playing track.

This can raise an exception if a network error happens.

Positional Arguments:

guild_id : Unsigned 64 bit integer
time : Unsigned 64 bit integer

Returns: Future<Result<None, lavasnek_rs.NetworkError>>

# def jump_to_time_millis(self, guild_id, time, /):

Alias to seek_millis()

# def scrub_millis(self, guild_id, time, /):

Alias to seek_millis()

# def volume(self, guild_id, volume, /):

Sets the volume of the player. Max is 1000, min is 0

This can raise an exception if a network error happens.

Positional Arguments:

guild_id : Unsigned 64 bit integer
Volume : Unsigned 16 bit integer

Returns: Future<Result<None, lavasnek_rs.NetworkError>>

# def equalize_all(self, guild_id, bands, /):

Sets all equalizer levels.

There are 15 bands (0-14) that can be changed.
The floating point value is the multiplier for the given band.
The default value is 0.
Valid values range from -0.25 to 1.0, where -0.25 means the given band is completely muted, and 0.25 means it is doubled.
Modifying the gain could also change the volume of the output.

This can raise an exception if a network error happens.

Positional Arguments:

guild_id : Unsigned 64 bit integer
bands : List<64 bit floating point> -- Must be 15 in length

Returns: Future<Result<None, lavasnek_rs.NetworkError>>

# def equalize_dynamic(self, guild_id, bands, /):

Equalize a dynamic set of bands, rather than just one or all of them at once.

Unmentioned bands will remain unmodified.

This can raise an exception if a network error happens.

Positional Arguments:

guild_id : Unsigned 64 bit integer
bands : List<64 bit floating point> -- Must be 15 or less in length

Returns: Future<Result<None, lavasnek_rs.NetworkError>>

# def equalize_band(self, guild_id, band, /):

Equalizes a specific band.

This can raise an exception if a network error happens.

Positional Arguments:

guild_id : Unsigned 64 bit integer
band : Band

Returns: Future<Result<None, lavasnek_rs.NetworkError>>

# def equalize_reset(self, guild_id, /):

Resets all equalizer levels.

This can raise an exception if a network error happens.

Positional Arguments:

guild_id : Unsigned 64 bit integer

Returns: Future<Result<None, lavasnek_rs.NetworkError>>

# def remove_guild_from_loops(self, guild_id, /):

Remove the guild from the queue loops.

Positional Arguments:

guild_id : Unsigned 64 bit integer

Returns: Future<None>

# def remove_guild_node(self, guild_id, /):

Remove the guild node.

Positional Arguments:

guild_id : Unsigned 64 bit integer

Returns: Future<None>

# def get_guild_node(self, guild_id, /):

Get the current guild from the queue nodes.

This returns a clone of the node, so modifying it won't change the real node, for that you will need to re-set the new node with set_guild_node().

Positional Arguments:

guild_id : Unsigned 64 bit integer

Returns: Future<Option<Node>>

# def set_guild_node(self, guild_id, node, /):

Set the node of a guild with a new one.

Positional Arguments:

guild_id : Unsigned 64 bit integer
node : Node

Returns: Future<None>

# def get_guild_gateway_connection_info(self, guild_id, /):

Get the current guild from the queue nodes.

This returns a clone of the value, modifying it won't change it internally.

Positional Arguments:

guild_id : Unsigned 64 bit integer

Returns: Future<Option<ConnectionInfo>>

# def wait_for_full_connection_info_insert(self, guild_id, /, event_count=10):

Waits until the ConnectionInfo is complete and returns it.

Positional Arguments:

guild_id : Unsigned 64 bit integer
event_count : Unsigned 128 bit integer defaults to 10

Returns: Future<ConnectionInfo>

# def wait_for_connection_info_remove(self, guild_id, /, event_count=10):

Waits until the ConnectionInfo is removed.

Positional Arguments:

guild_id : Unsigned 64 bit integer
event_count : Unsigned 128 bit integer defaults to 10

Returns: Future<None>

# def raw_handle_event_voice_server_update(self, guild_id, endpoint, token, /):

Handles voice events to manage ConnectionInfo internally. This one is for the VOICE_SERVER_UPDATE event.

Positional Arguments:

guild_id : Unsigned 64 bit integer
endpint : String
token : String

Returns: Future<None>

# def raw_handle_event_voice_state_update(self, guild_id, user_id, session_id, /, channel_id):

Handles voice events to manage ConnectionInfo internally. This one is for the VOICE_STATE_UPDATE event.

Positional Arguments:

guild_id : Unsigned 64 bit integer
user_id : Unsigned 64 bit integer
session_id : String
channel_id : Optional Unsigned 64 bit integer

Returns: Future<None>

# class LavalinkBuilder:

__new__()

All of the methods that return Self also modify Self, so you can chain them, or call the individually.

Positional Arguments:

bot_id : Unsigned 64 bit integer
bot_token : String

Returns: Self

# LavalinkBuilder()

# def build(self, event_handler, /):

Uses the Self data to build a Lavalink client and return it.

Can raise an exception if it's unable to connect to the lavalink server, discord server, or both.

Positional Arguments:

event_handler : impl LavalinkEventHandler

Returns: Future<Result<Lavalink, builtins.ConnectionError>>

# def set_host(self, host, /):

Sets the host. (Default to: 127.0.0.1)

Positional Arguments:

host : String

Returns: Self

# def set_port(self, port, /):

Sets the port. (Default to: 2333)

Positional Arguments:

port : Unsigned 16 bit integer

Returns: Self

# def set_addr(self, address, /):

Sets the host and port from an address.

Can raise an exception if the address is an invalid IPv4 or IPv6.

Positional Arguments:

address : String

Returns: Result<Self, ipaddress.AddressValueError>

# def set_password(self, password, /):

Sets the lavalink password. (Default to: "youshallnotpass")

Positional Arguments:

password : String

Returns: Self

# def set_shard_count(self, shard_count, /):

Sets the number of shards. (Default to: 1)

Positional Arguments:

shard_count : Unsigned 64 bit integer

Returns: Self

# def set_bot_id(self, bot_id, /):

Sets the ID of the bot.

Positional Arguments:

bot_id : Unsigned 64 bit integer

Returns: Self

# def set_bot_token(self, bot_token, /):

Sets the token of the bot.

Positional Arguments:

bot_token : String

Returns: Self

# def set_is_ssl(self, is_ssl, /):

Sets if the lavalink server is behind SSL. (Default to: False)

Positional Arguments:

is_ssl : bool

Returns: Self

# def set_start_gateway(self, start_gateway, /):

Sets if the discord gateway for voice connections should start or not. (Default to: True)

Positional Arguments:

start_gateway : bool

Returns: Self

# def set_gateway_start_wait_time_secs(self, time, /):

Sets the time to wait before starting the first discord gateway connection. (Default to: 6 seconds)

Positional Arguments:

time : Unsigned 64 bit integer

Returns: Self

# def set_gateway_start_wait_time_millis(self, time, /):

Sets the time to wait before starting the first discord gateway connection.

Positional Arguments:

time : Unsigned 64 bit integer

Returns: Self

# class PlayBuilder:

# PlayBuilder()

# def start(self, /):

Starts playing the track.

Returns: Future<Result<None, lavasnek_rs.NetworkError>>

# def queue(self, /):

Adds the track to the node queue.

If there's no queue loop running, this will start one up, and add it to the running loops on Lavalink.loops()

Needs for `Lavalink.create_session() to be called first.

Returns: Future<Result<None, [lavasnek_rs.NoSessionPresent, lavasnek_rs.NetworkError]>>

# def to_track_queue(self, /):

Generates a TrackQueue from the builder.

Returns: TrackQueue

# def requester(self, requester, /):

Sets the person that requested the song

Positional Arguments:

requester : Unsigned 64 bit integer (User ID)

Returns: Self

# def replace(self, replace, /):

Sets if the current playing track should be replaced with this new one.

Positional Arguments:

replace : bool

Returns: Self

# def start_time_secs(self, start, /):

Sets the time the track will start at in seconds.

Positional Arguments:

start : Unsigned 64 bit integer

Returns: Self

# def finish_time_secs(self, finish, /):

Sets the time the track will finish at in seconds.

Positional Arguments:

finish : Unsigned 64 bit integer

Returns: Self

# def start_time_millis(self, start, /):

Sets the time the track will start at in milliseconds.

Positional Arguments:

start : Unsigned 64 bit integer

Returns: Self

# def finish_time_millis(self, finish, /):

Sets the time the track will finish at in milliseconds.

Positional Arguments:

finish : Unsigned 64 bit integer

Returns: Self

# class LavalinkEventHandler:

The lavalink event handler. This is a trait, so it defines the structure a class should have.

Make a class with the methods and signatures this class defines, and add that class to LavalinkBuilder.build()

If code inside any of the event raises an error, the traceback will be printed to stderr, and the variables sys.last_type, sys.last_value and sys.last_traceback will be set to the type, value and traceback of the printed exception respectively.

Some examples:

# Just a single event
class EventHandler:
    async def track_start(self, lava_client, event):
        print(event)

lavalink_client = await client_builder.build(EventHandler)

# No events
class EventHandler:
    pass

lavalink_client = await client_builder.build(EventHandler)

# Just a single event
class EventHandler:
    async def stats(self, lava_client, event):
        print(event)
    async def player_update(self, lava_client, event):
        print(event)
    async def track_start(self, lava_client, event):
        print(event)
    async def track_finish(self, lava_client, event):
        print(event)
    async def track_exception(self, lava_client, event):
        print(event)
    async def track_stuck(self, lava_client, event):
        print(event)
    async def websocket_closed(self, lava_client, event):
        print(event)
    async def player_destroyed(self, lava_client, event):
        print(event)

lavalink_client = await client_builder.build(EventHandler)

# LavalinkEventHandler()

# def stats(self, client, event, /):

Periodic event that returns the statistics of the server.

Positional Arguments:

client : Lavalink
event : Stats

Returns: Future<None>

# def player_update(self, client, event, /):

Event that triggers when a player updates.

Positional Arguments:

client : Lavalink
event : PlayerUpdate

Returns: Future<None>

# def track_start(self, client, event, /):

Event that triggers when a track starts playing.

Positional Arguments:

client : Lavalink
event : TrackStart

Returns: Future<None>

# def track_finish(self, client, event, /):

Event that triggers when a track finishes playing.

Positional Arguments:

client : Lavalink
event : TrackFinish

Returns: Future<None>

# def track_exception(self, client, event, /):

Event that triggers when a track raises an exception on the Lavalink server.

Positional Arguments:

client : Lavalink
event : TrackException

Returns: Future<None>

# def track_stuck(self, client, event, /):

Event that triggers when a track gets stuck while playing.

Positional Arguments:

client : Lavalink
event : TrackStuck

Returns: Future<None>

# def websocket_closed(self, client, event, /):

Event that triggers when the websocket connection to the voice channel closes.

Positional Arguments:

client : Lavalink
event : WebSocketClosed

Returns: Future<None>

# def player_destroyed(self, client, event, /):

Event that triggers when the player gets destroyed on a guild.

Positional Arguments:

client : Lavalink
event : PlayerDestroyed

Returns: Future<None>

# class ConnectionInfo:

This is never actually used, a dictionary is used instead. If you use a 3rd party method of joining a voice channel, you can get this values from the VOICE_STATE_UPDATE and VOICE_SERVER_UPDATE events, and use raw_handle_event_voice_state_update() + raw_handle_event_voice_server_update() or manually build a dict with them.

With hikari:

@bot.listen()
async def voice_state_update(event: hikari.VoiceStateUpdateEvent) -> None:
    await bot.data.lavalink.raw_handle_event_voice_state_update(
        event.state.guild_id,
        event.state.user_id,
        event.state.session_id,
        event.state.channel_id,
    )

@bot.listen()
async def voice_server_update(event: hikari.VoiceServerUpdateEvent) -> None:
    await bot.data.lavalink.raw_handle_event_voice_server_update(
        event.guild_id, event.endpoint, event.token
    )

Fields:

guild_id : Unsigned 64 bit integer
channel_id : Unsigned 64 bit integer
endpoint : String
token : String
session_id : String

# ConnectionInfo()

# class Track:

# Track()

# track

The playable track.

Contains String

# info

Information about the track.

Contains Option<Info>

# class Tracks:

# Tracks()

# load_type

Contains String

# tracks

The tracks that can be played

Contains List<Track>

# playlist_info

Information about the playlist.

Contains Option<PlaylistInfo>

# class TrackQueue:

# TrackQueue()

# start_time

The time the track will start at.

Contains Unsigned 64 bit integer

# end_time

The time the track will finish at.

Contains Option<Unsigned 64 bit integer>

# requester

The user id who requested the track if set by the PlayBuilder

Contains Option<Unsigned 64 bit integer>

# track

The playable track.

Contains Track

# class Info:

# Info()

# length

Contains Unsigned 64 bit integer

# uri

Contains String

# is_stream

Contains bool

# is_seekable

Contains bool

# title

Contains String

# author

Contains String

# identifier

Contains String

# position

Contains Unsigned 64 bit integer

# class PlaylistInfo:

# PlaylistInfo()

# selected_track

Contains Option<Signed 64 bit integer>

# name

The name of the playlist.

Contains Option<String>

# class Node:

# Node()

# def get_data(self, /):

Use this to get the currently stored data on the Node.

T is whatever type you give to set_data's data parameter, but if you call this method before it, it will default to a Dict.

Returns Future<T>

# def set_data(self, data, /):

Use this to set the tored data of the Node.

Returns Future<None>

# guild

Contains Unsigned 64 bit integer

# volume

Contains Unsigned 16 bit integer

# is_paused

Contains bool

# is_on_loops

Contains bool

# now_playing

Contains Option<TrackQueue>

# queue

Contains List<TrackQueue>

# class Band:

See Lavalink.equalize_all for more info.

band_num: int = 14 # 0 to 14
bain: float = 0.125 # -0.25 to 1.0

band = Band(band_num, gain)

# Band()

# gain

Contains 64 bit float

# band

Contains Unsigned 8 bit integer

# class Stats:

# Stats()

# frame_stats_sent

Contains Optional Signed 64 bit integer

# playing_players

Contains Signed 64 bit integer

# uptime

Contains Signed 64 bit integer

# cpu_system_load

Contains 64 bit floating point

# frame_stats_deficit

Contains Optional Signed 64 bit integer

# memory_allocated

Contains Signed 64 bit integer

# frame_stats_nulled

Contains Optional Signed 64 bit integer

# op

Contains String

# memory_reservable

Contains Signed 64 bit integer

# memory_used

Contains Signed 64 bit integer

# players

Contains Signed 64 bit integer

# memory_free

Contains Signed 64 bit integer

# cpu_cores

Contains Signed 64 bit integer

# cpu_lavalink_load

Contains 64 bit floating point

# class PlayerUpdate:

# PlayerUpdate()

# guild_id

Contains Unsigned 64 bit integer

# state_time

Contains Signed 64 bit integer

# op

Contains String

# state_position

Contains Signed 64 bit integer

# class TrackStart:

# TrackStart()

# track

Contains String

# op

Contains String

# guild_id

Contains Unsigned 64 bit integer

# track_start_type

Contains String

# class TrackFinish:

# TrackFinish()

# reason

Contains String

# guild_id

Contains Unsigned 64 bit integer

# op

Contains String

# track_finish_type

Contains String

# track

Contains String

# class TrackException:

# TrackException()

# guild_id

Contains Unsigned 64 bit integer

# track_exception_type

Contains String

# op

Contains String

# track

Contains String

# error

Contains String

# exception_severity

Contains String

# exception_cause

Contains String

# exception_message

Contains String

# class TrackStuck:

# TrackStuck()

# op

Contains String

# threshold_ms

Contains Unsigned 64 bit integer

# track

Contains String

# guild_id

Contains Unsigned 64 bit integer

# track_stuck_type

Contains String

# class WebSocketClosed:

# WebSocketClosed()

# websocket_closed_type

Contains String

# code

Contains Unsigned 64 bit integer

# guild_id

Contains Unsigned 64 bit integer

# user_id

Contains Unsigned 64 bit integer

# op

Contains String

# by_remote

Contains bool

# class PlayerDestroyed:

# PlayerDestroyed()

# cleanup

Contains bool

# op

Contains String

# guild_id

Contains Unsigned 64 bit integer

# user_id

Contains Unsigned 64 bit integer

# player_destroyed_type

Contains String

# class NoSessionPresent(builtins.Exception):

Common base class for all non-exit exceptions.

Inherited Members

builtins.Exception: Exception
builtins.BaseException: with_traceback; args

# class NetworkError(builtins.Exception):

Common base class for all non-exit exceptions.

Inherited Members

builtins.Exception: Exception
builtins.BaseException: with_traceback; args