Lavalink is a standalone audio server for Discord bots. Instead of your bot downloading, decoding and encoding audio itself, it tells Lavalink what to play and Lavalink streams it to Discord. Your bot stays responsive, and one node can serve every server your bot is in. This guide sets up Lavalink v4 and connects a bot to it.
What you need
- A Lavalink node. Either a hosted Lavalink node, where Java and Lavalink are set up for you, or a VPS where you install it yourself.
- Java 17 or newer, if you run Lavalink yourself.
- A bot library with a Lavalink v4 client.
1. Configure application.yml
Lavalink reads its settings from application.yml next to Lavalink.jar. A minimal v4 configuration looks like this:
server:
port: 2333
address: 0.0.0.0
lavalink:
plugins:
- dependency: "dev.lavalink.youtube:youtube-plugin:VERSION"
snapshot: false
server:
password: "change-this-to-something-long"
sources:
youtube: false # handled by the YouTube plugin instead
bandcamp: true
soundcloud: true
twitch: true
vimeo: true
http: true
local: false
plugins:
youtube:
enabled: trueReplace VERSION with the latest release from the YouTube source plugin's GitHub page. In Lavalink v4, YouTube support moved out of Lavalink itself into this plugin, which is why the built-in youtube source is turned off.
2. Choose a strong password
Anyone who knows your node's address and password can play audio through it. Use a long random password, keep it in your bot's environment variables, and don't use the example password from tutorials.
3. Start the node and test it
Start Lavalink with java -jar Lavalink.jar (on a hosted node, just press start). When it's ready, you'll see a message that Lavalink has started. Test it from any computer:
curl -H "Authorization: your-password" http://your-node-host:2333/versionIf it returns a version number, the node is reachable and your password is correct.
4. Connect a discord.js bot
There are several Lavalink clients for Node.js, including Shoukaku, lavalink-client, Riffy and Moonlink. With Shoukaku, the connection looks like this:
const { Client, GatewayIntentBits } = require('discord.js');
const { Shoukaku, Connectors } = require('shoukaku');
const client = new Client({
intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildVoiceStates],
});
const nodes = [{
name: 'main',
url: 'your-node-host:2333',
auth: process.env.LAVALINK_PASSWORD,
}];
const shoukaku = new Shoukaku(new Connectors.DiscordJS(client), nodes);
shoukaku.on('error', (name, error) => console.error(`Lavalink ${name}:`, error));
client.login(process.env.DISCORD_TOKEN);Note the GuildVoiceStates intent: without it, your bot can't see which voice channel to join. From here, follow your client's documentation to join a channel, search for tracks and play them.
5. Connect a Python bot
For discord.py, Wavelink is the most popular client. Connect to your node in setup_hook:
import os
import discord
import wavelink
from discord.ext import commands
class MusicBot(commands.Bot):
async def setup_hook(self):
node = wavelink.Node(
uri="http://your-node-host:2333",
password=os.getenv("LAVALINK_PASSWORD"),
)
await wavelink.Pool.connect(nodes=[node], client=self)
intents = discord.Intents.default()
intents.voice_states = True
bot = MusicBot(command_prefix="!", intents=intents)
bot.run(os.getenv("DISCORD_TOKEN"))Useful plugins
- LavaSrc adds Spotify, Apple Music and Deezer links. It looks up the track's details and finds a playable version on another source.
- SponsorBlock skips sponsor segments in videos.
- LavaSearch adds richer search results such as albums and artists.
Plugins are added to the lavalink.plugins list the same way as the YouTube plugin.
Common problems
- 401 Unauthorized: the password in your bot doesn't match
lavalink.server.password. - Connection refused: wrong host or port, or a firewall is blocking it. Check the port in the panel or
server.port. - Tracks fail to load from YouTube: update the YouTube plugin. YouTube changes often, and the plugin is updated to keep up.
- Audio stutters: the node is short on CPU or memory, or is far from your bot. Host both in the same location, and upgrade the node if it's busy.
Please respect the terms of the sources you stream from. Our acceptable use policy applies to all audio hosted on our network.