REST API¶

Filter payloads¶

class sonolink.rest.schemas.PlayerFilters(*, volume: float | UnsetType = UNSET, equalizer: list[EqualizerFilter] | UnsetType = UNSET, karaoke: KaraokeFilter | UnsetType = UNSET, timescale: TimescaleFilter | UnsetType = UNSET, tremolo: TremoloFilter | UnsetType = UNSET, vibrato: VibratoFilter | UnsetType = UNSET, rotation: RotationFilter | UnsetType = UNSET, distortion: DistortionFilter | UnsetType = UNSET, channel_mix: ChannelMixFilter | UnsetType = UNSET, low_pass: LowPassFilter | UnsetType = UNSET, plugin_filters: dict[str, Any] | UnsetType = UNSET)[source]¶

Attributes

channel_mix
distortion
equalizer
karaoke
low_pass
plugin_filters
rotation
timescale
tremolo
vibrato
volume

Represents the full filter payload for a Lavalink player.

This object is sent in UpdatePlayerRequest under filters. Only provided attributes are updated; attributes set to None are ignored, allowing partial filter updates without resetting other filters.

channel_mix: ChannelMixFilter | UnsetType¶: Cross-channel matrix configuration (ChannelMixFilter).

distortion: DistortionFilter | UnsetType¶: Wave-shaping configuration (DistortionFilter).

equalizer: list[EqualizerFilter] | UnsetType¶: List of EqualizerFilter entries for bands 0..14.

karaoke: KaraokeFilter | UnsetType¶: Karaoke configuration (KaraokeFilter).

low_pass: LowPassFilter | UnsetType¶: Low-pass configuration (LowPassFilter).

plugin_filters: dict[str, Any] | UnsetType¶: Plugin-defined filter payloads keyed by plugin name. Values are plugin-specific and passed through as-is.

rotation: RotationFilter | UnsetType¶: Stereo rotation configuration (RotationFilter).

timescale: TimescaleFilter | UnsetType¶: Time-domain transform configuration (TimescaleFilter).

tremolo: TremoloFilter | UnsetType¶: Volume oscillation configuration (TremoloFilter).

vibrato: VibratoFilter | UnsetType¶: Pitch oscillation configuration (VibratoFilter).

volume: float | UnsetType¶: Linear volume multiplier from 0.0 to 5.0. 1.0 is 100% volume. Values above 1.0 may clip.

class sonolink.rest.schemas.EqualizerFilter(*, band: int, gain: float)[source]¶

Attributes

band
gain

Represents a single Lavalink equalizer band.

Lavalink exposes 15 bands indexed 0..14. The frequencies are approximately: 25, 40, 63, 100, 160, 250, 400, 630, 1000, 1600, 2500, 4000, 6300, 10000, 16000 Hz.

band: int¶: Target band index from 0 to 14.

gain: float¶: Band gain multiplier from -0.25 to 1.0. -0.25 mutes the band and 0.25 roughly doubles it.

class sonolink.rest.schemas.KaraokeFilter(*, level: float | UnsetType = UNSET, mono_level: float | UnsetType = UNSET, filter_band: float | UnsetType = UNSET, filter_width: float | UnsetType = UNSET)[source]¶

Attributes

filter_band
filter_width
level
mono_level

Represents karaoke filter configuration.

This filter reduces content in a target frequency region, commonly used for vocal reduction.

filter_band: float | UnsetType¶: Center frequency in Hz for the target region.

filter_width: float | UnsetType¶: Bandwidth around filter_band in Hz.

level: float | UnsetType¶: Overall effect intensity from 0.0 to 1.0.

mono_level: float | UnsetType¶: Mono signal amount from 0.0 to 1.0.

class sonolink.rest.schemas.TimescaleFilter(*, speed: float | UnsetType = UNSET, pitch: float | UnsetType = UNSET, rate: float | UnsetType = UNSET)[source]¶

Attributes

pitch
rate
speed

Represents timescale filter configuration.

This filter changes perceived playback speed, pitch, and rate. In Lavalink, omitted values are treated as 1.0.

pitch: float | UnsetType¶: Pitch multiplier (0.0 <= x). 1.0 is unchanged.

rate: float | UnsetType¶: Internal rate multiplier (0.0 <= x).

speed: float | UnsetType¶: Playback speed multiplier (0.0 <= x). 1.0 is normal.

class sonolink.rest.schemas.TremoloFilter(*, frequency: float | UnsetType = UNSET, depth: float | UnsetType = UNSET)[source]¶

Attributes

depth
frequency

Represents tremolo filter configuration.

Tremolo rapidly oscillates output volume.

depth: float | UnsetType¶: Effect depth (0.0 < x <= 1.0).

frequency: float | UnsetType¶: Oscillation frequency in Hz (0.0 < x).

class sonolink.rest.schemas.VibratoFilter(*, frequency: float | UnsetType = UNSET, depth: float | UnsetType = UNSET)[source]¶

Attributes

depth
frequency

Represents vibrato filter configuration.

Vibrato rapidly oscillates output pitch.

depth: float | UnsetType¶: Effect depth (0.0 < x <= 1.0).

frequency: float | UnsetType¶: Oscillation frequency in Hz (0.0 < x <= 14.0).

class sonolink.rest.schemas.RotationFilter(*, rotation_hz: float | UnsetType = UNSET)[source]¶

Attributes

rotation_hz

Represents stereo rotation filter configuration.

rotation_hz: float | UnsetType¶: Rotation frequency in Hz. 0.2 is a common slow rotation.

Attributes

cos_offset
cos_scale
offset
scale
sin_offset
sin_scale
tan_offset
tan_scale

Represents distortion filter configuration.

Distortion combines sinusoidal and linear transforms. Small changes can produce large audible differences, so tune incrementally.

cos_offset: float | UnsetType¶: Cosine input offset component.

cos_scale: float | UnsetType¶: Cosine scaling component.

offset: float | UnsetType¶: Linear output offset applied after shaping.

scale: float | UnsetType¶: Linear output scaling applied after shaping.

sin_offset: float | UnsetType¶: Sine input offset component.

sin_scale: float | UnsetType¶: Sine scaling component.

tan_offset: float | UnsetType¶: Tangent input offset component.

tan_scale: float | UnsetType¶: Tangent scaling component.

class sonolink.rest.schemas.ChannelMixFilter(*, left_to_left: float | UnsetType = UNSET, left_to_right: float | UnsetType = UNSET, right_to_left: float | UnsetType = UNSET, right_to_right: float | UnsetType = UNSET)[source]¶

Attributes

left_to_left
left_to_right
right_to_left
right_to_right

Represents channel mix filter configuration.

All coefficients satisfy 0.0 <= x <= 1.0. The default matrix keeps channels independent. Setting all coefficients to 0.5 yields dual-mono output.

left_to_left: float | UnsetType¶: Contribution of left input to left output.

left_to_right: float | UnsetType¶: Contribution of left input to right output.

right_to_left: float | UnsetType¶: Contribution of right input to left output.

right_to_right: float | UnsetType¶: Contribution of right input to right output.

class sonolink.rest.schemas.LowPassFilter(*, smoothing: float | UnsetType = UNSET)[source]¶

Attributes

smoothing

Represents low-pass filter configuration.

Low-pass filtering suppresses higher frequencies while preserving lower ones.

smoothing: float | UnsetType¶: Smoothing factor (x > 1.0). Values <= 1.0 disable this filter.

Info payloads¶

class sonolink.rest.schemas.InfoResponse(*, version: VersionObject, build_time: int, git: GitObject, jvm: str, lavaplayer: str, source_managers: list[str], filters: list[str], plugins: list[PluginObject])[source]¶

Attributes

build_time
filters
git
jvm
lavaplayer
plugins
source_managers
version

Represents the Lavalink Info response payload.

build_time: int¶: Build timestamp in Unix milliseconds.

filters: list[str]¶: Names of supported audio filters.

git: GitObject¶: Git repository information for this build.

jvm: str¶: JVM version used to run Lavalink.

lavaplayer: str¶: Embedded Lavaplayer version.

plugins: list[PluginObject]¶: Installed Lavalink plugins.

source_managers: list[str]¶: Enabled source managers.

version: VersionObject¶: Version metadata of the Lavalink server.

class sonolink.rest.schemas.VersionObject(*, semver: str, major: int, minor: int, patch: int, pre_release: str | None = None, build: str | None = None)[source]¶

Attributes

build
major
minor
patch
pre_release
semver

Represents Lavalink version metadata.

build: str | None¶: Optional build metadata string.

major: int¶: Major version number.

minor: int¶: Minor version number.

patch: int¶: Patch version number.

pre_release: str | None¶: Pre-release identifier if present.

semver: str¶: Full semantic version string.

class sonolink.rest.schemas.GitObject(*, branch: str, commit: str, commit_time: int)[source]¶

Attributes

branch
commit
commit_time

Represents Git metadata for the Lavalink build.

branch: str¶: Git branch name.

commit: str¶: Commit hash.

commit_time: int¶: Commit timestamp in Unix milliseconds.

class sonolink.rest.schemas.PluginObject(*, name: str, version: str)[source]¶

Attributes

name
version

Represents an installed Lavalink plugin.

name: str¶: Plugin name.

version: str¶: Plugin version string.

class sonolink.rest.schemas.MemoryObject(*, free: int, used: int, allocated: int, reservable: int)[source]¶

Attributes

allocated
free
reservable
used

Represents JVM memory usage statistics.

allocated: int¶: Allocated memory in bytes.

free: int¶: Free memory in bytes.

reservable: int¶: Maximum reservable memory in bytes.

used: int¶: Used memory in bytes.

class sonolink.rest.schemas.CPUObject(*, cores: int, system_load: float, lavalink_load: float)[source]¶

Attributes

cores
lavalink_load
system_load

Represents CPU usage statistics.

cores: int¶: Number of available CPU cores.

lavalink_load: float¶: CPU load caused by Lavalink.

system_load: float¶: System CPU load as a fraction.

class sonolink.rest.schemas.FrameStatsObject(*, sent: int, nulled: int, deficit: int)[source]¶

Attributes

deficit
nulled
sent

Represents audio frame delivery statistics.

deficit: int¶: Frame deficit relative to the expected rate (3000 frames/player). Negative means excess frames, positive means insufficient frames.

nulled: int¶: Number of frames that were missing audio data.

sent: int¶: Number of frames successfully sent.

class sonolink.rest.schemas.StatsResponse(*, players: int, playing_players: int, uptime: int, memory: MemoryObject, cpu: CPUObject, frame_stats: FrameStatsObject | None = None)[source]¶

Attributes

cpu
frame_stats
memory
penalty
players
playing_players
uptime

Represents the Lavalink Stats response payload.

Returned periodically over WebSocket and via /v4/stats.

cpu: CPUObject¶: CPU usage statistics.

frame_stats: FrameStatsObject | None¶: Optional audio frame statistics.

memory: MemoryObject¶: JVM memory usage statistics.

property penalty: float¶: Calculate node penalty; Lower - better.

players: int¶: Total number of players.

playing_players: int¶: Number of actively playing players.

uptime: int¶: Node uptime in milliseconds.

sonolink.rest.schemas.VersionResponse = <class 'str'>¶

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

Route planner payloads¶

class sonolink.rest.schemas.DetailsObject(*, ip_block: IPBlockObject, failing_addresses: list[FailingAddressObject] = <factory>, rotate_index: str | None = None, ip_index: int | None = None, block_index: int | None = None, current_address: str | None = None, current_address_index: int | None = None)[source]¶

Attributes

block_index
current_address
current_address_index
failing_addresses
ip_block
ip_index
rotate_index

Represents route planner details.

Provides runtime information about the active IP rotation strategy. Some attributes are only present for specific route planner types.

block_index: int | None¶: Index of the active /64 block. This value increases whenever an address block is rotated due to bans. Available for RotatingNanoIpRoutePlanner.

current_address: str | None¶: Currently selected outbound IP address. Available for RotatingIpRoutePlanner.

current_address_index: int | None¶: Offset of the active address inside the IP block. Available for NanoIpRoutePlanner and RotatingNanoIpRoutePlanner.

failing_addresses: list[FailingAddressObject]¶: List of addresses currently marked as failing (FailingAddressObject).

ip_block: IPBlockObject¶: IP block configuration currently used (IPBlockObject).

ip_index: int | None¶: Current offset within the IP block. Available for RotatingIpRoutePlanner.

rotate_index: str | None¶: Number of performed rotations. Available for RotatingIpRoutePlanner.

class sonolink.rest.schemas.IPBlockObject(*, type_: IPBlockType, size: str)[source]¶

Attributes

size
type_

Represents an IP block used by the route planner.

size: str¶: The size of the IP block.

type_: IPBlockType¶: Type of IP block (IPBlockType).

class sonolink.rest.schemas.FailingAddressObject(*, address: str, timestamp: int, time: str)[source]¶

Attributes

address
time
timestamp

Represents an address marked as failing by the route planner.

Addresses are temporarily excluded after connection failures.

address: str¶: The failing IP address.

time: str¶: Human-readable failure time string.

timestamp: int¶: Failure timestamp in Unix milliseconds.

class sonolink.rest.schemas.RoutePlannerStatusResponse(*, class_: RoutePlannerType | None = None, details: DetailsObject | None = None)[source]¶

Attributes

class_
details

Represents the response from GET /v4/routeplanner/status.

class_: RoutePlannerType | None¶: The type of route planner in use (RoutePlannerType).

details: DetailsObject | None¶: Status details (DetailsObject), or None if not enabled.

class sonolink.rest.schemas.UnmarkFailedAddressRequest(*, address: str)[source]¶

Attributes

address

Represents a request to unmark a previously failing address.

address: str¶: The address to unmark as failed. Must belong to the same IP block.

Player payloads¶

class sonolink.rest.schemas.Player(*, guild_id: str, track: Track | None = None, volume: int, paused: bool, state: PlayerState, voice: PlayerVoiceState, filters: PlayerFilters)[source]¶

Attributes

filters
guild_id
paused
state
track
voice
volume

Represents a Lavalink Player.

filters: PlayerFilters¶: Active audio filters (PlayerFilters).

guild_id: str¶: The Discord guild ID the player belongs to.

paused: bool¶: Whether the player is currently paused.

state: PlayerState¶: Current state of the player (PlayerState).

track: Track | None¶: Currently playing track (Track) or None if no track is loaded.

voice: PlayerVoiceState¶: Voice connection state (PlayerVoiceState).

volume: int¶: Player volume (0-1000 percent scale).

class sonolink.rest.schemas.PlayerState(*, time: int, position: int, connected: bool, ping: int)[source]¶

Attributes

connected
ping
position
time

Represents the state of a Lavalink Player.

connected: bool¶: Whether the player is connected to a voice channel.

ping: int¶: Connection ping in milliseconds, -1 if not connected.

position: int¶: Current track position in milliseconds.

time: int¶: Timestamp of the state in milliseconds.

class sonolink.rest.schemas.PlayerVoiceState(*, token: str, endpoint: str, session_id: str, channel_id: str | None = None)[source]¶

Attributes

channel_id
endpoint
session_id
token

Represents the voice connection state of a Lavalink Player.

channel_id: str | None¶: The Discord voice channel ID the bot is connecting to.

endpoint: str¶: Voice server endpoint.

session_id: str¶: Session ID of the voice connection.

token: str¶: Voice connection token.

class sonolink.rest.schemas.UpdatePlayerTrackRequest(*, encoded: str | UnsetType | None = UNSET, identifier: str | UnsetType = UNSET, user_data: dict[str, Any] | UnsetType = UNSET)[source]¶

Attributes

encoded
identifier
user_data

Represents a track update request for a Lavalink Player.

Used within UpdatePlayerRequest to play or modify a track.

encoded: str | UnsetType | None¶: Base64-encoded track string, optional.

identifier: str | UnsetType¶: Unique track identifier, optional.

user_data: dict[str, Any] | UnsetType¶: Optional user data previously provided when updating the player.

class sonolink.rest.schemas.UpdatePlayerRequest(*, track: UpdatePlayerTrackRequest | UnsetType = UNSET, position: int | UnsetType = UNSET, endtime: int | UnsetType = UNSET, volume: int | UnsetType = UNSET, paused: bool | UnsetType = UNSET, filters: PlayerFilters | UnsetType = UNSET, voice: PlayerVoiceState | UnsetType = UNSET)[source]¶

Attributes

endtime
filters
paused
position
track
voice
volume

Payload to update a Lavalink Player.

This object is sent to /players/{guildId} to modify player state.

endtime: int | UnsetType¶: Track end time in milliseconds, optional.

filters: PlayerFilters | UnsetType¶: Audio filters to apply (PlayerFilters), optional.

paused: bool | UnsetType¶: Whether to pause the player, optional.

position: int | UnsetType¶: Seek position in milliseconds, optional.

track: UpdatePlayerTrackRequest | UnsetType¶: Track to play or update (UpdatePlayerTrackRequest), optional.

voice: PlayerVoiceState | UnsetType¶: Voice state updates (PlayerVoiceState), optional.

volume: int | UnsetType¶: Volume to set (0-1000 percent scale), optional.

sonolink.rest.schemas.GetPlayersResponse = GetPlayersResponse¶

Type alias.

Type aliases are created through the type statement:

type Alias = int

In this example, Alias and int will be treated equivalently by static type checkers.

At runtime, Alias is an instance of TypeAliasType. The __name__ attribute holds the name of the type alias. The value of the type alias is stored in the __value__ attribute. It is evaluated lazily, so the value is computed only if the attribute is accessed.

Type aliases can also be generic:

type ListOrSet[T] = list[T] | set[T]

In this case, the type parameters of the alias are stored in the __type_params__ attribute.

See PEP 695 for more information.

sonolink.rest.schemas.GetPlayerResponse = GetPlayerResponse¶

Type alias.

Type aliases are created through the type statement:

type Alias = int

In this example, Alias and int will be treated equivalently by static type checkers.

Type aliases can also be generic:

type ListOrSet[T] = list[T] | set[T]

In this case, the type parameters of the alias are stored in the __type_params__ attribute.

See PEP 695 for more information.

sonolink.rest.schemas.UpdatePlayerResponse = UpdatePlayerResponse¶

Type alias.

Type aliases are created through the type statement:

type Alias = int

In this example, Alias and int will be treated equivalently by static type checkers.

Type aliases can also be generic:

type ListOrSet[T] = list[T] | set[T]

In this case, the type parameters of the alias are stored in the __type_params__ attribute.

See PEP 695 for more information.

sonolink.rest.schemas.DestroyPlayerResponse = DestroyPlayerResponse¶

Type alias.

Type aliases are created through the type statement:

type Alias = int

In this example, Alias and int will be treated equivalently by static type checkers.

Type aliases can also be generic:

type ListOrSet[T] = list[T] | set[T]

In this case, the type parameters of the alias are stored in the __type_params__ attribute.

See PEP 695 for more information.

Playlist and session payloads¶

class sonolink.rest.schemas.PlaylistInfo(*, name: str, selected_track: int)[source]¶

Attributes

name
selected_track

Represents metadata for a loaded playlist.

This object is embedded in playlist load responses.

name: str¶: Name of the playlist.

selected_track: int¶: Index of the selected track within the playlist, or -1 if no track is selected.

class sonolink.rest.schemas.UpdateSessionRequest(*, resuming: bool | None = None, timeout: int | None = None)[source]¶

Attributes

resuming
timeout

Represents a request to update a Lavalink session.

Sent via PATCH /v4/sessions/{sessionId} to modify the resuming state or the session timeout.

resuming: bool | None¶: Optional. Whether resuming is enabled for this session.

timeout: int | None¶: Optional. Timeout in seconds for resuming. Defaults to 60s.

Track payloads¶

class sonolink.rest.schemas.TrackInfo(*, identifier: str, uri: str | None = None, title: str, author: str, length: int, position: int, is_seekable: bool, is_stream: bool, source_name: str, artwork_url: str | None = None, isrc: str | None = None)[source]¶

Attributes

artwork_url
author
identifier
is_seekable
is_stream
isrc
length
position
source_name
title
uri

Represents metadata for Track, available under Track.info.

artwork_url: str | None¶: Artwork URL, if available (nullable).

author: str¶: Track author or artist name.

identifier: str¶: Unique track identifier.

is_seekable: bool¶: Whether the track is seekable.

is_stream: bool¶: Whether the track is a live stream.

isrc: str | None¶: International Standard Recording Code (nullable).

length: int¶: Total length of the track in milliseconds.

position: int¶: Current playback position in milliseconds.

source_name: str¶: Name of the source manager that provided the track.

title: str¶: Track title.

uri: str | None¶: The track’s URI, if available (nullable).

class sonolink.rest.schemas.Track(*, encoded: str, info: TrackInfo, plugin_info: Any, user_data: Any)[source]¶

Attributes

encoded
info
plugin_info
user_data

Represents a Track payload.

encoded: str¶: Base64-encoded track string.

info: TrackInfo¶: Track metadata object (TrackInfo).

plugin_info: Any¶: Additional track info provided by plugins.

user_data: Any¶: Additional track data previously provided (UpdatePlayerRequest).

class sonolink.rest.schemas.TrackLoadingResponse(*, load_type: TrackLoadResult, data: dict[str, Any] | list[dict[str, Any]] | None)[source]¶

Attributes

data
load_type

Represents a TrackLoadingResponse structure payload.

data: dict[str, Any] | list[dict[str, Any]] | None¶: Associated load result data, this is a dict that will be converted into a valid object in the respective object.

load_type: TrackLoadResult¶: Type of load result (TrackLoadResult).

class sonolink.rest.schemas.PlaylistData(*, info: PlaylistInfo, plugin_info: dict[str, Any], tracks: list[Track])[source]¶

Attributes

info
plugin_info
tracks

Contains the detailed results of a track load request.

For playlists, this contains playlist metadata and a list of tracks.

info: PlaylistInfo¶: Playlist metadata (PlaylistInfo).

plugin_info: dict[str, Any]¶: Additional data returned by the source plugin.

tracks: list[Track]¶: List of loaded tracks (Track).

sonolink.rest.schemas.TrackDecodeResponse = <class 'sonolink.rest.schemas.track.Track'>¶

Represents a Track payload.

sonolink.rest.schemas.TracksDecodeResponse¶

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

alias of list[Track]