Models

All the models (also called “Entities”) of Andesite, but as Python classes. This makes interacting with them a lot more comfortable.

The models reside in modules of the andesite.models module, but they are all exported to the andesite module, so you can import them from there.

Player

Player models.

MixerMap

(Type alias) Mapping from player id to MixerPlayer

Type

Dict[str, MixerPlayer]

class PlayerFrameStats(loss, success, usable)

Bases: object

Frame statistics of a player.

class BasePlayer(time, position, paused, volume, filters, frame)

Bases: abc.ABC

Abstract class for Andesite players.

See also

• Player

• MixerPlayer

time

current utc datetime on the node

Type

datetime

position

position of the current playing track, or None if nothing is playing

Type

Optional[float]

paused

whether or not the player is paused

Type

bool

volume

the volume of the player

Type

float

filters

map of filter name -> filter settings for each filter present

Type

FilterMap

frame

Type

PlayerFrameStats

property live_position

Interpolated version of position based on the time that has passed.

Return type

Optional[float]

Returns

None if there is no position attribute, equal to position if the player is paused, and interpolated otherwise.

class MixerPlayer(time, position, paused, volume, filters, frame)

Bases: andesite.models.player.BasePlayer

Player used by Player as a mixer player.

See also

BasePlayer

class Player(time, position, paused, volume, filters, frame, mixer, mixer_enabled)

Bases: andesite.models.player.BasePlayer

mixer

map of mixer player id -> mixer player

Type

MixerMap

mixer_enabled

whether or not the mixer is the current source of audio

Type

bool

Track

Track models.

UNKNOWN_ARTIST

Value used by Lavaplayer if an artist is unknown.

Type

str

class PlaylistInfo(name, selected_track)

Information for of the playlist a track belongs to.

name

name of the playlist

selected_track

index of the selected track in the tracks list, or None if no track is selected

class TrackMetadata(class_name, title, author, length, identifier, uri, is_stream, is_seekable, position)

Additional information for a track.

class_name

class name of the lavaplayer track

Type

str

title

title of the track

Type

str

author

author of the track

Type

str

length

duration of the track, in seconds. Set to None if it’s a stream. Andesite would normally return 2^63 - 1 (Long.MAX_VALUE), but that value doesn’t have any significance in Python so it’s represented with something more meaningful.

Type

Optional[float]

identifier

identifier of the track

Type

str

uri

uri of the track

Type

str

is_stream

whether or not the track is a livestream

Type

bool

is_seekable

whether or not the track supports seeking

Type

bool

position

current position of the track

Type

float

property author_unknown

Whether or not the author is unknown.

Uses constant UNKNOWN_ARTIST to check against.

Keep in mind that there is no way to detect whether the author’s name just happens to coincide with the UNKNOWN_ARTIST text. Use with caution.

Return type

bool

class TrackInfo(track, info)

Track info represents a track and its metadata.

track

base64 encoded track

Type

str

info

metadata of the track

Type

TrackMetadata

class LoadType

Load type of a LoadedTrack

TRACK_LOADED = 'TRACK_LOADED'

SEARCH_RESULT = 'SEARCH_RESULT'

PLAYLIST_LOADED = 'PLAYLIST_LOADED'

NO_MATCHES = 'NO_MATCHES'

LOAD_FAILED = 'LOAD_FAILED'

property success

Whether the load type is a successful one.

Only LOAD_FAILED counts as unsuccessful.

Return type

bool

class LoadedTrack(load_type, tracks, playlist_info, cause=None, severity=None)

Result provided by a load track request.

load_type

type of the response

Type

LoadType

tracks

loaded tracks

Type

Optional[List[TrackInfo]]

playlist_info

metadata of the loaded playlist

Type

Optional[PlaylistInfo]

cause

error that happened while loading tracks

Type

Optional[Error]

severity

severity of the error

Type

Optional[str]

This class provides the magic methods __bool__ and __len__ which operate in respect to tracks.

cause = None

severity = None

get_selected_track()

Get the selected track.

“Selected” means that either the result is a playlist with an entry selected (PlaylistInfo.selected_track), or the result is a LoadType.TRACK_LOADED result (in which case the first and only track is returned).

All other cases will return in None being returned.

Return type

Optional[TrackInfo]

Returns

The selected track if there is any, or None if the selected track doesn’t exist.

Filters

Andesite audio filters.

FILTER_MAP

Mapping from filter name to filter class. See: get_filter_model.

Type

Mapping[str, Type[Filter]]

FilterMapLike

(Type alias) Type of objects which can be used as filter maps. This includes the FilterMap.

Type

Union[FilterMap, Dict[str, Union[Filter, RawDataType]]]

class Filter(enabled=True)

Audio filter for Andesite.

enabled

Whether or not the filter is enabled. This value is mostly useful when receiving the filters from Andesite. However you can also set it to False when sending filters. This will cause the settings to be ignored and instead the default values are sent to Andesite which will cause the filter to be disabled.

Type

bool

When creating a new Filter instance its values are set to the default value.

enabled = True

reset()

Reset the filter settings back to their default values.

Return type

None

class EqualizerBand(band, gain=0.0)

band

band number to configure ( 0 - 14 )

Type

int

gain

value to set for the band ( [-0.25, 1.0] )

Type

float

gain = 0.0

set_band(value)

Setter for band which performs a value check.

Parameters

value (int) – Value to set for the band. ( [0, 14] )

Raises

ValueError – if the provided value is invalid.

Return type

None

set_gain(value)

Setter for gain which performs a value check.

Parameters

value (float) – Value to set for the gain. ( [-0.25, 1] )

Raises

ValueError – if the provided value is invalid.

Return type

None

class Equalizer(enabled=True, bands=<factory>)

bands

array of bands to configure

Type

List[EqualizerBand]

classmethod from_gains(gains)

Create an Equalizer filter from a list of gains.

Parameters

gains (Iterable[Optional[float]]) – Iterable of float which correspond to the gain for the band, or None if the band doesn’t specify a gain.

Return type

Equalizer

get_band(band, create=True)

Get the specified band from the bands list.

If the band doesn’t exist it is created. If you don’t want to automatically create a band, pass create=False.

Parameters

• band (int) – Band number to get

• create (bool) – Whether or not to create a new band if it doesn’t exist. (Defaults to True)

Return type

Optional[EqualizerBand]

get_band_gain(band)

Get the gain of a band.

Return type

Optional[float]

Returns

Gain of the band or None if it doesn’t exist.

set_band_gain(band, gain)

Set the gain of a band to the specified value.

If the band does not exist it is created.

Parameters

• band (int) – Band number to set the gain for.

• gain (float) – Value to set for the gain. ( [-0.25, 1] )

Raises

ValueError – if the provided gain is invalid.

Return type

None

iter_band_gains(use_default=True)

Get a list of all the bands’ gains in order.

Parameters

use_default (bool) – Whether or not to replace non-existent values with the default gain. If False and band doesn’t have a gain set, None is used instead.

Return type

List[Optional[float]]

class Karaoke(enabled=True, level=1.0, mono_level=1.0, filter_band=220.0, filter_width=100.0)

level

Type

float

mono_level

Type

float

filter_band

Type

float

filter_width

Type

float

level = 1.0

mono_level = 1.0

filter_band = 220.0

filter_width = 100.0

class Timescale(enabled=True, speed=1.0, pitch=1.0, rate=1.0)

speed

speed to play music at (> 0)

Type

float

pitch

pitch to set (> 0)

Type

float

rate

rate to set (> 0)

Type

float

speed = 1.0

pitch = 1.0

rate = 1.0

set_speed(value)

Setter for speed which performs a value check.

Parameters

value (float) – Value to set for the speed. ( (0, INF] )

Raises

ValueError – if the provided value is invalid.

Return type

None

set_pitch(value)

Setter for pitch which performs a value check.

Parameters

value (float) – Value to set for the pitch. ( (0, INF] )

Raises

ValueError – if the provided value is invalid.

Return type

None

set_rate(value)

Setter for rate which performs a value check.

Parameters

value (float) – Value to set for the rate. ( (0, INF] )

Raises

ValueError – if the provided value is invalid.

Return type

None

class Tremolo(enabled=True, frequency=2.0, depth=0.5)

frequency

(> 0)

Type

float

depth

( (0, 1] )

Type

float

frequency = 2.0

depth = 0.5

set_frequency(value)

Setter for frequency which performs a value check.

Parameters

value (float) – Value to set for the frequency. ( (0, INF] )

Raises

ValueError – if the provided value is invalid.

Return type

None

set_depth(value)

Setter for depth which performs a value check.

Parameters

value (float) – Value to set for the depth. ( (0, 1] )

Raises

ValueError – if the provided value is invalid.

Return type

None

class Vibrato(enabled=True, frequency=2.0, depth=0.5)

frequency

( (0, 14] )

Type

float

depth

( (0, 1] )

Type

float

frequency = 2.0

depth = 0.5

set_frequency(value)

Setter for frequency which performs a value check.

Parameters

value (float) – Value to set for the frequency. ( (0, 14] )

Raises

ValueError – if the provided value is invalid.

Return type

None

set_depth(value)

Setter for depth which performs a value check.

Parameters

value (float) – Value to set for the depth. ( (0, 1] )

Raises

ValueError – if the provided value is invalid.

Return type

None

class VolumeFilter(enabled=True, volume=1.0)

Volume filter settings.

volume

Volume modifier. This acts as a factor for the actual volume.

Type

float

volume = 1.0

get_filter_model(name)

Get the corresponding filter model for the given name.

If no model for the name exists, None is returned.

Parameters

name (str) – Name of the filter

Return type

Optional[Type[Filter]]

class FilterMap(filters)

Custom mapping type for filters.

filters

Dictionary containing all filters.

Type

Dict[str, Any]

Theoretically this is just a wrapper around the filters dictionary which contains the actual filter data. The class exposes the known filters as properties, but it also supports unknown filters should the library become outdated.

You can also use this as a wrapper for an existing filter dict.

get_filter(name, cls)

Get the filter with the name.

Parameters

• name (str) – Name of the filter to get

• cls (Type[~FT]) – Filter class to use for the filter.

Return type

~FT

property equalizer

Equalizer filter settings

Return type

Equalizer

property karaoke

Karaoke filter settings

Return type

Karaoke

property timescale

Timescale filter settings

Return type

Timescale

property tremolo

Tremolo filter settings

Return type

Tremolo

property vibrato

Vibrato filter settings

Return type

Vibrato

property volume

Volume filter settings

Return type

VolumeFilter

set_filter(andesite_filter)

Set the value for a filter.

Parameters

andesite_filter (Filter) – Filter to set

Return type

None

Send Operations

Sendable operations to Andesite.

These operations can be sent using AbstractWebSocket.send_operation.

See also

andesite.models.receive_operations for operations sent by Andesite.

MixerPlayerUpdateMap

(Type alias) str -> Play/Update map used by the MixerUpdate.

Type

Dict[str, Union[Play, Update]]

class SendOperation

SendOperation is a model that can be passed as a payload to the WebSocket client.

See also

WebSocket.send_operation

class VoiceServerUpdate(session_id, event)

Operation providing a voice server update.

session_id

Session ID for the current user in the event’s guild

Type

str

event

Voice server update event sent by discord

Type

Dict[str, Any]

class Play(track, start=None, end=None, pause=None, volume=None, no_replace=False)

Operation playing a track.

track

base64 encoded lavaplayer track

Type

str

start

timestamp, in seconds, to start the track

Type

Optional[float]

end

timestamp, in seconds, to end the track

Type

Optional[float]

pause

whether or not to pause the player

Type

Optional[bool]

volume

volume to set on the player

Type

Optional[float]

no_replace

if True and a track is already playing/paused, this command is ignored. (Defaults to False)

Type

bool

start = None

end = None

pause = None

volume = None

no_replace = False

class Pause(pause)

Operation pausing the player.

pause

whether or not to pause the player

Type

bool

class Seek(position)

Operation seeking the current track.

position

timestamp to set the current track to, in seconds

Type

float

class Volume(volume)

Operation adjusting the volume.

volume

volume to set on the player

Type

float

class FilterUpdate(filters)

Operation adjusting the filter settings.

See also

This class inherits from FilterMap.

class Update(pause=None, position=None, volume=None, filters=None)

Operation providing an update for the current track.

pause

whether or not to pause the player

Type

Optional[bool]

position

timestamp to set the current track to, in seconds

Type

Optional[float]

volume

volume to set on the player

Type

Optional[float]

filters

configuration for the filters

Type

Optional[FilterUpdate]

pause = None

position = None

volume = None

filters = None

class MixerUpdate(enable, players)

Operation adjusting the mixer players.

enable

if present, controls whether or not the mixer should be used

Type

Optional[bool]

players

map of player id to Play / Update payloads for each mixer source

Type

MixerPlayerUpdateMap

Receive Operations

Operations sent by Andesite.

EVENT_MAP

Mapping from the event name to the corresponding AndesiteEvent type. See: get_event_model

Type

Mapping[str, Type[AndesiteEvent]]

OP_MAP

Mapping from the op code to

Type

Mapping[str, Type[ReceiveOperation]]

the corresponding `ReceiveOperation` type. See

get_update_model

See also

andesite.models.send_operations for operations sent to Andesite.

class ReceiveOperation

Message sent by Andesite.

client

Client that received the message. This is set by the client that received the message.

Type

Optional[andesite.AbstractWebSocketClient]

client = None

class PongResponse(user_id, guild_id)

Simple pong response sent as a response to ping requests.

user_id

User id

Type

int

guild_id

Guild id

Type

int

class ConnectionUpdate(id)

Message sent upon connecting to the Web socket.

id

Connection ID

Type

str

class MetadataUpdate(data)

Payload sent on connection start containing handshake response header.

data

Map of metadata key to value.

Type

Dict[str, Union[int, str, List[str]]]

class StatsUpdate(user_id, stats)

Message containing statistics.

user_id

User ID

Type

int

stats

Statistics

Type

andesite.Stats

class PlayerUpdate(user_id, guild_id, state)

Player update sent by Andesite for active players.

user_id

user id

Type

int

guild_id

guild id

Type

int

state

State of the player. None if no player exists yet.

Type

Optional[andesite.Player]

class AndesiteEvent(type, user_id, guild_id)

Event sent by Andesite.

type

Event type name. This is equal to the name of the class (With the exception of UnknownAndesiteEvent)

Type

str

user_id

User ID

Type

int

guild_id

Guild ID

Type

int

track

Base64 encoded track data

Type

str

class TrackStartEvent(type, user_id, guild_id, track)

Event emitted when a new track starts playing.

class TrackEndReason

Reason why a track stopped playing.

See also

TrackEndEvent

FINISHED

Usually caused by the track reaching the end, however it will also be used when it ends due to an exception.

LOAD_FAILED

Track failed to start, throwing an exception before providing any audio.

STOPPED

Track was stopped due to the player being stopped.

REPLACED

Track stopped playing because a new track started playing.

CLEANUP

Track was stopped because the cleanup threshold for the audio player was reached.

FINISHED = 'FINISHED'

LOAD_FAILED = 'LOAD_FAILED'

STOPPED = 'STOPPED'

REPLACED = 'REPLACED'

CLEANUP = 'CLEANUP'

class TrackEndEvent(type, user_id, guild_id, track, reason, may_start_next)

Event emitted when a track ended.

reason

Reason why a track stopped playing.

Type

TrackEndReason

may_start_next

Indicates whether a new track should be started on receiving this event. If this is False, either this event is already triggered because another track started (TrackEndReason.REPLACED) or because the player is stopped (TrackEndReason.STOPPED, TrackEndReason.CLEANUP).

Type

bool

class TrackExceptionEvent(type, user_id, guild_id, track, error, exception)

Event emitted when there’s an error.

error

Error message

Type

str

exception

Error data

Type

Error

class TrackStuckEvent(type, user_id, guild_id, track, threshold)

Event emitted when a track is stuck.

threshold

Threshold in seconds

Type

float

class WebSocketClosedEvent(type, user_id, guild_id, reason, code, by_remote)

Event emitted when the Andesite node disconnects from a voice channel.

reason

Reason for the disconnect

Type

str

code

Error code

Type

int

by_remote

Whether the disconnect was caused by the remote.

Type

bool

class UnknownAndesiteEvent(type, user_id, guild_id, body)

Special kind of event for unknown events.

This shouldn’t occur at all unless the library is out-dated.

body

Entire event body sent by Andesite. Please note that the keys are in snake_case.

Type

object

get_event_model(event_type)

Get the model corresponding to the given event name.

Parameters

event_type (str) – Event type name.

Return type

Type[AndesiteEvent]

Returns

Model type for the given event type. UnknownAndesiteEvent if no matching event was found.

get_update_model(op, event_type=None)

Get the model corresponding to the given op code.

Parameters

• op (str) – Op code sent by Andesite

• event_type (Optional[str]) – Event type if and only if op is “event”. This is used to return the correct event type. See get_event_model. If not set and op is “event” the function returns None.

Return type

Optional[Type[ReceiveOperation]]

Debug

Debug models for Andesite.

These models are used in either Stats which represents the Andesite stats returned by WebSocketInterface.get_stats or Error which is used to represent an Andesite error.

class StackFrame(class_loader, module_name, module_version, class_name, method_name, file_name, line_number, pretty)

Andesite stack frame.

Can be found in Error.stack.

class_loader

name of the classloader

Type

Optional[str]

module_name

name of the module

Type

Optional[str]

module_version

version of the module

Type

Optional[str]

class_name

name of the class

Type

str

method_name

name of the method

Type

str

file_name

name of the source file

Type

Optional[str]

line_number

line in the source file

Type

Optional[int]

pretty

pretty printed version of this frame, as it would appear on Throwable#printStackTrace

Type

str

class Error(class_name, message, stack, suppressed, cause)

Andesite error.

You can convert the Andesite error data into a Python exception using the as_python_exception method and the raise_python_exception to raise it.

class_name

class of the error

Type

str

message

message of the error

Type

Optional[str]

stack

stacktrace of the error

Type

List[StackFrame]

cause

cause of the error

Type

Optional[Error]

suppressed

suppressed errors

Type

List[Error]

as_python_exception()

Create an AndesiteException which can be raised.

If cause is not None it is added to the exception.

Return type

AndesiteException

raise_error()

Raise the Andesite error as an AndesiteException.

Raises

AndesiteException – Generated using the as_python_exception method.

Return type

NoReturn

exception AndesiteException(class_name, message, stack, suppressed)

Andesite’s Error represented as python exceptions.

class_name

Class name of the error

Type

str

message

message of the error

Type

Optional[str]

stack

cause of the error

Type

List[StackFrame]

suppressed

suppressed errors

Type

List[Error]

class PlayersStats(total, playing)

Players statistics sent by Andesite.

total

Total amount of players

Type

int

playing

Amount of players that are actively playing

Type

int

See also

This statistic can be found in Stats which is retrieved from Andesite by the clients. Both HTTP and WebSocket are able to get them.

class RuntimeVMStats(name, vendor, version)

VM statistics.

name

Type

str

vendor

Type

str

version

Type

str

See also

This statistic can be found in Stats which is retrieved from Andesite by the clients. Both HTTP and WebSocket are able to get them.

class RuntimeSpecStats(name, vendor, version)

Spec statistics.

name

Type

str

vendor

Type

str

version

Type

str

See also

This statistic can be found in Stats which is retrieved from Andesite by the clients. Both HTTP and WebSocket are able to get them.

class RuntimeVersionStats(feature, interim, update, patch, pre, build, optional)

Version information stats.

feature

Type

int

interim

Type

int

update

Type

int

patch

Type

int

pre

Type

Optional[str]

build

Type

int

optional

Type

str

See also

This statistic can be found in Stats which is retrieved from Andesite by the clients. Both HTTP and WebSocket are able to get them.

class RuntimeStats(uptime, pid, management_spec_version, name, vm, spec, version)

Runtime statistics.

uptime

Type

int

pid

Type

int

management_spec_version

Type

str

name

Type

str

vm

Type

RuntimeVMStats

spec

Type

RuntimeSpecStats

version

Type

RuntimeVersionStats

See also

This statistic can be found in Stats which is retrieved from Andesite by the clients. Both HTTP and WebSocket are able to get them.

class OSStats(processors, name, arch, version)

OS statistics.

processors

Type

int

name

Type

str

arch

Type

str

version

Type

str

See also

This statistic can be found in Stats which is retrieved from Andesite by the clients. Both HTTP and WebSocket are able to get them.

class CPUStats(andesite, system)

CPU statistics.

andesite

Type

float

system

Type

float

See also

This statistic can be found in Stats which is retrieved from Andesite by the clients. Both HTTP and WebSocket are able to get them.

class ClassLoadingStats(loaded, total_loaded, unloaded)

Class loading statistics.

loaded

Type

int

total_loaded

Type

int

unloaded

Type

int

class ThreadStats(running, daemon, peak, total_started)

Thread statistics.

running

Type

int

daemon

Type

int

peak

Type

int

total_started

Type

int

See also

This statistic can be found in Stats which is retrieved from Andesite by the clients. Both HTTP and WebSocket are able to get them.

class CompilationStats(name, total_time)

Compilation statistics.

name

Type

str

total_time

Type

int

See also

This statistic can be found in Stats which is retrieved from Andesite by the clients. Both HTTP and WebSocket are able to get them.

class MemoryCommonUsageStats(init, used, committed, max)

Memory usage statistics.

init

Type

int

used

Type

int

committed

Type

int

max

Type

int

See also

This statistic can be found in Stats which is retrieved from Andesite by the clients. Both HTTP and WebSocket are able to get them.

class MemoryStats(pending_finalization, heap, non_heap)

Memory statistics.

pending_finalization

Type

int

heap

Type

MemoryCommonUsageStats

non_heap

Type

MemoryCommonUsageStats

See also

This statistic can be found in Stats which is retrieved from Andesite by the clients. Both HTTP and WebSocket are able to get them.

class GCStats(name, collection_count, collection_time, pools)

Garbage collection statistics.

name

Type

str

collection_count

Type

int

collection_time

Type

int

pools

Type

List[str]

See also

This statistic can be found in Stats which is retrieved from Andesite by the clients. Both HTTP and WebSocket are able to get them.

class MemoryPoolStats(name, type, collection_usage, collection_usage_threshold, collection_usage_threshold_count, peak_usage, usage, usage_threshold, usage_threshold_count, managers)

Memory pool statistics.

name

Name of the pool

Type

str

type

Type of the pool. This is either “HEAP” or “NON_HEAP”.

Type

str

collection_usage

Type

Optional[MemoryHeapStats]

collection_usage_threshold

Type

Optional[int]

collection_usage_threshold_count

Type

Optional[int]

peak_usage

Type

MemoryCommonUsageStats

usage

Type

MemoryCommonUsageStats

usage_threshold

Type

int

usage_threshold_count

Type

int

managers

Type

List[str]

See also

This statistic can be found in Stats which is retrieved from Andesite by the clients. Both HTTP and WebSocket are able to get them.

class MemoryManagerStats(name, pools)

Memory manager statistics.

name

Name of the manager

Type

str

pools

Memory pools

Type

List[str]

See also

This statistic can be found in Stats which is retrieved from Andesite by the clients. Both HTTP and WebSocket are able to get them.

class FrameStats(user, guild, success, loss)

Frame statistics for a guild player.

user

User ID

Type

int

guild

Guild ID

Type

int

success

Amount of successful frames

Type

int

loss

Amount of lost frames

Type

int

See also

This statistic can be found in Stats which is retrieved from Andesite by the clients. Both HTTP and WebSocket are able to get them.

class Stats(players, runtime, os, cpu, class_loading, thread, compilation, memory, gc, memory_pools, memory_managers, frame_stats)

Statistics sent by Andesite

players

Player statistics

Type

PlayersStats

runtime

Runtime statistics

Type

RuntimeStats

os

OS statistics

Type

OSStats

cpu

CPU statistics

Type

CPUStats

class_loading

Class loading statistics

Type

ClassLoadingStats

thread

Thread statistics

Type

ThreadStats

compilation

Compilation statistics

Type

CompilationStats

memory

Memory statistics

Type

MemoryStats

gc

GC statistics

Type

List[GCStats]

memory_pools

Memory pool statistics

Type

List[MemoryPoolStats]

memory_managers

Memory manager statistics

Type

List[MemoryManagerStats]

frame_stats

Frame statistics

Type

List[FrameStats]