wavelink

WaveLink events are dispatched via discord.py and must be implemented as coroutines. You can use the standard @commands.Cog.listener() syntax to respond to events.

Common event patterns include:

• Node Lifecycle: on_wavelink_node_ready (initial connection/reconnection), on_wavelink_node_disconnected (lost connection), and on_wavelink_node_closed (node cleaned up).
• Playback Lifecycle: on_wavelink_track_start (preferred for feedback), on_wavelink_track_end (note: if using AutoPlay, use on_wavelink_track_start for logic instead), on_wavelink_track_exception, and on_wavelink_track_stuck.
• Player/Voice Lifecycle: on_wavelink_player_update, on_wavelink_websocket_closed, and on_wavelink_inactive_player (triggered when Player.inactive_timeout expires).
• System/Plugin Events: on_wavelink_stats_update and on_wavelink_extra_event (for custom Lavalink plugin data like SponsorBlock).

@commands.Cog.listener()
async def on_wavelink_node_ready(self, payload: wavelink.NodeReadyEventPayload) -> None:
    print(f"Node {payload.node!r} is ready!")

Wavelink version 3 introduces several breaking changes and improvements over version 2:

Key Requirements & Changes

• Lavalink Version: Version 3 requires Lavalink v4+.
• Track Types: Specific track classes (e.g., YouTubeTrack, SoundCloudTrack) have been removed. All tracks now use the unified wavelink.Playable class.
• Spotify Support: The standalone Spotify Extension is removed. Use native support via the LavaSrc plugin.
• Naming Changes:
  • wavelink.Node.id $\rightarrow$ wavelink.Node.identifier
  • wavelink.NodePool $\rightarrow$ wavelink.Pool
  • wavelink.Player.current_node $\rightarrow$ wavelink.Player.node
  • wavelink.Player.is_connected() $\rightarrow$ wavelink.Player.connected (attribute)
  • wavelink.Player.is_paused() $\rightarrow$ wavelink.Player.paused (attribute)
  • wavelink.Player.is_playing() $\rightarrow$ wavelink.Player.playing (attribute)
  • wavelink.Player.stop() $\rightarrow$ wavelink.Player.skip() (alias exists)

API Behavior Changes

• Searching: Playlists can no longer be used as search queries. wavelink.Playable.search returns a wavelink.Search object (which is a list of Playable or a Playlist).
• Pausing: Logic for resuming has moved to wavelink.Player.pause(bool). To toggle, use await player.pause(not player.paused).
• Queue: wavelink.Queue.put_wait and put now return an int representing the number of tracks added.

Wavelink v3 uses the wavelink.Filters class to manage audio effects. You can apply filters to a player using player.set_filters(filters) or reset them using player.set_filters() with no arguments.

Common Operations:

• Create and apply new filters: Create a wavelink.Filters() instance and pass it to player.set_filters().
• Retrieve current filter payload: Access player.filters and call it as a function to get the payload.
• Modify specific filters: Use .set() on individual filter components (like timescale, rotation, or equalizer) and then call await player.set_filters(filters) to apply changes.
• Reset individual filters: Use .reset() on a specific filter component.
• Reset all filters: Use .reset() on the main Filters instance.
• Quick reset: Call await player.set_filters() to clear all filters from the player.

import wavelink

# Create and apply brand new filters
filters: wavelink.Filters = wavelink.Filters()
await player.set_filters(filters)

# Modify specific filters (e.g., timescale and rotation)
filters: wavelink.Filters = player.filters
filters.timescale.set(pitch=1.2, speed=1.1, rate=1)
filters.rotation.set(rotation_hz=0.2)
filters.equalizer.reset()
await player.set_filters(filters)

# Reset a single filter
filters: wavelink.Filters = player.filters
filters.timescale.reset()
await player.set_filters(filters)

# Reset all filters
filters: wavelink.Filters = player.filters
filters.reset()
await player.set_filters(filters)

# Quick method to reset and apply filters
await player.set_filters()