root/jukebox-vibe
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

README: Komplett überarbeitet - umfassende Anleitung mit allen Features, Themes, Admin-Funktionen und Deployment-Instruktionen

Browse source
This commit is contained in:
vibe-bot 2025-08-09 01:10:09 +02:00
parent 82e4ad7e3e
commit 7020c07edf
1 changed files with 285 additions and 60 deletions
Download patch file Download diff file Expand all files Collapse all files

345
README.md
View file

@ -1,98 +1,323 @@
# Discord Soundboard (Docker)
# 🎵 Jukebox 420 - Discord Soundboard
Eine Docker-fähige Web-App mit Discord-Bot. Nutzer wählen im Web-Frontend Sound-Dateien, wählen einen Discord-Sprachkanal per Dropdown und lassen den Bot dort den Sound abspielen. Neue Sounds können dem Bot per privater Discord-Nachricht als MP3 gesendet werden; der Bot speichert sie automatisch und sie erscheinen im Frontend.
Ein modernes, feature-reiches Discord Soundboard mit Web-Frontend, Discord-Bot und Docker-Deployment. Perfekt für Gaming-Communities, Streamer und Discord-Server.
Inspiration/Referenz: `davefurrer/discordsoundboard` auf Docker Hub ([Link](https://hub.docker.com/r/davefurrer/discordsoundboard)).
![Version](https://img.shields.io/badge/version-2.0-blue)
![Docker](https://img.shields.io/badge/docker-ready-green)
![Discord](https://img.shields.io/badge/discord-bot-purple)
## Features
- Schönes Web-Frontend mit Suchfeld und Buttons für Sounds
- Dropdown-Auswahl der verfügbaren Discord-Sprachkanäle (guild-übergreifend)
- Discord-Bot joint den gewählten Voice-Channel und spielt MP3-Sounds
- MP3-Uploads via DM an den Bot; automatische Ablage im Backend und sofort im Frontend sichtbar
- Einfache Installation via Docker Compose
## ✨ Features
## Architektur
- Ein Container (Node.js):
- Express REST-API und statische Auslieferung des Frontends
- Discord-Bot (discord.js, @discordjs/voice, ffmpeg)
- Gemeinsames Datenverzeichnis `/data/sounds` für MP3s
### 🎮 **Kern-Funktionen**
- **Web-Frontend** mit modernem UI und 4 Themes (Dark, Rainbow, 420)
- **Discord-Bot** für Voice-Channel Integration
- **Sound-Management** mit Ordner-Unterstützung
- **Live-Uhrzeit** (Berlin Timezone)
- **Volume Control** pro Server
- **Favoriten-System** mit Cookie-Persistenz
## Anforderungen
- Docker und Docker Compose
- Discord Bot Token mit Intents: Guilds, GuildVoiceStates, DirectMessages, MessageContent
### 🎨 **UI/UX Features**
- **4 Themes**: Dark, Rainbow, 420 (Cannabis/Trippy)
- **Responsive Design** für Desktop & Mobile
- **Glassmorphism-Effekte** mit Backdrop-Blur
- **Animierte Hintergründe** (Rainbow & 420 Theme)
- **Live-Zähler** für Sounds und Abspielungen
## Schnellstart
### 🔧 **Admin-Funktionen**
- **Admin-Login** (Passwort-basiert)
- **Bulk-Delete** für mehrere Sounds
- **Sound-Umbenennen** mit Inline-Editor
- **Checkbox-Auswahl** für Massenoperationen
1) `.env` anlegen (siehe `.env.example`).
### 🎵 **Audio-Features**
- **MP3 & WAV Support** für Uploads und Playback
- **Audio-Normalisierung** (Loudnorm)
- **URL-Download** für MP3/WAV Links
- **Random-Play** für zufällige Sounds
- **Panic-Button** zum sofortigen Stoppen
2) Docker bauen und starten:
### 📁 **Organisation**
- **Ordner-Unterstützung** mit Tab-Navigation
- **Favoriten-Tab** für gespeicherte Sounds
- **Neu-Tab** für die letzten 10 Uploads
- **Most Played** für Top 3 Sounds
- **Suchfunktion** für alle Sounds
## 🚀 Quick Start
### 1. Voraussetzungen
- **Docker & Docker Compose**
- **Discord Bot Token** mit folgenden Intents:
- `Guilds`
- `GuildVoiceStates`
- `DirectMessages`
- `MessageContent`
### 2. Setup
```bash
docker compose up --build -d
# Repository klonen
git clone https://github.com/flex420/jukebox-vibe.git
cd jukebox-vibe
# .env Datei erstellen
cp .env.example .env
```
3) Öffne `http://localhost:8080` im Browser.
4) Lade dem Bot per privater Nachricht eine `.mp3` hoch. Der Sound erscheint automatisch im Frontend.
## Umgebungsvariablen (`.env`)
```
DISCORD_TOKEN=dein_discord_bot_token
### 3. Konfiguration
```env
# .env Datei bearbeiten
DISCORD_TOKEN=dein_discord_bot_token_hier
PORT=8080
SOUNDS_DIR=/data/sounds
```
Optional: Du kannst die Liste der Kanäle auf bestimmte Guilds beschränken:
```
# Optional: Bestimmte Server erlauben
ALLOWED_GUILD_IDS=GUILD_ID_1,GUILD_ID_2
# Optional: Audio-Normalisierung
NORMALIZE_AUDIO=true
NORMALIZE_TARGET=-14
NORMALIZE_THRESHOLD=-70
```
## Endpunkte (API)
- `GET /api/health` – Healthcheck
- `GET /api/sounds` – Liste der Sounds
- `GET /api/channels` – Liste der Voice-Channels (mit Guild-Infos)
- `POST /api/play` – Body: `{ soundName, guildId, channelId }`
## Entwicklung lokal (ohne Docker)
1) Server:
### 4. Deployment
```bash
# Container starten
docker compose up --build -d
# Logs anzeigen
docker compose logs -f
# Status prüfen
docker compose ps
```
### 5. Zugriff
- **Web-Interface**: `http://localhost:8199`
- **Health Check**: `http://localhost:8199/api/health`
## 🎯 Verwendung
### **Erste Schritte**
1. **Discord Bot einladen** mit Voice-Permissions
2. **Sounds hochladen** via DM an den Bot (MP3/WAV)
3. **Web-Interface öffnen** und Theme wählen
4. **Voice-Channel auswählen** und Sounds abspielen
### **Admin-Panel**
1. **Admin-Login** mit Passwort
2. **Sounds auswählen** via Checkboxen
3. **Bulk-Delete** oder **Umbenennen** durchführen
4. **Logout** zum Beenden
### **URL-Downloads**
- **MP3/WAV Links** in das URL-Feld eingeben
- **Download-Button** klicken
- **Automatische Integration** in 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 Endpunkte
### **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` - Hilfe anzeigen
- `?list` - Alle Sounds auflisten
- `?restart` - Bot neu starten (mit Bestätigung)
### **Upload via DM**
- **MP3/WAV Dateien** direkt an Bot senden
- **Automatische Speicherung** in `/data/sounds`
- **Sofortige Verfügbarkeit** im Frontend
## 🐳 Docker Deployment
### **Docker Compose (Empfohlen)**
```yaml
# docker-compose.yml
version: '3.8'
services:
jukebox:
build: .
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
```
## 📁 Projekt-Struktur
```
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
```
## 🔧 Entwicklung
### **Lokale Entwicklung**
```bash
# Backend
cd server
npm install
npm run dev
```
2) Web:
```bash
# Frontend (neues Terminal)
cd web
npm install
npm run dev
```
Das Web-Frontend erwartet die API standardmäßig unter `http://localhost:8080/api`. Passe sonst `VITE_API_BASE_URL` an.
## Veröffentlichung auf Docker Hub
1) Image bauen:
### **Build**
```bash
docker build -t <dein-dockerhub-user>/discord-soundboard:latest .
# Production Build
docker build -t jukebox-vibe .
# Development Build
docker build --target development -t jukebox-vibe:dev .
```
2) Einloggen und pushen:
## 📈 Statistiken
### **Persistente Daten**
- **Sounds**: `/data/sounds/` (Volume Mount)
- **State**: `/data/sounds/state.json` (Volume, Channel, Plays)
- **Favoriten**: 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 joint nicht Voice-Channel:**
- Prüfe Bot-Permissions (Voice)
- Prüfe Intents in Discord Developer Portal
- Prüfe Network/Firewall
**Sounds werden nicht angezeigt:**
- Prüfe Volume Mount `/data/sounds`
- Prüfe Datei-Permissions
- Prüfe Bot-Uploads via DM
**Admin-Login funktioniert nicht:**
- Prüfe Browser-Cookies
- Prüfe Admin-Passwort
- Prüfe Server-Logs
### **Logs anzeigen**
```bash
docker login
docker push <dein-dockerhub-user>/discord-soundboard:latest
# Docker Compose Logs
docker compose logs -f
# Container-spezifische Logs
docker compose logs -f jukebox
# Letzte 100 Zeilen
docker compose logs --tail=100 jukebox
```
3) Installation irgendwo:
```bash
docker pull <dein-dockerhub-user>/discord-soundboard:latest
docker run --name discord-soundboard -p 8080:8080 --env-file .env -v $(pwd)/data/sounds:/data/sounds -d <dein-dockerhub-user>/discord-soundboard:latest
```
## 🤝 Contributing
Hinweis: Dieses Projekt ist eigenständig implementiert, angelehnt an die Funktionsbeschreibung von `davefurrer/discordsoundboard` ([Link](https://hub.docker.com/r/davefurrer/discordsoundboard)).
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! 🚀