API Reference

Utility and Miscellaneous

Event Reference

Payloads

class wavelink.NodeReadyPayload(node: Node, *, data: ReadyMsgT)
class wavelink.NodeStatsPayload(node: Node, *, data: StatsData)
class wavelink.PlayerUpdatePayload(node: Node, *, data: PlayerUpdateMsgT)
class wavelink.TrackEndPayload(node: Node, *, data: TrackEndEventT)
class wavelink.TrackExceptionPayload(node: Node, *, data: TrackExceptionEventT)
class wavelink.TrackStartPayload(node: Node, *, data: TrackStartEventT | TrackEndEventT | TrackStuckEventT | TrackExceptionEventT)
class wavelink.TrackStuckPayload(node: Node, *, data: TrackStuckEventT)
class wavelink.WebsocketClosedPayload(node: Node, *, data: WebSocketClosedEventT)

Strategy Helpers

Enums

class wavelink.AutoPlay(*values)

…

Attributes
class wavelink.EventType(*values)

enum.StrEnum representing the event types dispatched via the Websocket.

TrackStart
Type:

Literal[“track_start”]

TrackEnd
Type:

Literal[“track_end”]

TrackException
Type:

Literal[“track_exception”]

TrackStuck
Type:

Literal[“track_stuck”]

WebsocketClosed
Type:

Literal[“websocket_closed”]

PlayerUpdate
Type:

Literal[“player_update”]

NodeStats
Type:

Literal[“node_stats”]

NodeReady
Type:

Literal[“node_ready”]

Attributes
class wavelink.LoadResult(*values)

enum.StrEnum representing the load result from the /loadtracks endpoint.

track

A single track has been loaded.

Type:

str

playlist

A playlist has been loaded.

Type:

str

search

A search has been loaded.

Type:

str

empty

There has been no matches for your identifier.

Type:

str

error

There was an error loading results.

Type:

str

Attributes
class wavelink.Source(*values)

enum.StrEnum representing a music source to search from. E.g. Youtube or Spotify.

youtube

Source representing Youtube.

Type:

Literal[“ytsearch”]

youtube_music

A source representing Youtube Music.

Type:

Literal[“ytmsearch”]

soundcloud

A source representing SoundCloud.

Type:

Literal[“scsearch”]

spotify

A source representing Spotify.

Type:

Literal[“spsearch”]

local

A source representing a raw or local search. E.g. a URL or File Path.

Type:

Literal[“local”]

Attributes
class wavelink.TrackEndReason(*values)

enum.StrEnum representing the Track End Reason received by Lavalink.

finished

The track finished playing. Can start the next track.

Type:

str

load_failed

The track failed to load. Can start the next track.

Type:

str

stopped

The track was stopped. Cannot start the next track.

Type:

str

replaced

The track was replaced. Cannot start the next track.

Type:

str

cleanup

The track was cleaned up. Cannot start the next track.

Type:

str

Core

Music Bot

Nodes

Player

Attributes
Methods
class wavelink.Player(client: Client, channel: Connectable, /, *, node: Node | None = None)

Wavelink Player class which inherits from your libraries VoiceProtocol.

The Player class is usually not constructed manually, instead you pass it to your libraries channel.connect(cls=wavelink.Player) method instead; e.g. discord.VoiceChannel.connect().

Since the Player requires a Node, there are a few options available to allow Player to work.

  • Use MusicBot. This will automatically pass the best Node to this player.

  • Use Pool and assign it to your Client as the .wave attribute. This will automatically pass the best Node to this player.

  • Use either Pool or a standalone Node and pass that to discord.VoiceChannel.connect(). This will construct a Player for you based on what you provide. e.g. Channel.connect(cls=self.node)

Players are unique to each discord.Guild. You may only have one Player connected per discord.Guild at any given time.

The Player will automatically attempt to re-establish connection to discord in cases where disconnection was not intended. You should not and do not need to implement re-connection logic on this class. Doing so may interfere or conflict with the internal logic. If you would like to implement you own activity/inactivity checks on this player, please refer to inactivity_strategy.

Note

Any MusicBot, Pool or Node can be passed to discord.VoiceChannel.connect() to create a Player and assign it an appropriate Node.

Parameters:

  • client (discord.Client) – The discord.Client currently running.

  • channel (discord.Connectable) – The voice channel this Player has connected to.

  • node (Node | None) – An optional Node to pass to use for this Player. Defaults to None. See above for more details.

property node: Node

Property returning the Node associated with the player.

Return type:

Node

property guild: Guild | None

Property returning the Guild associated with the player.

Return type:

discord.Guild

property volume: int

Property returning the current volume of the player. Defaults to 100.

Return type:

int

property ping: int

Property returning the ping of Lavalink to Discord.

If the ping is -1 the player is disconnected.

Return type:

int

property position: int

Property returning the current playing track position in ms.

Return type:

int

property last_update: datetime | None

Property return the datetime the player was last updated via Lavalink.

Could be None if the player has not been updated.

Returns:

  • datetime.datetime – The time the player was last updated.

  • None – The player has not been updated.

property is_playing: bool

Property returning a bool indicating whether the player is currently playing a track.

Note

Pausing the player has no effect on this property.

Return type:

bool

property is_paused: bool

Property returning a bool indicating whether the player is currently paused.

Return type:

bool

property is_deaf: bool

Property returning a bool indicating whether the player is currently self deafened.

Return type:

bool

property is_mute: bool

Property returning a bool indicating whether the player is self muted.

Note

This is not the same as turning down the volume to 0.

Return type:

bool

await on_voice_server_update(data: VoiceServerUpdatePayload) → None

This function is a coroutine.

An abstract method that is called when initially connecting to voice. This corresponds to VOICE_SERVER_UPDATE.

Parameters:

data (dict) – The raw voice server update payload.

await on_voice_state_update(data: GuildVoiceStatePayload) → None

This function is a coroutine.

An abstract method that is called when the client’s voice state has changed. This corresponds to VOICE_STATE_UPDATE.

Warning

This method is not the same as the event. See: on_voice_state_update()

Parameters:

data (dict) – The raw voice state payload.

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

This function is a coroutine.

An abstract method called when the client initiates the connection request.

When a connection is requested initially, the library calls the constructor under __init__ and then calls connect(). If connect() fails at some point then disconnect() is called.

Within this method, to start the voice connection flow it is recommended to use Guild.change_voice_state() to start the flow. After which, on_voice_server_update() and on_voice_state_update() will be called. The order that these two are called is unspecified.

Parameters:

  • timeout (float) – The timeout for the connection.

  • reconnect (bool) – Whether reconnection is expected.

  • self_mute (bool) –

    Indicates if the client should be self-muted.

    Added in version 2.0.

  • self_deaf (bool) –

    Indicates if the client should be self-deafened.

    Added in version 2.0.

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

This function is a coroutine.

An abstract method called when the client terminates the connection.

See cleanup().

Parameters:

force (bool) – Whether the disconnection was forced.

Search and Tracks

Queue

Exceptions