KawaLink

KawaLink is a lightweight Lavalink client for Discord bots. It provides node management, player controls, queues, filters, resume support, and typed events for building music bots with discord.js.

Installation

npm install kawalink discord.js

yarn add kawalink discord.js

pnpm add kawalink discord.js

bun add kawalink discord.js

You also need a running Lavalink server.

Basic Setup

const { Client, GatewayIntentBits } = require("discord.js");
const { Manager } = require("kawalink");

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

client.manager = new Manager({
  nodes: [
    {
      host: "127.0.0.1",
      port: 2333,
      password: "youshallnotpass",
      identifier: "main",
      secure: false,
      version: "v4",

      // REST reliability tuning
      requestTimeout: 10000,
      requestRetryAmount: 1,
      requestRetryDelay: 250,
    },
  ],
  send: (guildId, payload) => {
    const guild = client.guilds.cache.get(guildId);
    guild?.shard?.send(payload);
  },
  autoPlay: true,
  autoMove: true,
  autoResume: true,
  defaultSearchPlatform: "youtube music",
  shards: client.shard?.count ?? 1,
});

client.once("ready", () => {
  client.manager.init(client.user.id);
  console.log(`Logged in as ${client.user.tag}`);
});

client.on("raw", (packet) => client.manager.updateVoiceState(packet));

client.login("YOUR_BOT_TOKEN");

Play a Track

async function play(message, query) {
  const member = message.member;
  const voiceChannel = member.voice.channel;

  if (!voiceChannel) {
    return message.reply("Join a voice channel first.");
  }

  const player = message.client.manager.create({
    guild: message.guild.id,
    voiceChannel: voiceChannel.id,
    textChannel: message.channel.id,
    selfDeafen: true,
    volume: 80,
  });

  player.connect();

  const result = await player.search(query, message.author);
  const track = result.tracks[0];

  if (!track) {
    return message.reply("No results found.");
  }

  player.enqueue(track);

  if (!player.playing && !player.paused) {
    await player.play();
  }

  return message.reply(`Queued: ${track.title}`);
}

Search Sources

await manager.search("lofi hip hop");

await manager.search({
  query: "never gonna give you up",
  source: "youtube",
});

await manager.search({
  query: "artist name - song title",
  source: "soundcloud",
});

Built-in source aliases:

• youtube music
• youtube
• soundcloud
• deezer
• spotify

Queue Controls

const player = manager.get(guildId);

player.skip();              // skip current track
player.skip(3);             // skip current track and 2 queued tracks
player.skipTo(4);           // jump to queue index 4
player.moveQueue(5, 1);     // move a queued track

const removed = player.removeDuplicates();
console.log(`Removed ${removed} duplicate tracks`);

player.queue.shuffle();
player.queue.clear();
player.queue.clearHistory();

You can also add tracks at a specific queue position:

player.enqueue(track, 0); // add as next track

Player Controls

player.pause(true);
player.pause(false);

player.setVolume(120);
player.seek(60_000);

player.setTrackRepeat(true);
player.setQueueRepeat(true);
player.setDynamicRepeat(true, 30_000);

player.setAutoplay(true);
player.stop();
player.destroy();

Filters

player.filters.bassBoost();
player.filters.nightcore();
player.filters.vaporwave();
player.filters.eightD();

await player.filters.clearFilters();

Custom filters:

player.filters.setTimescale({
  speed: 1.05,
  pitch: 1.1,
  rate: 1.0,
});

player.filters.setEqualizer([
  { band: 0, gain: 0.15 },
  { band: 1, gain: 0.10 },
]);

Events

manager.on("nodeConnect", (node) => {
  console.log(`Node connected: ${node.options.identifier}`);
});

manager.on("nodeDisconnect", (node, reason) => {
  console.log(`Node disconnected: ${node.options.identifier}`, reason);
});

manager.on("nodeError", (node, error) => {
  console.error(`Node error: ${node.options.identifier}`, error);
});

manager.on("nodeResume", (node, players) => {
  console.log(`Node resumed ${players} players`);
});

manager.on("trackStart", (player, track) => {
  console.log(`Now playing in ${player.guild}: ${track.title}`);
});

manager.on("queueEnd", (player) => {
  console.log(`Queue ended in ${player.guild}`);
});

manager.on("queueUpdate", (player) => {
  console.log(`Queue changed: ${player.queue.length} tracks waiting`);
});

manager.on("playerPause", (player, paused) => {
  console.log(`${player.guild} paused: ${paused}`);
});

manager.on("playerVolumeChange", (player, volume) => {
  console.log(`${player.guild} volume: ${volume}`);
});

manager.on("filtersError", (player, error) => {
  console.error(`Filter update failed in ${player.guild}`, error);
});

Multiple Nodes and Failover

KawaLink sorts healthy nodes by playback load, Lavalink CPU load, and frame penalties. When a node disconnects and autoMove is enabled, players are moved to the best available playback node.

const manager = new Manager({
  nodes: [
    { host: "lavalink-1.example.com", identifier: "primary", password: "pass" },
    { host: "lavalink-2.example.com", identifier: "backup", password: "pass" },
  ],
  autoMove: true,
  send: sendPayload,
});

You can inspect node health:

for (const node of manager.idealNodes.values()) {
  console.log(node.options.identifier, {
    connected: node.connected,
    unhealthy: node.unhealthy,
    penalty: node.penalty,
    players: node.stats.playingPlayers,
  });
}

Resume

Enable autoResume to store player state in the local datastore and reconnect players after a Lavalink session resumes.

const manager = new Manager({
  autoResume: true,
  nodes: [{ host: "127.0.0.1", password: "youshallnotpass" }],
  send: sendPayload,
});

KawaLink stores:

• voice channel
• text channel
• volume
• current track
• queue
• custom player data

Common Command Example

client.on("messageCreate", async (message) => {
  if (message.author.bot || !message.guild) return;

  const [command, ...args] = message.content.trim().split(/\s+/);
  const query = args.join(" ");

  if (command === "!play") {
    return play(message, query);
  }

  const player = message.client.manager.get(message.guild.id);
  if (!player) return;

  if (command === "!skip") player.skip();
  if (command === "!pause") player.pause(true);
  if (command === "!resume") player.pause(false);
  if (command === "!stop") player.destroy();
  if (command === "!shuffle") {
    player.queue.shuffle();
    message.reply("Queue shuffled.");
  }
});

Notes

• Manager#init(clientId) must be called after the Discord client is ready.
• Always forward Discord raw voice packets with client.on("raw", packet => manager.updateVoiceState(packet)).
• Use player.enqueue(track) when adding tracks so queueUpdate and resume data stay in sync.
• For production bots, configure more than one Lavalink node and keep autoMove enabled.

Credits

KawaLink is inspired by and forked from work in the Lavalink ecosystem, including Sakulink, Magmastream, Erela.JS, and Moonlink.JS.