lavaclient

A lightweight and powerful lavalink v4 client for NodeJs.

• Easy-to-use: lavaclient has a neat and user-friendly promise-based api.
• Performant: designed to be small and lightweight, it's a great choice for any project.
• Library Agnostic: lavaclient doesn't require you to use a specific discord library. Use anything you want!

Installation

Node.js LTS (or higher) is required to use lavaclient.

Stable

(p)npm install lavaclient
// or
yarn add lavaclient

Beta (may be outdated)

(p)npm install lavaclient@next
// or
yarn add lavaclient@next

Deno

Take a look at lavadeno :)

Usage

Setup

import { Cluster, Node, type NodeOptions } from "lavaclient";

const info: NodeOptions["info"] = {
    host: "127.0.0.1",
    port: 2333,
    auth: "youshallnotpass"
}

// If you only have a single lavalink node, use the `Node` class.
const lavaclient = new Node({
    info,
    ws: {
        // The client name to use, defaults to some very long string lol.
        clientName: "my very cool bot",
        // Resuming is enabled by default, but you can disable it if you want.
        // The timeout defaults to 1 minute.
        resuming: false | { timeout: 30_000 },
        // The reconnecting options, this is enabled by default.
        // If you want to disable it, set it to `false`.
        reconnecting: {
            // The number of tries to reconnect before giving up, defaults to Infinity.
            tries: 3,
            // The delay in milliseconds between each attempt, defaults to 5 seconds.
            // This can either be a function that accepts the current try and returns the delay, or a static delay.
            delay: (attempt) => attempt * 1_000
        }
    },
    rest: {
        // Whether lavalink should return stack traces for requests that ran into exceptions.
        enableTrace: true,
        // The fetch implementation to use, defaults to node.js built-in fetch.
        fetch: fetch,
        // The user agent to use for requests, defaults to some very long string lol.
        userAgent: "my very cool bot (v1.0.0, <user id>)"
    },
    discord: {
        sendGatewayCommand: (id, payload) => // Send the payload to the Discord Gateway.
    }
});

// If you have multiple lavalink nodes, use the `Cluster` class.
const lavaclient = new Cluster({
    // An array of lavalink node options, this supports the same thing as the `Node` class.
    nodes: [{ info }],
    discord: {
        sendGatewayCommand: (id, payload) => // Send the payload to the Discord Gateway.
    }
});

// Connect to the lavalink node(s).
await lavaclient.connect("1077037369850605599");

Using Players

Creation

const player = lavaclient.players.create("<guild id>");

Destruction

// Passing `true` as the 2nd arg will skip checking if the player exists locally.
await lavaclient.players.destroy("<guild id>", true);

If you want a player to leave the voice channel, you can do this first:

player.voice.disconnect();

Playing Tracks

import { S, getUserData } from "lavaclient";

const results = await lavaclient.api.loadTracks("ytsearch:never gonna give you up");
if (results.loadType === "search") {
    const track = results.data[0];

    // You can pass a track object directly.
    await player.play(track);

    // If you want to pass some user data to the track, you can do this:
    await player.play({
        encoded: track.encoded,
        userData: { requesterId: interaction.user.id },
    });

    // There's also an option to pass a user data schema for type-safe user data values.
    const schema = S.struct({
        requesterId: S.string,
    });

    await player.play({
        encoded: track.encoded,
        userData: { requesterId: interaction.user.id },
        userDataSchema: schema,
    });

    getUserData(player.track, schema); // { requesterId: string }
}

Misc

player.resume()
player.pause()

player.setFilters({ volume: 0.5 });
player.setFilters("volume", 0.5);

player.seek(1000);
player.stop();

// A little experimental but you can transfer a player to a different node.
player.transfer(lavaclient2)

Handling Voice Updates

Lavalink requires you to forward voice server & state updates to it so that it can connect to the voice channel.

Here's a discord.js v14 example:

import { Client, GatewayDispatchEvents } from "discord.js";

const client = new Client({ ... });

client.ws.on(GatewayDispatchEvents.VoiceStateUpdate,  (u) => lavaclient.players.handleVoiceUpdate(u));
client.ws.on(GatewayDispatchEvents.VoiceServerUpdate, (u) => lavaclient.players.handleVoiceUpdate(u));

Support Server