Build a music bot with Lavalink

A music bot is really two programs working together, and understanding that split is most of the battle. This guide is an honest architecture walkthrough: what runs where, how the two halves connect on Falix, and where to get the actual playback code. It deliberately does not hand you a full copy-paste music bot — those go stale fast and every library does it differently — but it gets the platform pieces exactly right so the library's own examples will just work.

Expect to read your chosen library's docs alongside this.

Why two servers

Streaming audio into a voice channel is heavy work, and a Discord bot process is bad at it. The standard solution is Lavalink: a standalone audio node that does the fetching, decoding, and streaming, while your bot just sends it instructions. So on Falix you run two servers:

1. A Lavalink application server — the audio engine.
2. A Node.js or Python bot server — your bot, which connects to the Lavalink server and tells it what to play.

The flow at play time: a user runs /play in Discord → your bot receives the interaction and passes the track (or search query) to Lavalink → Lavalink fetches the audio and streams it into the voice channel.

🎯 Good to know: Your bot never touches the audio itself — it's the remote control, and Lavalink is the speaker.

1. Set up the Lavalink server

Create a new server and choose the Lavalink application (in the Applications → software section). Start it once so it installs and generates its config. Which build it downloads is set by the VERSION variable on the Settings page — it defaults to latest, which is what you want unless your client library targets a specific major version (see the version-mismatch note in Troubleshooting).

Lavalink is configured by a file called application.yml. Two things there matter to you:

• The address and port are auto-set to this server's own allocation, so Lavalink listens where Falix expects. You don't edit these.
• The password lives in application.yml. Open the file in the File Manager and read the configured server password — you'll need it on the bot side. (Change it there if you like; keep the value.)

Then find this server's public address and port on its Network page. That address-and-port pair is what your bot will connect to — note it down.

🎯 Good to know: application.yml is written by the install. Reinstalling this server — or switching its application — wipes its files and re-runs that install, which re-downloads Lavalink and lays down a fresh application.yml with a newly generated password. Keep the password recorded somewhere, and re-read it from the file after any reinstall.

⚠️ Heads up: On Falix the port is your server's own allocation from the Network page, not Lavalink's usual default of 2333. Use the allocated port.

2. Set up the bot server

Your second server is an ordinary discord.js or discord.py bot — build it exactly as in the discord.js or discord.py guide, with a token in .env and at least one working command. Then add a Lavalink client library, which is the piece that speaks Lavalink's protocol for you. Well-established choices:

• discord.js — libraries such as lavalink-client, Shoukaku, or Magmastream.
• discord.py — libraries such as Wavelink, Mafic, or Pomice.

Install your chosen one from the Packages page. Which you pick is up to you; each has its own API and its own docs, and those docs are the source of truth for the actual playback code — the /play, queue, skip, and voice-join logic.

3. Point the bot at Lavalink

Whatever library you choose, you configure it with the same four facts about your Lavalink server: its host, its port, its password, and whether the connection is secure. Keep the password and address in the bot's .env, not in code. The shape looks like this — but treat it strictly as a sketch:

// SKETCH ONLY. Every Lavalink client names these fields differently — check
// your library's current docs for the exact API and connection method.
const nodes = [
  {
    host: process.env.LAVALINK_HOST,        // Lavalink server's public address (its Network page)
    port: Number(process.env.LAVALINK_PORT), // its public port (the allocation, not 2333)
    password: process.env.LAVALINK_PASSWORD, // the password from application.yml
    secure: false,                           // plain connection to address:port
  },
];

From there, follow your library's guide for handling /play, joining the voice channel, and managing a queue. The connection details above are the only Falix-specific part; everything else is standard for the library.

Troubleshooting

• Bot can't connect / authentication failed — the password or address is wrong. Re-read the password from application.yml, and re-check the host and port on the Lavalink server's Network page (remember: the allocated port, not 2333).
• Connection times out — on the free plan the Lavalink server stops when its session timer runs out, and then the bot has nothing to reach. Extend it on its Timer page, or run Lavalink on premium for 24/7. See Keep your bot online. Note that two servers means two timers to keep an eye on.
• Connects, but playback breaks or the node is rejected — a version mismatch. Lavalink v4 and v3 speak different protocols; make sure your client library supports the Lavalink version you're running. Your library's docs state which versions it targets.
• Killed under load / audio stutters — audio nodes are memory-hungry; a Lavalink server starved for RAM gets killed. See Out of memory.

Next steps

• Host a discord.js bot
• Keep your bot online
• Store data for your bot