Gateway API¶

The gateway layer contains the queue, enum, error, and event-related runtime types. The top-level sonolink.Client, sonolink.Node, and sonolink.Player classes are documented on Core API.

Voice state¶

class sonolink.PlayerConnectionState[source]¶

Attributes

channel_id
endpoint
is_complete
session_id
token

Represents the voice connection state for a BasePlayer.

This class is intended to be subclassed if you need to store extra metadata during the Discord handshake.

channel_id: str | None¶

endpoint: str | None¶

property is_complete: bool¶: Indicates if all gateway data has been received.

session_id: str | None¶

token: str | None¶

Websocket payloads¶

class sonolink.gateway.schemas.PlayerState(_time: int, position: int, connected: bool, ping: int)[source]¶

Attributes

connected
ping
position
time

Represents a Player state on a Player Update event.

connected: bool¶: Whether a connection is established.

ping: int¶: The ping of the connection node to the voice server in milliseconds. If this is -1, it has not been yet connected.

position: int¶: The position of the track in milliseconds.

property time: datetime¶: The timestamp of when this state is from.

class sonolink.gateway.schemas.MemoryStats(free: int, used: int, allocated: int, reservable: int)[source]¶

Attributes

allocated
free
reservable
used

Represents the stats of the memory of the machine received within a stats event.

allocated: int¶: The amount of allocated memory in bytes.

free: int¶: The amount of free memory in bytes.

reservable: int¶: The amount of reservable memory in bytes.

used: int¶: The amount of used memory in bytes.

class sonolink.gateway.schemas.CPUStats(cores: int, system_load: float, lavalink_load: float)[source]¶

Attributes

cores
lavalink_load
system_load

Represents the stats of the CPU of the machine received within a stats event.

cores: int¶: The amount of cores the node has.

lavalink_load: float¶: The load of lavalink on the node.

system_load: float¶: The system load of the node.

class sonolink.gateway.schemas.FrameStats(sent: int, nulled: int, deficit: int)[source]¶

Attributes

deficit
nulled
sent

Represents the audio frames stats of the players received within a stats event.

deficit: int¶: The difference between sent frames and the expected amount of frames. If this number is negative, too many frames were sent, and if it’s positive, not enough frames are being sent.

nulled: int¶: The amount of frames that were nulled.

sent: int¶: The amount of frames sent to Discord.

class sonolink.gateway.schemas.StatsEvent(players: int, playing_players: int, uptime: int, memory: MemoryStats, cpu: CPUStats, frame_stats: FrameStats | None = None)[source]¶

Attributes

cpu
frame_stats
memory
players
playing_players
uptime

Represents the statistics received every minute via the websocket.

cpu: CPUStats¶: The CPU stats of the node.

frame_stats: FrameStats | None¶: The frame stats of the node.

memory: MemoryStats¶: The memory stats of the node.

players: int¶: The players count attached to the node.

playing_players: int¶: The players count attached to the node that are playing a track..

uptime: int¶: The node uptime in milliseconds.

class sonolink.gateway.schemas.WebSocketClosedEvent(code: int, reason: str, by_remote: bool)[source]¶

Attributes

by_remote
code
reason

Represents the websocket closed event received when an audio WebSocket to Discord is terminated.

by_remote: bool¶: Whether the closure was made by Discord.

code: int¶: The Discord close event code.

reason: str¶: The reason why the connection was closed.

Library adapters¶

These classes are the concrete Player implementations for each supported Discord library. You will not normally instantiate them directly — Player resolves the correct adapter automatically at runtime via the SONOLINK_FRAMEWORK environment variable. They are documented here for completeness and for users who need to type-annotate their voice channel references precisely.

All three classes inherit the full public API of BasePlayer (playback, queue, filters, volume, etc.) in addition to the members listed below.

class sonolink.gateway.player._base.BasePlayer(*, node: Node | None = None, queue_mode: QueueMode = QueueMode.NORMAL, autoplay_settings: AutoPlaySettings | None = None, history_settings: HistorySettings | None = None, volume: int | None = None, paused: bool | None = None, filters: Filters | None = None)[source]¶

Attributes

autoplay
autoplay_settings
channel
client
current
filters
guild
history_settings
node
paused
position
queue
queue_mode
volume

Methods

defcleanup
asyncconnect
asyncdisconnect
defget_connection_state
asyncmove_to
asyncon_voice_server_update
asyncon_voice_state_update
asyncpause
asyncplay
asyncprevious
asyncresume
asyncseek
asyncset_filters
asyncset_volume
asyncskip
asyncstop
asyncupdate

Abstract base class that defines the interface for a Lavalink player.

This class is library-agnostic and is intended to be subclassed to provide concrete implementations compatible with discord.py, py-cord`, disnake, or nextcord. Each library-specific subclass is responsible for implementing the voice protocol integration (e.g., inheriting from the appropriate VoiceProtocol class) and fulfilling the abstract methods defined here.

The public API exposed by this class remains consistent across all three Discord library backends, allowing shared business logic, extensions, and third-party integrations to target BasePlayer without coupling to any specific library.

Parameters:

node (Node | None) – The Lavalink node to associate this player with. If None, the player will attempt to resolve an available node at connection time.
queue_mode (QueueMode) – The initial queue looping mode. Defaults to QueueMode.NORMAL.
autoplay_settings (AutoPlaySettings | None) – Configuration for the AutoPlay feature. If None, a default configuration is used. History must be enabled if AutoPlay is used.
history_settings (HistorySettings | None) – Configuration for queue history. If None, a default configuration is used.
volume (int | None) – The initial volume of the player (0–1000). Defaults to 100.
paused (bool | None) – Whether the player should start in a paused state. Defaults to False.
filters (Filters | None) – The initial set of audio filters to apply. If None, an empty Filters instance is used.

guild¶: The guild this player is attached to. The concrete type depends on the underlying Discord library (e.g. discord.Guild (discord.py), discord.Guild (py-cord), disnake.Guild (disnake), or nextcord.Guild (nextcord)).

channel¶

The voice channel this player is currently connected to. The concrete type depends on the underlying Discord library.

Type:: Any

client¶

The Discord client instance driving this player. The concrete type depends on the underlying Discord library.

Type:: Any

abstractmethod cleanup() → None[source]¶

Cleans the internal state of the Player. This is automatically called by the library when failures or disconnects occur.

If this is overridden, it must call the original cleanup.

async connect(*, timeout: float = 10.0, reconnect: bool = False, self_deaf: bool = False, self_mute: bool = False) → None[source]¶

Connect this player to its assigned voice channel.

Called automatically by libraries after the player is instantiated. Manual invocation is not normally required.

Parameters:

timeout (float) – Seconds to wait for the Discord gateway handshake before raising. Defaults to 10.0.
reconnect (bool) – Whether to attempt reconnection on failure. Defaults to False.
self_deaf (bool) – Whether to join the channel self-deafened. Defaults to False.
self_mute (bool) – Whether to join the channel self-muted. Defaults to False.

async disconnect(*, force: bool = False) → None[source]¶

Disconnect this player, destroy it on the Lavalink node, and clean up all internal state.

Parameters:: force (bool) – If True, proceeds even if the player is not currently connected. Defaults to False.

get_connection_state() → PlayerConnectionState[source]¶

Return a PlayerConnectionState instance for this player.

Override this method to supply a custom connection state subclass with additional metadata relevant to your application.

Return type:: PlayerConnectionState

async move_to(node: Node, /) → None[source]¶

Migrate this player to a different Lavalink node without interrupting playback.

Parameters:: node (Node) – The destination node.

abstractmethod async on_voice_server_update(data: Any) → None[source]¶

Handle a VOICE_SERVER_UPDATE payload from the Discord gateway.

This provides the voice server token and endpoint required by the Lavalink node to establish or re-establish the audio stream. This method should be called by the library-specific subclass in response to the corresponding gateway event.

The data dictionary is passed as a raw mapping so that this base class remains decoupled from any specific library’s type aliases. Subclasses may cast it to the appropriate typed dict for their library (e.g., discord.types.voice.VoiceServerUpdate, disnake.types.voice.VoiceServerUpdate).

Parameters:: data (Any) – The raw VOICE_SERVER_UPDATE payload received from the Discord gateway.

abstractmethod async on_voice_state_update(data: Any) → None[source]¶

Handle a VOICE_STATE_UPDATE payload from the Discord gateway.

This provides the session ID and channel ID required for the voice connection handshake with the Lavalink node. This method should be called by the library-specific subclass in response to the corresponding gateway event.

The data dictionary is passed as a raw mapping so that this base class remains decoupled from any specific library’s type aliases. Subclasses may cast it to the appropriate typed dict for their library (e.g., discord.types.voice.GuildVoiceState, disnake.types.voice.GuildVoiceState).

Parameters:: data (Any) – The raw VOICE_STATE_UPDATE payload received from the Discord gateway.

async pause() → None[source]¶

Set the pause state of the player.

Raises:: RuntimeError – If the player is not connected to a node or an active session.

async play(track: Playable, /, *, start: int = 0, end: int | None = None, volume: int | None = None, paused: bool | None = None) → Playable[source]¶

Begin playback of the specified track.

If a track is already playing, it is stopped and the currently playing track is added to history (if history is enabled) before the new track starts.

Parameters:

track (Playable) – The track to play.
start (int) – The position in milliseconds at which to begin playback. Defaults to 0.
end (int | None) – The position in milliseconds at which to stop playback. If None, the track plays to completion. Defaults to None.
volume (int | None) – Override the player volume for this track only. If None, the current player volume is used. Defaults to None.
paused (bool | None) – If True, the track begins in a paused state. If None, the player’s current pause state is preserved. Defaults to None.

Returns:

The track that was dispatched to the Lavalink node for playback.

Return type:

Playable

async previous() → Playable[source]¶

Return to the most recently played track in the history.

The current track is pushed back to the front of the queue so it can be reached again via skip(). The historical track then begins playing immediately.

Returns:

The historical track that is now playing.

Return type:

Playable

Raises:

RuntimeError – If the player is not connected to a node or an active session.
HistoryEmpty – If there is no previous track in the history.

async resume() → None[source]¶

Resume playback if the player is currently paused.

Raises:: RuntimeError – If the player is not connected to a node or an active session.

async seek(position: int, /) → None[source]¶

Seek to an arbitrary position within the current track.

Parameters:: position (int) – The target position in milliseconds. Must be within the bounds of the current track’s duration.
Raises:: RuntimeError – If the player is not connected to a node or an active session.

async set_filters(filters: Filters, /, *, seek: bool = False) → None[source]¶

Apply a new set of audio filters to this player.

Parameters:

filters (Filters) – The Filters instance to apply.
seek (bool) – If True, the player seeks to the current position immediately after applying filters. This forces Lavalink to process the audio through the new filter chain without a audible delay. Defaults to False.

Raises:

RuntimeError – If the player is not connected to a node or an active session.

async set_volume(value: int, /) → None[source]¶

Set the player’s output volume.

Parameters:

value (int) – The desired volume level, in the range 0–1000. 100 is the default (unmodified) level.

Raises:

ValueError – If value is outside the range 0–1000.
RuntimeError – If the player is not connected to a node or an active session.

async skip() → Playable | None[source]¶

Skip the currently playing track and advance to the next one in the queue.

If the queue is empty and AutoPlay is enabled, a related track may be fetched automatically. If neither a queued nor an AutoPlay track is available, playback stops and None is returned.

Returns:

The track that began playing after the skip, or None if the player stopped due to an empty queue with no AutoPlay fallback.

Return type:

Playable | None

Raises:

RuntimeError – If the player is not connected to a node or an active session.
QueueEmpty – If the queue is empty and AutoPlay is disabled or yields no results.

async stop(*, clear_queue: bool = False, clear_history: bool = False) → None[source]¶

Stop the currently playing track.

This sends a stop request to the Lavalink node and resets the player’s internal position tracking and current track reference.

Parameters:

clear_queue (bool) – If True, all pending tracks in the queue are removed. Defaults to False.
clear_history (bool) – If True, the playback history is cleared. Defaults to False.

Raises:

RuntimeError – If the player is not connected to a node or an active session.

Update the player’s configuration in-place.

Added in version 1.1.0.

Parameters:

queue_mode (QueueMode | None) – The new queue looping mode. If None, the current mode is preserved.
autoplay_settings (AutoPlaySettings | None) – New AutoPlay configuration. If None, the current settings are preserved.
history_settings (HistorySettings | None) – New history configuration. If None, the current settings are preserved.
volume (int | None) – New volume in the range 0–1000. If None, the current volume is preserved.
filters (Filters | None) – New audio filters. If None, the current filters are preserved.

property autoplay: AutoPlayMode¶

The current AutoPlayMode for this player.

When AutoPlay is enabled, the player will automatically fetch and enqueue related tracks when the queue is exhausted.

Raises:: RuntimeError – When setting, if the player’s history is disabled (history is required for AutoPlay to function).

property autoplay_settings: AutoPlaySettings¶

The current AutoPlaySettings for this player.

Can be mutated directly to update individual fields, or replaced entirely.

Added in version 1.1.0.

Return type:: AutoPlaySettings

channel: Any¶

client: Any¶

property current: Playable | None¶

The track that is currently playing, or None if the player is idle.

Return type:: Playable | None

property filters: Filters¶

The Filters currently applied to this player.

To apply new filters, use set_filters() rather than mutating this object directly, so that the updated state is dispatched to the Lavalink node.

Return type:: Filters

property guild: Any¶

The guild this player is associated with.

The concrete return type is the guild class of the underlying Discord library (e.g. discord.Guild, disnake.Guild).

Raises:: RuntimeError – If the player has not yet been attached to a guild.

property history_settings: HistorySettings¶

The current HistorySettings for this player’s queue.

Can be mutated directly to update individual fields, or replaced entirely.

Added in version 1.1.0.

Return type:: HistorySettings

property node: Node¶

The Node this player is currently attached to.

Raises:: RuntimeError – If the player is not currently attached to a node.

property paused: bool¶

Whether the player is currently paused.

Return type:: bool

property position: int¶

The estimated current playback position in milliseconds.

When the player is paused or has not yet started, this returns the last known position. Otherwise, it is calculated by interpolating the time elapsed since the last state update received from the Lavalink node.

Returns:: Position in milliseconds.
Return type:: int

property queue: Queue¶

The Queue associated with this player.

The queue manages both upcoming tracks and playback history. Tracks can be added with queue.put() / queue.put_wait() and inspected or manipulated via the queue’s public API.

Return type:: Queue

property queue_mode: QueueMode¶

The current QueueMode for this player’s queue.

Added in version 1.1.0.

Return type:: QueueMode

property volume: int¶

The current volume of the player as an integer in the range 0–1000.

100 represents the default (unmodified) volume. Values above 100 amplify the audio and may introduce distortion.

Return type:: int

class sonolink.gateway.player.adapters._dpy.DpyPlayer(*args: Any, **kwargs: Any)[source]¶

Bases: BasePlayer, VoiceProtocol

A discord.py implementation of BasePlayer.

This class satisfies the discord.VoiceProtocol contract expected by discord.py’s voice connection machinery, whilst delegating all Lavalink playback logic to the handlers initialised by BasePlayer.

There are two primary ways to create a player:

Class-pass — pass the class itself to discord.abc.Connectable.connect(). discord.py will instantiate it by calling Player(client, channel):
```
player = await voice_channel.connect(cls=Player)
```
Instance-pass — construct a pre-configured instance and pass it instead. discord.py will call player(client, channel) which hits __call__():
```
player = Player(node=some_node, volume=80)
await voice_channel.connect(cls=player)
```

Parameters:

node (Node | None) – The Lavalink node to associate with this player. If None, an available node is resolved from the client’s node pool at connection time.
queue_mode (QueueMode) – The initial queue looping mode. Defaults to QueueMode.NORMAL.
autoplay_settings (AutoPlaySettings | None) – AutoPlay configuration. None uses the default configuration. History must be enabled when AutoPlay is active.
history_settings (HistorySettings | None) – History configuration. None uses the default configuration.
volume (int | None) – Initial volume in the range 0–1000. Defaults to 100.
paused (bool | None) – Whether the player should start in a paused state. Defaults to False.
filters (Filters | None) – Initial audio filters. Defaults to an empty Filters instance.

guild¶

The guild this player is attached to.

Type:: discord.Guild

channel¶

The voice channel this player is currently connected to.

Type:: discord.VoiceChannel | discord.StageChannel

client¶

The discord.py client driving this player.

Type:: discord.Client

cleanup() → None[source]¶

Cleans the internal state of the Player. This is automatically called by the library when failures or disconnects occur.

If this is overridden, it must call the original cleanup.

async connect(*, timeout: float = 10.0, reconnect: bool = False, self_deaf: bool = False, self_mute: bool = False) → None¶

Connect this player to its assigned voice channel.

Called automatically by libraries after the player is instantiated. Manual invocation is not normally required.

Parameters:

timeout (float) – Seconds to wait for the Discord gateway handshake before raising. Defaults to 10.0.
reconnect (bool) – Whether to attempt reconnection on failure. Defaults to False.
self_deaf (bool) – Whether to join the channel self-deafened. Defaults to False.
self_mute (bool) – Whether to join the channel self-muted. Defaults to False.

async disconnect(*, force: bool = False) → None¶

Disconnect this player, destroy it on the Lavalink node, and clean up all internal state.

Parameters:: force (bool) – If True, proceeds even if the player is not currently connected. Defaults to False.

get_connection_state() → PlayerConnectionState¶

Return a PlayerConnectionState instance for this player.

Override this method to supply a custom connection state subclass with additional metadata relevant to your application.

Return type:: PlayerConnectionState

async move_to(node: Node, /) → None¶

Migrate this player to a different Lavalink node without interrupting playback.

Parameters:: node (Node) – The destination node.

async on_voice_server_update(data: VoiceServerUpdate) → None[source]¶

Handle a VOICE_SERVER_UPDATE payload from the Discord gateway.

Provides the voice server token and endpoint to the Lavalink node so it can establish or re-establish the audio stream.

Parameters:: data (discord.types.voice.VoiceServerUpdate) – The raw payload received from the Discord gateway.

async on_voice_state_update(data: GuildVoiceState) → None[source]¶

Handle a VOICE_STATE_UPDATE payload from the Discord gateway.

Provides the session ID and channel ID required for the voice connection handshake with the Lavalink node.

Parameters:: data (discord.types.voice.GuildVoiceState) – The raw payload received from the Discord gateway.

async pause() → None¶

Set the pause state of the player.

Raises:: RuntimeError – If the player is not connected to a node or an active session.

async play(track: Playable, /, *, start: int = 0, end: int | None = None, volume: int | None = None, paused: bool | None = None) → Playable¶

Begin playback of the specified track.

If a track is already playing, it is stopped and the currently playing track is added to history (if history is enabled) before the new track starts.

Parameters:

track (Playable) – The track to play.
start (int) – The position in milliseconds at which to begin playback. Defaults to 0.
end (int | None) – The position in milliseconds at which to stop playback. If None, the track plays to completion. Defaults to None.
volume (int | None) – Override the player volume for this track only. If None, the current player volume is used. Defaults to None.
paused (bool | None) – If True, the track begins in a paused state. If None, the player’s current pause state is preserved. Defaults to None.

Returns:

The track that was dispatched to the Lavalink node for playback.

Return type:

Playable

async previous() → Playable¶

Return to the most recently played track in the history.

The current track is pushed back to the front of the queue so it can be reached again via skip(). The historical track then begins playing immediately.

Returns:

The historical track that is now playing.

Return type:

Playable

Raises:

RuntimeError – If the player is not connected to a node or an active session.
HistoryEmpty – If there is no previous track in the history.

async resume() → None¶

Resume playback if the player is currently paused.

Raises:: RuntimeError – If the player is not connected to a node or an active session.

async seek(position: int, /) → None¶

Seek to an arbitrary position within the current track.

Parameters:: position (int) – The target position in milliseconds. Must be within the bounds of the current track’s duration.
Raises:: RuntimeError – If the player is not connected to a node or an active session.

async set_filters(filters: Filters, /, *, seek: bool = False) → None¶

Apply a new set of audio filters to this player.

Parameters:

filters (Filters) – The Filters instance to apply.
seek (bool) – If True, the player seeks to the current position immediately after applying filters. This forces Lavalink to process the audio through the new filter chain without a audible delay. Defaults to False.

Raises:

RuntimeError – If the player is not connected to a node or an active session.

async set_volume(value: int, /) → None¶

Set the player’s output volume.

Parameters:

value (int) – The desired volume level, in the range 0–1000. 100 is the default (unmodified) level.

Raises:

ValueError – If value is outside the range 0–1000.
RuntimeError – If the player is not connected to a node or an active session.

async skip() → Playable | None¶

Skip the currently playing track and advance to the next one in the queue.

If the queue is empty and AutoPlay is enabled, a related track may be fetched automatically. If neither a queued nor an AutoPlay track is available, playback stops and None is returned.

Returns:

The track that began playing after the skip, or None if the player stopped due to an empty queue with no AutoPlay fallback.

Return type:

Playable | None

Raises:

RuntimeError – If the player is not connected to a node or an active session.
QueueEmpty – If the queue is empty and AutoPlay is disabled or yields no results.

async stop(*, clear_queue: bool = False, clear_history: bool = False) → None¶

Stop the currently playing track.

This sends a stop request to the Lavalink node and resets the player’s internal position tracking and current track reference.

Parameters:

clear_queue (bool) – If True, all pending tracks in the queue are removed. Defaults to False.
clear_history (bool) – If True, the playback history is cleared. Defaults to False.

Raises:

RuntimeError – If the player is not connected to a node or an active session.

Update the player’s configuration in-place.

Added in version 1.1.0.

Parameters:

queue_mode (QueueMode | None) – The new queue looping mode. If None, the current mode is preserved.
autoplay_settings (AutoPlaySettings | None) – New AutoPlay configuration. If None, the current settings are preserved.
history_settings (HistorySettings | None) – New history configuration. If None, the current settings are preserved.
volume (int | None) – New volume in the range 0–1000. If None, the current volume is preserved.
filters (Filters | None) – New audio filters. If None, the current filters are preserved.

property autoplay: AutoPlayMode¶

The current AutoPlayMode for this player.

When AutoPlay is enabled, the player will automatically fetch and enqueue related tracks when the queue is exhausted.

Raises:: RuntimeError – When setting, if the player’s history is disabled (history is required for AutoPlay to function).

property autoplay_settings: AutoPlaySettings¶

The current AutoPlaySettings for this player.

Can be mutated directly to update individual fields, or replaced entirely.

Added in version 1.1.0.

Return type:: AutoPlaySettings

channel: discord.abc.Connectable¶

client: discord.Client¶

property current: Playable | None¶

The track that is currently playing, or None if the player is idle.

Return type:: Playable | None

property filters: Filters¶

The Filters currently applied to this player.

To apply new filters, use set_filters() rather than mutating this object directly, so that the updated state is dispatched to the Lavalink node.

Return type:: Filters

property guild: Any¶

The guild this player is associated with.

The concrete return type is the guild class of the underlying Discord library (e.g. discord.Guild, disnake.Guild).

Raises:: RuntimeError – If the player has not yet been attached to a guild.

property history_settings: HistorySettings¶

The current HistorySettings for this player’s queue.

Can be mutated directly to update individual fields, or replaced entirely.

Added in version 1.1.0.

Return type:: HistorySettings

property node: Node¶

The Node this player is currently attached to.

Raises:: RuntimeError – If the player is not currently attached to a node.

property paused: bool¶

Whether the player is currently paused.

Return type:: bool

property position: int¶

The estimated current playback position in milliseconds.

Returns:: Position in milliseconds.
Return type:: int

property queue: Queue¶

The Queue associated with this player.

The queue manages both upcoming tracks and playback history. Tracks can be added with queue.put() / queue.put_wait() and inspected or manipulated via the queue’s public API.

Return type:: Queue

property queue_mode: QueueMode¶

The current QueueMode for this player’s queue.

Added in version 1.1.0.

Return type:: QueueMode

property volume: int¶

The current volume of the player as an integer in the range 0–1000.

100 represents the default (unmodified) volume. Values above 100 amplify the audio and may introduce distortion.

Return type:: int

class sonolink.gateway.player.adapters._pycord.PycordPlayer(*args: Any, **kwargs: Any)[source]¶

Bases: BasePlayer, Client

A py-cord implementation of BasePlayer.

This class satisfies the discord.voice.VoiceProtocol contract expected by py-cord’s voice connection machinery, whilst delegating all Lavalink playback logic to the handlers initialised by BasePlayer.

There are two primary ways to create a player:

Class-pass - pass the class itself to discord.abc.Connectable.connect(). py-cord will instantiate it by calling Player(client, channel):
```
player = await voice_channel.connect(cls=Player)
```
Instance-pass - construct a pre-configured instance and pass it instead. py-cord will call player(client, channel) which hits __call__():
```
player = Player(node=some_node, volume=80)
await voice_channel.connect(cls=player)
```

Parameters:

node (Node | None) – The Lavalink node to associate with this player. If None, an available node is resolved from the client’s node pool at connection time.
queue_mode (QueueMode) – The initial queue looping mode. Defaults to QueueMode.NORMAL.
autoplay_settings (AutoPlaySettings | None) – AutoPlay configuration. None uses the default configuration. History must be enabled when AutoPlay is active.
history_settings (HistorySettings | None) – History configuration. None uses the default configuration.
volume (int | None) – Initial volume in the range 0–1000. Defaults to 100.
paused (bool | None) – Whether the player should start in a paused state. Defaults to False.
filters (Filters | None) – Initial audio filters. Defaults to an empty Filters instance.

guild¶

The guild this player is attached to.

Type:: discord.Guild

channel¶

The voice channel this player is currently connected to.

Type:: discord.VoiceChannel | discord.StageChannel

client¶

The py-cord client driving this player.

Type:: discord.Client

cleanup() → None[source]¶

Cleans the internal state of the Player. This is automatically called by the library when failures or disconnects occur.

If this is overridden, it must call the original cleanup.

async connect(*, timeout: float = 10.0, reconnect: bool = False, self_deaf: bool = False, self_mute: bool = False) → None¶

Connect this player to its assigned voice channel.

Called automatically by libraries after the player is instantiated. Manual invocation is not normally required.

Parameters:

timeout (float) – Seconds to wait for the Discord gateway handshake before raising. Defaults to 10.0.
reconnect (bool) – Whether to attempt reconnection on failure. Defaults to False.
self_deaf (bool) – Whether to join the channel self-deafened. Defaults to False.
self_mute (bool) – Whether to join the channel self-muted. Defaults to False.

async disconnect(*, force: bool = False) → None¶

Disconnect this player, destroy it on the Lavalink node, and clean up all internal state.

Parameters:: force (bool) – If True, proceeds even if the player is not currently connected. Defaults to False.

get_connection_state() → PlayerConnectionState¶

Return a PlayerConnectionState instance for this player.

Override this method to supply a custom connection state subclass with additional metadata relevant to your application.

Return type:: PlayerConnectionState

async move_to(node: Node, /) → None¶

Migrate this player to a different Lavalink node without interrupting playback.

Parameters:: node (Node) – The destination node.

async on_voice_server_update(data: VoiceServerUpdate) → None[source]¶

Handle a VOICE_SERVER_UPDATE payload from the Discord gateway.

Parameters:: data (Any) – The raw VOICE_SERVER_UPDATE payload received from the Discord gateway.

async on_voice_state_update(data: VoiceStateUpdate) → None[source]¶

Handle a VOICE_STATE_UPDATE payload from the Discord gateway.

The data dictionary is passed as a raw mapping so that this base class remains decoupled from any specific library’s type aliases. Subclasses may cast it to the appropriate typed dict for their library (e.g., discord.types.voice.GuildVoiceState, disnake.types.voice.GuildVoiceState).

Parameters:: data (Any) – The raw VOICE_STATE_UPDATE payload received from the Discord gateway.

async pause() → None¶

Set the pause state of the player.

Raises:: RuntimeError – If the player is not connected to a node or an active session.

async play(track: Playable, /, *, start: int = 0, end: int | None = None, volume: int | None = None, paused: bool | None = None) → Playable¶

Begin playback of the specified track.

If a track is already playing, it is stopped and the currently playing track is added to history (if history is enabled) before the new track starts.

Parameters:

track (Playable) – The track to play.
start (int) – The position in milliseconds at which to begin playback. Defaults to 0.
end (int | None) – The position in milliseconds at which to stop playback. If None, the track plays to completion. Defaults to None.
volume (int | None) – Override the player volume for this track only. If None, the current player volume is used. Defaults to None.
paused (bool | None) – If True, the track begins in a paused state. If None, the player’s current pause state is preserved. Defaults to None.

Returns:

The track that was dispatched to the Lavalink node for playback.

Return type:

Playable

async previous() → Playable¶

Return to the most recently played track in the history.

The current track is pushed back to the front of the queue so it can be reached again via skip(). The historical track then begins playing immediately.

Returns:

The historical track that is now playing.

Return type:

Playable

Raises:

RuntimeError – If the player is not connected to a node or an active session.
HistoryEmpty – If there is no previous track in the history.

async resume() → None¶

Resume playback if the player is currently paused.

Raises:: RuntimeError – If the player is not connected to a node or an active session.

async seek(position: int, /) → None¶

Seek to an arbitrary position within the current track.

Parameters:: position (int) – The target position in milliseconds. Must be within the bounds of the current track’s duration.
Raises:: RuntimeError – If the player is not connected to a node or an active session.

async set_filters(filters: Filters, /, *, seek: bool = False) → None¶

Apply a new set of audio filters to this player.

Parameters:

filters (Filters) – The Filters instance to apply.
seek (bool) – If True, the player seeks to the current position immediately after applying filters. This forces Lavalink to process the audio through the new filter chain without a audible delay. Defaults to False.

Raises:

RuntimeError – If the player is not connected to a node or an active session.

async set_volume(value: int, /) → None¶

Set the player’s output volume.

Parameters:

value (int) – The desired volume level, in the range 0–1000. 100 is the default (unmodified) level.

Raises:

ValueError – If value is outside the range 0–1000.
RuntimeError – If the player is not connected to a node or an active session.

async skip() → Playable | None¶

Skip the currently playing track and advance to the next one in the queue.

If the queue is empty and AutoPlay is enabled, a related track may be fetched automatically. If neither a queued nor an AutoPlay track is available, playback stops and None is returned.

Returns:

The track that began playing after the skip, or None if the player stopped due to an empty queue with no AutoPlay fallback.

Return type:

Playable | None

Raises:

RuntimeError – If the player is not connected to a node or an active session.
QueueEmpty – If the queue is empty and AutoPlay is disabled or yields no results.

async stop(*, clear_queue: bool = False, clear_history: bool = False) → None¶

Stop the currently playing track.

This sends a stop request to the Lavalink node and resets the player’s internal position tracking and current track reference.

Parameters:

clear_queue (bool) – If True, all pending tracks in the queue are removed. Defaults to False.
clear_history (bool) – If True, the playback history is cleared. Defaults to False.

Raises:

RuntimeError – If the player is not connected to a node or an active session.

Update the player’s configuration in-place.

Added in version 1.1.0.

Parameters:

queue_mode (QueueMode | None) – The new queue looping mode. If None, the current mode is preserved.
autoplay_settings (AutoPlaySettings | None) – New AutoPlay configuration. If None, the current settings are preserved.
history_settings (HistorySettings | None) – New history configuration. If None, the current settings are preserved.
volume (int | None) – New volume in the range 0–1000. If None, the current volume is preserved.
filters (Filters | None) – New audio filters. If None, the current filters are preserved.

property autoplay: AutoPlayMode¶

The current AutoPlayMode for this player.

When AutoPlay is enabled, the player will automatically fetch and enqueue related tracks when the queue is exhausted.

Raises:: RuntimeError – When setting, if the player’s history is disabled (history is required for AutoPlay to function).

property autoplay_settings: AutoPlaySettings¶

The current AutoPlaySettings for this player.

Can be mutated directly to update individual fields, or replaced entirely.

Added in version 1.1.0.

Return type:: AutoPlaySettings

channel: discord.abc.Connectable¶

client: discord.Client¶

property current: Playable | None¶

The track that is currently playing, or None if the player is idle.

Return type:: Playable | None

property filters: Filters¶

The Filters currently applied to this player.

To apply new filters, use set_filters() rather than mutating this object directly, so that the updated state is dispatched to the Lavalink node.

Return type:: Filters

property guild: Any¶

The guild this player is associated with.

The concrete return type is the guild class of the underlying Discord library (e.g. discord.Guild, disnake.Guild).

Raises:: RuntimeError – If the player has not yet been attached to a guild.

property history_settings: HistorySettings¶

The current HistorySettings for this player’s queue.

Can be mutated directly to update individual fields, or replaced entirely.

Added in version 1.1.0.

Return type:: HistorySettings

property node: Node¶

The Node this player is currently attached to.

Raises:: RuntimeError – If the player is not currently attached to a node.

property paused: bool¶

Whether the player is currently paused.

Return type:: bool

property position: int¶

The estimated current playback position in milliseconds.

Returns:: Position in milliseconds.
Return type:: int

property queue: Queue¶

The Queue associated with this player.

The queue manages both upcoming tracks and playback history. Tracks can be added with queue.put() / queue.put_wait() and inspected or manipulated via the queue’s public API.

Return type:: Queue

property queue_mode: QueueMode¶

The current QueueMode for this player’s queue.

Added in version 1.1.0.

Return type:: QueueMode

property volume: int¶

The current volume of the player as an integer in the range 0–1000.

100 represents the default (unmodified) volume. Values above 100 amplify the audio and may introduce distortion.

Return type:: int

class sonolink.gateway.player.adapters._disnake.DisnakePlayer(*args: Any, **kwargs: Any)[source]¶

Bases: BasePlayer, VoiceProtocol

A disnake implementation of BasePlayer.

This class satisfies the disnake.VoiceProtocol contract expected by disnake’s voice connection machinery, whilst delegating all Lavalink playback logic to the handlers initialised by BasePlayer.

There are two primary ways to create a player:

Class-pass — pass the class itself to disnake.abc.Connectable.connect(). disnake will instantiate it by calling Player(client, channel):
```
player = await voice_channel.connect(cls=Player)
```
Instance-pass — construct a pre-configured instance and pass it instead. disnake will call player(client, channel) which hits __call__():
```
player = Player(node=some_node, volume=80)
await voice_channel.connect(cls=player)
```

Parameters:

node (Node | None) – The Lavalink node to associate with this player. If None, an available node is resolved from the client’s node pool at connection time.
queue_mode (QueueMode) – The initial queue looping mode. Defaults to QueueMode.NORMAL.
autoplay_settings (AutoPlaySettings | None) – AutoPlay configuration. None uses the default configuration. History must be enabled when AutoPlay is active.
history_settings (HistorySettings | None) – History configuration. None uses the default configuration.
volume (int | None) – Initial volume in the range 0–1000. Defaults to 100.
paused (bool | None) – Whether the player should start in a paused state. Defaults to False.
filters (Filters | None) – Initial audio filters. Defaults to an empty Filters instance.

guild¶

The guild this player is attached to.

Type:: disnake.Guild

channel¶

The voice channel this player is currently connected to.

Type:: disnake.VoiceChannel | disnake.StageChannel

client¶

The disnake client driving this player.

Type:: disnake.Client

cleanup() → None[source]¶

Cleans the internal state of the Player. This is automatically called by the library when failures or disconnects occur.

If this is overridden, it must call the original cleanup.

async connect(*, timeout: float = 10.0, reconnect: bool = False, self_deaf: bool = False, self_mute: bool = False) → None¶

Connect this player to its assigned voice channel.

Called automatically by libraries after the player is instantiated. Manual invocation is not normally required.

Parameters:

timeout (float) – Seconds to wait for the Discord gateway handshake before raising. Defaults to 10.0.
reconnect (bool) – Whether to attempt reconnection on failure. Defaults to False.
self_deaf (bool) – Whether to join the channel self-deafened. Defaults to False.
self_mute (bool) – Whether to join the channel self-muted. Defaults to False.

async disconnect(*, force: bool = False) → None¶

Disconnect this player, destroy it on the Lavalink node, and clean up all internal state.

Parameters:: force (bool) – If True, proceeds even if the player is not currently connected. Defaults to False.

get_connection_state() → PlayerConnectionState¶

Return a PlayerConnectionState instance for this player.

Override this method to supply a custom connection state subclass with additional metadata relevant to your application.

Return type:: PlayerConnectionState

async move_to(node: Node, /) → None¶

Migrate this player to a different Lavalink node without interrupting playback.

Parameters:: node (Node) – The destination node.

async on_voice_server_update(data: VoiceServerUpdateEvent) → None[source]¶

Handle a VOICE_SERVER_UPDATE payload from the Discord gateway.

Provides the voice server token and endpoint to the Lavalink node so it can establish or re-establish the audio stream.

Parameters:: data (disnake.types.voice.VoiceServerUpdate) – The raw payload received from the Discord gateway.

async on_voice_state_update(data: GuildVoiceState) → None[source]¶

Handle a VOICE_STATE_UPDATE payload from the Discord gateway.

Provides the session ID and channel ID required for the voice connection handshake with the Lavalink node.

Parameters:: data (disnake.types.voice.GuildVoiceState) – The raw payload received from the Discord gateway.

async pause() → None¶

Set the pause state of the player.

Raises:: RuntimeError – If the player is not connected to a node or an active session.

async play(track: Playable, /, *, start: int = 0, end: int | None = None, volume: int | None = None, paused: bool | None = None) → Playable¶

Begin playback of the specified track.

If a track is already playing, it is stopped and the currently playing track is added to history (if history is enabled) before the new track starts.

Parameters:

track (Playable) – The track to play.
start (int) – The position in milliseconds at which to begin playback. Defaults to 0.
end (int | None) – The position in milliseconds at which to stop playback. If None, the track plays to completion. Defaults to None.
volume (int | None) – Override the player volume for this track only. If None, the current player volume is used. Defaults to None.
paused (bool | None) – If True, the track begins in a paused state. If None, the player’s current pause state is preserved. Defaults to None.

Returns:

The track that was dispatched to the Lavalink node for playback.

Return type:

Playable

async previous() → Playable¶

Return to the most recently played track in the history.

The current track is pushed back to the front of the queue so it can be reached again via skip(). The historical track then begins playing immediately.

Returns:

The historical track that is now playing.

Return type:

Playable

Raises:

RuntimeError – If the player is not connected to a node or an active session.
HistoryEmpty – If there is no previous track in the history.

async resume() → None¶

Resume playback if the player is currently paused.

Raises:: RuntimeError – If the player is not connected to a node or an active session.

async seek(position: int, /) → None¶

Seek to an arbitrary position within the current track.

Parameters:: position (int) – The target position in milliseconds. Must be within the bounds of the current track’s duration.
Raises:: RuntimeError – If the player is not connected to a node or an active session.

async set_filters(filters: Filters, /, *, seek: bool = False) → None¶

Apply a new set of audio filters to this player.

Parameters:

filters (Filters) – The Filters instance to apply.
seek (bool) – If True, the player seeks to the current position immediately after applying filters. This forces Lavalink to process the audio through the new filter chain without a audible delay. Defaults to False.

Raises:

RuntimeError – If the player is not connected to a node or an active session.

async set_volume(value: int, /) → None¶

Set the player’s output volume.

Parameters:

value (int) – The desired volume level, in the range 0–1000. 100 is the default (unmodified) level.

Raises:

ValueError – If value is outside the range 0–1000.
RuntimeError – If the player is not connected to a node or an active session.

async skip() → Playable | None¶

Skip the currently playing track and advance to the next one in the queue.

If the queue is empty and AutoPlay is enabled, a related track may be fetched automatically. If neither a queued nor an AutoPlay track is available, playback stops and None is returned.

Returns:

The track that began playing after the skip, or None if the player stopped due to an empty queue with no AutoPlay fallback.

Return type:

Playable | None

Raises:

RuntimeError – If the player is not connected to a node or an active session.
QueueEmpty – If the queue is empty and AutoPlay is disabled or yields no results.

async stop(*, clear_queue: bool = False, clear_history: bool = False) → None¶

Stop the currently playing track.

This sends a stop request to the Lavalink node and resets the player’s internal position tracking and current track reference.

Parameters:

clear_queue (bool) – If True, all pending tracks in the queue are removed. Defaults to False.
clear_history (bool) – If True, the playback history is cleared. Defaults to False.

Raises:

RuntimeError – If the player is not connected to a node or an active session.

Update the player’s configuration in-place.

Added in version 1.1.0.

Parameters:

queue_mode (QueueMode | None) – The new queue looping mode. If None, the current mode is preserved.
autoplay_settings (AutoPlaySettings | None) – New AutoPlay configuration. If None, the current settings are preserved.
history_settings (HistorySettings | None) – New history configuration. If None, the current settings are preserved.
volume (int | None) – New volume in the range 0–1000. If None, the current volume is preserved.
filters (Filters | None) – New audio filters. If None, the current filters are preserved.

property autoplay: AutoPlayMode¶

The current AutoPlayMode for this player.

When AutoPlay is enabled, the player will automatically fetch and enqueue related tracks when the queue is exhausted.

Raises:: RuntimeError – When setting, if the player’s history is disabled (history is required for AutoPlay to function).

property autoplay_settings: AutoPlaySettings¶

The current AutoPlaySettings for this player.

Can be mutated directly to update individual fields, or replaced entirely.

Added in version 1.1.0.

Return type:: AutoPlaySettings

channel: disnake.abc.Connectable¶

client: disnake.Client¶

property current: Playable | None¶

The track that is currently playing, or None if the player is idle.

Return type:: Playable | None

property filters: Filters¶

The Filters currently applied to this player.

To apply new filters, use set_filters() rather than mutating this object directly, so that the updated state is dispatched to the Lavalink node.

Return type:: Filters

property guild: Any¶

The guild this player is associated with.

The concrete return type is the guild class of the underlying Discord library (e.g. discord.Guild, disnake.Guild).

Raises:: RuntimeError – If the player has not yet been attached to a guild.

property history_settings: HistorySettings¶

The current HistorySettings for this player’s queue.

Can be mutated directly to update individual fields, or replaced entirely.

Added in version 1.1.0.

Return type:: HistorySettings

property node: Node¶

The Node this player is currently attached to.

Raises:: RuntimeError – If the player is not currently attached to a node.

property paused: bool¶

Whether the player is currently paused.

Return type:: bool

property position: int¶

The estimated current playback position in milliseconds.

Returns:: Position in milliseconds.
Return type:: int

property queue: Queue¶

The Queue associated with this player.

The queue manages both upcoming tracks and playback history. Tracks can be added with queue.put() / queue.put_wait() and inspected or manipulated via the queue’s public API.

Return type:: Queue

property queue_mode: QueueMode¶

The current QueueMode for this player’s queue.

Added in version 1.1.0.

Return type:: QueueMode

property volume: int¶

The current volume of the player as an integer in the range 0–1000.

100 represents the default (unmodified) volume. Values above 100 amplify the audio and may introduce distortion.

Return type:: int

class sonolink.gateway.player.adapters._nextcord.NextcordPlayer(*args: Any, **kwargs: Any)[source]¶

Bases: BasePlayer, VoiceProtocol

A nextcord implementation of BasePlayer.

This class satisfies the nextcord.VoiceProtocol contract expected by nextcord’s voice connection machinery, whilst delegating all Lavalink playback logic to the handlers initialised by BasePlayer.

There are two primary ways to create a player:

Class-pass — pass the class itself to nextcord.abc.Connectable.connect(). nextcord will instantiate it by calling Player(client, channel):
```
player = await voice_channel.connect(cls=Player)
```
Instance-pass — construct a pre-configured instance and pass it instead. nextcord will call player(client, channel) which hits __call__():
```
player = Player(node=some_node, volume=80)
await voice_channel.connect(cls=player)
```

Parameters:

node (Node | None) – The Lavalink node to associate with this player. If None, an available node is resolved from the client’s node pool at connection time.
queue_mode (QueueMode) – The initial queue looping mode. Defaults to QueueMode.NORMAL.
autoplay_settings (AutoPlaySettings | None) – AutoPlay configuration. None uses the default configuration. History must be enabled when AutoPlay is active.
history_settings (HistorySettings | None) – History configuration. None uses the default configuration.
volume (int | None) – Initial volume in the range 0–1000. Defaults to 100.
paused (bool | None) – Whether the player should start in a paused state. Defaults to False.
filters (Filters | None) – Initial audio filters. Defaults to an empty Filters instance.

guild¶

The guild this player is attached to.

Type:: nextcord.Guild

channel¶

The voice channel this player is currently connected to.

Type:: nextcord.VoiceChannel | nextcord.StageChannel

client¶

The nextcord client driving this player.

Type:: nextcord.Client

cleanup() → None[source]¶

Cleans the internal state of the Player. This is automatically called by the library when failures or disconnects occur.

If this is overridden, it must call the original cleanup.

async connect(*, timeout: float = 10.0, reconnect: bool = False, self_deaf: bool = False, self_mute: bool = False) → None¶

Connect this player to its assigned voice channel.

Called automatically by libraries after the player is instantiated. Manual invocation is not normally required.

Parameters:

timeout (float) – Seconds to wait for the Discord gateway handshake before raising. Defaults to 10.0.
reconnect (bool) – Whether to attempt reconnection on failure. Defaults to False.
self_deaf (bool) – Whether to join the channel self-deafened. Defaults to False.
self_mute (bool) – Whether to join the channel self-muted. Defaults to False.

async disconnect(*, force: bool = False) → None¶

Disconnect this player, destroy it on the Lavalink node, and clean up all internal state.

Parameters:: force (bool) – If True, proceeds even if the player is not currently connected. Defaults to False.

get_connection_state() → PlayerConnectionState¶

Return a PlayerConnectionState instance for this player.

Override this method to supply a custom connection state subclass with additional metadata relevant to your application.

Return type:: PlayerConnectionState

async move_to(node: Node, /) → None¶

Migrate this player to a different Lavalink node without interrupting playback.

Parameters:: node (Node) – The destination node.

async on_voice_server_update(data: VoiceServerUpdate) → None[source]¶

Handle a VOICE_SERVER_UPDATE payload from the Discord gateway.

Provides the voice server token and endpoint to the Lavalink node so it can establish or re-establish the audio stream.

Parameters:: data (nextcord.types.voice.VoiceServerUpdate) – The raw payload received from the Discord gateway.

async on_voice_state_update(data: GuildVoiceState) → None[source]¶

Handle a VOICE_STATE_UPDATE payload from the Discord gateway.

Provides the session ID and channel ID required for the voice connection handshake with the Lavalink node.

Parameters:: data (nextcord.types.voice.GuildVoiceState) – The raw payload received from the Discord gateway.

async pause() → None¶

Set the pause state of the player.

Raises:: RuntimeError – If the player is not connected to a node or an active session.

async play(track: Playable, /, *, start: int = 0, end: int | None = None, volume: int | None = None, paused: bool | None = None) → Playable¶

Begin playback of the specified track.

If a track is already playing, it is stopped and the currently playing track is added to history (if history is enabled) before the new track starts.

Parameters:

track (Playable) – The track to play.
start (int) – The position in milliseconds at which to begin playback. Defaults to 0.
end (int | None) – The position in milliseconds at which to stop playback. If None, the track plays to completion. Defaults to None.
volume (int | None) – Override the player volume for this track only. If None, the current player volume is used. Defaults to None.
paused (bool | None) – If True, the track begins in a paused state. If None, the player’s current pause state is preserved. Defaults to None.

Returns:

The track that was dispatched to the Lavalink node for playback.

Return type:

Playable

async previous() → Playable¶

Return to the most recently played track in the history.

The current track is pushed back to the front of the queue so it can be reached again via skip(). The historical track then begins playing immediately.

Returns:

The historical track that is now playing.

Return type:

Playable

Raises:

RuntimeError – If the player is not connected to a node or an active session.
HistoryEmpty – If there is no previous track in the history.

async resume() → None¶

Resume playback if the player is currently paused.

Raises:: RuntimeError – If the player is not connected to a node or an active session.

async seek(position: int, /) → None¶

Seek to an arbitrary position within the current track.

Parameters:: position (int) – The target position in milliseconds. Must be within the bounds of the current track’s duration.
Raises:: RuntimeError – If the player is not connected to a node or an active session.

async set_filters(filters: Filters, /, *, seek: bool = False) → None¶

Apply a new set of audio filters to this player.

Parameters:

filters (Filters) – The Filters instance to apply.
seek (bool) – If True, the player seeks to the current position immediately after applying filters. This forces Lavalink to process the audio through the new filter chain without a audible delay. Defaults to False.

Raises:

RuntimeError – If the player is not connected to a node or an active session.

async set_volume(value: int, /) → None¶

Set the player’s output volume.

Parameters:

value (int) – The desired volume level, in the range 0–1000. 100 is the default (unmodified) level.

Raises:

ValueError – If value is outside the range 0–1000.
RuntimeError – If the player is not connected to a node or an active session.

async skip() → Playable | None¶

Skip the currently playing track and advance to the next one in the queue.

If the queue is empty and AutoPlay is enabled, a related track may be fetched automatically. If neither a queued nor an AutoPlay track is available, playback stops and None is returned.

Returns:

The track that began playing after the skip, or None if the player stopped due to an empty queue with no AutoPlay fallback.

Return type:

Playable | None

Raises:

RuntimeError – If the player is not connected to a node or an active session.
QueueEmpty – If the queue is empty and AutoPlay is disabled or yields no results.

async stop(*, clear_queue: bool = False, clear_history: bool = False) → None¶

Stop the currently playing track.

This sends a stop request to the Lavalink node and resets the player’s internal position tracking and current track reference.

Parameters:

clear_queue (bool) – If True, all pending tracks in the queue are removed. Defaults to False.
clear_history (bool) – If True, the playback history is cleared. Defaults to False.

Raises:

RuntimeError – If the player is not connected to a node or an active session.

Update the player’s configuration in-place.

Added in version 1.1.0.

Parameters:

queue_mode (QueueMode | None) – The new queue looping mode. If None, the current mode is preserved.
autoplay_settings (AutoPlaySettings | None) – New AutoPlay configuration. If None, the current settings are preserved.
history_settings (HistorySettings | None) – New history configuration. If None, the current settings are preserved.
volume (int | None) – New volume in the range 0–1000. If None, the current volume is preserved.
filters (Filters | None) – New audio filters. If None, the current filters are preserved.

property autoplay: AutoPlayMode¶

The current AutoPlayMode for this player.

When AutoPlay is enabled, the player will automatically fetch and enqueue related tracks when the queue is exhausted.

Raises:: RuntimeError – When setting, if the player’s history is disabled (history is required for AutoPlay to function).

property autoplay_settings: AutoPlaySettings¶

The current AutoPlaySettings for this player.

Can be mutated directly to update individual fields, or replaced entirely.

Added in version 1.1.0.

Return type:: AutoPlaySettings

channel: nextcord.abc.Connectable¶

client: nextcord.Client¶

property current: Playable | None¶

The track that is currently playing, or None if the player is idle.

Return type:: Playable | None

property filters: Filters¶

The Filters currently applied to this player.

To apply new filters, use set_filters() rather than mutating this object directly, so that the updated state is dispatched to the Lavalink node.

Return type:: Filters

property guild: Any¶

The guild this player is associated with.

The concrete return type is the guild class of the underlying Discord library (e.g. discord.Guild, disnake.Guild).

Raises:: RuntimeError – If the player has not yet been attached to a guild.

property history_settings: HistorySettings¶

The current HistorySettings for this player’s queue.

Can be mutated directly to update individual fields, or replaced entirely.

Added in version 1.1.0.

Return type:: HistorySettings

property node: Node¶

The Node this player is currently attached to.

Raises:: RuntimeError – If the player is not currently attached to a node.

property paused: bool¶

Whether the player is currently paused.

Return type:: bool

property position: int¶

The estimated current playback position in milliseconds.

Returns:: Position in milliseconds.
Return type:: int

property queue: Queue¶

The Queue associated with this player.

The queue manages both upcoming tracks and playback history. Tracks can be added with queue.put() / queue.put_wait() and inspected or manipulated via the queue’s public API.

Return type:: Queue

property queue_mode: QueueMode¶

The current QueueMode for this player’s queue.

Added in version 1.1.0.

Return type:: QueueMode

property volume: int¶

The current volume of the player as an integer in the range 0–1000.

100 represents the default (unmodified) volume. Values above 100 amplify the audio and may introduce distortion.

Return type:: int