Gaming Hub

Plugin-basierte Discord-Bot-Plattform mit Web-Dashboard. Zwei Bots (Jukebox + Radio) laufen parallel mit eigenem Discord-Token und eigener Voice-Connection pro Guild.

Architektur

gaming-hub/
├── server/                 # Backend (Node.js + Express + TypeScript)
│   └── src/
│       ├── index.ts        # Entry Point, SSE, Plugin-Loader
│       ├── core/
│       │   ├── discord.ts      # Discord.js Client Factory
│       │   ├── plugin.ts       # Plugin-System + Voice Claims
│       │   ├── sse.ts          # Server-Sent Events Broadcasting
│       │   └── persistence.ts  # JSON State auf Disk
│       └── plugins/
│           ├── radio/          # World Radio Plugin
│           │   ├── index.ts    # Routes, Voice, Streaming
│           │   └── api.ts      # Radio Garden API Client
│           └── soundboard/     # Jukebox / Soundboard Plugin
│               └── index.ts    # Sounds, Upload, Normalisierung
│
├── web/                    # Frontend (React 19 + Vite + TypeScript)
│   └── src/
│       ├── App.tsx             # Root, Tab-Navigation, SSE-Handler
│       ├── styles.css          # Globale Styles + Radio-Styles
│       └── plugins/
│           ├── radio/
│           │   ├── RadioTab.tsx           # 3D Globe UI
│           │   └── TileTextureManager.ts  # Tile Loader + Mercator-Reprojection
│           └── soundboard/
│               ├── SoundboardTab.tsx      # Sound Grid UI
│               └── soundboard.css         # Soundboard Styles
│
├── Dockerfile              # Multi-Stage Production Build (4 Stages)
├── .gitlab-ci.yml          # CI/CD Pipeline (Kaniko)
└── .dockerignore

Tech Stack

Komponente	Technologie	Version
Runtime	Node.js	24 (slim)
Backend	Express	5.x
Frontend	React + Vite	19.x / 6.x
Discord	discord.js + @discordjs/voice	14.x / 0.19.x
3D Globe	globe.gl + three.js	2.35 / 0.172
Audio	FFmpeg (GPL Build) + @discordjs/opus	latest / 0.10.x
TypeScript	tsc	5.9.x
CI/CD	GitLab + Kaniko	v1.23.2

Plugins

Radio (radio)

• 3D-Globus mit 30.000+ Radiosendern weltweit (Radio Garden API)
• Tile-basierte Satellitentextur (Mercator -> Equirectangular Reprojection)
• Server-seitiger Tile-Proxy mit In-Memory Cache (CDN erfordert Referer)
• FFmpeg PCM-Streaming in Discord Voice Channels
• Per-Guild Lautstaerke, Favoriten, Suche
• Voice Stats (Ping, Status, Uptime) via SSE

Soundboard / Jukebox (soundboard)

• Sound-Upload (MP3/WAV) mit Drag & Drop
• Automatische Audio-Normalisierung (LUFS, FFmpeg)
• PCM Memory Cache (Standard 512 MB) fuer sofortige Wiedergabe
• Kategorien, Badges, Statistiken
• Admin-Panel mit Passwortschutz
• Party-Modus (Chaos Mode)

Environment Variables

Erforderlich

Variable	Beschreibung
DISCORD_TOKEN_JUKEBOX	Discord Bot Token fuer Soundboard/Jukebox
DISCORD_TOKEN_RADIO	Discord Bot Token fuer Radio

Beide Bots muessen im Discord Developer Portal separat erstellt werden. Jeder braucht die Intents: GUILDS, GUILD_VOICE_STATES, GUILD_MEMBERS.

Optional

Variable	Default	Beschreibung
PORT	8080	HTTP Server Port
DATA_DIR	/data	Persistenter Speicher (State, Sounds)
ADMIN_PWD	(leer)	Admin-Passwort fuer Soundboard-Verwaltung
ALLOWED_GUILD_IDS	(leer)	Komma-separierte Guild-IDs (Whitelist, leer = alle)
DISCORD_TOKEN	(leer)	Legacy Fallback fuer Jukebox (wenn DISCORD_TOKEN_JUKEBOX fehlt)

Soundboard-spezifisch

Variable	Default	Beschreibung
SOUNDS_DIR	/data/sounds	Verzeichnis fuer Sound-Dateien
NORMALIZE_ENABLE	true	Audio-Normalisierung aktivieren
NORMALIZE_I	-16	LUFS Integrated Loudness
NORMALIZE_LRA	11	LUFS Loudness Range
NORMALIZE_TP	-1.5	LUFS True Peak
NORM_CONCURRENCY	2	Parallele Normalisierungs-Threads
PCM_CACHE_MAX_MB	512	Max. PCM Memory Cache in MB

Build-Time (Vite)

Variable	Default	Beschreibung
VITE_APP_VERSION	1.0.0-dev	Angezeigte Version im Frontend
VITE_BUILD_CHANNEL	dev	Release-Kanal (stable / nightly / dev)

Docker

Image bauen

docker build -t gaming-hub:latest .

Container starten

docker run -d \
  --name gaming-hub \
  --restart unless-stopped \
  -p 8080:8080 \
  -v gaming-hub-data:/data \
  -e DISCORD_TOKEN_JUKEBOX="dein-jukebox-token" \
  -e DISCORD_TOKEN_RADIO="dein-radio-token" \
  -e ADMIN_PWD="dein-admin-passwort" \
  gaming-hub:latest

Docker Compose

version: "3.8"

services:
  gaming-hub:
    image: gaming-hub:latest
    container_name: gaming-hub
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - gaming-hub-data:/data
    environment:
      # Erforderlich
      - DISCORD_TOKEN_JUKEBOX=dein-jukebox-token
      - DISCORD_TOKEN_RADIO=dein-radio-token
      # Optional
      - ADMIN_PWD=dein-admin-passwort
      - ALLOWED_GUILD_IDS=
      # Soundboard Tuning
      - PCM_CACHE_MAX_MB=512
      - NORMALIZE_ENABLE=true

volumes:
  gaming-hub-data:

Unraid Docker Template

<?xml version="1.0"?>
<Container version="2">
  <Name>gaming-hub</Name>
  <Repository>10.10.10.10:9080/root/gaming-hub:latest</Repository>
  <Registry>http://10.10.10.10:9080/</Registry>
  <Network>bridge</Network>
  <Privileged>false</Privileged>
  <Support/>
  <Overview>Discord Gaming Hub - Soundboard + World Radio mit Web-Dashboard</Overview>
  <Category>MediaApp:Other</Category>
  <WebUI>http://[IP]:[PORT:8080]/</WebUI>
  <ExtraParams>--restart unless-stopped</ExtraParams>
  <Config Name="Web UI Port" Target="8080" Default="8080" Mode="tcp" Description="Web Dashboard Port" Type="Port" Display="always" Required="true" Mask="false">8080</Config>
  <Config Name="Data" Target="/data" Default="/mnt/user/appdata/gaming-hub" Mode="rw" Description="Persistenter Speicher (State + Sounds)" Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/gaming-hub</Config>
  <Config Name="Discord Token Jukebox" Target="DISCORD_TOKEN_JUKEBOX" Default="" Mode="" Description="Discord Bot Token fuer Soundboard" Type="Variable" Display="always" Required="true" Mask="true"/>
  <Config Name="Discord Token Radio" Target="DISCORD_TOKEN_RADIO" Default="" Mode="" Description="Discord Bot Token fuer Radio" Type="Variable" Display="always" Required="true" Mask="true"/>
  <Config Name="Admin Passwort" Target="ADMIN_PWD" Default="" Mode="" Description="Admin-Passwort fuer Soundboard-Verwaltung" Type="Variable" Display="always" Required="false" Mask="true"/>
  <Config Name="Erlaubte Guild IDs" Target="ALLOWED_GUILD_IDS" Default="" Mode="" Description="Komma-separierte Guild-IDs (leer = alle)" Type="Variable" Display="advanced" Required="false" Mask="false"/>
  <Config Name="PCM Cache MB" Target="PCM_CACHE_MAX_MB" Default="512" Mode="" Description="Max. PCM Memory Cache in MB" Type="Variable" Display="advanced" Required="false" Mask="false">512</Config>
  <Config Name="Normalisierung" Target="NORMALIZE_ENABLE" Default="true" Mode="" Description="Audio-Normalisierung aktivieren" Type="Variable" Display="advanced" Required="false" Mask="false">true</Config>
  <Config Name="Sound-Verzeichnis" Target="SOUNDS_DIR" Default="/data/sounds" Mode="" Description="Sound-Dateien Pfad im Container" Type="Variable" Display="advanced" Required="false" Mask="false">/data/sounds</Config>
</Container>

Lokale Entwicklung

Voraussetzungen

• Node.js 20+
• FFmpeg im PATH
• Zwei Discord Bot Tokens

Setup

git clone http://10.10.10.10:9080/root/gaming-hub.git
cd gaming-hub

# Server Dependencies
cd server && npm install && cd ..

# Web Dependencies
cd web && npm install && cd ..

Dev Server starten

# Terminal 1: Backend
cd server
DISCORD_TOKEN_JUKEBOX="..." DISCORD_TOKEN_RADIO="..." ADMIN_PWD="test" DATA_DIR="./data" npm run dev

# Terminal 2: Frontend (Proxy auf localhost:8080)
cd web
npm run dev

Backend laeuft auf http://localhost:8080, Frontend auf http://localhost:5173 (mit API-Proxy).

Production Build

cd server && npm run build    # -> server/dist/
cd ../web && npm run build    # -> web/dist/

# Starten
cd ../server
NODE_ENV=production node dist/index.js

API Endpoints

Core

Method	Pfad	Beschreibung
GET	/api/health	Server-Status, Plugins, Bots, SSE-Clients
GET	/api/plugins	Plugin-Liste (Name, Version, Description)
GET	/api/events	SSE-Stream (Snapshot + Live-Updates)
POST	/api/admin/login	Admin-Login (Body: { password })

Radio Plugin

Method	Pfad	Beschreibung
GET	/api/radio/places	Alle Orte fuer den Globus
GET	/api/radio/place/:id/channels	Sender an einem Ort
GET	/api/radio/search?q=...	Sender/Orte suchen
GET	/api/radio/guilds	Verfuegbare Guilds + Voice Channels
POST	/api/radio/play	Stream starten
POST	/api/radio/stop	Stream stoppen
POST	/api/radio/volume	Lautstaerke setzen (0-1)
GET	/api/radio/favorites	Favoriten lesen
POST	/api/radio/favorites	Favorit togglen
GET	/api/radio/status	Aktueller Wiedergabestatus
GET	/api/radio/tile/:z/:x/:y	Tile-Proxy (Satellitenbild)

Soundboard Plugin

Method	Pfad	Beschreibung
GET	/api/soundboard/channels	Voice Channels aller Guilds
GET	/api/soundboard/sounds	Sound-Liste (mit Filter/Suche)
POST	/api/soundboard/play	Sound abspielen
POST	/api/soundboard/stop	Wiedergabe stoppen
POST	/api/soundboard/volume	Lautstaerke setzen
POST	/api/soundboard/upload	Sound hochladen (Multipart)

CI/CD Pipeline

GitLab CI mit Kaniko (.gitlab-ci.yml):

Branch	Tag	Version	Channel
main	latest, main	1.0.0	stable
nightly	nightly	1.0.0-nightly	nightly
andere	branch-name	1.0.0-dev	dev

Registry: 10.10.10.10:9080/root/gaming-hub

SSE Event Types

Alle Clients empfangen Events ueber GET /api/events:

Event Type	Plugin	Beschreibung
snapshot	-	Initialer Gesamtstatus beim Connect
radio	radio	Wiedergabestatus (playing/stopped)
radio_volume	radio	Lautstaerkeaenderung
radio_voicestats	radio	Voice-Ping, Gateway-Ping, Status, Uptime
radio_favorites	radio	Favoriten-Update
soundboard_voicestats	soundboard	Voice-Verbindungsdetails
soundboard_nowplaying	soundboard	Aktuell gespielter Sound
soundboard_volume	soundboard	Lautstaerkeaenderung
soundboard_channel	soundboard	Channel-Wechsel
soundboard_party	soundboard	Party-Modus Status

Discord Bot Setup

1. Discord Developer Portal oeffnen
2. Zwei Applications erstellen (z.B. "Jukebox Bot" und "Radio Bot")
3. Fuer jede Application:
   • Bot erstellen unter "Bot"
   • Token kopieren
   • Privileged Gateway Intents aktivieren:
     • Server Members Intent
     • Message Content Intent (optional)
   • Unter "OAuth2 > URL Generator":
     • Scopes: bot
     • Bot Permissions: Connect, Speak, Use Voice Activity
   • Generierte URL im Browser oeffnen, Bot zum Server einladen
4. Tokens als DISCORD_TOKEN_JUKEBOX und DISCORD_TOKEN_RADIO setzen

Persistenz

Alle Daten werden im DATA_DIR (/data) gespeichert:

/data/
├── state.json          # Plugin-State (Volumes, Favorites, Channels, ...)
└── sounds/             # Soundboard Audio-Dateien
    ├── sound1.mp3
    ├── subfolder/
    │   └── sound2.wav
    └── ...

State wird automatisch bei Aenderungen geschrieben und beim Start geladen.

Dockerfile (Multi-Stage)

4 Build-Stages:

1. web-build - React/Vite Frontend kompilieren
2. server-build - TypeScript Backend kompilieren + native Dependencies (python3, make, g++)
3. ffmpeg-fetch - FFmpeg Binary von yt-dlp/FFmpeg-Builds herunterladen
4. runtime - Finales Image (node:24-slim) mit yt-dlp, ffmpeg, kompiliertem Code

Finales Image enthaelt nur Production Dependencies, kein TypeScript/Dev-Tooling.