Sonora

A full-featured, enterprise-grade Python Lavalink client for building high-performance Discord music bots. The most advanced Lavalink client available.

🚀 v1.2.8 - Stability Patch Release with Enhanced Reliability!

Features

• 🚀 Enterprise-Grade Performance: Lock-free async architecture, zero-copy routing, adaptive backpressure
• 🔐 Advanced Security: AES-encrypted credentials, plugin sandboxing, secure deserialization
• 🧠 Smart Autoplay Engine: Context-aware recommendations with multi-strategy scoring
• 📊 Intelligent Queue System: Session memory, similarity scoring, adaptive reordering
• 💾 Session Persistence: Complete state snapshots with crash recovery
• 🧪 Offline Simulation: Full Lavalink protocol simulator with fault injection
• 🛠 High-Level SDKs: SonoraMusicBotSDK and SonoraVoiceSDK for rapid development
• 🔍 Advanced Diagnostics: Performance profiling, wiretap debugging, timeline analysis
• 📈 Enterprise Monitoring: 92% test coverage, comprehensive metrics, structured logging
• 🔌 Extensible Plugin System: Secure plugin architecture with marketplace-ready APIs
• Full Lavalink protocol support (v3 & v4) with Python 3.11+ compatibility
• Integrations for discord.py, py-cord, and nextcord
• Multi-node load balancing with health checks and failover
• 15+ audio filters with real-time hot-swapping
• CLI utilities for debugging, benchmarking, and session management

v1.2.7 Enterprise Features

🔐 Enterprise Security

• AES Credential Vault: Encrypted storage with key rotation and secure access
• Plugin Firewall: Advanced sandboxing with code analysis and import restrictions
• Secure Deserialization: Type-validated JSON parsing with size limits
• Runtime Exploit Protection: Guardrails against malicious inputs and attacks

🛠 High-Level SDKs

• SonoraMusicBotSDK: Pre-built commands with auto queue binding and filter pipelines
• SonoraVoiceSDK: Voice-only streaming with connection management and statistics
• Rapid Development: Get started in minutes with production-ready components

💾 Session Management

• Complete State Snapshots: Player, queue, filters, and autoplay state persistence
• Crash Recovery: Automatic restoration across restarts and deployments
• Background Snapshots: Configurable intervals with intelligent cleanup

🧪 Advanced Testing & Simulation

• Offline Protocol Simulator: Full Lavalink simulation with fault injection
• Mock Factory: Deterministic test objects for comprehensive CI/CD
• Fault Injection: Packet loss, latency spikes, connection drops for testing
• 92% Test Coverage: Stress tests, fuzz tests, memory leak detection

⚡ Performance Overdrive

• Lock-Free Architecture: High-throughput async queues without blocking
• Zero-Copy Routing: Optimized payload handling for maximum performance
• Adaptive Backpressure: Intelligent load shedding under high load
• CPU-Aware Balancing: Optimized resource distribution across nodes

🔍 Developer Experience

• Built-in Profiler: cProfile integration with memory tracking
• Structured Logging: JSON logging for debugging and monitoring
• Wiretap Debugger: Protocol-level packet inspection and capture
• Timeline Analysis: Playback event debugging with pattern recognition
• Reproducible Testing: Session recording and replay for debugging

Installation

pip install py-sonora

Quickstart

First, set up your environment variables:

cp .env.example .env
# Edit .env with your Lavalink server details and Discord token

Minimal Discord Bot Example

import discord
from discord.ext import commands
from sonora import SonoraClient

intents = discord.Intents.default()
intents.message_content = True

bot = commands.Bot(command_prefix='!', intents=intents)
sonora = SonoraClient(
    lavalink_nodes=[{"host": "127.0.0.1", "port": 2333, "password": "youshallnotpass"}],
    node_pooling=True,
    reconnect_policy={"max_retries": 5, "backoff": "exponential"}
)

@bot.event
async def on_ready():
    await sonora.start()
    print(f'Logged in as {bot.user}')

@bot.command()
async def join(ctx):
    if ctx.author.voice:
        await ctx.author.voice.channel.connect()
        player = await sonora.get_player(ctx.guild.id)
        await ctx.send("Joined voice channel!")
    else:
        await ctx.send("You need to be in a voice channel!")

@bot.command()
async def play(ctx, *, query):
    player = await sonora.get_player(ctx.guild.id)
    track = await player.play(query)
    await ctx.send(f"Now playing: {track.title}")

bot.run(os.getenv('DISCORD_TOKEN'))

For more examples, see the examples/ directory.

Configuration

Sonora supports configuration via environment variables:

• LAVALINK_HOST: Lavalink server host (default: 127.0.0.1)
• LAVALINK_PORT: Lavalink server port (default: 2333)
• LAVALINK_PASSWORD: Lavalink server password
• DISCORD_TOKEN: Your Discord bot token

See .env.example for a full list.

Documentation

Full documentation is available at https://code-xon.github.io/sonora/.

• Quickstart Guide
• API Reference
• Migration from Riffy

Development

Prerequisites

• Python 3.11+
• A Lavalink server (see examples/docker-compose.yml for local setup)

Setup

git clone https://github.com/code-xon/sonora.git
cd sonora
pip install -e .[dev]
pre-commit install

Testing

pytest

Building Docs

mkdocs serve

Contributing

See CONTRIBUTING.md for details.

License

MIT License - see LICENSE for details.

Changelog

v1.2.8 (2025-12-06) - Stability Patch Release

• Fixed: Rare async task cancellation leaks in autoplay shutdown and node reconnect
• Fixed: Clean shutdown of background tasks in player.destroy(), node.disconnect(), client.shutdown()
• Fixed: Edge-case deadlock in smart queue adaptive reorder
• Fixed: Crash during plugin hot-reload under high CPU load
• Fixed: Permission scope mismatches for filters.write and autoplay.read
• Fixed: Cold-start fallback not triggering in rare startup states
• Enhanced: Smart shuffle randomness distribution
• Enhanced: Skip-fatigue detection sensitivity stability
• Enhanced: Credential vault validation with structure checks
• Enhanced: Sandbox escape detection heuristics
• Enhanced: Snapshot integrity verification with SHA256 checksums
• Improved: CLI formatting and status messages
• Added: Safety timeouts on lingering asyncio tasks
• Added: Regression tests for critical fixes
• Added: Core contributor Manjunath (manjunathh-dev)

See CHANGELOG.md for full details.

Contact

• Lead Developer: Ramkrishna
• Core Contributor: Manjunath
• Email: ramkrishna@code-xon.fun
• Issues: GitHub Issues