Discord-Bot-Go/README.md

discord music bot

A music bot for Discord written in Go. Plays songs and playlists in a voice channel through Lavalink, with the usual set of commands you'd expect: queue, skip, pause, seek, volume, loop, shuffle.

Why Go

Discord bots are usually a Node or Python thing, but I wanted something that starts instantly, uses barely any memory while idle, and doesn't need a runtime installed on the host. Go fits that well, and disgo turned out to be a solid, well typed library to build on top of.

Stack

• disgo for the Discord gateway and REST client
• disgolink to talk to Lavalink and manage player state
• Lavalink does the actual audio streaming and decoding, running as a separate process
• godotenv for loading .env files in local development
• the standard slog package for logging, nothing fancier than that

How it's organized

cmd/bot            entry point, wires everything together and starts the bot
internal/config    reads and validates environment variables
internal/logging   slog setup
internal/lavalink  connects to the Lavalink node
internal/discord   disgo client, voice event handling, command router
internal/commands  one file per slash command
internal/music     per guild queue and player, no Discord imports at all

internal/music is kept independent from disgo on purpose. It's the part with actual logic (queueing, shuffling, looping) so it made sense to be able to test it without spinning up a bot or a Lavalink server. That's what queue_test.go covers.

Running it

You need Go 1.27+ and a Lavalink server. Lavalink is just a jar file, running it locally only needs Java 17+:

java -jar Lavalink.jar

By default that listens on localhost:2333 with password youshallnotpass, both configurable in Lavalink's own application.yml.

Then copy the example env file and fill in your bot token:

cp .env.example .env

Variable	Required	What it's for
DISCORD_TOKEN	yes	your bot's token from the Discord Developer Portal
LAVALINK_ADDRESS	yes	host:port of the Lavalink node
LAVALINK_PASSWORD	yes	Lavalink node password
LAVALINK_NODE_NAME	no	just an internal label, defaults to main
LAVALINK_SECURE	no	set to true if the node uses wss://
DEBUG	no	true turns on debug level logs

Never commit your .env. If a token leaks anywhere (a commit, a screenshot, whatever) go revoke it right away from the Developer Portal and generate a new one.

Once configured:

go run ./cmd/bot

Commands register globally on startup, which means the bot works in every server it's in without extra setup, though Discord can take up to an hour to propagate a fresh global registration. Existing servers keep working fine while that happens.

Commands

Command	Does what
/play query	searches and plays a song or a whole playlist, or queues it if something's already playing
/skip	skips the current song
/stop	stops everything, clears the queue and leaves the channel
/pause	pauses
/resume	resumes
/queue	lists what's coming up
/nowplaying	shows the current track
/seek position	jumps to a spot in the track, accepts seconds, mm:ss or hh:mm:ss
/volume level	sets volume from 0 to 200 percent, default is 100
/loop mode	off, track to repeat the current song, or queue to send it to the back once it ends
/shuffle	shuffles the upcoming tracks
/remove position	removes a track by its position in /queue

/play takes a direct link or plain text, which gets searched on YouTube through ytsearch:. If your Lavalink instance doesn't have YouTube configured you can pass a link from whatever source it does support, or prefix your search manually, scsearch: for SoundCloud for example.

Queueing a playlist link adds every track from it: if nothing's playing yet the first one starts right away and the rest go into the queue, otherwise the whole thing just gets appended at the end.

About voice channels

Only one listening session per server at a time. Once the bot has joined a channel, /play, /skip, /stop, /pause, /resume, /seek, /volume, /loop, /shuffle and /remove only respond to people in that same channel, so another group somewhere else in the server can't take over or interrupt playback. Before the bot has joined anywhere, anyone can start it. /queue and /nowplaying are read only and work for anybody.

If everyone leaves the channel the bot is in (or the last real member moves elsewhere), it stops playback, empties the queue and disconnects on its own.

Adding a command

Create a new file under internal/commands with a struct implementing the Command interface, Definition() and Execute(), copying the shape of any existing command. Then register it in commands.NewRegistry(...) inside cmd/bot/main.go. Nothing else needs touching, the router picks it up automatically.

Tests

go test ./...