py-sonora 1.2.0b0

A full-featured Python Lavalink client for Discord music bots

Sonora

A full-featured, production-ready Python Lavalink client for building music-capable Discord bots. Equivalent to Riffy but in Python.

🚀 v1.2.0-beta now available with Smart Autoplay & Queue Intelligence!

Features

• Async-first Python library compatible with Python 3.11+
• Full Lavalink protocol support (v3 & v4)
• Integrations for discord.py, py-cord, and nextcord
• Plugin system for platform adapters (YouTube, Spotify, SoundCloud)
• Voice connection management, track loading, queue management, player controls
• Node pooling & reconnection, smart autoplay, per-guild voice state resumption
• Intelligent queue system with session memory and adaptive reordering
• Clean high-level API + low-level control
• Well-documented with MkDocs
• Thoroughly tested (coverage >= 36%)
• Packaged for PyPI, CI/CD with GitHub Actions, Docker support

v1.2.0-beta Features

⚠️ BETA FEATURES - Experimental and subject to change

• Smart Autoplay Engine: Context-aware track recommendations based on artist, genre, and popularity
• Intelligent Queue: Session memory, similarity scoring, smart shuffle, skip fatigue detection
• Adaptive Queue Reordering: Automatic queue optimization based on metrics
• Plugin Hooks: Extend autoplay strategies and similarity scorers
• Enhanced CLI: New commands for autoplay and queue management

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.

Contact

• Lead Developer: Ramkrishna
• Email: [e-mail]
• Issues: GitHub Issues