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:

Go to Discord Developer Portal
Create a new application
Go to "Bot" section and create a bot
Copy the bot token to your .env file
Enable necessary intents (Guilds, Voice States)
Go to "OAuth2" → "URL Generator"
Select scopes: bot
Select permissions: Connect, Speak, View Channels
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.