DwarvenStack
← All products
Shipped

RuneBeats

Open-source Discord music bot — stream YouTube, SoundCloud, and direct audio URLs.

View repository on GitHub:★ 0⑂ 0JavaScriptBotsMIT
  • Node.js
  • discord.js v14
  • @discordjs/voice
  • FFmpeg
  • yt-dlp
Star on GitHub

RuneBeats is a self-hostable Discord music bot. It resolves a query or URL, detects the source, and pipes audio through FFmpeg (PCM → Opus) straight to Discord’s voice servers. It streams from YouTube (URLs, playlists, and search), SoundCloud (tracks and sets), and direct audio files (MP3, WAV, OGG, FLAC, AAC, M4A, OPUS, WEBM). A Spotify bridge resolves track/playlist metadata into YouTube searches when credentials are configured.

It’s for anyone who wants their own bot instead of renting a hosted one — small communities, homelabbers, and devs who’d rather run free infrastructure. The README documents a full deploy onto Oracle Cloud’s Always Free tier (1 vCPU, 1 GB RAM) under PM2.

Highlights

  • 20+ slash commands with autocomplete: play, skip, seek, volume, loop, shuffle, move, history
  • Full per-server queue system — each guild gets its own isolated in-memory MusicQueue
  • Loop modes (off / song / queue), Now Playing embed with a live progress bar
  • Multi-source detection layer (sourceDetector.js) routing YouTube / SoundCloud / direct / search
  • Auto-disconnect when the voice channel empties

What’s notable in the build: a clean source-handler abstraction so each provider (YouTube, SoundCloud, direct URL, Spotify) is an isolated module behind one detector — and a deliberate target of running for free on a permanent free-tier VM rather than a paid host. Built on Node 22 and discord.js v14.

Setup

Self-hosting takes a few minutes. You’ll need a Discord bot token and application ID.

Prerequisites

  • Node.js 22+
  • yt-dlp installed and on your PATH (the primary YouTube extractor)

FFmpeg is bundled via ffmpeg-static, so you don’t need to install it separately.

# Install yt-dlp — Linux / macOS
sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp
sudo chmod +x /usr/local/bin/yt-dlp

# Install yt-dlp — Windows (scoop)
scoop install yt-dlp

Install

git clone https://github.com/dwarvenstack/runebeats
cd runebeats
npm install
cp .env.example .env

Configure — fill in .env:

# Required
DISCORD_TOKEN=your_bot_token_here
CLIENT_ID=your_application_id_here

# Optional: a test-server ID for instant slash-command registration.
# Leave blank to register globally (~1 hour to propagate).
GUILD_ID=

# Optional: SoundCloud support (free app at developers.soundcloud.com)
SOUNDCLOUD_CLIENT_ID=your_soundcloud_client_id_here

# error | warn | info (default) | debug
LOG_LEVEL=info

Verify your environment, register commands, then run:

node setup_environment.js   # checks Node, yt-dlp/ffmpeg, folders, and .env
npm run deploy              # registers the slash commands with Discord
npm start                  # run the bot

Run it free, forever — RuneBeats fits Oracle Cloud’s Always Free VM.Standard.E2.1.Micro (1 vCPU / 1 GB RAM). Keep it alive with PM2:

npm install -g pm2
pm2 start src/index.js --name runebeats
pm2 startup    # auto-restart after reboots
pm2 save

Get it