257 lines
6.3 KiB
Markdown
257 lines
6.3 KiB
Markdown
# 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.
|