v1.2.8
Powered by

# Sonora Documentation

Welcome to the official documentation for Sonora v1.2.8 - the enterprise-grade Python Lavalink client for building high-performance Discord music bots.

# 🚀 What is Sonora?

Sonora is a full-featured, enterprise-grade Python Lavalink client that provides:

  • High-performance async architecture with zero-copy routing
  • Advanced security with encrypted credentials and plugin sandboxing
  • Intelligent features like smart autoplay and adaptive queue management
  • Enterprise SDKs for rapid bot development
  • Comprehensive CLI for debugging and management
  • Session persistence with crash recovery

# 📚 Documentation Overview

# Getting Started

# Core Features

# Advanced Topics

  • Security - Security best practices
  • Snapshots - Session persistence
  • SDK - High-level development kits

# Reference

# 🎯 Key Features

# Enterprise Performance

  • Lock-free async architecture
  • Adaptive backpressure control
  • CPU-aware load balancing
  • Memory-efficient streaming

# Intelligent Audio

  • 15+ built-in audio filters
  • Real-time filter stacking
  • Smart shuffle algorithms
  • Context-aware recommendations

# Developer Experience

  • TypeScript-like Python typing
  • Comprehensive error handling
  • Structured logging
  • Built-in performance profiling

# Production Ready

  • Encrypted credential storage
  • Plugin execution sandboxing
  • Session crash recovery
  • Comprehensive testing suite

# 📦 Installation 

pip install sonora

For more details, see the Installation Guide.

# 🚀 Quick Example 

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

bot = commands.Bot(command_prefix='!')
sonora = SonoraClient(
    lavalink_nodes=[{
        "host": "localhost",
        "port": 2333,
        "password": "youshallnotpass"
    }]
)

@bot.event
async def on_ready():
    await sonora.start()
    print("Sonora ready!")

@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('YOUR_BOT_TOKEN')

# 🆘 Support

# 📄 License

Sonora is licensed under the MIT License. See the LICENSE file for details.

Version: v1.2.8 (Stability Patch Release)
Last Updated: December 2025 🚀 Get Started 📖 API Reference 💻 GitHub

69
Public Modules
92%+
Test Coverage
15+
Audio Filters
3.11+
Python Support

# ✨ Why Sonora?

Sonora MusicPy is a modern, async-first Python Lavalink client designed for building high-performance Discord music bots. Built with performance, reliability, and developer experience in mind.

# 🎯 Key Features

🔐

Enterprise Security

AES-encrypted credentials, plugin sandboxing, secure deserialization, and runtime exploit protection.

🚀

High Performance

Lock-free async architecture, zero-copy routing, adaptive backpressure, and CPU-aware load balancing.

🧠

Smart Autoplay

Context-aware recommendations with multi-strategy scoring, similarity analysis, and intelligent fallback.

💾

Session Persistence

Complete state snapshots with crash recovery, automatic background saves, and deployment-safe persistence.

🧪

Offline Simulation

Full Lavalink protocol simulator with fault injection, mock factories, and comprehensive CI/CD testing.

🛠️

Developer Experience

High-level SDKs, performance profiling, wiretap debugging, structured logging, and timeline analysis.

# 📦 Quick Installation

```bash pip install py-sonora ```

# 🚀 Quick Example

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

bot = commands.Bot(command_prefix='!') sonora = SonoraClient( lavalink_nodes=[{ "host": "127.0.0.1", "port": 2333, "password": "youshallnotpass" }] )

@bot.event async def on_ready(): await sonora.start() print("🎵 Bot is ready!")

@bot.command() async def play(ctx, *, query): player = await sonora.get_player(ctx.guild.id) track = await sonora.load_track(f"ytsearch:")

if track:
    await player.play(track)
    await ctx.send(f"🎵 Now playing: **{track.title}**")
else:
    await ctx.send("❌ No results found!")

bot.run('YOUR_BOT_TOKEN')

</div>

## 🎼 Audio Features

### Advanced Filters & Effects

<div class="code-example">
```python
# Bass boost preset
player.filters.bass_boost("high")

# Nightcore effect
player.filters.nightcore()

# Custom equalizer
from sonora import Equalizer
eq = Equalizer()
eq.set_band(0, 0.5)  # Boost bass
eq.set_band(14, -0.2)  # Cut treble
player.filters.set_filter(eq)

# Smart Queue Management

```python # Add tracks with advanced queue control player.queue.add(track) player.queue.shuffle() player.queue.move(0, 1) # Move track positions

# View different queue perspectives

upcoming = player.queue.get_view("upcoming", limit=10) history = player.queue.get_view("history", limit=5)

</div>

## 🏗️ Architecture

### Core Components

- **🎛️ Player Engine**: High-performance audio playback with effects
- **📋 Queue System**: Advanced queue with history and multiple views
- **🔗 Node Manager**: Multi-node load balancing and failover
- **🎚️ Filter System**: Comprehensive DSP effects and presets
- **📡 Event System**: Typed async events with middleware support
- **🔌 Plugin API**: Extensible architecture for custom functionality

### Integrations

- **Discord.py** - Full voice state management
- **Nextcord** - Modern Discord library support
- **PyCord** - Lightweight Discord integration
- **Custom** - Easy to extend for other frameworks

## 📊 Performance & Reliability

- **⚡ Enterprise Performance**: Lock-free async queues, zero-copy routing, adaptive backpressure
- **🔄 Intelligent Load Balancing**: CPU-aware distribution with latency optimization
- **📈 Advanced Monitoring**: 92% test coverage, performance profiling, structured logging
- **🧪 Comprehensive Testing**: Stress tests, fuzz tests, fault injection, memory leak detection
- **🔐 Enterprise Security**: AES encryption, plugin firewall, secure deserialization
- **💾 Session Resilience**: Crash recovery, state snapshots, deployment-safe persistence

## 🛠️ Developer Experience

### CLI Tools

<div class="code-example">
```bash
# Environment and health checks
sonoractl doctor                    # Check environment and dependencies
sonoractl health-check --host 127.0.0.1 --port 2333

# Session management
sonoractl snapshot save            # Save current session state
sonoractl snapshot list            # List saved snapshots
sonoractl snapshot restore file.json  # Restore from snapshot

# Performance and debugging
sonoractl profile                  # Performance profiling and metrics
sonoractl benchmark                # Run performance benchmarks
sonoractl wiretap start            # Start protocol wiretap
sonoractl debug                    # Interactive debug monitor

# Plugin and autoplay management
sonoractl plugin list/enable/disable/info <name>
sonoractl autoplay status/strategy
sonoractl queue inspect --guild-id 123

# Development tools
sonoractl create-bot discord.py mybot

# Rich Event System

```python from sonora import event_manager, EventType

@event_manager.on(EventType.TRACK_START) async def on_track_start(event): track = event.data['track'] print(f"🎵 Playing: ")

@event_manager.on(EventType.QUEUE_EMPTY) async def on_queue_empty(event): print("📭 Queue is empty!")

</div>

## 🌟 Why Sonora?

<table class="comparison-table">
  <thead>
    <tr>
      <th>Feature</th>
      <th>Sonora</th>
      <th>Other Clients</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>Language</strong></td>
      <td>Python 3.11+</td>
      <td>Various</td>
    </tr>
    <tr>
      <td><strong>Performance</strong></td>
      <td><span class="checkmark">⚡ Async-first</span></td>
      <td>Mixed</td>
    </tr>
    <tr>
      <td><strong>Audio Quality</strong></td>
      <td><span class="checkmark">🎵 15-band EQ + DSP</span></td>
      <td>Basic filters</td>
    </tr>
    <tr>
      <td><strong>Queue System</strong></td>
      <td><span class="checkmark">📋 Advanced with history</span></td>
      <td>Basic FIFO</td>
    </tr>
    <tr>
      <td><strong>Node Management</strong></td>
      <td><span class="checkmark">🌐 Load balancing</span></td>
      <td>Single node</td>
    </tr>
    <tr>
      <td><strong>Plugin System</strong></td>
      <td><span class="checkmark">🔌 Extensible</span></td>
      <td>Limited</td>
    </tr>
    <tr>
      <td><strong>Monitoring</strong></td>
      <td><span class="checkmark">📊 Prometheus metrics</span></td>
      <td><span class="crossmark">❌ None</span></td>
    </tr>
    <tr>
      <td><strong>CLI Tools</strong></td>
      <td><span class="checkmark">🛠️ Debug & templates</span></td>
      <td><span class="crossmark">❌ None</span></td>
    </tr>
    <tr>
      <td><strong>Documentation</strong></td>
      <td><span class="checkmark">📚 Comprehensive</span></td>
      <td>Basic</td>
    </tr>
  </tbody>
</table>

## 🤝 Community

- **📖 [Documentation](https://code-xon.github.io/sonora/)** - Complete guides and API reference
- **🐛 [Issues](https://github.com/code-xon/sonora/issues)** - Report bugs and request features
- **💬 [Discord](https://discord.gg/sonora)** - Community support and discussions
- **📧 Email**: [ramkrishna@code-xon.fun](mailto:ramkrishna@code-xon.fun)

## 📄 License

**MIT License** - See [LICENSE](https://github.com/code-xon/sonora/blob/main/LICENSE) for details.

---

<div class="footer-section">
  <div class="footer-content">
    <h3>Ready to build amazing Discord music bots?</h3>
    <p>Get started with Sonora MusicPy today and experience the future of Python Lavalink clients.</p>

    <div class="footer-links">
      <a href="quickstart/" class="footer-link">🚀 Quick Start</a>
      <a href="api/" class="footer-link">📖 API Reference</a>
      <a href="migration/" class="footer-link">🔄 Migration Guide</a>
      <a href="contributing/" class="footer-link">🤝 Contributing</a>
      <a href="https://github.com/code-xon/sonora" class="footer-link">💻 GitHub</a>
      <a href="https://pypi.org/project/py-sonora/" class="footer-link">📦 PyPI</a>
    </div>
  </div>
</div>

© 2025 code-xon. All rights reserved.