10nmusicbot/README.md

Discord Music Bot with Web DJ Interface

A self-hosted Discord bot that plays local MP3 files in a voice channel 24/7, with a beautiful web interface for control and management.

Features

• 24/7 Playback: Bot automatically joins your voice channel and plays music continuously
• Web Control: Beautiful React-based DJ interface with real-time updates
• Local Library: All music stored on your server (no streaming services)
• File Upload: Drag-and-drop MP3 uploads through the web interface
• Playback Controls: Play, pause, skip, shuffle, and volume control
• Real-time Updates: WebSocket connection for instant UI updates
• ID3 Tag Support: Automatically reads artist, title, and duration from MP3s
• Docker Deployment: Easy setup with docker-compose

Quick Start

Prerequisites

• Docker and Docker Compose installed
• Discord bot token (see Discord Setup Guide)
• A Discord server with a voice channel

1. Clone and Configure

git clone <your-repo-url>
cd offline-music-bot

# Copy environment template
cp .env.example .env

# Edit .env with your Discord credentials
nano .env

Required environment variables:

DISCORD_BOT_TOKEN=your_bot_token_here
DISCORD_GUILD_ID=your_server_id
DISCORD_CHANNEL_ID=voice_channel_id

2. Add Music

Place your MP3 files in the music/ directory:

mkdir -p music
cp ~/Music/*.mp3 music/

Or upload files later through the web interface.

3. Launch

# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

4. Access the Web Interface

Open your browser to:

• Local: http://localhost:3000
• Network: http://YOUR_SERVER_IP:3000

The bot should automatically join your configured voice channel and start playing!

Architecture

The project consists of three services:

Bot Service (Node.js + discord.js)

• Connects to Discord voice channels
• Plays MP3 files using @discordjs/voice
• Exposes internal API for control (port 8080)

API Service (Node.js + Express)

• REST API for track management and playback control
• WebSocket server for real-time updates
• Handles file uploads and metadata extraction
• Communicates with bot service

Web Service (React + Vite + Tailwind)

• Modern, responsive UI
• Real-time playback display
• Drag-and-drop file uploads
• Volume and playback controls

API Endpoints

Playback

• GET /api/playback - Get current state
• POST /api/playback/play - Resume playback
• POST /api/playback/pause - Pause playback
• POST /api/playback/skip - Skip to next track
• POST /api/playback/volume - Set volume (0-100)

Tracks

• GET /api/tracks - List all tracks
• POST /api/tracks/upload - Upload MP3 files
• DELETE /api/tracks/:id - Delete a track
• POST /api/tracks/scan - Rescan music directory

Queue

• GET /api/queue - Get current queue
• POST /api/queue/shuffle - Shuffle the queue

Status

• GET /api/status - Get bot connection status

Configuration

All configuration is done through environment variables in .env:

# Discord Configuration
DISCORD_BOT_TOKEN=your_token
DISCORD_GUILD_ID=your_server_id
DISCORD_CHANNEL_ID=voice_channel_id

# Server Ports
WEB_PORT=3000
API_PORT=3001

# Upload Settings
MAX_UPLOAD_SIZE_MB=50
MAX_BATCH_SIZE=20
DUPLICATE_HANDLING=rename  # skip | overwrite | rename

# Logging
LOG_LEVEL=info  # debug | info | warn | error

Development

Running Without Docker

Bot:

cd bot
npm install
npm start

API:

cd api
npm install
npm start

Web:

cd web
npm install
npm run dev

Project Structure

offline-music-bot/
├── bot/                  # Discord bot service
│   ├── src/
│   │   └── index.js     # Main bot logic
│   ├── Dockerfile
│   └── package.json
├── api/                  # API backend
│   ├── src/
│   │   ├── index.js     # Express server
│   │   └── routes/      # API routes
│   ├── Dockerfile
│   └── package.json
├── web/                  # React frontend
│   ├── src/
│   │   ├── App.jsx      # Main component
│   │   ├── components/  # UI components
│   │   └── hooks/       # React hooks
│   ├── Dockerfile
│   └── package.json
├── music/                # MP3 files go here
├── docker-compose.yml
└── .env

Troubleshooting

Bot Won't Connect

• Verify DISCORD_BOT_TOKEN is correct
• Check bot has permissions in your server
• Ensure voice channel ID is correct

No Audio Playing

• Check bot has "Speak" permission in the voice channel
• Verify MP3 files exist in music/ directory
• Check bot service logs: docker-compose logs bot

Web Interface Not Loading

• Ensure port 3000 is not in use
• Check API is running: curl http://localhost:3001/api/health
• Check web service logs: docker-compose logs web

Upload Fails

• Check file is valid MP3 format
• Verify file size is under MAX_UPLOAD_SIZE_MB
• Ensure music/ directory is writable

Discord Bot Setup

If you need to create a Discord bot from scratch:

1. Go to Discord Developer Portal
2. Create a new application
3. Go to "Bot" section and create a bot
4. Copy the bot token to your .env file
5. Enable necessary intents (Guilds, Voice States)
6. Go to "OAuth2" → "URL Generator"
7. Select scopes: bot
8. Select permissions: Connect, Speak, View Channels
9. Use the generated URL to invite the bot to your server

For detailed instructions, see the Discord Setup Guide in the spec.

Phase 1 Implementation Status

This is a complete Phase 1 (MVP) implementation with all core features:

• ✅ Bot auto-join to voice channel
• ✅ Continuous playback with automatic loop
• ✅ Now playing display with track info
• ✅ Skip track functionality
• ✅ Pause/Resume playback
• ✅ Full track list display
• ✅ MP3 file upload via web interface
• ✅ Volume control
• ✅ Shuffle mode
• ✅ Real-time WebSocket updates
• ✅ ID3 metadata extraction

See spec.md for Phase 2 and Phase 3 features.

License

MIT

Contributing

Contributions welcome! Please read the spec.md for architecture details and planned features.