voltricx 1.0.0

A modern, simple, and powerful Lavalink wrapper for discord.py.

The Next-Generation Lavalink Wrapper for Python

---

Voltricx is a high-performance, feature-rich Lavalink wrapper built for modern Discord bot development in Python. Engineered for speed, reliability, and ease of use, Voltricx offers a professional-grade API that makes audio integration seamless and powerful.

---

Table of Contents

• Why Voltricx?
• Features
• Installation
• Quickstart
• Examples
• Contributing
• License

---

Why Voltricx?

	Next-Gen Performance: Dual-tier caching (LRU/LFU) powered by HyperCache for lightning-fast data retrieval.
	Strictly Typed: Comprehensive type hinting and Pydantic v2 validation ensure your code is robust and maintainable.
	High-Fidelity Failover: Automated node shifting and silent reconnects ensure a seamless listening experience.
	Modern Standards: Fully compatible with Lavalink v4.0+, including native support for the DAVE E2EE protocol and filters.
	Smart Load Balancing: Advanced penalty-based node selection for optimal performance across multiple Lavalink nodes.

---

Features

• 🚀 Asynchronous Architecture: Built from the ground up to be fully async and non-blocking.
• 📡 Websocket Management: Efficient handling of Lavalink websocket connections with automatic retries.
• 🎹 Rich Audio Control: Full support for filters including Equalizer, Timescale, Vibrato, and more.
• 🌐 DAVE Protocol: Support for the latest Discord Audio Video Encryption standards.
• ⚖️ Regional Selection: Intelligent node selection based on guild region and node latency.

---

Installation

Voltricx requires Python 3.12+.

# Stable version from PyPI
pip install voltricx

For the latest development version:

pip install git+https://github.com/revvlabs/voltricx.git

---

Quickstart

Here is a minimal example of how to get up and running with Voltricx.

import discord
from discord.ext import commands
import voltricx

class MyBot(commands.Bot):
    def __init__(self):
        super().__init__(command_prefix="!", intents=discord.Intents.all())

    async def setup_hook(self):
        # Configuration for your Lavalink Node
        config = voltricx.NodeConfig(
            uri="http://localhost:2333",
            password="youshallnotpass",
            identifier="MAIN-NODE"
        )

        # Initialize the Pool and add the node
        node = voltricx.Node(config=config)
        await voltricx.Pool.add_node(node)

bot = MyBot()

@bot.event
async def on_voltricx_node_ready(node: voltricx.Node):
    print(f"✅ Lavalink Node {node.identifier} is ready and connected!")

@bot.command()
async def play(ctx, *, query: str):
    # Retrieve or create a player for the guild
    player: voltricx.Player = ctx.voice_client or await ctx.author.voice.channel.connect(cls=voltricx.Player)

    # Search for tracks
    tracks = await voltricx.Pool.get_tracks(query)
    if not tracks:
        return await ctx.send("❌ No tracks found.")

    track = tracks[0]
    await player.play(track)
    await ctx.send(f"🎶 **Now playing**: {track.title}")

bot.run("YOUR_BOT_TOKEN")

---

Examples

Check the example directory for advanced usage, including:

• Basic Bot Implementation
• Custom Queue Handlers
• Advanced Filters (Nightcore, etc.)

---

Contributing

We welcome contributions! If you'd like to help improve Voltricx:

1. Fork the repository.
2. Clone your fork and create a new feature branch (git checkout -b feature/amazing-feature).
3. Commit your improvements (git commit -m 'feat: add some amazing feature').
4. Push the changes to your fork (git push origin feature/amazing-feature).
5. Open a Pull Request.

---

License

Voltricx is released under the MIT License. See LICENSE for more information.