Quickstart

Get started with Aqualink - the powerful Discord Lavalink wrapper

Get started with Aqualink in three steps

Set up Aqualink and start building music bots with enhanced Lavalink functionality.

Step 1: Installation and Setup

Install Aqualink

Install Aqualink in your Node.js project using your preferred package manager:

npm install aqualink
# or
yarn add aqualink
# or
pnpm add aqualink

Set up Lavalink server

Before using Aqualink, you need a running Lavalink server:

1. Download the latest Lavalink.jar from GitHub releases
2. Create an application.yml configuration file
3. Start your Lavalink server: java -jar Lavalink.jar

Make sure your Lavalink server is running before initializing Aqualink!

Step 2: Initialize Aqualink

Quick setup

Create your first Aqualink instance and connect to your Lavalink server:

const { Client, GatewayIntentBits } = require('discord.js');
const { Aqua } = require('aqualink');

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

client.aqua = new Aqua(client, {
    nodes: [{
        host: 'localhost',
        port: 2333,
        auth: 'youshallnotpass',
        ssl: false
    }]
});

client.on('ready', async () => {
    await client.aqua.init(client.user.id);
    console.log('Bot is ready and connected to Lavalink!');
});

client.login('YOUR_BOT_TOKEN');

Complete configuration

For production use, here’s a full configuration with all available options:

const { Aqua } = require('aqualink');

const aqua = new Aqua(client, {
  nodes: [{
    host: 'localhost',
    port: 2333,
    auth: 'youshallnotpass',
    ssl: false,
    name: 'main-node'
  }],
  defaultSearchPlatform: 'ytsearch',
  nodeResolver: 'LeastLoad'
  shouldDeleteMessage: false,
  leaveOnEnd: true,
  restVersion: 'v4',
  plugins: [],
  autoResume: false,
  infiniteReconnects: false,
  failoverOptions: {
    enabled: true,
    maxRetries: 3,
    retryDelay: 1000,
    preservePosition: true,
    resumePlayback: true,
    cooldownTime: 5000,
    maxFailoverAttempts: 5
  }
});

The failover options provide robust error handling and automatic reconnection!

Step 3: Play your first track

Create a player and play music

Here’s how to create a connection and play your first track:

// Create a player connection
const player = client.aqua.createConnection({
    guildId: interaction.guild.id,
    textChannel: interaction.channel.id,
    voiceChannel: interaction.member.voice.channel.id,
    deaf: true,
    defaultVolume: 100
});

// Search and play a track
client.on('interactionCreate', async (interaction) => {
    if (interaction.commandName === 'play') {
        const query = interaction.options.getString('song');
        
        const results = await player.search(query);
        if (results.tracks.length > 0) {
            await player.play(results.tracks[0]);
            interaction.reply(`Now playing: ${results.tracks[0].title}`);
        } else {
            interaction.reply('No tracks found!');
        }
    }
});

Next steps

Explore Aqualink’s powerful features for Discord music bots:

Player Management

Learn how to create, manage, and control music players.

Queue System

Implement playlists and queue management for your bot.

Audio Filters

Add effects like bass boost, nightcore, and more to audio.

Events & Listeners

Handle player events and create responsive music experiences.

Key Features

Aqualink provides enhanced functionality over standard Lavalink clients:

• Easy-to-use API with intuitive methods and properties
• Built-in queue management with shuffle, loop, and skip functionality
• Advanced search supporting YouTube, Spotify, SoundCloud, and more
• Audio filters for dynamic sound modification
• Event-driven architecture for responsive bot behavior
• TypeScript support with full type definitions

Need help? Check out our API Reference or join our community Discord server for support and examples.