Metadata-Version: 2.4
Name: voltricx
Version: 1.0.5
Summary: A modern, simple, and powerful Lavalink wrapper for discord.py.
Author: @JustNixx, @Dipendra-creator
License: MIT
Project-URL: Homepage, https://github.com/ded-lmfao/voltricx
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: discord.py>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: yarl>=1.9.0
Requires-Dist: python-dotenv>=1.0.0
Dynamic: license-file

# Voltricx ⚡

A modern, high-performance, and feature-rich Lavalink wrapper for **discord.py** and its derivatives. Built for developers who demand speed, reliability, and ease of use.

[![Python Version](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Pydantic v2](https://img.shields.io/badge/pydantic-v2-orange.svg)](https://docs.pydantic.dev/latest/)

## ✨ Features

- 🚀 **Next-Gen Performance**: Dual-tier caching (LRU/LFU) powered by `HyperCache`.
- 🛠️ **Fully Typed**: Comprehensive type hinting and Pydantic v2 validation for a robust developer experience.
- 📡 **High-Fidelity Failover**: Automated node shifting and silent reconnects to keep the music playing.
- 🎹 **Rich Audio Control**: Full support for Lavalink v4 filters (Equalizer, Timescale, Vibrato, etc.).
- 🌐 **DAVE Protocol**: Support for the latest Discord Audio Video Encryption (DAVE) standards.
- ⚖️ **Smart Load Balancing**: Penalty-based node selection for optimal performance across multiple Lavalink nodes.

## 📦 Installation

Install the library in editable mode for development:

```bash
pip install -e .
```

## 🚀 Quick Start

```python
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")
```

## 📂 Project Structure

- `voltricx/`: Core package containing all library logic.
- `tests/`: Comprehensive test suite for ensuring stability.
- `full_test_bot.py`: A feature-complete demonstration bot.

## 📜 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
