LavaClient

Powerful and easy-to-use Lavalink implementation for JDA.

Installation

Warning: Minimal Java version: 14.

We're using own Maven repository for distributing our project. Replace %VERSION in the examples below with the latest version: .

Gradle

repositories {
    maven { url = uri("https://m2.pelfox.dev/releases") }
}

dependencies {
    implementation 'team.honeycombs.lavaclient:LavaClient:%VERSION%'
}

Maven

<repositories>
    <repository>
        <id>pelfox-releases</id>
        <name>Pelfox's Maven Repository</name>
        <url>https://m2.pelfox.dev/releases</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>team.honeycombs.lavaclient</groupId>
        <artifactId>LavaClient</artifactId>
        <version>%VERSION%</version>
    </dependency>
</dependencies>

For LavaClient to work properly, you need to install JDA as a dependency of your project. You will also probably want to set the configuration for the logger. You can read more about how to configure the logger on the JDA wiki page.

Note: We use the same logging framework as JDA, so the JDA configuration will work for LavaClient as well.

Setting up the Lavalink

In order to start using Lavalink via LavaClient, you need to install and configure a Lavalink server. To do that, download Lavalink from here. You need to download the version that has the green indicator "latest".

After that, you will also need to put the application.yml file in the same folder as Lavalink.jar. You can find a sample file here.

Adding a node

First, you need to create an instance of class LavalinkClient. To do this, you need to call the static create method in the LavalinkClient interface. It takes one argument - your bot's user ID. This client should be created only once and should be used in all shards. An example of how you can do this:

LavalinkClient client = LavalinkClient.create(/* your bot's user ID */);

Once you have an instance of class LavaClient, you can start creating a new Lavalink node. To do this, you just need to call the createNodeBuilder method inside an instance of the LavalinkClient class. It will automatically create a new builder for your node. After this, you'll need to call setHost, setPassword and setPort methods necessarily. It's not required, but you can also set a resume timeout and should the node enable resuming. build method will automatically start the startup process, and it'll add node to the list of all other client's nodes. Here's an example:

LavalinkNode node = client.createNodeBuilder()
                    .setHost(/* Lavalink's server host */)
                    .setPort(/* Lavalink's server port */)
                    .setPassword(/* Lavalink's server password */)
                    .build();

That's it. Note that this method will return an instance of class LavalinkNode. It also won't create a new node if an identical node already exists.

Creating a player

In order to change the volume, play tracks or stop playback, you need to get an instance of class LavalinkPlayer, which is the player. Each player is unique for each individual guild. To create a player instance, you need to call the createPlayer method on LavalinkNode class and give the ID of the guild you want to make a player for as argument. Here's an example:

LavalinkPlayer player = node.createPlayer(/* assigned guild ID */);

That's it. Note that this method will return an instance of class LavalinkPlayer. It also won't create a new player if a player for this guild already exists.

Playing a track

In order to play a track, you first need to find information about it through the Lavalink server. This is done with an instance of class LavalinkPlayer, via method searchTrack. You can specify some specific prefix before the search request, if required.

TrackLoadResult trackLoadResult = player.searchTrack(/* search query */);

It will return an instance of class TrackLoadResult. From this instance you can understand what kind of result was found (a playlist, or just a track), and also get an encoded version of the found track or get information about the playlist.

Once you have an instance of class TrackLoadResult, you need to check the search result. Just check the load type via the getLoadType method. If it returns LoadType.TRACK_LOADED or TRACK_LOADED.PLAYLIST_LOADED, then it was successful. In both cases, you need to get an instance of class AudioTrack (which is the track you want to play) to start playing the track. Here's an example:

if (trackLoadResult.equals(LoadType.TRACK_LOADED) || trackLoadResult.equals(LoadType.PLAYLIST_LOADED)) {
    player.playTrack(trackLoadResult.getTracks().get(0));
}

The example above selects the first available track and starts playing it.

Event System

Our library has an event system. They (events) can be used for different purposes. We'll show you how to set up listener for an event, and then you can use them for your own purposes. The event system applies to all classes that are marked as Eventable (i.e. LavalinkClient, LavalinkNode, LavalinkPlayer).

Registering an inline listener

/* Class that marked as Eventable */.registerListener(/* Event type class */.class, e -> {
    // here you go!
});

Registering a separate class with listener

public class YourListener extends EventListener</* Event type class */> {
    @Override
    public @NotNull Class<T> getType() {
        return /* Event type class */;
    }

    @Override
    public void execute(@NotNull T event) {
        // here you go!
    }
}

Want more?

Perhaps you should look in the module with examples, or ask for help in project's discussions page.

About contribution

We have a couple of documents that are mandatory before you want to contribute to our project: Code of Conduct and Contribution Guidelines. Thank you to everyone who shows interest in the project!

About versioning

We use a standard for versioning our library called Semantic Versioning. You can read more about it here.

HoneycombsTeam/LavaClient