From 432f9c610fb4ccadde9aca6dc2049758b11cdd98 Mon Sep 17 00:00:00 2001 From: Daniel Date: Mon, 9 Mar 2026 00:19:53 +0100 Subject: [PATCH] v1.8.0: README aktualisiert + Version Bump README komplett ueberarbeitet mit allen 7 Plugins, Electron Desktop App, Streaming Qualitaets-Presets, aktualisierte Env-Variablen und CI/CD Doku. Version auf 1.8.0 in VERSION, server, web und electron package.json. Co-Authored-By: Claude Opus 4.6 --- README.md | 252 +++++++++++++++++++++++++++++++++--------- VERSION | 2 +- electron/package.json | 2 +- server/package.json | 2 +- web/package.json | 2 +- 5 files changed, 203 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index 152c161..5e6dcc9 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # 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. +Plugin-basierte Discord-Bot-Plattform mit Web-Dashboard und Electron Desktop App. +Drei Bots (Jukebox, Radio, Notifications) laufen parallel mit eigenem Discord-Token und eigener Voice-Connection pro Guild. ## Architektur @@ -8,36 +9,42 @@ Plugin-basierte Discord-Bot-Plattform mit Web-Dashboard. Zwei Bots (Jukebox + Ra gaming-hub/ ├── server/ # Backend (Node.js + Express + TypeScript) │ └── src/ -│ ├── index.ts # Entry Point, SSE, Plugin-Loader +│ ├── index.ts # Entry Point, SSE, Plugin-Loader, WebSocket │ ├── core/ -│ │ ├── discord.ts # Discord.js Client Factory +│ │ ├── discord.ts # Discord.js Client Factory (Multi-Bot) │ │ ├── plugin.ts # Plugin-System + Voice Claims │ │ ├── sse.ts # Server-Sent Events Broadcasting -│ │ └── persistence.ts # JSON State auf Disk +│ │ └── persistence.ts # JSON State auf Disk (Atomic Writes) │ └── 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 +│ ├── radio/ # World Radio (3D Globe + FFmpeg) +│ ├── soundboard/ # Jukebox / Soundboard (PCM Cache) +│ ├── lolstats/ # League of Legends Statistiken +│ ├── streaming/ # P2P Live-Streaming (WebRTC) +│ ├── watch-together/ # Synchron Video schauen +│ ├── game-library/ # Steam + GOG Spielebibliothek +│ └── notifications/ # Discord Benachrichtigungen │ ├── web/ # Frontend (React 19 + Vite + TypeScript) -│ ├── public/ -│ │ └── nasa-blue-marble.jpg # NASA Blue Marble Globus-Textur (~28 MB) │ └── src/ │ ├── App.tsx # Root, Tab-Navigation, SSE-Handler -│ ├── styles.css # Globale Styles + Radio-Styles +│ ├── styles.css # Globale Styles │ └── plugins/ -│ ├── radio/ -│ │ ├── RadioTab.tsx # 3D Globe UI (Sprite Particles) -│ │ └── TileTextureManager.ts # Tile Loader (Fallback) -│ └── soundboard/ -│ ├── SoundboardTab.tsx # Sound Grid UI -│ └── soundboard.css # Soundboard Styles +│ ├── radio/ # 3D Globe UI (Three.js Sprites) +│ ├── soundboard/ # Sound Grid UI + Admin Panel +│ ├── lolstats/ # Summoner-Suche + Match History +│ ├── streaming/ # Stream-Erstellung + Viewer +│ ├── watch-together/ # Raeume, Queue, Chat, Voting +│ └── game-library/ # Spielebibliothek Grid +│ +├── electron/ # Desktop App (Windows, Squirrel Installer) +│ ├── main.js # BrowserWindow, Auto-Updater, Ad-Blocker +│ ├── preload.js # IPC Bridge (contextBridge) +│ ├── ad-blocker.js # Request-Filter + Filterliste +│ └── forge.config.js # Electron Forge (Squirrel.Windows) │ ├── Dockerfile # Multi-Stage Production Build (4 Stages) -├── .gitlab-ci.yml # CI/CD Pipeline (Kaniko) -└── .dockerignore +├── .gitlab-ci.yml # CI/CD (Kaniko Build + Deploy + Electron Build) +└── VERSION # Aktuelle Version (SemVer) ``` ## Tech Stack @@ -50,6 +57,8 @@ gaming-hub/ | 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 | +| Streaming | WebSocket (ws) + WebRTC (Browser) | 8.x | +| Desktop | Electron + Squirrel.Windows | 33.x | | TypeScript | tsc | 5.9.x | | CI/CD | GitLab + Kaniko | v1.23.2 | @@ -59,7 +68,7 @@ gaming-hub/ - 3D-Globus mit 30.000+ Radiosendern weltweit (Radio Garden API) - NASA Blue Marble Globus-Textur (statisches Satellitenbild) - Sender als Sprite-Partikel mit radialer Gradient-Textur (Theme-Farbe) -- Server-seitiger Tile-Proxy mit In-Memory Cache (Fallback fuer CDN) +- Server-seitiger Tile-Proxy mit In-Memory Cache (max 500 Tiles) - FFmpeg PCM-Streaming in Discord Voice Channels - Per-Guild Lautstaerke, Favoriten, Suche - Voice Stats (Ping, Status, Uptime) via SSE @@ -68,10 +77,64 @@ gaming-hub/ - 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 +- Kategorien, Badges, Statistiken, Entrance/Exit Sounds +- Admin-Panel mit HMAC-Token-Authentifizierung - Party-Modus (Chaos Mode) +### LoL Stats (`lolstats`) +- League of Legends Spielerstatistiken via op.gg +- Summoner-Suche nach Game Name + Tag Line + Region +- Match History mit Detail-Analyse +- Letzte Suchen (max 10) persistent gespeichert +- Unterstuetzte Regionen: NA, EUW, EUNE, KR, JP, BR, LAN, LAS, OCE, TR, RU, PH, SG, TH, TW, VN + +### Streaming (`streaming`) +- Peer-to-Peer Live-Streaming via WebRTC (kein Media-Server noetig) +- WebSocket-Signaling fuer Offer/Answer/ICE-Austausch +- Qualitaets-Presets: 720p30, 1080p30, 1080p60, 1440p60, 4K60, 4K165 Ultra +- Einstellbare Bitrate (2.5 Mbit/s bis 50 Mbit/s je nach Preset) +- Optionaler Passwortschutz (Server-seitige Verifikation) +- Viewer-Liste mit Echtzeit-Updates +- Discord-Benachrichtigungen bei Stream-Start/-Ende (via Notifications Plugin) +- Stream-Link Auto-Join aus Discord (?viewStream=UUID) +- Heartbeat-basierte Client-Erkennung (5s Intervall) + +### Watch Together (`watch-together`) +- Synchronisiertes Video-Schauen in Raeumen +- Video-Queue mit URL-Eingabe +- Demokratisches Voting (Skip, Pause) +- Integrierter Chat pro Raum +- Raum-Passwortschutz +- Playback-Sync alle 2.5 Sekunden +- Host/Member-Rollen +- Auto-Cleanup nach 30s Inaktivitaet + +### Game Library (`game-library`) +- Multi-Plattform Spielebibliothek (Steam + GOG) +- Steam API Integration (Spielzeit-Tracking) +- GOG OAuth2 Login Flow (mit Token-Refresh) +- IGDB Game-Enrichment (Metadaten, Cover-Bilder) +- Mehrere Benutzerprofile pro Instanz +- Spiele-Caching mit Ablaufzeit + +### Notifications (`notifications`) +- Discord Embed-Benachrichtigungen fuer andere Plugins +- Kanal-Abonnement-Verwaltung pro Guild +- Event-Filterung (stream_start, stream_end, etc.) +- Konfigurierbare Ziel-Kanaele pro Event-Typ +- Klickbare Stream-Links in Benachrichtigungen + +## Electron Desktop App + +- Native Windows-Anwendung (Squirrel.Windows Installer) +- Automatische Updates via `/downloads` Endpoint +- Integrierter Ad-Blocker (Request-Filter + Filterliste) +- Screen Capture Picker (getDisplayMedia mit nativem Dialog) +- GOG OAuth Redirect-Handling in Child Windows +- Stream-Warnung beim Schliessen (wenn Broadcast aktiv) +- Windows Toast Notifications +- Custom User-Agent (`GamingHubDesktop/{version}`) + ## Environment Variables ### Erforderlich @@ -80,8 +143,9 @@ gaming-hub/ |----------|-------------| | `DISCORD_TOKEN_JUKEBOX` | Discord Bot Token fuer Soundboard/Jukebox | | `DISCORD_TOKEN_RADIO` | Discord Bot Token fuer Radio | +| `DISCORD_TOKEN_NOTIFICATIONS` | Discord Bot Token fuer Benachrichtigungen | -> Beide Bots muessen im Discord Developer Portal separat erstellt werden. +> Alle drei Bots muessen im Discord Developer Portal separat erstellt werden. > Jeder braucht die Intents: `GUILDS`, `GUILD_VOICE_STATES`, `GUILD_MEMBERS`. ### Optional @@ -90,9 +154,11 @@ gaming-hub/ |----------|---------|-------------| | `PORT` | `8080` | HTTP Server Port | | `DATA_DIR` | `/data` | Persistenter Speicher (State, Sounds) | -| `ADMIN_PWD` | _(leer)_ | Admin-Passwort fuer Soundboard-Verwaltung | +| `ADMIN_PWD` | _(leer)_ | Admin-Passwort fuer geschuetzte Bereiche | | `ALLOWED_GUILD_IDS` | _(leer)_ | Komma-separierte Guild-IDs (Whitelist, leer = alle) | -| `DISCORD_TOKEN` | _(leer)_ | Legacy Fallback fuer Jukebox (wenn `DISCORD_TOKEN_JUKEBOX` fehlt) | +| `PUBLIC_URL` | _(leer)_ | Oeffentliche URL fuer Notification-Links (z.B. `https://hub.example.de`) | +| `STEAM_API_KEY` | _(leer)_ | Steam Web API Key fuer Game Library | +| `DISCORD_TOKEN` | _(leer)_ | Legacy Fallback fuer Jukebox | ### Soundboard-spezifisch @@ -131,7 +197,9 @@ docker run -d \ -v gaming-hub-data:/data \ -e DISCORD_TOKEN_JUKEBOX="dein-jukebox-token" \ -e DISCORD_TOKEN_RADIO="dein-radio-token" \ + -e DISCORD_TOKEN_NOTIFICATIONS="dein-notifications-token" \ -e ADMIN_PWD="dein-admin-passwort" \ + -e PUBLIC_URL="https://hub.example.de" \ gaming-hub:latest ``` @@ -153,8 +221,11 @@ services: # Erforderlich - DISCORD_TOKEN_JUKEBOX=dein-jukebox-token - DISCORD_TOKEN_RADIO=dein-radio-token + - DISCORD_TOKEN_NOTIFICATIONS=dein-notifications-token # Optional - ADMIN_PWD=dein-admin-passwort + - PUBLIC_URL=https://hub.example.de + - STEAM_API_KEY=dein-steam-api-key - ALLOWED_GUILD_IDS= # Soundboard Tuning - PCM_CACHE_MAX_MB=512 @@ -170,20 +241,23 @@ volumes: gaming-hub - 10.10.10.10:9080/root/gaming-hub:latest - http://10.10.10.10:9080/ + 192.168.1.100:5050/root/gaming-hub:latest + http://192.168.1.100:9080/ bridge false - Discord Gaming Hub - Soundboard + World Radio mit Web-Dashboard + Discord Gaming Hub - Soundboard, Radio, Streaming, LoL Stats, Watch Together, Game Library MediaApp:Other http://[IP]:[PORT:8080]/ --restart unless-stopped 8080 - /mnt/user/appdata/gaming-hub + /mnt/user/appdata/gaming-hub - + + + + 512 true @@ -197,12 +271,12 @@ volumes: - Node.js 20+ - FFmpeg im PATH -- Zwei Discord Bot Tokens +- Drei Discord Bot Tokens ### Setup ```bash -git clone http://10.10.10.10:9080/root/gaming-hub.git +git clone http://192.168.1.100:9080/root/gaming-hub.git cd gaming-hub # Server Dependencies @@ -217,7 +291,12 @@ cd web && npm install && cd .. ```bash # Terminal 1: Backend cd server -DISCORD_TOKEN_JUKEBOX="..." DISCORD_TOKEN_RADIO="..." ADMIN_PWD="test" DATA_DIR="./data" npm run dev +DISCORD_TOKEN_JUKEBOX="..." \ +DISCORD_TOKEN_RADIO="..." \ +DISCORD_TOKEN_NOTIFICATIONS="..." \ +ADMIN_PWD="test" \ +DATA_DIR="./data" \ +npm run dev # Terminal 2: Frontend (Proxy auf localhost:8080) cd web @@ -226,6 +305,23 @@ npm run dev Backend laeuft auf `http://localhost:8080`, Frontend auf `http://localhost:5173` (mit API-Proxy). +### Electron Desktop App (Windows) + +```bash +cd electron +npm install +npm start +``` + +Build fuer Distribution: + +```bash +cd electron +npx electron-forge make +``` + +Erzeugt einen Squirrel.Windows Installer unter `electron/out/make/`. + ### Production Build ```bash @@ -275,17 +371,52 @@ NODE_ENV=production node dist/index.js | POST | `/api/soundboard/volume` | Lautstaerke setzen | | POST | `/api/soundboard/upload` | Sound hochladen (Multipart) | +### Streaming Plugin + +| Method | Pfad | Beschreibung | +|--------|------|-------------| +| WebSocket | `/ws` | Signaling (offer, answer, ice, viewer_joined, stream_ended) | + +### Watch Together Plugin + +| Method | Pfad | Beschreibung | +|--------|------|-------------| +| WebSocket | `/ws` | Raum-Sync (create, join, queue, vote, chat, playback) | + +### Game Library Plugin + +| Method | Pfad | Beschreibung | +|--------|------|-------------| +| GET | `/api/game-library/profiles` | Benutzerprofile | +| POST | `/api/game-library/profiles` | Profil erstellen/aktualisieren | +| GET | `/api/game-library/games` | Spieleliste (Steam + GOG) | +| POST | `/api/game-library/gog/exchange` | GOG OAuth Code Exchange | + +### Notifications Plugin + +| Method | Pfad | Beschreibung | +|--------|------|-------------| +| GET | `/api/notifications/config` | Kanal-Konfiguration lesen | +| POST | `/api/notifications/config` | Kanal-Konfiguration speichern | + ## 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` | +| Stage | Job | Beschreibung | +|-------|-----|-------------| +| build | docker-build | Kaniko Multi-Platform Image Build | +| deploy | deploy | Docker Pull + Run auf adriahub | +| deploy | electron-build | Squirrel.Windows Installer + `.nupkg` + `.exe` | +| bump-version | bump-version | PATCH-Version in VERSION auto-inkrementieren | -Registry: `10.10.10.10:9080/root/gaming-hub` +| Branch | Tags | Version | Channel | +|--------|------|---------|---------| +| `main` | `latest`, `main` | `1.8.0` | `stable` | +| `nightly` | `nightly` | `x.y.z-nightly` | `nightly` | +| andere | `branch-name` | `x.y.z-dev` | `dev` | + +Registry: `192.168.1.100:5050/root/gaming-hub` ## SSE Event Types @@ -307,7 +438,7 @@ Alle Clients empfangen Events ueber `GET /api/events`: ## Discord Bot Setup 1. [Discord Developer Portal](https://discord.com/developers/applications) oeffnen -2. **Zwei** Applications erstellen (z.B. "Jukebox Bot" und "Radio Bot") +2. **Drei** Applications erstellen (z.B. "Jukebox Bot", "Radio Bot", "Notifications Bot") 3. Fuer jede Application: - Bot erstellen unter "Bot" - Token kopieren @@ -316,9 +447,9 @@ Alle Clients empfangen Events ueber `GET /api/events`: - Message Content Intent (optional) - Unter "OAuth2 > URL Generator": - Scopes: `bot` - - Bot Permissions: `Connect`, `Speak`, `Use Voice Activity` + - Bot Permissions: `Connect`, `Speak`, `Use Voice Activity`, `Send Messages`, `Embed Links` - Generierte URL im Browser oeffnen, Bot zum Server einladen -4. Tokens als `DISCORD_TOKEN_JUKEBOX` und `DISCORD_TOKEN_RADIO` setzen +4. Tokens als `DISCORD_TOKEN_JUKEBOX`, `DISCORD_TOKEN_RADIO` und `DISCORD_TOKEN_NOTIFICATIONS` setzen ## Persistenz @@ -326,23 +457,38 @@ 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 - └── ... +├── sounds/ +│ ├── hub-state.json # Plugin-State (Volumes, Favorites, Channels, Profiles, ...) +│ ├── sound1.mp3 +│ ├── subfolder/ +│ │ └── sound2.wav +│ └── ... ``` -State wird automatisch bei Aenderungen geschrieben und beim Start geladen. +State wird automatisch bei Aenderungen geschrieben (Atomic Writes mit `.tmp` + `.bak` Rotation) 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 +2. **server-deps** - npm install + native Build-Tools (python3, make, g++) +3. **server-build** - TypeScript Backend kompilieren + Dev-Dependencies entfernen +4. **runtime** - Finales Image (node:24-slim) mit FFmpeg + kompiliertem Code Finales Image enthaelt nur Production Dependencies, kein TypeScript/Dev-Tooling. + +## Streaming Qualitaets-Presets + +Der Streamer kann vor dem Broadcast ein Preset waehlen: + +| Preset | Aufloesung | FPS | Bitrate | +|--------|-----------|-----|---------| +| 720p30 | 1280x720 | 30 | 2.5 Mbit/s | +| 1080p30 | 1920x1080 | 30 | 5 Mbit/s | +| 1080p60 | 1920x1080 | 60 | 8 Mbit/s | +| 1440p60 | 2560x1440 | 60 | 14 Mbit/s | +| 4K60 | 3840x2160 | 60 | 25 Mbit/s | +| 4K165 Ultra | 3840x2160 | 165 | 50 Mbit/s | + +Standard: 1080p60. Das Dropdown ist waehrend eines aktiven Broadcasts deaktiviert. diff --git a/VERSION b/VERSION index 48b2a23..27f9cd3 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.7.25 +1.8.0 diff --git a/electron/package.json b/electron/package.json index b17c5f7..1ae33db 100644 --- a/electron/package.json +++ b/electron/package.json @@ -1,7 +1,7 @@ { "name": "gaming-hub-desktop", "productName": "Gaming Hub", - "version": "1.6.5", + "version": "1.8.0", "description": "Gaming Hub Desktop App mit Ad-Blocker", "author": "Gaming Hub", "main": "main.js", diff --git a/server/package.json b/server/package.json index 6c2f1e5..cf3cfea 100644 --- a/server/package.json +++ b/server/package.json @@ -1,6 +1,6 @@ { "name": "gaming-hub-server", - "version": "1.5.0", + "version": "1.8.0", "type": "module", "scripts": { "build": "tsc", diff --git a/web/package.json b/web/package.json index 1b098c9..d831ba2 100644 --- a/web/package.json +++ b/web/package.json @@ -1,6 +1,6 @@ { "name": "gaming-hub-web", - "version": "1.5.0", + "version": "1.8.0", "type": "module", "scripts": { "dev": "vite",