Supplementary¶

This section contains reference documentation for the more advanced concepts and types in SonoLink. If you’re new to SonoLink, you should start with the SonoLink Documentation and the Guides before diving into this section.

Queue¶

class sonolink.History(settings: HistorySettings | None = None)[source]¶

Attributes

count
enabled

A specialized queue for tracking playback history.

This class is intended to be read-only for users. Mutation methods will raise AttributeError.

property count: int¶

The number of tracks in this collection.

Returns:: The total number of tracks currently held.
Return type:: int

property enabled: bool¶

Whether history recording is enabled.

Added in version 1.3.0.

Returns:: True if history is enabled, False otherwise.
Return type:: bool

class sonolink.Queue(*, mode: QueueMode = QueueMode.NORMAL, history_settings: HistorySettings | None = None)[source]¶

Attributes

autoplay_tracks
count
current_track
history
mode
shuffle_mode
tracks

Methods

defclear
defclear_history
defcopy
defdedupe
defget
asyncget_wait
defmove
defpop
defpop_at
defprevious
defput
defput_at
defput_autoplay
asyncput_wait
defremove
defremove_at
asyncremove_wait
defreset
defreverse
defshuffle
defsort
defswap

A queue implementation for managing playable tracks.

clear()¶

Remove all items from the queue.

clear_history()[source]¶

Clear the queue history if history is enabled.

copy()[source]¶

Create a shallow copy of the queue.

Returns:: A shallow copy of the queue with the same items, mode, shuffle state, and history.
Return type:: Queue

dedupe(*, key: ~typing.Callable[[~sonolink.models.track.Playable], ~typing.Any] = <function Queue.<lambda>>)[source]¶

Remove duplicate tracks in place, keeping the first occurrence of each.

Parameters:: key (Callable[[Playable], Any]) – A function that returns the value used to determine duplicates. Defaults to comparing by identifier.
Returns:: The number of tracks removed.
Return type:: int

get(*, key: Callable[[Playable], Any] | None = None)[source]¶

Get the next track from the queue, respecting the current queue mode.

User-added tracks always take priority over AutoPlay-discovered tracks. If the user lane is empty, falls back to the AutoPlay lane. If the queue is in LOOP mode, returns the current track. If the queue is in LOOP_ALL mode and empty, restores tracks from history. If shuffle_mode is ShuffleMode.PERSISTENT, a random track is popped from the user lane instead of the head.

Parameters:

key (Callable[[Playable], Any] | None) –

If provided and current_track is set, the picked track is skipped in favour of the next candidate whose key(track) differs from key(current_track). Useful to avoid repeats, e.g. key=lambda track: track.author to avoid picking a track by the currently playing artist. If every remaining candidate matches, the match is allowed rather than raising. Only applies to the user lane. Defaults to None.

Added in version 1.3.0.

Returns:

The retrieved track.

Return type:

Playable

Raises:

QueueEmpty – Both the user queue and AutoPlay queue are empty.

async get_wait(*, key: Callable[[Playable], Any] | None = None)[source]¶

Asynchronously get a track from the queue, waits if necessary.

This method will wait indefinitely until a track is available in the queue. This method can be used to implement a system that waits for a next track to play after the current track finishes, for example.

Parameters:

key (Callable[[Playable], Any] | None) –

See get() for details on how this parameter is used.

Added in version 1.3.0.

Returns:

The retrieved track.

Return type:

Playable

move(old: int, new: int)[source]¶

Move a track from one index to another, shifting other tracks.

Parameters:

old (int) – The index of the track to move.
new (int) – The target index for the track.
versionadded: (..) – 1.3.0:

Returns:

The moved track.

Return type:

Playable

Raises:

QueueEmpty – The queue is empty.
IndexError – One or both indices are out of range.

pop()[source]¶

Remove and return the next track from the queue.

The returned track is set as the current track. If history is enabled, the previous current track is added to history.

Returns:: The popped track.
Return type:: Playable
Raises:: QueueEmpty – The queue is empty.

pop_at(index: int)[source]¶

Remove and return a track from a specific queue index.

The returned track is set as the current track. If history is enabled, the previous current track is added to history.

Parameters:

index (int) – The index to pop from.

Returns:

The popped track.

Return type:

Playable

Raises:

QueueEmpty – The queue is empty.
IndexError – There is no item at the given index.

previous()[source]¶

Pop the most recent track from history and set it as current.

The current track is pushed back to the front of the queue.

Returns:: The track retrieved from history.
Return type:: Playable
Raises:: QueueEmpty – The history is empty.

put(tracks: Iterable[Playable] | Playable | Playlist, /, *, atomic: bool = True)[source]¶

Put one or more tracks at the end of the queue.

Parameters:

tracks (Iterable[Playable] | Playable | Playlist) – The track(s) or playlist to add to the queue.
atomic (bool) – Whether to insert the items atomically. If True, all items must be Playable or a TypeError is raised and nothing is added. If False, non-Playable items are filtered out. Defaults to True.

Returns:

The number of tracks added to the queue.

Return type:

int

Raises:

TypeError – When atomic=True and a non-Playable item is encountered.

put_at(index: int, tracks: Iterable[Playable] | Playable | Playlist, /, *, atomic: bool = True)¶

Put one or more tracks at index.

Parameters:

index (int) – The index to insert the track(s) to.
tracks (Iterable[Playable] | Playable | Playlist) – The track(s) or playlist to add to the queue.
atomic (bool) – Whether to insert the items atomically. If True, all items must be Playable or a TypeError is raised and nothing is added. If False, non-Playable items are filtered out. Defaults to True.

Returns:

The number of tracks added to the queue.

Return type:

int

Raises:

TypeError – When atomic=True and a non-Playable item is encountered.

put_autoplay(tracks: Iterable[Playable] | Playable, /)[source]¶

Add AutoPlay-discovered tracks to the AutoPlay lane.

These tracks are only played once all user-added tracks are exhausted. Each track is automatically tagged with autoplay.

Parameters:

tracks (Iterable[Playable] | Playable) – The AutoPlay track(s) to stage.

Return type:

int

Returns:

int – The number of tracks added.
.. versionadded:: 1.1.0

async put_wait(tracks: Iterable[Playable] | Playable | Playlist, /, *, atomic: bool = True)[source]¶

Asynchronously put one or more tracks into the queue.

This method is thread-safe and maintains insert order through a lock.

Parameters:

tracks (Iterable[Playable] | Playable | Playlist) – The track(s) or playlist to add to the queue.
atomic (bool) – Whether to insert the items atomically. If True, all items must be Playable or a TypeError is raised and nothing is added. If False, non-Playable items are filtered out. Defaults to True.

Returns:

The number of tracks added to the queue.

Return type:

int

Raises:

TypeError – When atomic=True and a non-Playable item is encountered.

remove(tracks: Iterable[Playable] | Playable | Playlist, /, *, remove_all: bool = True, key: Callable[[Playable], Any] | None = None)¶

Remove one or more tracks from this queue.

Parameters:

tracks (Iterable[Playable] | Playable | Playlist) – The track(s) or playlist to remove from the queue.
remove_all (bool) – Whether to remove all occurrences of a track from this queue. When set to False, only the first occurrence of each track is removed. Defaults to True.
key (Callable[[Playable], Any] | None) –
If provided, tracks are matched by comparing key(track) against each value in tracks instead of using equality directly. This lets you remove tracks without holding the original Playable instance, e.g. queue.remove([track.identifier], key=lambda t: t.identifier). When key is set, items in tracks are used as-is and are not coerced to Playable. Defaults to None.

Added in version 1.3.0.

Returns:

The number of tracks removed from the queue.

Return type:

int

remove_at(index: int)[source]¶

Remove and return a track at the given index without side effects.

Unlike pop_at(), this method does not set the removed track as the current track or push the previous current track to history.

Added in version 1.3.0.

Parameters:

index (int) – The index of the track to remove.

Returns:

The removed track.

Return type:

Playable

Raises:

QueueEmpty – The queue is empty.
IndexError – There is no item at the given index.

async remove_wait(tracks: Iterable[Playable] | Playable | Playlist, /, *, remove_all: bool = True, key: Callable[[Playable], Any] | None = None)[source]¶

Asynchronously remove one or more tracks from the queue.

This method is thread-safe.

Parameters:

tracks (Iterable[Playable] | Playable | Playlist) – The track(s) or playlist to remove from the queue.
remove_all (bool) – Whether to remove all occurrences of a track from this queue. When set to False, only the first occurrence of each track is removed. Defaults to True.
key (Callable[[Playable], Any] | None) –
If provided, tracks are matched by comparing key(track) against each value in tracks instead of using equality directly. Defaults to None.

Added in version 1.3.0.

Returns:

The number of tracks removed from the queue.

Return type:

int

reset()[source]¶

Reset the queue to its default state.

This will:

Clear all items from the queue
Clear AutoPlay-discovered tracks
Clear history
Reset the mode to QueueMode.NORMAL
Reset shuffle_mode to ShuffleMode.DEFAULT
Clear the current track
Cancel all waiting futures

reverse()[source]¶

Reverse the queue in place.

This does not return anything.

shuffle()[source]¶

Shuffle the queue in place, once.

This permanently reorders tracks; there is no way to undo it or recover the previous order afterwards. This is unrelated to, and does not change, shuffle_mode – for a toggleable shuffle that can be turned back off without losing the original order, set shuffle_mode to ShuffleMode.PERSISTENT instead.

This does not return anything.

sort(*, key: Callable[[Playable], Any], reverse: bool = False)[source]¶

Sort the queue in place.

Parameters:

key (Callable[[Playable], Any]) – A function that takes a track and returns a value to sort by, e.g. key=lambda track: track.title.
reverse (bool) – Whether to sort in descending order. Defaults to False.

swap(old: int, new: int)[source]¶

Swap two tracks in the queue by index.

Parameters:

old (int) – The index of the first track.
new (int) – The index of the second track.

Raises:

IndexError – One or both indices are out of range.

property autoplay_tracks: list[Playable]¶

The list of AutoPlay-discovered tracks currently staged in the queue.

These tracks are only played once all user-added tracks are exhausted. Modifying this list will not affect the actual queue.

Added in version 1.1.0.

Returns:: A list of AutoPlay tracks.
Return type:: list[Playable]

property count: int¶

The number of tracks in this collection.

Returns:: The total number of tracks currently held.
Return type:: int

property current_track: Playable | None¶

The currently loaded track.

This track is typically the one being played or most recently played.

This is also used when mode is set to QueueMode.LOOP to determine which track to repeat. This can be manually set too.

Returns:: The current track, or None if not set.
Return type:: sonolink.models.Playable | None

property history: History | None¶

The queue history.

Returns:: The queue history if history is enabled, otherwise None.
Return type:: History | None

property mode: QueueMode¶

The current queue mode.

QueueMode.NORMAL: Tracks are played in order and removed from the queue.
QueueMode.LOOP: current_track is repeated indefinitely until manually changed.
QueueMode.LOOP_ALL: When the queue is empty, all tracks from history are restored
to the queue and played again.

Returns:: The current queue mode.
Return type:: QueueMode

property shuffle_mode: ShuffleMode¶

The queue’s current shuffle state.

When ShuffleMode.PERSISTENT, get() pops a random track from the user lane (tracks) instead of always popping the head. This is independent of shuffle(), and never touches tracks itself — setting this back to ShuffleMode.DEFAULT does not need to restore anything, since the underlying order was never changed while persistent shuffle was on.

This is independent of mode and composes with any QueueMode. It only affects the user lane; the AutoPlay lane is unaffected.

Added in version 1.3.0.

Returns:: The queue’s current shuffle state.
Return type:: ShuffleMode

property tracks: list[Playable]¶

The list of tracks currently in the queue.

This does not include the current_track or AutoPlay-discovered tracks. Modifying this list will not affect the actual queue; use methods like put() or pop_at() for modifications.

Returns:: A list of tracks in the queue.
Return type:: list[Playable]

Network¶

Messages¶

class sonolink.network.message.MessageType(*values)[source]¶

Attributes

BINARY
CLOSE
CONTINUATION
PING
PONG
TEXT
as_integer_ratio
bit_count
bit_length
conjugate
denominator
from_bytes
imag
is_integer
numerator
real
to_bytes

classmethod from_bytes(bytes, byteorder='big', *, signed=False)¶

Return the integer represented by the given array of bytes.

bytes: Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol.
byteorder: The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use sys.byteorder as the byte order value. Default is to use ‘big’.
signed: Indicates whether two’s complement is used to represent the integer.

as_integer_ratio()¶

Return a pair of integers, whose ratio is equal to the original int.

The ratio is in lowest terms and has a positive denominator.

>>> (10).as_integer_ratio()
(10, 1)
>>> (-10).as_integer_ratio()
(-10, 1)
>>> (0).as_integer_ratio()
(0, 1)

bit_count()¶

Number of ones in the binary representation of the absolute value of self.

Also known as the population count.

>>> bin(13)
'0b1101'
>>> (13).bit_count()
3

bit_length()¶

Number of bits necessary to represent self in binary.

>>> bin(37)
'0b100101'
>>> (37).bit_length()
6

conjugate()¶: Returns self, the complex conjugate of any int.

is_integer()¶: Returns True. Exists for duck type compatibility with float.is_integer.

to_bytes(length=1, byteorder='big', *, signed=False)¶

Return an array of bytes representing an integer.

length: Length of bytes object to use. An OverflowError is raised if the integer is not representable with the given number of bytes. Default is length 1.
byteorder: The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use sys.byteorder as the byte order value. Default is to use ‘big’.
signed: Determines whether two’s complement is used to represent the integer. If signed is False and a negative integer is given, an OverflowError is raised.

BINARY = 2¶

CLOSE = 8¶

CONTINUATION = 0¶

PING = 9¶

PONG = 10¶

TEXT = 1¶

denominator¶: the denominator of a rational number in lowest terms

imag¶: the imaginary part of a complex number

numerator¶: the numerator of a rational number in lowest terms

real¶: the real part of a complex number

class sonolink.network.message.Message(data: bytes | bytearray | str, flags: MessageType)[source]¶

Attributes

data
flags

Methods

defjson
deftext

json()[source]¶

Return type:: Any

text()[source]¶

Return type:: str

data: bytes | bytearray | str | None¶

flags: MessageType¶

Utilities API¶

sonolink.utils.cached_property(attribute: str)[source]¶

Create a cached property that stores the result under class.attribute.

Return type:: Callable[[Callable[[TypeVar(T)], TypeVar(T_co, covariant=True)]], _cached_property[TypeVar(T), TypeVar(T_co, covariant=True)]]

sonolink._registry.get_client(bot: Any)[source]¶

Get the SonoLink client associated with a Discord client instance.

Added in version 1.1.0.

Parameters:: bot (Any) – The Discord client instance to retrieve the client for.
Returns:: The SonoLink client associated with the Discord client, if any. Otherwise, None.
Return type:: Client[Any] | None