# API Reference

Complete API documentation for Sonora.

# SonoraClient

The main client class for interacting with Lavalink nodes.

# Constructor

SonoraClient(
    lavalink_nodes: list[dict],
    node_pooling: bool = True,
    reconnect_policy: dict | None = None,
    user_id: int | None = None
)

Parameters:

lavalink_nodes: List of node configurations
node_pooling: Enable load balancing across nodes
reconnect_policy: Reconnection settings
user_id: Discord user ID for the bot

# Methods

# `async start()`

Initialize the client and connect to nodes.

# `async close()`

Shutdown the client and disconnect from all nodes.

# `async get_player(guild_id: int) -> Player`

Get or create a player for a Discord guild.

# Player

Represents a music player for a Discord guild.

# Methods

# `async play(query: str) -> Track`

Search and play a track.

# `async skip() -> Track | None`

Skip to the next track.

# `async stop()`

Stop playback and clear the queue.

# `async pause()`

Pause playback.

# `async resume()`

Resume playback.

# `async seek(position: int)`

Seek to a position in the current track.

# `async set_volume(volume: int)`

Set playback volume (0-1000).

# `async destroy()`

Destroy the player and clean up resources.

# Properties

current: Track | None - Currently playing track
queue: SmartQueue - The player's queue
paused: bool - Whether playback is paused
volume: int - Current volume level
position: int - Current playback position

# SmartQueue

Intelligent queue with advanced features.

# Methods

# `async add(track: Track, position: int | None = None)`

Add a track to the queue.

# `async add_multiple(tracks: list[Track], position: int | None = None)`

Add multiple tracks to the queue.

# `async pop(position: int = 0) -> Track`

Remove and return a track from the queue.

# `async clear()`

Clear all tracks from the queue.

# `async smart_shuffle()`

Shuffle the queue while preserving recently played tracks.

# `async perform_adaptive_reorder()`

Reorder queue based on popularity metrics.

# Properties

current: Track | None - Currently playing track
upcoming: list[Track] - Tracks waiting to be played
history: list[Track] - Recently played tracks
length: int - Number of upcoming tracks
is_empty: bool - Whether the queue is empty

# Track

Represents an audio track.

# Properties

title: str - Track title
author: str - Track author/artist
uri: str - Track URL
identifier: str - Lavalink track identifier
length: int - Track duration in milliseconds
is_stream: bool - Whether the track is a live stream
is_seekable: bool - Whether the track supports seeking

# AutoplayEngine

Handles automatic track recommendations.

# Methods

# `async fetch_next_track(context: dict) -> Track | None`

Get the next recommended track based on context.

# `async start()`

Start the autoplay engine.

# `async stop()`

Stop the autoplay engine.

# Configuration

enabled: bool - Whether autoplay is enabled
strategy: str - Recommendation strategy ('similar_artist', 'similar_genre', etc.)
max_history: int - Maximum history tracks to consider
smart_shuffle: bool - Enable smart shuffling

# Filters

Audio filter management.

# Available Filters

BassBoost - Enhance low frequencies
Nightcore - Increase speed and pitch
Reverb - Add echo effects
Equalizer - Frequency-specific adjustments

# Methods

# `async set_filter(filter_name: str, **kwargs)`

Apply an audio filter.

# `async clear_filters()`

Remove all active filters.

# `async reset_filters()`

Reset filters to default state.

# Node

Represents a Lavalink node connection.

# Methods

# `async connect()`

Connect to the Lavalink node.

# `async disconnect()`

Disconnect from the node.

# `async send(op: str, **data)`

Send a payload to the node.

# `async receive() -> dict`

Receive a payload from the node.

# Properties

connected: bool - Connection status
stats: dict - Node statistics

# Events

Event system for handling Lavalink events.

# Event Types

TRACK_START - Track started playing
TRACK_END - Track finished playing
TRACK_EXCEPTION - Track encountered an error
QUEUE_EMPTY - Queue became empty
PLAYER_UPDATE - Player state changed

# Usage

from sonora import event_manager, EventType

@event_manager.on(EventType.TRACK_START)
async def on_track_start(event):
    print(f"Started playing: {event.data['track'].title}")

# Exceptions

# SonoraError

Base exception for Sonora-related errors.

# NodeException

Raised when node operations fail.

# TrackLoadError

Raised when track loading fails.

# Security

Security-related classes and functions.

# CredentialManager

Manages encrypted credentials.

# PluginFirewall

Sandboxes plugin execution.

# SecureDeserializationLayer

Safe JSON deserialization with validation.

# API Reference

# SonoraClient

# Constructor

# Methods

# async start()

# async close()

# async get_player(guild_id: int) -> Player

# Player

# Methods

# async play(query: str) -> Track

# async skip() -> Track | None

# async stop()

# async pause()

# async resume()

# async seek(position: int)

# async set_volume(volume: int)

# async destroy()

# Properties

# SmartQueue

# Methods

# async add(track: Track, position: int | None = None)

# async add_multiple(tracks: list[Track], position: int | None = None)

# async pop(position: int = 0) -> Track

# async clear()

# async smart_shuffle()

# async perform_adaptive_reorder()

# Properties

# Track

# Properties

# AutoplayEngine

# Methods

# async fetch_next_track(context: dict) -> Track | None

# async start()

# async stop()

# Configuration

# Filters

# Available Filters

# Methods

# async set_filter(filter_name: str, **kwargs)

# async clear_filters()

# async reset_filters()

# Node

# Methods

# async connect()

# async disconnect()

# async send(op: str, **data)

# async receive() -> dict

# Properties

# Events

# Event Types

# Usage

# Exceptions

# SonoraError

# NodeException

# TrackLoadError

# Security

# CredentialManager

# PluginFirewall

# SecureDeserializationLayer

# `async start()`

# `async close()`

# `async get_player(guild_id: int) -> Player`

# `async play(query: str) -> Track`

# `async skip() -> Track | None`

# `async stop()`

# `async pause()`

# `async resume()`

# `async seek(position: int)`

# `async set_volume(volume: int)`

# `async destroy()`

# `async add(track: Track, position: int | None = None)`

# `async add_multiple(tracks: list[Track], position: int | None = None)`

# `async pop(position: int = 0) -> Track`

# `async clear()`

# `async smart_shuffle()`

# `async perform_adaptive_reorder()`

# `async fetch_next_track(context: dict) -> Track | None`

# `async start()`

# `async stop()`

# `async set_filter(filter_name: str, **kwargs)`

# `async clear_filters()`

# `async reset_filters()`

# `async connect()`

# `async disconnect()`

# `async send(op: str, **data)`

# `async receive() -> dict`