Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DJERLO/Simple-Discord-Music-Bot-Using-Nextcord/llms.txt

Use this file to discover all available pages before exploring further.

Simple Discord Music Bot is configured through three places: a .env file for secrets, a small section of bot.py for the Lavalink connection, and application.yml for the Lavalink server itself. Understanding where each setting lives — and how they must stay in sync — will save you time when moving the bot from a local machine to a remote server or adjusting audio performance.

​
Environment Variables

The bot uses python-dotenv to load sensitive values from a .env file in the project root at startup. This keeps secrets out of source code and out of version control.
The .env file is listed in .gitignore and should never be committed to your repository. Anyone with your bot token can control your bot and potentially abuse your Discord application.

​
Required Variables

VariableDescription
BOT_TOKENYour Discord bot’s secret token. Required — the bot will not start without it.
How to get your token:
  1. Go to the Discord Developer Portal
  2. Select your application (or create one) and open the Bot tab
  3. Click Reset Token to reveal a fresh token, then copy it immediately
  4. Paste it into your .env file as shown below
Example .env file: 
BOT_TOKEN=your_discord_bot_token_here
The bot establishes its connection to the Lavalink audio server inside the on_ready event in bot.py. The URI and password are currently hard-coded: 
node: wavelink.Node = wavelink.Node(uri="http://127.0.0.1:2333", password="youshallnotpass")
await wavelink.Pool.connect(nodes=[node], client=bot)
ParameterDefault ValueDescription
urihttp://127.0.0.1:2333The address of the Lavalink node. Port 2333 must match server.port in application.yml.
passwordyoushallnotpassThe shared secret used to authenticate with the Lavalink node. Must match lavalink.server.password in application.yml.
Running Lavalink on a remote server: If your Lavalink node is hosted on a separate machine (for example, a VPS), update the uri to point to that server’s IP or hostname: 
node: wavelink.Node = wavelink.Node(
    uri="http://your-server-ip:2333",
    password="your-custom-password"
)
Make sure the remote server’s firewall exposes port 2333 and that application.yml on that server uses the same password you set here.
Changing the password in application.yml without updating the matching password argument in bot.py (or vice versa) will cause the bot to fail authentication against the Lavalink node and audio will not work. Always update both values together.
The application.yml file is mounted into the Lavalink Docker container and controls the audio server’s behaviour. It is located in the project root and passed to Docker via the volume definition in docker-compose.yml.

​
Server Settings

server:
  port: 2333
  address: 0.0.0.0
SettingValueDescription
server.port2333The port Lavalink listens on. Must match the port in bot.py’s uri.
server.address0.0.0.0Binds Lavalink to all network interfaces so Docker can route traffic to it.

​
Authentication

lavalink:
  server:
    password: "youshallnotpass"
This password must match the password argument in bot.py. See the warning above before changing it.

​
Audio Sources

lavalink:
  server:
    sources:
      youtube: false      # Handled by the YouTube plugin instead
      soundcloud: true
      scSearch: true
      local: false
      http: true
    bufferDurationMs: 400
SourceEnabledNotes
youtubefalse (via native)YouTube is handled by the external plugin below — the built-in source is disabled
soundcloudtrueEnables SoundCloud track streaming
scSearchtrueEnables SoundCloud search queries
httptrueEnables streaming from direct audio URLs (MP3, etc.) — required for 24/7 stream URLs
localfalseLocal file playback is disabled
bufferDurationMs400Audio buffer size in milliseconds; increase if you experience dropouts on slow connections

​
YouTube Plugin

YouTube support is provided by the youtube-plugin rather than Lavalink’s built-in YouTube source, which gives more reliable access: 
lavalink:
  plugins:
    - dependency: "dev.lavalink.youtube:youtube-plugin:1.18.1"

plugins:
  youtube:
    enabled: true
    allowSearch: true
    allowDirectVideoIds: true
    allowDirectPlaylistIds: true
SettingValueDescription
enabledtrueActivates the YouTube plugin
allowSearchtrueAllows searching YouTube by keyword (e.g., /play lofi hip hop)
allowDirectVideoIdstrueAllows playing tracks via a direct YouTube video URL
allowDirectPlaylistIdstrueAllows enqueueing an entire YouTube playlist via its URL

​
Memory Allocation

The Docker container is configured to allocate a maximum of 512 MB of RAM to the Java process: 
# docker-compose.yml
environment:
  - _JAVA_OPTIONS=-Xmx512M
This is suitable for a small to medium-sized server. If you run many simultaneous streams or notice Lavalink being terminated by the OS, increase this value (e.g., -Xmx1G for 1 GB).

​
Discord Bot Permissions

When inviting the bot to your server, grant the following permissions. All of these are required for normal operation: Voice Permissions:
  • Connect — allows the bot to join voice channels
  • Speak — allows the bot to transmit audio into a voice channel
Text Permissions:
  • Send Messages — required to post Now Playing embeds and command responses
  • Embed Links — required to render rich embeds with artwork and track details
  • Read Message History — required so the bot can locate and edit its persistent Now Playing message
Gateway Intents: The bot enables the message_content privileged intent in code: 
intents = nextcord.Intents.default()
intents.message_content = True
You must also enable Message Content Intent in the Discord Developer Portal under your application’s Bot → Privileged Gateway Intents section, otherwise Discord will silently deny the intent and certain bot behaviours may not function correctly.

Build docs developers (and LLMs) love

Get started for freeTalk to us