🎵 Aliana-Client

A premium TypeScript Lavalink v4 client library for building powerful Discord music bots with enhanced audio quality, advanced filters, and comprehensive queue management.

✨ Features

• 🎯 Multi-Source Support - YouTube, Spotify, SoundCloud, Apple Music, Deezer, JioSaavn, Yandex Music (via Lavalink plugins)
• 🔄 Autoplay System - Configurable autoplay for continuous playback
• 🎛️ Advanced Audio Filters - 10+ presets including bassboost, nightcore, vaporwave, 8D, karaoke
• 📋 Queue Management - Full queue control with persistence support
• 🖼️ Music Card Generation - Beautiful visual music cards with built-in generator
• 🔊 Audio Normalization - Automatic volume leveling across tracks
• 🌐 Multi-Node Support - Load balancing across multiple Lavalink servers
• 🔌 Auto-Reconnection - Automatic reconnection with session resumption
• 📦 TypeScript - Full type safety and IntelliSense support
• 🚀 High Performance - Optimized for speed and low memory usage

📝 Recent Updates

v1.0.7 (Latest)

Bug Fixes:

• 🐛 Fixed Queue.clear() not clearing the current track, which caused paused songs to persist in storage
• 🔧 Fixed Player.stop() not clearing queue state properly
• ⚡ Improved player state management to prevent stale queue data
• 🔗 Added queue.setPlayer() integration for better state synchronization

What Changed: Previously, when using player.destroy() or stopping playback, the queue's current track wasn't properly cleared from persistent storage. This could cause the wrong song to play after reconnecting. The fixes ensure clean state management.

📦 Installation

npm install aliana-client

Requirements:

• Node.js 18 or higher
• A running Lavalink v4 server
• Discord.js v14 or compatible Discord library

🚀 Quick Start

import { Client, GatewayIntentBits } from 'discord.js';
import { LavalinkManager } from 'aliana-client';

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildVoiceStates,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent
  ]
});

// Initialize Lavalink Manager
const manager = new LavalinkManager({
  nodes: [
    {
      id: 'main',
      host: 'localhost',
      port: 2333,
      password: 'youshallnotpass'
    }
  ],
  sendPayload: (guildId, payload) => {
    const guild = client.guilds.cache.get(guildId);
    if (guild) guild.shard.send(payload);
  }
});

// Handle voice state updates
client.on('raw', (d) => {
  if (d.t === 'VOICE_STATE_UPDATE') {
    manager.updateVoiceState(d.d);
  }
  if (d.t === 'VOICE_SERVER_UPDATE') {
    manager.updateVoiceServer(d.d);
  }
});

// Initialize manager when bot is ready
client.once('ready', async () => {
  await manager.init(client.user.id);
  console.log('Bot is ready!');
});

// Play a song
client.on('messageCreate', async (message) => {
  if (message.content.startsWith('!play')) {
    const query = message.content.slice(6).trim();
    
    // Search for tracks
    const result = await manager.search(query, message.author);
    
    if (result.tracks.length === 0) {
      return message.reply('No tracks found!');
    }
    
    // Get or create player
    const player = manager.createPlayer({
      guildId: message.guild.id,
      voiceChannelId: message.member.voice.channelId,
      textChannelId: message.channel.id,
      selfDeaf: true
    });
    
    // Add track to queue and play
    player.queue.add(result.tracks[0]);
    
    if (!player.playing && !player.paused) {
      await player.play();
    }
    
    message.reply(`Added to queue: **${result.tracks[0].title}**`);
  }
});

client.login('YOUR_BOT_TOKEN');

🎵 Supported Sources

Aliana-Client forwards queries to Lavalink, which supports multiple music sources:

⚠️ Note: Source availability depends on your Lavalink configuration and installed plugins. The client supports these search prefixes, but the actual source must be enabled in your Lavalink server.

| Platform | Source ID | Search Prefix | Lavalink Plugin Required | |----------|-----------|---------------|--------------------------| | YouTube | youtube | ytsearch: | ❌ Built-in to Lavalink | | YouTube Music | youtubemusic | ytmsearch: | ❌ Built-in to Lavalink | | SoundCloud | soundcloud | scsearch: | ❌ Built-in to Lavalink | | Spotify | spotify | spsearch: | ✅ LavaSrc Plugin | | Apple Music | applemusic | amsearch: | ✅ LavaSrc Plugin | | Deezer | deezer | dzsearch: | ✅ LavaSrc Plugin | | JioSaavn | jiosaavn | jssearch: | ✅ JioSaavn Plugin | | Yandex Music | yandex | ymsearch: | ✅ LavaSrc Plugin |

Usage Examples

// Direct URLs - auto-detected
await manager.search('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
await manager.search('https://open.spotify.com/track/...');
await manager.search('https://music.apple.com/...');

// Search queries - specify source
await manager.search('Imagine Dragons', user, 'youtube');
await manager.search('Arijit Singh', user, 'jiosaavn');
await manager.search('The Weeknd', user, 'spotify');

// Using search prefixes
await manager.search('spsearch:Coldplay');
await manager.search('ytmsearch:Believer');

🎛️ Audio Filters

Apply professional audio effects with built-in filter presets:

const player = manager.getPlayer(guildId);

// Apply preset filters
await player.filters.setEqualizer('bassboost');
await player.filters.setEqualizer('nightcore');
await player.filters.setEqualizer('vaporwave');
await player.filters.setEqualizer('8d');
await player.filters.setEqualizer('karaoke');

// Custom filters
await player.filters.setFilters({
  equalizer: [
    { band: 0, gain: 0.25 },
    { band: 1, gain: 0.25 }
  ],
  timescale: { speed: 1.1, pitch: 1.1, rate: 1 },
  tremolo: { frequency: 4.0, depth: 0.5 }
});

// Clear all filters
await player.filters.clearFilters();

Available presets: bassboost, nightcore, vaporwave, 8d, karaoke, soft, pop, electronic, rock, classical

📋 Queue Management

const player = manager.getPlayer(guildId);

// Add tracks to queue
player.queue.add(track);
player.queue.add([track1, track2, track3]);

// Get queue information
const current = player.queue.current;
const upcoming = player.queue.tracks;
const previous = player.queue.previous;

// Queue controls
player.queue.shuffle();
player.queue.clear();
player.queue.remove(index);

// Enable persistence with Redis
import { RedisStoreAdapter } from 'aliana-client';
import Redis from 'ioredis'; // or your preferred Redis client

const redis = new Redis();
const manager = new LavalinkManager({
  // ... other options
  queueStore: new RedisStoreAdapter(redis)
});

🔄 Autoplay System

Enable autoplay for continuous playback:

const player = manager.createPlayer({
  guildId: message.guild.id,
  voiceChannelId: voiceChannelId,
  textChannelId: textChannelId
});

// Enable or disable autoplay at any time
player.setAutoPlay(true);

// Check if autoplay is enabled
if (player.autoPlay) {
  console.log('Autoplay is enabled');
}

🔊 Audio Normalization

Automatically level audio across tracks:

const player = manager.createPlayer({
  guildId: message.guild.id,
  voiceChannelId: voiceChannelId,
  textChannelId: textChannelId,
  audioNormalizer: true  // Enable audio normalization
});

// Normalization automatically adjusts volume to prevent
// sudden loudness changes between tracks

🖼️ Music Cards

Generate beautiful visual music cards:

import { MusicCardGenerator } from 'aliana-client';

const player = manager.getPlayer(guildId);
const track = player.queue.current;

// Generate card with default options
const card = await MusicCardGenerator.generateCard(track);

// Or customize the card
const customCard = await MusicCardGenerator.generateCard(
  track,
  {
    backgroundColor: '#070707',
    progressColor: '#FF7A00',
    nameColor: '#FF7A00',
    authorColor: '#696969'
  },
  'classic' // Theme: 'classic', 'classicPro', or 'dynamic'
);

// Send the card
message.channel.send({ files: [customCard] });

📚 Example Bot

Check out Ayira-Bot - a production-ready Discord music bot built with Aliana-Client!

Ayira-Bot features:

• Full music playback with queue management
• Advanced audio filters and effects
• Smart autoplay system
• Music card generation
• Multi-source support (YouTube, Spotify, JioSaavn, etc.)
• Slash commands and button interactions
• And much more!

View Ayira-Bot on GitHub →

🎯 Advanced Features

Multiple Lavalink Nodes

const manager = new LavalinkManager({
  nodes: [
    { id: 'node1', host: 'lavalink1.example.com', port: 2333, password: 'pass1' },
    { id: 'node2', host: 'lavalink2.example.com', port: 2333, password: 'pass2' }
  ],
  // Load balancing strategy
  nodeStrategy: 'roundrobin'
});

Event Handling

// Manager events
manager.on('nodeConnect', (node) => {
  console.log(`Node ${node.id} connected`);
});

manager.on('nodeError', (node, error) => {
  console.error(`Node ${node.id} error:`, error);
});

// Player events
player.on('trackStart', (track) => {
  console.log(`Now playing: ${track.title}`);
});

player.on('trackEnd', (track) => {
  console.log(`Finished: ${track.title}`);
});

player.on('queueEnd', () => {
  console.log('Queue finished');
});

Custom Queue Storage

import { QueueStore } from 'aliana-client';

class MyCustomStore implements QueueStore {
  async get(guildId: string): Promise<any> {
    // Your custom storage logic
  }
  
  async set(guildId: string, data: any): Promise<void> {
    // Your custom storage logic
  }
  
  async delete(guildId: string): Promise<void> {
    // Your custom storage logic
  }
  
  async has(guildId: string): Promise<boolean> {
    // Your custom storage logic
  }
}

const manager = new LavalinkManager({
  queueStore: new MyCustomStore()
});

📖 Documentation

For detailed documentation, visit the full documentation or check out the docs/ folder.

API Reference

• LavalinkManager
• Player
• Queue
• Filters
• Events

🔧 Lavalink Setup

Aliana-Client requires a Lavalink v4 server. Here's a quick setup:

1. Download Lavalink v4 from GitHub Releases

2. Create application.yml:

server:
  port: 2333
  address: 0.0.0.0

lavalink:
  server:
    password: "youshallnotpass"
    sources:
      youtube: true
      bandcamp: true
      soundcloud: true
      twitch: true
      vimeo: true
      http: true

3. Install plugins (optional):

   • LavaSrc - For Spotify, Apple Music, Deezer
   • JioSaavn Plugin - For JioSaavn

4. Run Lavalink:

java -jar Lavalink.jar

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with inspiration from:

• Lavalink-Client
• Shoukaku
• Kazagumo

💬 Support

• Example Bot: Ayira-Bot
• Issues: GitHub Issues
• Documentation: Full Docs

Made with ❤️ by the Npg