Skip to content

Home

Jump to bottom
toddynnn edited this page Mar 9, 2025 · 5 revisions

AquaLink Wiki

Overview

AquaLink is a lightweight and efficient Lavalink wrapper designed for performance and stability. It allows developers to integrate Lavalink into their Discord bots with minimal dependencies. AquaLink handles voice connections, track playback, and queue management with ease.

Features

  • 🚀 Minimal Dependencies – AquaLink is designed to be lightweight and fast.
  • 🎵 Built-in Queue Management – No need for external queue handling.
  • 🔄 Auto-Reconnect for Lavalink Nodes – Ensures a stable connection.
  • 🔊 High-Quality Audio Streaming – Supports multiple formats and platforms.
  • 🌍 Supports Multiple Lavalink Nodes – Load balancing for better performance.
  • 🔥 Easy-to-Use API – Simple and intuitive commands for managing playback.

Installation

Prerequisites

Before using AquaLink, ensure you have:

Installing AquaLink

npm install aqualink

You also need to have a running Lavalink server:

  1. Download Lavalink from here.
  2. Install Java 17 or newer.
  3. Configure the application.yml file with your preferred settings.
  4. Start the Lavalink server using:
java -jar Lavalink.jar

Getting Started

Importing and Initializing AquaLink

const { AquaLink } = require("aqualink");

const nodes = [
    {
        host: "127.0.0.1",
        password: "yourpass",
        port: 233,
        secure: false,
        name: "localhost"
    }
];

const aqua = Aqua(client, nodes, {
  defaultSearchPlatform: "ytsearch",
  restVersion: "v4",
  autoResume: false,
  infiniteReconnects: true,
});

Handling Voice State Updates

AquaLink requires voice state updates to maintain connections. Ensure you handle these events properly:

client.on("raw", (d) => {
    if (![GatewayDispatchEvents.VoiceStateUpdate, GatewayDispatchEvents.VoiceServerUpdate].includes(d.t)) return;
    client.aqua.updateVoiceState(d);
});

Playing Audio

Connecting to a Voice Channel

async function connectToChannel(guildId, channelId) {
  const player = client.aqua.players.get(interaction.guildId);
  player.connect(channelId);
}

Playing a Track

async function playTrack(guildId, track) {
        let player = client.aqua.players.get(interaction.guildId);
        if (!player) {
            player = client.aqua.createConnection({
                defaultVolume: 65,
                guildId: interaction.guildId,
                voiceChannel: interaction.member.voice.channelId,
                textChannel: interaction.channelId,
                deaf: true
            });
        }
  player.play(track);
}

Example of Searching for a Track Using Lavalink

async function searchAndPlay(guildId, query) {
  const resolve = await client.aqua.resolve({
  query,
  requester: interaction.member, // optional!
  source: "scsearch"
});
  if (!results.tracks.length) return console.log("No results found.");

  const track = results.tracks[0]; 
  await player.queue.add(track)
      if (!player.playing && !player.paused && player.queue.size > 0) {
        player.play();
      }
}

Controlling Playback

Pausing and Resuming

async function pausePlayback(guildId) {
  const player = client.aqua.players.get(interaction.guildId);
  if (player) player.pause(true);
}

async function resumePlayback(guildId) {
  const player = client.aqua.players.get(interaction.guildId);
  if (player) player.pause(false);
}

Skipping a Track

async function skipTrack(guildId) {
  const player = client.aqua.players.get(interaction.guildId);
  if (player) player.stop();
}

Stopping and Disconnecting

async function stopPlayback(guildId) {
  const player = client.aqua.players.get(interaction.guildId);
  if (player) player.stop();
}

async function disconnectPlayer(guildId) {
  const player = client.aqua.players.get(interaction.guildId);
  if (player) player.destroy();
}

Managing Queues

AquaLink provides a built-in queue manager for handling track queues.

Adding a Track to the Queue

async function addToQueue(guildId, track) {
  const player = client.aqua.players.get(interaction.guildId);
  if (!player.queue) player.queue = [];

  player.queue.push(track);
  if (!player.playing) playTrack(guildId, player.queue.shift());
}

Viewing the Current Queue

async function viewQueue(guildId) {
  const player = client.aqua.players.get(interaction.guildId);
  if (!player || !player.queue.length) return console.log("The queue is empty.");

  console.log("Current Queue:");
  player.queue.forEach((track, index) => {
    console.log(`${index + 1}. ${track.info.title}`);
  });
}

Looping a Track

async function loopTrack(guildId) {
  const player = client.aqua.players.get(interaction.guildId);
  if (!player) return;

  player.queue.unshift(player.queue[player.queue.length - 1]); 
}

Event Handling

AquaLink provides event listeners to monitor and manage playback.

Listening for Track Start

client.aqua.on("trackStart", (player, track) => {
  console.log(`Now playing: ${track.info.title}`);
});

Listening for Track End

client.aqua.on("trackEnd", (player, track) => {
  console.log(`Finished playing: ${track.info.title}`);
  if (player.queue.length > 0) {
    player.play(player.queue.shift());
  }
});

Handling Player Errors

client.aqua.on("trackError", (player, track, error) => {
  console.error(`Error playing ${track.info.title}: ${error.message}`);
});

Disconnecting and Cleanup

To ensure your bot properly disconnects and cleans up resources, use the following:

async function cleanup(guildId) {
  const player = client.aqua.players.get(interaction.guildId);
  if (player) {
    player.stop();
    player.destroy();
  }
}

Troubleshooting

1. No Sound or Bot Not Joining

  • Ensure the Lavalink server is running and accessible.
  • Verify the Lavalink password and port are correct in your code.
  • Ensure your bot has the correct permissions (CONNECT and SPEAK).

2. Bot Leaves the Channel Unexpectedly

  • The bot may be idle for too long. Consider implementing an inactivity timeout.
  • Lavalink may be crashing—check your Lavalink logs.

3. Music Skipping or Lagging

  • Check your server’s CPU and memory usage. Lavalink requires adequate resources.
  • If hosting Lavalink remotely, ensure the network connection is stable.

Bots That Use AquaLink

AquaLink is used in various Discord music bots, including:

  • 🎵 Chippy Music – A high-quality music bot powered by AquaLink.
  • 🎵 Kenium - An Open Source music bot

If you are using AquaLink for your bot, feel free to submit a PR to add it to this list!

Conclusion

AquaLink provides a simple yet powerful way to integrate Lavalink with Discord bots. With built-in queue management, efficient resource handling, and easy-to-use methods, it makes audio playback seamless.

For more information, visit the GitHub repository.

Clone this wiki locally