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
- v1.2.8 Enterprise Features
- Installation
- Quickstart
- Configuration
- Documentation
- Development
- Testing
- Building Docs
- Contributing
- License
- Changelog
- Roadmap
- Contributors
- Support
- Acknowledgments
- Contact
- 🚀 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
- 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
- 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
- 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
- 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
- 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
- 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
pip install py-sonoraFirst, set up your environment variables:
cp .env.example .env
# Edit .env with your Lavalink server details and Discord tokenimport 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.
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 passwordDISCORD_TOKEN: Your Discord bot token
See .env.example for a full list.
Full documentation is available at https://code-xon.github.io/sonora/.
- Python 3.11+
- A Lavalink server (see examples/docker-compose.yml for local setup)
git clone https://github.com/code-xon/sonora.git
cd sonora
pip install -e .[dev]
pre-commit installpytestmkdocs serveSee CONTRIBUTING.md for details.
This project follows a code of conduct to ensure a welcoming environment for all contributors. See CODE_OF_CONDUCT.md for details.
MIT License - see LICENSE for details.
- 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.
- Machine Learning Recommendations: Advanced ML models for music discovery
- Voice Activity Detection: Automatic voice/music separation
- Smart Crossfading: AI-powered transition detection
- Personalized Playlists: User behavior analysis
- Multi-Cloud Support: AWS, GCP, Azure integration
- Serverless Deployment: Lambda/container support
- Global CDN: Distributed Lavalink nodes
- Auto-scaling: Dynamic resource allocation
- Real-time Collaboration: Multi-user playlist editing
- Advanced Analytics: Comprehensive usage statistics
- Plugin Marketplace: Official plugin ecosystem
- Mobile SDK: iOS/Android support
Thanks to all our contributors! Special thanks to:
- Ramkrishna - Lead Developer
- Manjunath (manjunathh-dev) - Core Contributor
We welcome contributions! See our Contributing Guide for details.
- Lavalink: The underlying audio proxy technology
- Discord.py: Python Discord API wrapper
- aiohttp: Async HTTP client library
- Pydantic: Data validation library
- All Contributors: Thank you for your contributions!
- Lead Developer: Ramkrishna
- Core Contributor: Manjunath
- Email: ramkrishna@code-xon.fun
- Issues: GitHub Issues