# 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](spec.md#discord-setup-guide))
- A Discord server with a voice channel

### 1. Clone and Configure

```bash
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:
```bash
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:

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

Or upload files later through the web interface.

### 3. Launch

```bash
# 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`:

```bash
# 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:**
```bash
cd bot
npm install
npm start
```

**API:**
```bash
cd api
npm install
npm start
```

**Web:**
```bash
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](https://discord.com/developers/applications)
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](spec.md#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](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.