Lavalink is a standalone audio sending node based on Lavaplayer and JDA-Audio. Allows for sending audio without it ever reaching any of your shards. In human terms, it is a server that queries sources for our music requests. Public Lavalink servers do exist, but they are not documented here. Please use the modern technologies available (such as https://google.com) to search for one if you intend to use a public server.
If you are not interested in using the music addon, Lavalink is not necessary. Remove music.js from your /addons/
directory and restart your bot. Otherwise, please follow the steps you will find below on how to obtain, set up and secure Lavalink.
(Edit on 30/07/2022: Lavalink team seems to have fixed their CI, so prebuilt official binaries can be obtained from the releases page, instead of following the steps below. "Building steps" have been kept for archiving purposes. This does not mean that building from source does not work, but obtaining prebuilt binaries is more convenient for the end user. The choice is yours.)
There are currently no reliable sources distributing up-to-date Lavalink binaries, which is why we would like to build the jar ourselves. The process has been tested with OpenJDK 18, but officially Zulu 13 seems to be encouraged by the developers. The building steps may differ slightly based on your operating system. This guide assumes you have some degree of respect to your device and use Linux. After ensuring Java is installed on your system, follow the steps below to build Lavalink
git clone -b dev https://github.com/freyacodes/Lavalink.git
cd Lavalink && ./gradlew build
Do note that you may alternatively use gradle (instead of gradlew, the gradle wrapper) but that is discouraged as it may cause gradle version related issues.
And you are done. Should you need to update, simply run git pull
to update tthe cloned folder and build with gradlew.
Lavalink.jar we have built from source wil be available in Lavalink/LavalinkServer/build/libs
as Lavalink.jar. Do not mistake it for the build artifact that has "snapshot" in it's name.
Java 11 LTS and above is required to run Lavalink, Java 13 is recommended by the Lavalink team.
Move Lavalink.jar to a folder of your choice, in my case $HOME/Lavalink, and start it with
java -jar Lavalink.jar
Alternative runtime flags may be used to customize the JVM, passing flags like -Djdk.tls.client.protocols=TLSv1.1,TLSv1.2
and -Xmx4G
may even be useful to improve the performance and security of your Lavalink server.
Example:
java -Djdk.tls.client.protocols=TLSv1.1,TLSv1.2 -Xmx4G -jar Lavalink.jar
Configuration for the Lavalink server is optional, but for reasons provided below; should be exercised. An example configuration can be found here. Application.yml is expected by Lavalink.jar to be in the same directory as the jar, but default options will be used if it is not found.
Lavalink is an open-source and relatively actively maintained program, which makes it safer than some out there but we must remember to exercise common sense and secure our Lavalink application to the outside world.
Do note that enabling SSL for Lavalink does not help with improving security, and should be avodied as Corebot does not handle SSL connections to Lavalink servers.
Lavalink's default password is not randomized as you would expect from a safe application, and is the same for everyone. Thus, a malicious user may connect to your server, or overflow it with thousands of requests to damage you. This is also known as DDoS attack. To get around this, we change the default password to something strong. If you set it to 1234, you will know pain.
You should limit your connections to Localhost (127.0.0.1), or if your bot and Lavalink are on different servers; to the IP of the server Corebot is on. Change the address: 0.0.0.0
value to ensure not everyone can connect to your server. Unless, of course, your are hosting a public node.
Ratelimiting is a simple security layer that if your node is somehow compromised, the attacker cannot launch a DoS or DDoS attack to you. It is important to alter the ratelimit block in application.yml
to your needs. Remove the #s at the beginning of each line to uncomment settings.
#ratelimit:
#ipBlocks: ["1.0.0.0/8", "..."] # list of ip blocks
#excludedIps: ["...", "..."] # ips which should be explicit excluded from usage by lavalink
#strategy: "RotateOnBan" # RotateOnBan | LoadBalance | NanoSwitch | RotatingNanoSwitch
#searchTriggersFail: true # Whether a search 429 should trigger marking the ip as failing
#retryLimit: -1 # -1 = use default lavaplayer value | 0 = infinity | >0 = retry will happen this numbers times
Squid is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Fortunately for us, it also caches content and acts like a security layer.
If you are an advanced user, you may consider setting up SquidProxy inside a docker container, allowing Lavalink to use the proxy by altering the settings. According to the config, it is "useful for blocking bad-actors from ip-grabbing your music node and attacking it, this way only the http proxy will be attacked".
Lavalink is a seperate application that queries our music sources upon request, so Corebot must be configured to connect to the correct Lavalink instance in order to be able to search for music.
(VPS 1)---------------+
| | (VPS 2)-------------+
| Corebot | == Search request ==> | |
| 127.0.0.1 | <== Search results == | Lavalink |
| | | 127.0.0.2:2223 |
+---------------------+ +-------------------+
The diagram above demonstrates the protocol behind Lavalink in simplest terms possible. For demonstration purposes, we assume Lavalink and Corebot are on different machines.
You will first want to have the credientals to a Lavalink server you want to connect to. If you are self-hosting Lavalink, configure your application.yml
as instructed above and use the credientals you have set. You are primarily interested in host:
, port:
and password:
values.
If you are using a public Lavalink instance, then use the credientals they provide. Public instances are not listed here as they can become outdated with a single breaking Lavalink change. And because Google exists.
Insert previously obtained Lavalink credientals in /path/to/Corebot/configs/addons/music_config.yml
. A fairly straightforward process.
Moving on from the diagram above, assuming our Lavalink instance is at http://127.0.0.2:2223 (not a real host, do not try) with the password SuperSecureEpicPasword123!
you would fill out the configuration as follows:
Settings:
Lavalink:
Node:
host: http://127.0.0.2 # could also be a domain name, such as http://lavalink.domain.com
port: 2223 # the port your service is running on, configured in Lavalink application.yml
password: "SuperSecureEpicPasword123!" # the password for your Lavalink instance, make it strong.
And that's it. If you are selfhosting Lavalink, monitor your Lavalink logs. You will notice Corebot (127.0.0.1 in our example) has made a connection and that our Lavalink client (127.0.0.2 in our example) has responded. If you see something like "Connection refused", double check your credientals and Corebot error logs.
For public instances, we will not provide support. You are (mostly) on your own as we do not have any control over public Lavalink instances. Any support will be provided on a best effort basis.
As you might have noticed from the config, Corebot also supports Spotify to play music. But before it can play tracks from Spotify, a dev application must be created on Spotify Developer Portal.
Simply visit https://developer.spotify.com/dashboard, create a new application and then enter your Client ID
and Client Secret
. Enable Spotify support (change Enabled: false
to Enabled: true
) and enjoy playing music from Spotify.
Spotify:
Enabled: false # boolean, change to true in order to enable
ClientID: PUT-CLIENT-ID-HERE # Client ID from the developer portal
ClientSecret: PUT-CLIENT-SECRET-HERE # Client Secret from the developer portal
WIP Section, each (known) error code will be attempted to be documented here upon proper testing. Until then, please see the "Getting Support" section below.
SyntaxError: Unexpected token in JSON at position 0
This is a known issue and users that are receiving this error are advised to follow the steps relevant documentation page depending on their ecosystem.
Lavalink may be complicating and the official documentation for Lavalink, well, does not exist. Should you require assistance on how to set up Lavalink, and the documentation above appears insufficient; please open a ticket on our Discord Server and state that you need assistance with setting up Lavalink even after reading the documentation.
If you have successfully set up Lavalink, but are getting errors; please open a ticket with both Lavalink and Corebot logs included. Thanks!