Set up a Discord music bot that still plays in 2026
Music bots are harder to run than they were a few years ago. YouTube increasingly blocks playback from servers in data centres, which is where every hosted bot lives. This guide sets up the Music module in Build Discord Bots, explains exactly what happens when you ask for a song, and is upfront about which requests can fail and how the bot falls back when they do.
Start free, 14 days of Pro, no cardBefore you start
- A Build Discord Bots bot that is invited to your server and online. Music is included on the Free plan, so no upgrade is needed to follow this guide.
- A voice channel where the bot's role has the Connect and Speak permissions, and a text channel where it can send messages and embed links. You also need to be in that voice channel yourself when you test.
Understand how the bot finds and plays music
Your bot does not download audio itself. When someone runs /play, the Music module sends the request to a Lavalink audio server run by the platform, which looks up the track and streams it into your voice channel. If that server cannot be reached, the bot answers that the music system is not available or that all Lavalink servers are unavailable and it is trying to reconnect. That is a platform-side outage rather than a problem with your settings, so wait a minute and try again before you change anything.
The /play command accepts either a song name or an http or https link. Plain search words go to SoundCloud first by default, because SoundCloud tracks found from a hosted bot usually play all the way through. If SoundCloud has no match for the words, the bot repeats the same search on YouTube before giving up. Any other kind of address, such as a file path, is refused with a message asking you to search for the song name instead.
Know the YouTube limits before you promise anything
Be honest with your members about YouTube. It asks for a signed-in account before it will play much major-label, age-restricted or region-locked content, and the wall appears most often for traffic from data centres. A hosted bot cannot sign in on anyone's behalf, so some YouTube links will find a title and then fail when playback starts. No hosted music bot can guarantee that every YouTube video plays, and this one does not claim to.
When a YouTube track fails with a login, age or availability error, the bot takes the artist and title, searches SoundCloud for the same song, and plays the first match. It posts a yellow notice in the channel saying that YouTube requires login for the track and naming the SoundCloud track it used instead. That match can be a different upload of the song, such as a remaster, a live version or a cover, so check the notice if the result sounds unfamiliar.
If SoundCloud has nothing suitable, the bot says that YouTube requires login and no SoundCloud fallback was found, then skips to the next track in the queue. A pasted YouTube video link that returns nothing at all is retried once as a YouTube search for that video, and a track that stalls mid-stream is announced as stuck and skipped, so one bad entry does not block the rest of the queue.
Enable Music and choose the server
Open your bot in the dashboard, select the Modules tab, and switch Music on. Enabling a module on an online bot can restart it, so wait until the status is back to online. Then click the gear button titled Settings on the Music card to open the Module Settings dialog.
Use the Server selector at the top of the dialog to choose the server you are configuring. Music settings are stored per server, so a volume or queue size you save here does not change any other server the bot has joined.
Set volume, queue size and duplicates in Playback
Default Volume accepts 0 to 100 and starts at 80 on a new bot. Many servers are happier around 50 or 60, since members can raise it for a session with /volume. Max Queue Size sets how many tracks can wait in line, from 10 up to 500, and starts at 100. When Free plan limits apply, the queue is capped at 20 tracks whatever this field says, and the dashboard limits the field to match.
Allow Duplicates decides whether the same song may be queued more than once. It is on by default. Turn it off in busy servers where the same request gets added repeatedly: the bot then tells the member the song is already in the queue, and it skips duplicates when importing a playlist and reports how many it left out.
Decide when the bot leaves voice
In the Auto Leave section, Leave when empty is on by default. When every human member has left the voice channel, the bot waits for the Leave delay, anywhere from 5 to 300 seconds with 30 as the starting value, then stops playback, clears the queue and posts that everyone left. A longer delay helps if members often drop out briefly and rejoin.
Under Pro Music Features, 24/7 Mode, labelled Stay in voice when idle, keeps the bot connected after the queue ends and ignores the empty-channel timer. Audio Filter offers a Filter preset of Off, Bass boost, Nightcore, Vaporwave, Karaoke, Tremolo or Vibrato, and applies to new playback and the current player. Both controls show a Pro badge and stay locked when Free plan limits apply. Leave them off for your first test so there are fewer variables if something goes wrong.
Click Save Settings and wait for Saved ✓. If the dashboard warns that live sync to the bot runtime failed, restart it from the bot page and reopen the dialog to confirm the values stuck.
Play a first song and use the queue
Join your voice channel first; the bot refuses with a reminder if you are not in one. In a text channel, run /play with an artist and song name. The bot joins your voice channel, posts an embed confirming the track was added with its duration and queue position, and a Now Playing embed showing who requested it once the track starts. If it replies that it needs permissions to join and speak, fix the channel's Connect and Speak permissions for the bot's role rather than granting Administrator.
Add a second request, then run /queue to see the list, one page at a time. /nowplaying repeats the current track, /pause and /resume hold and continue it, and /skip moves to the next entry. /seek jumps to a position such as 1:30, /shuffle mixes the waiting tracks, and /loop accepts off, track or queue. /stop ends playback, clears the queue and disconnects the bot.
Every command also works with the bot's prefix instead of a slash, for example !play followed by the song. Slash commands show their options in Discord's picker, which makes them easier for members who have not used the bot before.
Check what changes on Free and Pro
When Free plan limits apply, the bot enforces a 20-track queue and imports at most 20 tracks from a pasted playlist, and it posts a short notice with an upgrade link when a member reaches either limit. Saved playlists, audio filters and 24/7 mode are Pro features; on Free, those commands reply that the feature needs Pro instead of silently doing nothing.
On Pro the queue has no plan cap beyond your own Max Queue Size, and members can use /playlist to save the current queue under a name and load, list or delete saved playlists, /filter to switch presets from Discord, and /247 to toggle staying in voice. New accounts start with a 14-day Pro trial, so check which of these features your server depends on before the trial ends.
Frequently asked questions
Does the bot play YouTube links?
Often, but not always. YouTube blocks some tracks for hosted bots behind a login wall, and those links fail even though the title is found. The bot then tries to play the same song from SoundCloud and posts a notice; if no match exists it skips the track.
Why did the bot play a different version of my song?
The YouTube source failed and the bot used its SoundCloud fallback, which plays the first SoundCloud result for the same artist and title. The yellow notice in the channel names the track it chose.
Why does the bot leave the voice channel?
Leave when empty is on by default, so the bot leaves after the configured delay once no human members remain. Raise the Leave delay in Auto Leave, or on Pro turn on Stay in voice when idle.
Is Music available on the Free plan?
Yes. Music is a Free module. When Free plan limits apply, queues and playlist imports are capped at 20 tracks, and saved playlists, audio filters and 24/7 mode need Pro.