The Discord music bot that plays your songs and judges you for them.
Heckbox is a self-hosted music bot for you and your friends. Paste a link or type a song name and it plays in your voice channel. It also drops a sarcastic line under almost everything you do: skipping a song after 4 seconds, queueing a 12-minute track at 3 AM, putting on the same song for the fifth time today.
It updates itself and its YouTube backend, and runs at low CPU priority in about 75 MB of RAM, so it can stay open while you play.
Heckbox is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Discord, YouTube/Google, Spotify, SoundCloud, or X. See Responsible use.
- 🎵 Music: YouTube, SoundCloud, X (Twitter) videos and more (anything yt-dlp supports). Spotify track/album/playlist links are matched to YouTube. Search by name and pick from 10 results. Queue, history, per-user favorites, server playlists, autoplay (radio mode), loop, shuffle, lyrics, volume, 10-second rewind/forward.
- 🛡️ Control when you need it: optional DJ role and vote-skip for busier servers, and a 24/7 mode that keeps the bot in its channel, also after restarts. All off by default, so small friend groups don't have to set anything up.
- 🎛️ Effects: bass boost, slowed + reverb, nightcore, sped up, 8D, old radio, blown speaker, and karaoke.
- 😏 Heckling: context-aware one-liners (early skips, skip streaks, skipping someone else's song, late-night
requests, Monday mornings, sad songs, rickrolls...). Turn them off with
ROASTS=off. - 🎭 Fun: random quotes, a Who Said It? quiz game with a leaderboard, a fake news bulletin about people in your server, a very unreliable fortune teller, face-offs between two friends, daily luck, and a weekly report (DJ of the week, Skip King, most impatient listener, song of the week).
- 🧰 Tools: reminders, polls, birthdays, a daily post (quote of the day, song of the day, birthdays), entrance and exit sounds when people join or leave voice.
- 🤖 AI voice (optional): clone a voice from a sample of up to a minute and make the bot say things with it. Also powers real karaoke (removes the vocals from the song). Runs 100% locally on your GPU. See AI voice.
- 🖥️ Windows app: no installers, no terminal. Heckbox.exe sets itself up, then shows status, uptime, RAM, live logs, a tray icon, auto-restart on crash and start-with-Windows.
- 🐳 Docker image for running 24/7 on a Linux server (amd64 and arm64).
Only 4 slash commands: everything else lives in /menu and in the buttons under the now-playing message.
 |
 |
| Search: type a name, pick one of 10 results | /menu: everything besides the 4 commands |
 |
 |
| Who Said It?: a quote quiz with a leaderboard | News bulletin: breaking news starring your friends |
 |
 |
| Fortune: from a very unreliable fortune teller | Heckbox.exe: setup, status, logs, updates |
- Create a bot: go to https://discord.com/developers/applications → New Application → give it a name. Open Bot on the left → Reset Token → copy the token.
- Download Heckbox: grab
Heckbox-vX.Y.Z-windows.zipfrom the latest release and extract it anywhere (e.g.Documents\Heckbox). - Double-click
Heckbox.exe. On the first run it downloads a portable Node.js (about 38 MB) and the bot's packages into its own folder, with a progress bar. Nothing is installed system-wide, no admin rights needed. - Paste your token when it asks for it.
- Click Invite link and add the bot to your server.
- Join a voice channel and type
/play never gonna give you up.
Keep your token secret. If it ever leaks, press Reset Token on the same Discord page.
echo "DISCORD_TOKEN=your_token_here" > .env
docker run -d --name heckbox --restart unless-stopped --env-file .env -e TZ=Europe/London \
-v heckbox-data:/app/data ghcr.io/kizzuwatnaa/heckbox:latestOr use the docker-compose.yml from this repo (docker compose up -d). Stats, favorites,
playlists, settings and added quotes are kept in the heckbox-data volume. Set TZ to your time zone so reminders
and daily posts fire at the right hour. The invite link is printed in the log: docker logs heckbox.
The bot itself is plain Node.js (22+). The Windows app is optional.
npm install --omit=dev
cp .env.example .env # then put your token in it
npm startyt-dlp is downloaded automatically into bin/. ffmpeg comes from the ffmpeg-static package.
| Command | What it does |
|---|---|
/play <name or link> |
A link plays right away. A name shows 10 results to pick from (or "⚡ Play the first one"). next:true puts it at the front of the queue |
/menu |
Control center: 🎵 Music · 🎭 Fun · 🤖 AI Voice · 🧰 Tools · ⚙️ Settings |
/say voice:<name> text:<...> |
Reads your text out loud in that AI voice |
/quote [source] [voice] |
A random quote. source limits it to one work/author, voice reads it with an AI voice |
Settings (in /menu): server-wide settings (DJ role, vote-skip, 24/7, Auto-quotes, Daily post, entrance sounds
on/off for the server) need the Manage Server permission; everyone can set their own entrance and exit sound.
With a DJ role set, only DJs and server managers can skip, stop, change effects or volume, or put songs at the front
of the queue; everyone can still add songs. With vote-skip on, a song is skipped once half of the listeners vote for
it. Whoever requested a song can always skip it.
Now-playing panel (under every song): ⏪ 10s · ⏸️ · ⏩ 10s · ⏭️ Skip · ⏹️ Stop · ⭐ Favorite · 📜 Lyrics · 📻 Autoplay · 🔁 Loop · 📃 Queue (remove / shuffle) · 🎛️ Effects · 🗣️ audio language (for videos with dubbed tracks).
Heckbox can clone a voice from a short sample (VoxCPM2) and remove vocals from songs for karaoke (Demucs). You don't need any of this for the music bot.
- Install it with the Add AI voice button in Heckbox.exe. It's a one-time ~9 GB download (Python, PyTorch and the models, all kept inside the Heckbox folder) with a progress bar in percent. You don't need to install Python yourself. Recommended: an NVIDIA GPU with 8 GB+ VRAM. It works on the CPU, but very slowly. Windows only.
- Everything runs on your own computer. No audio is sent to any online service.
- Record my voice: the bot joins your voice channel and records only the person who ran the command.
- Add voice: from a file or a link, of someone who agreed to it. Clear speech with no music works best.
- While a voice is talking, the music pauses and then resumes where it left off.
- The model loads on first use (~6 GB VRAM) and unloads itself after 5 idle minutes to give the memory back.
- Every generated clip is posted with a 🤖 AI voice label.
⚠️ Only clone voices of people who have agreed to it. Don't use cloned voices to impersonate, deceive, harass, or to pass generated audio off as real, and don't use them in ways that break the law where you live or Discord's rules. You are responsible for what you generate.
quotes.txt feeds /quote, Auto-quotes and the Who Said It? game. One quote per line:
Source (Character): quote
Author: quote
It ships with public-domain lines (Shakespeare, Lewis Carroll, Oscar Wilde, Mark Twain...). Add your server's inside
jokes with Notepad or from /menu → Fun → Add quote. No restart needed.
Everything is optional except the token. Put these in .env:
| Variable | Default | Meaning |
|---|---|---|
DISCORD_TOKEN |
— | Your bot token (the app's Token button writes it for you) |
ROASTS |
on | off = polite mode, no teasing lines |
BOT_PRIORITY |
below normal | normal = don't lower the bot's CPU priority |
YTDLP_COOKIES |
— | Path to a cookies.txt, only if YouTube asks you to sign in |
HECKBOX_DATA |
./data |
Where stats, favorites, playlists and settings are saved |
HECKBOX_QUOTES |
./quotes.txt |
Use a quotes file from somewhere else |
TZ |
system | Time zone for reminders and daily posts (Docker / Linux) |
- The bot and everything it starts (ffmpeg, yt-dlp, the AI) run at below-normal priority, so when the CPU is busy, Windows gives it to your game first.
- ~75 MB RAM, almost no CPU when idle. The app uses a few MB while it sits in the tray.
- The AI starts only when it's used and fully unloads after 5 idle minutes.
- Data lives in
data/: stats, favorites, playlists, scores, entrance sounds, voice samples, karaoke cache,bot.log.
Heckbox.exe checks GitHub for a new release, downloads it in the background and installs it on the next restart (turn it off with the Auto-update switch). Your settings, token, stats and quotes are kept.
The YouTube side is handled by yt-dlp, which Heckbox keeps up to date on its own: on every start and every 12 hours. If a song fails, it retries, and if that fails too, it updates yt-dlp right then and tries again. If the connection drops mid-song, it resumes where it left off.
- Commands don't show up / "Unknown Integration": reload Discord with Ctrl+R.
- "Sign in to confirm you're not a bot" / age-restricted videos: export your YouTube cookies as
cookies.txtwith a browser extension and setYTDLP_COOKIES=C:\path\to\cookies.txtin.env. - The bot goes offline when my PC is off: it runs on your computer. For 24/7, run it on a small server (see Linux / VPS).
- Something else: check the log in the app (or
data/bot.log) and open an issue. Ideas are welcome there too.
npm install
npm test # smoke test, no Discord login needed
powershell -File panel/build.ps1 # builds Heckbox.exe (Windows, uses the C# compiler built into Windows)The bot is src/ (discord.js, CommonJS). The Windows app is a single file, panel/panel.cs. The optional AI
server is tts/. Pull requests are welcome; keep the bot's lines friendly: tease habits and music taste, never
looks, identity or real-life problems.
Releasing: bump version in package.json, then push a tag like v1.1.0. GitHub Actions builds
Heckbox.exe, publishes the Windows zip as a release and pushes the Docker image. No local build needed.
Heckbox is a tool you run yourself, for your own friends. Please use it responsibly:
- Platforms' terms: streaming from YouTube and other sites through yt-dlp, and matching Spotify links by reading their public link pages, may conflict with those services' terms. It's up to you to check what applies to you. Heckbox is meant for small private servers; please don't turn it into a large public bot.
- Copyright: only play, record, and share content you're allowed to. Heckbox doesn't host or distribute music:
it streams what you request into your own voice channel. Karaoke tracks and entrance sounds are cached locally in
data/. - Voice cloning: consent first, always. See the warning in AI voice.
- Trademarks: Discord, YouTube, Google, Spotify, SoundCloud and X are trademarks of their respective owners and are mentioned only to describe compatibility.
- The software is provided "as is", without warranty (see LICENSE).
Built on discord.js and @discordjs/voice (Apache-2.0), yt-dlp (Unlicense), FFmpeg (GPL builds via ffmpeg-static, GPL-3.0-or-later), and for the optional AI: VoxCPM2 (Apache-2.0), Demucs (MIT), PyTorch (BSD-3-Clause). Lyrics from LRCLIB.
This repository contains none of these; setup downloads them from their official sources. The Docker image includes the npm dependencies (among them the ffmpeg-static GPL binary) under their own licenses; FFmpeg's source code is available at https://ffmpeg.org/download.html.