RatoMusicBot

RatoMusicBot is a Discord music bot built with Node.js, discord.js v14, and @discordjs/voice. It can play YouTube music in voice channels using slash commands (/), with support for per-server queues, pause, resume, skip, stop, and loop modes.

Features

• Plays YouTube audio in Discord voice channels.
• Accepts YouTube video links and search terms.
• Accepts playlist links by adding the first track found.
• Keeps an independent queue for each server.
• Shows the currently playing track and upcoming queue items.
• Supports pause, resume, skip, and stop controls.
• Supports looping the current song or the entire queue.
• Registers global slash commands on Discord.
• Exposes a minimal HTTP health check endpoint.
• Includes an initial Next.js dashboard app prepared to call the bot HTTP API through backend routes.

Commands

Command	Description
/play <link>	Plays a YouTube track by URL or search.
/pause	Pauses the current playback.
/resume	Resumes paused playback.
/skip	Skips to the next track in the queue.
/stop	Clears the queue, stops playback, and disconnects the bot.
/loop <mode>	Sets the loop mode: off, song, or queue.
/queue	Shows the current track, upcoming tracks, and loop mode.

Technologies

• Node.js
• discord.js v14
• @discordjs/voice
• play-dl
• youtubei.js
• ffmpeg-static
• dotenv
• Next.js
• React
• Tailwind CSS

Requirements

• Node.js 22.12 or higher.
• An application created in the Discord Developer Portal.
• A bot with permissions to connect and speak in voice channels.
• The bot token and application Client ID.

Setup

1. Install dependencies:

pnpm install

2. Validate and build the bot:

pnpm check
pnpm build

To validate and build the dashboard:

pnpm check:web
pnpm build:web

3. Create the .env file based on .env.example:

DISCORD_TOKEN=your_token_here
CLIENT_ID=your_client_id_here
API_HOST=localhost
API_PORT=5000
BOT_INTERNAL_API_URL=http://localhost:5000

4. Register the slash commands on Discord:

pnpm deploy

5. Start the bot:

pnpm start

6. Check the bot health endpoint:

curl http://localhost:5000/health

7. Start the dashboard in development:

pnpm dev:web

To start the bot and dashboard together in development:

pnpm dev:all

Docker

1. Create the .env file based on .env.example:

DISCORD_TOKEN=your_token_here
CLIENT_ID=your_client_id_here
API_HOST=localhost
API_PORT=5000

2. Build the Docker image:

docker compose build

3. Register the slash commands on Discord:

docker compose run --rm rato-music-bot pnpm deploy

4. Start the bot in the background:

docker compose up -d

5. Follow the logs:

docker compose logs -f rato-music-bot

6. Check the bot health endpoint:

curl http://localhost:5000/health

7. Stop the bot:

docker compose down

Proxmox Deployment

The recommended setup is to run this container inside a Linux VM on Proxmox with Docker and Docker Compose installed. Running Docker inside an LXC container can work, but a VM is usually simpler and more reliable for long-running services.

The bot needs outbound internet access for Discord and YouTube. The HTTP health check is exposed on API_PORT, which defaults to 5000.

Suggested server flow:

git clone <repository-url>
cd RatoMusicBot
cp .env.example .env
nano .env
docker compose build
docker compose run --rm rato-music-bot pnpm deploy
docker compose up -d
docker compose logs -f rato-music-bot

The docker-compose.yml file uses restart: unless-stopped, so the bot will start again automatically after container failures or server reboots.

Usage

1. Invite the bot to your server with the required permissions.
2. Join a voice channel.
3. Use /play with a YouTube link or a search term.
4. Control playback using /pause, /resume, /skip, /stop, /loop, and /queue.

Project Structure

RatoMusicBot/
├── apps/
│   ├── bot/
│   │   └── src/
│   │       ├── index.ts                         # Discord client and command handlers
│   │       ├── api/
│   │       │   ├── routes/
│   │       │   │   └── health.ts                 # Health check route handler
│   │       │   └── server.ts                     # HTTP server and route dispatcher
│   │       ├── discord/
│   │       │   ├── commands/
│   │       │   │   └── .gitkeep
│   │       │   ├── events/
│   │       │   │   └── .gitkeep
│   │       │   └── deploy-commands.ts           # Slash command registration
│   │       └── music/
│   │           └── queue-manager.ts             # Queue, audio player, and YouTube streaming
│   └── web/
│       └── src/
│           ├── app/                         # Next.js App Router pages and API routes
│           ├── components/                  # Dashboard UI components
│           ├── lib/                         # Internal service clients
│           └── types/                       # Shared web types
├── packages/
│   ├── shared/
│   │   └── .gitkeep
│   ├── database/
│   │   └── .gitkeep
│   └── config/
│       └── .gitkeep
├── docs/
│   └── DEBUG_PLAY_STREAM.md
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── pnpm-workspace.yaml
├── pnpm-lock.yaml
├── package.json
└── logo.png

Notes

• Commands are registered globally, so they may take a few minutes to appear on all servers.
• The bot needs the Connect and Speak permissions in the voice channel.
• The .env file should not be committed because it contains sensitive credentials.

License

This project is licensed under the ISC license.