abdulive/docs/projects/chat-control.md

7 — Chat steuert Dinge (apps/overlay-server + apps/overlay-web)

Wirkrichtung: Bindung. Aus Zuschauen wird Mitmachen.

Aufbau

Chat-Command ──► overlay-server (4791) ──► WS ──► Browser-Source in OBS
                        │
                        ├──► obs-websocket   (Szenen, Filter, Quellen, Hotkeys)
                        ├──► Home Assistant / WLED  (Licht)
                        └──► Helix            (Umfragen, Titel)

overlay-server ist ein Fastify-Server, der drei Dinge tut: Overlay-Seiten ausliefern, den WS-Kanal zu den Browser-Sources halten, und Commands vom Event-Bus in Aktionen übersetzen.

Overlay-Seiten (Browser-Sources in OBS)

Pfad	Zweck	Größe
/overlay/alerts	Follow/Sub/Raid-Einblendungen	1920x1080
/overlay/effects	Emote-Regen, Soundboard-Feedback, Konfetti	1920x1080
/overlay/community	Chatter-Hinweis (nur für Abdu)	480x220
/overlay/poll	laufende Umfrage	480x600
/overlay/game	Minigame-Anzeige	1920x1080
/overlay/raid-panel	Raid-Ziele am Streamende	900x600

Alle Seiten teilen sich einen WS-Client (packages/shared/overlay-client.ts) mit automatischem Reconnect — eine Browser-Source, die nach einem Serverneustart tot bleibt, ist der häufigste Fehler bei solchen Overlays.

Command-Registry

Commands liegen deklarativ in config/commands.yaml:

- trigger: "!sound"
  args: [name]
  cooldown: { global: 20, user: 120 }
  permission: everyone
  cost: 50            # Punkte, optional
  action: { type: sound, file: "sounds/{name}.mp3" }

- trigger: "!licht"
  args: [farbe]
  cooldown: { global: 60 }
  permission: subscriber
  action: { type: wled, preset: "{farbe}" }

Aktionstypen: sound, overlay-effect, obs-hotkey, obs-source-toggle, obs-filter, wled, helix-poll, set-title, script.

Cooldowns und Rechte sind nicht optional. Ein Soundboard ohne Cooldown ist nach zwei Streams abgeschaltet. Default: 20 s global, 120 s pro User, Sounds nur für Follower.

Minispiele

Ausbaustufe 2. Kandidaten, die bei kleinem Chat funktionieren (wichtig: sie dürfen mit 3 Mitspielern genauso gut sein wie mit 30):

• Tipprunde — !tipp <zahl>, Abdu löst auf, Punkte für die Nächsten
• Kollektive Entscheidung — Helix-Umfrage mit echter Konsequenz im Spiel
• Boss-Bingo — Karte im Overlay, Chat ruft Felder aus

Umfragen mit Konsequenz

!umfrage startet eine Helix-Poll (POST /helix/polls). Bei poll.end führt der Server die hinterlegte Aktion zur Gewinneroption aus — Szenenwechsel, Schwierigkeitsgrad, nächstes Spiel. Der Unterschied zu einer normalen Umfrage ist, dass das Ergebnis automatisch etwas tut, statt nur angezeigt zu werden.

Sicherheit

Alles, was den Stream sichtbar verändert oder Geräte im Haus schaltet, ist missbrauchbar. Deshalb:

• overlay-server bindet nur auf 127.0.0.1.
• Der Panik-Command !aus (Mods) schaltet alle Effekte für 10 min ab.
• Aktionen mit requires_approval: true erscheinen erst in einer Warteschlange im Overlay-Panel und laufen nach Abdus Klick.
• Kein Command darf beliebigen Text auf dem Bildschirm anzeigen. TTS und freie Textanzeigen sind bewusst nicht Teil von Ausbaustufe 1.

Abnahmekriterien

• !sound huch spielt innerhalb von 300 ms den Sound ab.
• Cooldown greift und wird im Chat sichtbar quittiert (einmal, nicht bei jedem Versuch).
• OBS-Neustart oder Server-Neustart: Browser-Source verbindet sich innerhalb von 5 s automatisch neu.
• !aus stoppt sofort alle laufenden Effekte.