first attempt at code mostly working
This commit is contained in:
256
README.md
Normal file
256
README.md
Normal file
@@ -0,0 +1,256 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user