@karumusic/erela

Erela.js ·

An easy-to-use Lavalink client for NodeJS.

Documentation

Note: Some links do not work, I'll fix them when I can. The sidebar menu has the links that are broken.

You can find the documentation at http://projects.warhammer.codes/erelajs (this link does work)

Installation

Prerequisites

• Java

• Lavalink

Note: Java v11 or newer is required to run the Lavalink.jar.

npm install erela.js

Getting Started

• Create an application.yml file in your working directory and copy the example into the created file and edit it with your configuration.

• Run the jar file by running java -jar Lavalink.jar in a Terminal window.

Example usage

Note: Discord.js is used in this example, but it does work with other libraries with the same example but with your library functions.

// To install Discord.JS and Erela.JS, run:
// npm install discord.js erela.js
const { Client } = require("discord.js");
const { Manager, Player } = require("erela.js");

// Initialize the Discord.JS Client.
const client = new Client();

// Initiate the Manager with some options and listen to some events.
client.manager = new Manager({
    // Pass an array of node. Note: You do not need to pass any if you are using the default values (ones shown below).
    nodes: [{
        host: "localhost",
        port: 2333,
        password: "youshallnotpass",
    }],
    // Auto plays tracks after one ends, defaults to "false".
    autoPlay: true,
    // A send method to send data to the Discord WebSocket using your library.
    // Getting the shard for the guild and sending the data to the WebSocket.
    send(id, payload) {
        const guild = client.guilds.cache.get(id);
        if (guild) guild.shard.send(payload);
    }
})
.on("nodeConnect", node => console.log("New node connected"))
.on("nodeError", (node, error) => console.log(`Node error: ${error.message}`))
.on("trackStart", (player, track) => {
    player.textChannel.send(`Now playing: ${track.title}`)
})
.on("queueEnd", player => {
    player.textChannel.send("Queue has ended.");
    player.destroy();
})
// You must handle moves by yourself, by default Erela.JS will not change the voice channel.
.on("playerMove", (player, currentChannel, newChannel) => {
    // Note: newChannel will always be a string, if you pass the channel object you will need to get the cached channel.
    player.voiceChannel = client.channels.cache.get(newChannel);
});

// Ready event fires when the Discord.JS client is ready.
// Use EventEmitter#once() so it only fires once.
client.once("ready", () => {
    console.log("I am ready!")
    // Initiate the manager.
    client.manager.init(client.user.id);
});

// Here we send voice data to lavalink whenever the bot joins a voice channel to play audio in the channel.
client.on("raw", d => client.manager.updateVoiceState(d));

client.on("message", async message => {
    if (message.content.startsWith("!play")) {
        // Retrieves tracks with your query and the requester of the track(s).
        // Note: This retrieves tracks from youtube by default, to get from other sources you must enable them in application.yml and provide a link for the source.
        // Note: If you want to "search" with you must provide an object with a "query" property being the query to use, and "source" being one of "youtube", "soundcloud".
        // Note: This example only works for searching tracks using a query, such as "Rick Astley - Never Gonna Give You Up".
        // Returns a SearchResult.
        const res = await client.manager.search(message.content.slice(6), message.author);

        // Create a new player. This will return the player if it already exists.
        const player = client.manager.create({
            guild: message.guild,
            voiceChannel: message.member.voice.channel,
            textChannel: message.channel,
        });

        // Connect to the voice channel.
        player.connect();

        // Adds the first track to the queue.
        player.queue.add(res.tracks[0]);
        message.channel.send(`Enqueuing track ${res.tracks[0].title}.`);

        // Plays the player (plays the first track in the queue).
        // The if statement is needed else it will play the current track again
        if (!player.playing && !player.paused && !player.queue.length) player.play();
    }
});

client.login("your token");

Extending

Erela.JS can expand on its functionality by extending its classes. Note: This should only used if you are adding your own functions.

const { Structure } = require("erela.js");

// Use the extend method to extend the class.
Structure.extend("Queue", Queue => class extends Queue {
    save() {
        somehowSaveQueue();
    }
});

// Usage:
const player = somehowGetPlayer();
player.queue.save();

Plugins

Erela.JS can expand on its functionality with plugins. Note: This should only be used if you want to use others functions.

// Only for demonstration.
const { Manager } = require("erela.js");
const SaveQueue = require("erela.js-save-queue");

const manager = new Manager({
    plugins: [ new SaveQueue({ max: 10 }) ],
})

// Usage.
const player = somehowGetPlayer();
player.queue.save();

Creating your own plugin

const { Structure, Plugin } = require('erela.js');

Structure.extend("Queue", Queue => class extends Queue {
    save() {
        somehowSaveQueue();
    }
});

module.exports = class MyQueuePlugin extends Plugin {
    // Use the constructor to pass values to the plugin.
    constructor(options) {
        // Able to use "max" as a option.
        this.options = options;
    }

    load(manager) {}
}

Contributors

👤 WarHammer414

• Author
• Website: https://warhammer.codes/
• Github: @WarHammer414

👤 Anish Shobith

• Contributor
• Github: @Anish-Shobith

👤 Chroventer

• Contributor
• Github: @chroventer