This configuration doesn't happen in a specific configuration file, it's just a general guide.
Key words:
Boolean: A true or false switch
String: An assortment of "text" or "numbers" like this
Numbers: Just numbers!
Array: Strings or Numbers["in", "a", "pattern", "like", "this"]
Welcome to the Music Setup Tutorial!
Here we'll go over the Music Plugin setup in its entirety, with brief (or not so brief!) explanations and descriptions on things.
I made sure to separate everything the best possible so that the sidebar has a quick reference to what you're looking for.
If you're not interested in Self-Hosting Lavalink, this Tutorial isn't for you! Check out our Music Master Tutorial instead!
Feedback is welcome!
If you think something is missing, or needs a bit more work, then make sure to leave us a note at our support server!
Where do I start?
The basics on Lavalink!
What is Lavalink?
From Lavalink's Github page:
Lavalink is a standalone audio sending node based on Lavaplayer and Koe. Allows for sending audio without it ever reaching any of your shards.
Basically, it's an audio streaming system that allows you to stream audio from one place to another. It's a very popular method used by hundreds of bots, both private and public, is expandable and modifiable to suit your needs.
Why does it matter?
Well, without it, you couldn't get music streamed to your bot! It's pretty simple!
How do I get a Lavalink?
It's a silly way of asking that question, but it's entirely valid, there's multiple ways of getting Lavalink working for you! Like we'll explain next to you!
Options for Lavalink Hosting!
Buy Lavalink Hosting from us!
It's simple to get this! Just purchase the addon directly from our BBB store!
Do I have to do anything special for it?
Nope. Just...
Purchase the addon
Use /claim in our Support Server
Restart Athena
Done!
It really doesn't get easier than that! No need to find a hosting system, no need to deal with being IP banned off your hosting later on, etc.
And if I don't purchase the addon?
No hard feelings! Everyone's situation is different, and we won't make people buy it if they don't want to or can't do it. It's just recommended!
If you wanted to get Lavalink, without having to pay for the addon, you can always look up a public Lavalink server!
Where do I find one?
There's a few places to look for them, for example:
Well, the other real option at the end of the day is hosting your own Lavalink instance!
How do I do that?
We'll run a course very quickly about it, but it might be outdated overtime, given that Lavalink tutorials aren't my thing!
Self-Hosting Lavalink
This is an optional tutorial!
Keep in mind, we want to make things as easy as possible for people, so we encourage alternative methods of getting Lavalink working, but this is here for the sake of transparency and fairness to customers.
What do I do first?
Looking for Hosting
Well, you want to find a hosting service that can natively handle Lavalink, or at minimum, handle Java binaries. A place I can recommend that does this natively is SparkedHost (Affiliate Link, for transparency). They've been fair to me and they've actually got pretty good prices. Now this isn't a binding agreement you're reading, so you don't have to join with my link! You can always look up more sources that could handle it!
Just make sure that whatever hosting you do find has these minimum specs!
1 Core (2 is preferred)
1 GB of RAM
A decent internet connection (the higher the better really, but usually aiming for 100Mbps is okay)
Java 17 LTS or newer required. (we recommend running the latest LTS version or newer)
OpenJDK or Zulu running on Linux AMD64 is officially supported.
Best case scenario, a host that supports IPv6 Rotation, or has dedicated IP slots
Potentially Blocked Hosts
I cannot recommend these for Lavalink, given they are very likely IP banned by YouTube's/Spotify's API's, preventing connections from happening. This list may expand based on word of mouth or proven testing reported by customers/individuals online.
OVHcloud
Found a good host, now what?
Congrats! Getting a good host is an awesome step, because it means you're able to stream audio with as little interruption and issues as possible. Now comes the time to install Lavalink.
Getting Started
If you are on a Pterodactyl Panel
Check and see if you have a Lavalink Egg first! Alternatively, look for a Java 17+ Egg! Either one will get you to where you need since Lavalink requires Java 17 or higher anyway.
If you are on a self-owned machine
I cannot recommend running it locally. There's just too much that can go wrong or it won't be the most optimal experience. At minimum, attempt to get it on a VPS system that has Docker/Systemd installed, so you can keep the process alive after you close the console window. Plus, you'll have better chances of a more reliable connection and protection against power outages, internet failures, etc.
Download the Lavalink.jar file
You want to download something from the Latest section directly from Lavalink's Github! This gives you the best chance to find the most up to date solution that has much higher chances of working properly. Just drop it into the (hopefully) empty root folder!
Run the Lavalink.jar file
Time to run the file! For that, you run it with java -jar Lavalink.jar
Yep! That's it! Well, in terms of running it!
Wait for Lavalink to Launch
Lavalink will take a moment to start up, and it generates all the files it needs to get ready. If everything went well, it will present you with a Lavalink is ready to accept connections message in the console
Is that it?
Technically, yes, you could go on your merry way just like that, but things might not all fully work or be available. So that's why these next steps come into play...
Configuring Lavalink
So you got this far, nice! Now we have to configure Lavalink to work at its best. And we'll start now.
The Defaults
That's Lavalinks' config file. That's where you can configure (or tamper with most likely) Lavalinks' settings. I will paste the default configuration for your sanity here.
application.yml
server:# REST and WS serverport:2333address:0.0.0.0http2:enabled:false# Whether to enable HTTP/2 supportplugins:# name: # Name of the plugin# some_key: some_value # Some key-value pair for the plugin# another_key: another_valuelavalink:plugins:# - dependency: "com.github.example:example-plugin:1.0.0" # required, the coordinates of your plugin# repository: "https://maven.example.com/releases" # optional, defaults to the Lavalink releases repository by default# snapshot: false # optional, defaults to false, used to tell Lavalink to use the snapshot repository instead of the release repository# pluginsDir: "./plugins" # optional, defaults to "./plugins"# defaultPluginRepository: "https://maven.lavalink.dev/releases" # optional, defaults to the Lavalink release repository# defaultPluginSnapshotRepository: "https://maven.lavalink.dev/snapshots" # optional, defaults to the Lavalink snapshot repositoryserver:password:"youshallnotpass"sources:# The default Youtube source is now deprecated and won't receive further updates. Please use https://github.com/lavalink-devs/youtube-source#plugin instead.youtube:falsebandcamp:truesoundcloud:truetwitch:truevimeo:truenico:truehttp:true# warning: keeping HTTP enabled without a proxy configured could expose your server's IP address.local:falsefilters:# All filters are enabled by defaultvolume:trueequalizer:truekaraoke:truetimescale:truetremolo:truevibrato:truedistortion:truerotation:truechannelMix:truelowPass:truebufferDurationMs:400# The duration of the NAS buffer. Higher values fare better against longer GC pauses. Duration <= 0 to disable JDA-NAS. Minimum of 40ms, lower values may introduce pauses.frameBufferDurationMs:5000# How many milliseconds of audio to keep bufferedopusEncodingQuality:10# Opus encoder quality. Valid values range from 0 to 10, where 10 is best quality but is the most expensive on the CPU.resamplingQuality:LOW# Quality of resampling operations. Valid values are LOW, MEDIUM and HIGH, where HIGH uses the most CPU.trackStuckThresholdMs:10000# The threshold for how long a track can be stuck. A track is stuck if does not return any audio data.useSeekGhosting:true# Seek ghosting is the effect where whilst a seek is in progress, the audio buffer is read from until empty, or until seek is ready.youtubePlaylistLoadLimit:6# Number of pages at 100 eachplayerUpdateInterval:5# How frequently to send player updates to clients, in secondsyoutubeSearchEnabled:truesoundcloudSearchEnabled:truegc-warnings:true#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#youtubeConfig: # Required for avoiding all age restrictions by YouTube, some restricted videos still can be played without.#email: "" # Email of Google account#password: "" # Password of Google account#httpConfig: # Useful for blocking bad-actors from ip-grabbing your music node and attacking it, this way only the http proxy will be attacked#proxyHost: "localhost" # Hostname of the proxy, (ip or domain)#proxyPort: 3128 # Proxy port, 3128 is the default for squidProxy#proxyUser: "" # Optional user for basic authentication fields, leave blank if you don't use basic auth#proxyPassword: "" # Password for basic authenticationmetrics:prometheus:enabled:falseendpoint:/metricssentry:dsn:""environment:""# tags:# some_key: some_value# another_key: another_valuelogging:file:path:./logs/level:root:INFOlavalink:INFOrequest:enabled:trueincludeClientInfo:trueincludeHeaders:falseincludeQueryString:trueincludePayload:truemaxPayloadLength:10000logback:rollingpolicy:max-file-size:1GBmax-history:30
This file gives you the basic essentials for running Lavalink and configuring it to some degree. I am not an expert on configuring Lavalink either, but I can at least try to describe what each option does!
Any commented code does not apply to the actual functionality!
Commented code is hidden from execution by using #'s
Rest and WS Server
This handles whatever backend/frontend you may have for Lavalink if you're into that. Dashboards perhaps? Controlling music remotely? The world (read: this section) is your oyster.
server:# REST and WS serverport:2333address:0.0.0.0http2:enabled:false# Whether to enable HTTP/2 support
Plugins
This handles any kind of plugins you may have. Sponsorblock, Lyrics, and so on. You can customize these with whatever plugins you may find by "calling" the folder directly, or by using direct links to things like private repositories, GitHub, etc!
plugins:# name: # Name of the plugin# some_key: some_value # Some key-value pair for the plugin# another_key: another_value
or...
lavalink:plugins:# - dependency: "com.github.example:example-plugin:1.0.0" # required, the coordinates of your plugin# repository: "https://maven.example.com/releases" # optional, defaults to the Lavalink releases repository by default# snapshot: false # optional, defaults to false, used to tell Lavalink to use the snapshot repository instead of the release repository# pluginsDir: "./plugins" # optional, defaults to "./plugins"# defaultPluginRepository: "https://maven.lavalink.dev/releases" # optional, defaults to the Lavalink release repository# defaultPluginSnapshotRepository: "https://maven.lavalink.dev/snapshots" # optional, defaults to the Lavalink snapshot repository
Password
Self-explanatory really. This is the password you would need to use on your bot to connect to the Lavalink Host.
server:password:"youshallnotpass"
Sources
This is where your music would be playing from, as long as the bot supports it. In this case, Athena only supports YouTube and Spotify, but the config can still be useful to have for futureproofing.
sources:# The default Youtube source is now deprecated and won't receive further updates. Please use https://github.com/lavalink-devs/youtube-source#plugin instead.youtube:falsebandcamp:truesoundcloud:truetwitch:truevimeo:truenico:truehttp:true# warning: keeping HTTP enabled without a proxy configured could expose your server's IP address.local:false
Filters
Given that Lavalink allows you to tamper with how music sounds, these are the switches for that. Athena supports these just fine!
filters:# All filters are enabled by defaultvolume:trueequalizer:truekaraoke:truetimescale:truetremolo:truevibrato:truedistortion:truerotation:truechannelMix:truelowPass:true
Lightning Round
We'll shoot through all these real quick.
bufferDurationMs:400# The duration of the NAS buffer. Higher values fare better against longer GC pauses. Duration <= 0 to disable JDA-NAS. Minimum of 40ms, lower values may introduce pauses.frameBufferDurationMs:5000# How many milliseconds of audio to keep bufferedopusEncodingQuality:10# Opus encoder quality. Valid values range from 0 to 10, where 10 is best quality but is the most expensive on the CPU.resamplingQuality:LOW# Quality of resampling operations. Valid values are LOW, MEDIUM and HIGH, where HIGH uses the most CPU.trackStuckThresholdMs:10000# The threshold for how long a track can be stuck. A track is stuck if does not return any audio data.useSeekGhosting:true# Seek ghosting is the effect where whilst a seek is in progress, the audio buffer is read from until empty, or until seek is ready.youtubePlaylistLoadLimit:6# Number of pages at 100 eachplayerUpdateInterval:5# How frequently to send player updates to clients, in secondsyoutubeSearchEnabled:truesoundcloudSearchEnabled:truegc-warnings:true
bufferDurationMs
The higher the number here, the better the music player handles being paused. The lower the number, the less capable it is and the more prone to "breaking" it is.
frameBufferDurationMs
The amount of audio to keep buffered. The longer the buffer, the less stutter overall since more is loaded beforehand.
opusEncodingQuality
How much quality the audio stream will have when encoded in Opus (your usual audio streams), since YouTube loves encoding with it, and it just so happens Discord likes that encoding too, so yeah! The higher the number, the higher the quality is, but the more power it requires on your CPU to handle.
resamplingQuality
If things need to be resampled into an audio stream Discord supports, this is the process for that. Setting it to HIGH causes the most CPU draw.
trackStuckThresholdMs
When and if songs get stuck, Lavalink gets jammed up. So instead, they handle it in a way in which if an audio track isn't transmitting data, it just culls it and stops it from continuing. Nifty stuff really.
useSeekGhosting
Seeking is supported on all non-stream formats and sources. When a seek is performed on a playing track, the previously buffered audio samples will be provided until the seek is finished (this is configurable). LavaPlayer handles it by remembering the position where it was requested to seek to, jumping to the highest position which is not after that and then ignoring the audio until the actual position that was requested. TL;DR, seeking is pretty fast and accurate down to the second for the most part.
youtubePlaylistLoadLimit
The maximum amount of playlists that can be loaded at a time, in HUNDREDS per each one. Eg, if you set it to 2, you can handle up to 200 playlists at one time. Obviously, you'll never hit that amount. I'd be concerned otherwise.
playerUpdateInterval
How quickly updates are sent to players. It's a bit of a 'heartbeat' so to speak, letting players know that 'Hey! I'm alive! I'm doing x, y, and z, or nothing at all' and the like.
youtubeSearchEnabled
Self-explanatory, this simply enables YouTube search.
soundcloudSearchEnabled
Same as above, but for Soundcloud.
gc-warnings
Enables Garbage Collector warnings. Basically lets you know if something is going wrong with track handling/processing of memory, etc., which can potentially guide you to changing your settings to tune accordingly
Ratelimit
This helps circumvent IP blocks if your host supports it and if you know how to configure it properly, I've never had to use it personally, but it's worth looking into if you have an IPv6 subnet.
#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
Youtube Config
This is specifically a login that can use whatever tokens you throw into it, to be able to play age-restricted videos. You don't have to use it, but keep in mind your experience might be affected.
#youtubeConfig: # Required for avoiding all age restrictions by YouTube, some restricted videos still can be played without.#email: "" # Email of Google account#password: "" # Password of Google account
HTTP Config
This allows you to set up proxies to protect your Lavalink Host from attacks or malicious users.
#httpConfig: # Useful for blocking bad-actors from ip-grabbing your music node and attacking it, this way only the http proxy will be attacked#proxyHost: "localhost" # Hostname of the proxy, (ip or domain)#proxyPort: 3128 # Proxy port, 3128 is the default for squidProxy#proxyUser: "" # Optional user for basic authentication fields, leave blank if you don't use basic auth#proxyPassword: "" # Password for basic authentication
DSN and Sentry
Quite personally, I'll be honest, I have no idea what these do. It's best to leave them default for most situations though.
This handles logging levels, the kinds of logs kept, how big they can be, and how long they're kept. The defaults are usually good, unless you don't like seeing a ton of logs, then you can alter them as you see fit.
Just don't break anything, and I'm not responsible for configurations conflicting somehow, or your bot not working with music anymore, I use multiple other music bots, and it just so happens Athena works with this configuration perfectly fine.
