Master-Bot is a production-ready, high-performance Discord Music and Utility Bot with a full-featured Next.js Web Dashboard. Built with TypeScript, Sapphire Framework, discord.js v14, Next.js 15, tRPC v11, Prisma ORM (SQLite), and Lavalink v4.
Master-Bot is organized as a Turborepo workspace managed with pnpm:
Master-Bot/
├── apps/
│ ├── bot/ # Sapphire & Discord.js v14 Bot Application
│ └── dashboard/ # Next.js 15 Web Dashboard (Tailwind CSS, NextAuth, tRPC)
├── packages/
│ ├── auth/ # Shared NextAuth.js (Discord OAuth) Configuration
│ ├── config/ # Shared Tooling Config (eslint/, tailwind/)
│ └── db/ # Shared Prisma ORM Client & SQLite Schema
├── scripts/
│ ├── common.mjs # Shared cross-platform port management & log writers
│ ├── dev.mjs # Unified Development Launcher & Service Manager
│ └── start.mjs # Unified Production Launcher & Service Manager
├── wiki/ # Project documentation (Setup, Configuration, Commands)
├── logs/ # Service-specific log files (bot.log, dashboard.log, lavalink.log)
├── packages/db/prisma/ # Prisma schema + db.sqlite (auto-created on install)
├── application.yml.example # Lavalink v4 Configuration Template (copy to application.yml)
├── Dockerfile # Containerized single-service deployment
└── docker-compose.yml # Stack orchestration helpers (legacy; see the Wiki)
🔄 Note: the project has migrated from a managed database server to SQLite.
docker-compose.ymland the launcher helpers still contain some legacy service wiring that hasn't been migrated yet — for accurate deployment today, follow the Deployment Wiki.
- 🎵 High-Performance Audio Engine: Powered by Lavalink v4 with support for YouTube (multi-client + OAuth), Spotify metadata resolution (
lavasrc-plugin), free built-in SoundCloud, Twitch, Vimeo, and direct audio streams. Includes interactive channel player embeds with real-time progress bars and audio filters (/bassboost,/karaoke,/nightcore,/vaporwave). - 📚 Custom Playlists: Per-user, per-server playlists via
/create-playlist,/save-to-playlist,/my-playlists,/display-playlist,/delete-playlist, and/remove-from-playlist. - 🔨 Full Moderation Suite: Dedicated slash commands (
/ban,/kick,/slowmode,/timeout,/purge) with permission hierarchy validation and safety checks. - 🎫 Thread-Based Support Ticket System: Interactive ticket panel, thread management, a configurable manager role, and
.txttranscript archiving. - 📜 Granular Audit Logging: 20 event triggers across members, messages, channels, roles, voice, and moderation — tuned per server via
/setor the dashboard. - 🗄️ Zero-Ops Database: SQLite via Prisma. The schema is generated and pushed automatically on
pnpm install; no database server to install or manage. - 🔑 Native YouTube Device-Flow OAuth:
/youtube-authauthorizes a streaming account; the refresh token persists to.youtube-oauth.jsonwithout rewriting.env. - 🌐 Interactive Web Dashboard: Next.js 15 App Router command center — per-server studios for welcome messages, audit logs, tickets, reminders, per-command toggles, music, broadcasts, integrations, and system telemetry.
- 🎯 Feature Flags: Individual bot modules (Lavalink audio, GIFs, Twitch, News, IGDB) can be enabled or disabled via environment variables.
- 🚀 Cross-Platform Unified Launchers:
pnpm devandpnpm startmanage ports, route output to isolated log files (logs/), and present a clean console status UI. - 🖼️ Reaction GIFs & Media: Powered by Klipy API and Waifu.im (
/gif,/hug,/waifu,/cat,/doggo, and more). - 🎮 Gaming & Info: Live Twitch channel alerts, IGDB game search, TVMaze TV show info, and a suite of fun utilities (
/8ball,/urban,/trump,/kanye,/translate, and more).
- Node.js:
>=20.0.0 - pnpm:
>=8.0.0(npm install -g pnpm) - Java: Java 17+ (21 LTS recommended) — only required for a local Lavalink server (music)
- Database: None — SQLite file (
db.sqlite) is created automatically
git clone https://github.com/galnir/Master-Bot.git
cd Master-Bot
pnpm installpnpm install generates the Prisma client and creates the SQLite database (db.sqlite).
Create .env in the workspace root from .env.example:
cp .env.example .envFill in your mandatory credentials:
DISCORD_TOKEN: Bot token from the Discord Developer PortalDISCORD_CLIENT_ID&DISCORD_CLIENT_SECRET: Application OAuth2 credentialsNEXTAUTH_SECRET: Random 32+ character signing secretNEXTAUTH_URL: Public dashboard URL (e.g.http://localhost:3000)
Optional audio/feature keys (Spotify, YouTube, Twitch, News, Genius, Klipy) and the LAVA_* + feature-flag variables are documented in the Configuration Wiki.
pnpm devStarts the bot, dashboard, and (when LAVA_ENABLED=true and Java is present) a local Lavalink server with a unified status console and logs/. For production: pnpm build && pnpm start.
- Run
/youtube-authin Discord (or the terminal device-flow prompt at first launch). - Open the returned URL, log in with the YouTube account you want to stream through, and approve the scopes.
- The bot stores the refresh token atomically in
.youtube-oauth.jsonand keeps aYOUTUBE_REFRESH_TOKENbinding for Lavalink.
Authorized playback defeats YouTube throttling/blocking. See Music & Lavalink.
Master-Bot ships with 74 slash commands across Music, Moderation, GIFs, Games, Utilities, News, and Reminders. For the complete, up-to-date list and the
/setsubcommands, see the Commands Reference.
| Category | Highlights |
|---|---|
| 🎵 Music | /play, /queue, /shuffle, /jump, /seek, /volume, /lyrics, /bassboost, /music-trivia, playlists, /youtube-auth |
| 🔨 Moderation | /ban, /kick, /timeout, /slowmode, /purge |
| ⚙️ Utility | /set, /help, /reminder, /poll, /weather, /translate, /world-news, /8ball, /reddit, /urban |
| 🎮 Games | /connect-four, /tic-tac-toe, /rockpaperscissors, /game-search |
| 😂 GIFs | /gif, /hug, /waifu, /cat, /doggo, /slap, and more |
| 🟣 Twitch | /twitch-status + live stream alerts via /set twitch |
A portableDockerfile (node:20-slim, port 3000) is included. For single-service container deployment, a cloud walkthrough, and persistence guidance, see Deployment Wiki.
Visit the Wiki for full documentation:
- 🚀 Getting Started
- ⚙️ Configuration & API Keys
- 🏗️ Architecture & Database
- ⌨️ Commands Reference
- 🎵 Music & Lavalink
- 🌐 Web Dashboard
- 🚀 Deployment & Cloud Hosting
- ❓ FAQ & Troubleshooting
⭐ Bacon Fixation — countless contributions across the project.
| Contributor | Contributions |
|---|---|
| ModoSN | resolve-ip, rps, 8ball, bored, trump, advice, kanye, urban dictionary commands and visual updates |
| PhantomNimbi | GIF commands, Lavalink v4 engine, Next.js 15 migration, moderation suite, support ticket system, live ASCII progress bar & auto-updater |
| rafaeldamasceno | music-trivia and Dockerfile improvements |
| navidmafi | LeaveTimeOut and MaxResponseTime options, update issue template, fix leave command |
| Kyoyo | brought back now-playing |
| MontejoJorge | brought back remind |
| malokdev | uptime command |
| chimaerra | minor command tweaks |
We welcome contributions of all kinds! Please read our Contributing Guidelines to get started with local setup, coding standards, and pull request workflows.
Distributed under the MIT License. See LICENSE.md for more information.