300 lines
7.9 KiB
Markdown
300 lines
7.9 KiB
Markdown
# Jukebox 420 – Discord Soundboard (v1.1.2)
|
||
|
||
A modern, self‑hosted Discord soundboard with a slick web UI and a Discord bot that plays sounds into your voice channels. Easy to run via Docker, fun to use with friends.
|
||
|
||
|
||
|
||
|
||
|
||
## ✨ Features
|
||
|
||
- Web UI (Vite + React + TypeScript), 3 themes (Dark, Rainbow, 420)
|
||
- Discord bot (discord.js + @discordjs/voice)
|
||
- MP3 & WAV playback, ffmpeg normalization
|
||
- Favorites, search, folders view (auto counters)
|
||
- Live counters and a clean header/footer
|
||
- Admin area: bulk delete, inline rename, categories (CRUD) + bulk assign, remove custom badges
|
||
- Partymode: server‑side random playback every 30–90 seconds, globally synced via SSE; Panic stops for everyone
|
||
- Persistent state: volumes, plays, totalPlays, categories, badges in `/data/sounds/state.json`
|
||
- Entrance/Exit sounds: per‑user sounds played when joining/leaving voice; users set them via DM (`?entrance`, `?exit`); Exit plays only on disconnect (not on channel switch)
|
||
|
||
## 🚀 Quick start
|
||
|
||
### 1. Requirements
|
||
- Docker & Docker Compose
|
||
- Discord bot token with intents: `Guilds`, `GuildVoiceStates`, `DirectMessages`
|
||
|
||
### 2. Setup
|
||
```bash
|
||
# Clone repository
|
||
git clone https://github.com/flex420/jukebox-vibe.git
|
||
cd jukebox-vibe
|
||
|
||
# Create .env
|
||
cp .env.example .env
|
||
```
|
||
|
||
### 3. Configuration
|
||
```env
|
||
# Edit the .env file
|
||
DISCORD_TOKEN=your_discord_bot_token_here
|
||
ADMIN_PWD=choose-a-strong-password
|
||
PORT=8080
|
||
SOUNDS_DIR=/data/sounds
|
||
|
||
# Optionally restrict allowed guilds
|
||
ALLOWED_GUILD_IDS=GUILD_ID_1,GUILD_ID_2
|
||
```
|
||
|
||
### 4. Deployment
|
||
```bash
|
||
# Start container
|
||
docker compose up --build -d
|
||
|
||
# Logs
|
||
docker compose logs -f
|
||
|
||
# Status
|
||
docker compose ps
|
||
```
|
||
|
||
### 5. Access
|
||
- **Web-Interface**: `http://localhost:8199`
|
||
- **Health Check**: `http://localhost:8199/api/health`
|
||
|
||
## 🎯 Usage
|
||
|
||
### **Getting started**
|
||
1. Invite the Discord bot with voice permissions
|
||
2. Upload sounds via DM to the bot (MP3/WAV)
|
||
3. Open the web UI and choose a theme
|
||
4. Select a voice channel and play sounds
|
||
|
||
### **Admin panel**
|
||
1. Log in with the admin password
|
||
2. Select sounds via checkboxes
|
||
3. Perform bulk delete or rename
|
||
4. Logout to finish
|
||
|
||
### **URL downloads**
|
||
- Enter MP3/WAV links into the URL field
|
||
- Click Download
|
||
- The file will be added automatically to the soundboard
|
||
|
||
## 🎨 Themes
|
||
|
||
### **Dark Theme**
|
||
- Klassisches dunkles Design
|
||
- Blaue Akzente (#0a84ff)
|
||
- Glassmorphism-Effekte
|
||
|
||
### **Rainbow Theme**
|
||
- Animierter Regenbogen-Hintergrund
|
||
- Bunte Borders und Effekte
|
||
- 15s Animation-Loop
|
||
|
||
### **420 Theme**
|
||
- Cannabis-grüne Farbpalette
|
||
- Trippy animierte Gradienten
|
||
- 20s Animation-Loop
|
||
- Grüne Glow-Effekte
|
||
|
||
## 📊 API endpoints
|
||
|
||
### **Public Endpoints**
|
||
```http
|
||
GET /api/health # Health Check + Statistiken
|
||
GET /api/sounds # Sound-Liste mit Ordner-Struktur
|
||
GET /api/channels # Voice-Channel Liste
|
||
POST /api/play # Sound abspielen
|
||
POST /api/play-url # URL downloaden & abspielen
|
||
POST /api/stop # Aktuellen Sound stoppen
|
||
GET /api/volume # Volume abrufen
|
||
POST /api/volume # Volume setzen
|
||
```
|
||
|
||
### **Admin endpoints**
|
||
```http
|
||
POST /api/admin/login # Admin-Login
|
||
POST /api/admin/logout # Admin-Logout
|
||
GET /api/admin/status # Login-Status
|
||
POST /api/admin/sounds/delete # Sounds löschen
|
||
POST /api/admin/sounds/rename # Sound umbenennen
|
||
```
|
||
|
||
## 🔧 Discord bot commands
|
||
|
||
### **DM commands**
|
||
- `?help` – show help
|
||
- `?list` – list all sounds
|
||
- `?entrance <file.mp3|file.wav> | remove` – set or remove your entrance sound
|
||
- `?exit <file.mp3|file.wav> | remove` – set or remove your exit sound
|
||
|
||
### **Upload via DM**
|
||
- Send MP3/WAV files directly to the bot
|
||
- Files are stored under `/data/sounds`
|
||
- Immediately available in the frontend
|
||
|
||
## 🐳 Docker deployment
|
||
|
||
### **Docker Compose (Empfohlen)**
|
||
```yaml
|
||
# docker-compose.yml
|
||
services:
|
||
app:
|
||
build: .
|
||
container_name: discord-soundboard
|
||
ports:
|
||
- "8199:8080"
|
||
env_file:
|
||
- .env
|
||
volumes:
|
||
- ./data/sounds:/data/sounds
|
||
restart: unless-stopped
|
||
```
|
||
|
||
### **Docker Run**
|
||
```bash
|
||
docker run -d \
|
||
--name jukebox-420 \
|
||
-p 8199:8080 \
|
||
--env-file .env \
|
||
-v $(pwd)/data/sounds:/data/sounds \
|
||
flex420/jukebox-vibe:latest
|
||
```
|
||
|
||
### **Docker Hub**
|
||
```bash
|
||
# Image pullen
|
||
docker pull flex420/jukebox-vibe:latest
|
||
|
||
# Container starten
|
||
docker run -d --name jukebox-420 -p 8199:8080 --env-file .env -v $(pwd)/data/sounds:/data/sounds flex420/jukebox-vibe:latest
|
||
```
|
||
|
||
## 🔒 SSL/HTTPS Hinweis (wichtig für Discord)
|
||
|
||
- Das Web-Frontend MUSS hinter HTTPS (SSL) ausgeliefert werden. Empfohlen ist ein Domain‑Mapping (Reverse Proxy) mit gültigem Zertifikat (z. B. Traefik, Nginx, Caddy, Cloudflare).
|
||
- Hintergrund: Ohne TLS kann es zu Verschlüsselungs-/Encrypt‑Fehlern kommen, und Audio wird in Discord nicht korrekt wiedergegeben.
|
||
- Praxis: Richte eine Domain wie `https://soundboard.deinedomain.tld` auf das Frontend ein und aktiviere SSL (Let’s Encrypt). Danach sollten Uploads/Playback stabil funktionieren.
|
||
|
||
## 📁 Project structure
|
||
|
||
```
|
||
jukebox-vibe/
|
||
├── server/ # Backend (Node.js/Express)
|
||
│ ├── src/
|
||
│ │ ├── index.ts # Main Server + Discord Bot
|
||
│ │ └── types/ # TypeScript Definitions
|
||
│ ├── package.json
|
||
│ └── tsconfig.json
|
||
├── web/ # Frontend (React/Vite)
|
||
│ ├── src/
|
||
│ │ ├── App.tsx # Main React Component
|
||
│ │ ├── api.ts # API Client
|
||
│ │ ├── styles.css # Theme Styles
|
||
│ │ └── types.ts # TypeScript Types
|
||
│ ├── package.json
|
||
│ └── index.html
|
||
├── docker-compose.yml # Docker Compose Config
|
||
├── Dockerfile # Multi-Stage Build
|
||
├── .env.example # Environment Template
|
||
└── README.md # Diese Datei
|
||
```
|
||
|
||
## 🔧 Development
|
||
|
||
### **Lokale Entwicklung**
|
||
```bash
|
||
# Backend
|
||
cd server
|
||
npm install
|
||
npm run dev
|
||
|
||
# Frontend (neues Terminal)
|
||
cd web
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
### **Build**
|
||
```bash
|
||
# Production Build
|
||
docker build -t jukebox-vibe .
|
||
|
||
# Development Build
|
||
docker build --target development -t jukebox-vibe:dev .
|
||
```
|
||
|
||
## 📈 Stats
|
||
|
||
### **Persistent data**
|
||
- Sounds: `/data/sounds/` (volume mount)
|
||
- State: `/data/sounds/state.json` (volume, channel, plays)
|
||
- Favorites: browser cookies
|
||
- Theme: browser localStorage
|
||
|
||
### **Monitoring**
|
||
- Health check: `/api/health`
|
||
- Docker logs: `docker compose logs -f`
|
||
- Container status: `docker compose ps`
|
||
|
||
## 🛠️ Troubleshooting
|
||
|
||
### **Häufige Probleme**
|
||
|
||
**Bot does not join the voice channel:**
|
||
- Check bot permissions (Connect, Speak, Request to Speak for Stage)
|
||
- Verify gateway intents in the Discord Developer Portal (GuildVoiceStates, DirectMessages, MessageContent)
|
||
- Check network/firewall
|
||
|
||
**Sounds do not show up:**
|
||
- Verify volume mount `/data/sounds`
|
||
- Check file permissions
|
||
- Confirm uploads via DM
|
||
|
||
**Admin login fails:**
|
||
- Check browser cookies
|
||
- Confirm admin password
|
||
- Inspect server logs
|
||
|
||
### **Logs anzeigen**
|
||
```bash
|
||
# Docker Compose Logs
|
||
docker compose logs -f
|
||
|
||
# Container-spezifische Logs
|
||
docker compose logs -f app
|
||
|
||
# Letzte 100 Zeilen
|
||
docker compose logs --tail=100 app
|
||
```
|
||
|
||
## 🤝 Contributing
|
||
|
||
1. **Fork** das Repository
|
||
2. **Feature Branch** erstellen (`git checkout -b feature/AmazingFeature`)
|
||
3. **Commit** Änderungen (`git commit -m 'Add AmazingFeature'`)
|
||
4. **Push** zum Branch (`git push origin feature/AmazingFeature`)
|
||
5. **Pull Request** erstellen
|
||
|
||
## 📄 Lizenz
|
||
|
||
Dieses Projekt ist unter der MIT Lizenz lizenziert - siehe [LICENSE](LICENSE) Datei für Details.
|
||
|
||
## 🙏 Credits
|
||
|
||
- **Discord.js** für Bot-Funktionalität
|
||
- **React** für das Frontend
|
||
- **Vite** für Build-Tooling
|
||
- **Docker** für Containerisierung
|
||
- **Tailwind CSS** für Styling
|
||
|
||
---
|
||
|
||
**🎵 Jukebox 420** - Dein ultimatives Discord Soundboard! 🚀
|
||
|
||
|
||
|
||
|
||
|