# StreamDeck Elgato Stream Deck mit Chatlix verbinden. # StreamDeck Grundlagen # StreamDeck Grundlagen Chatlix unterstützt **Elgato Stream Deck**. Du belegst die physischen Tasten deines Stream Decks mit Chatlix-Aktionen — Reward triggern, Automation starten, Sound abspielen, Overlay-Szene wechseln und mehr. Das ist gedacht für Streamer, die viele wiederkehrende Aktionen im Stream nutzen und nicht zwischen Tabs hin- und herklicken wollen. ## Komponenten Das Setup hat zwei Seiten: - **Chatlix-Plugin für Stream Deck**: Eine separate Installation im Stream Deck SDK, die Chatlix-Aktionen in der Stream-Deck-Software als auswählbare Aktion verfügbar macht. - **Chatlix-Dashboard**: `/dashboard/streamdeck` (Component `StreamDeck`). Hier siehst du verbundene Geräte, kannst Aktions-Templates anlegen und die zugewiesenen Aktionen pro Button prüfen. Die Kommunikation läuft so: 1. Stream-Deck-Software lädt das Chatlix-Plugin. 2. Plugin authentifiziert sich gegen Chatlix mit einem **API-Token** (eines pro Gerät, verwaltet über `/v1/tokens/`). 3. Bei Tastendruck schickt das Plugin den Aktions-Call an `/v1/streamdeck/`. 4. Chatlix führt die Aktion serverseitig aus (z.B. Reward auslösen, Sound an Overlay schicken). ## Warum Server-seitige Aktionen Im Gegensatz zu einem reinen lokalen Stream-Deck-Setup (das nur OBS-Szenen wechselt) hat das Chatlix-Plugin Zugriff auf alles, was deine Chatlix-Instanz kann. Das heißt: - Aktionen funktionieren auch, wenn dein OBS nicht läuft (z.B. Hype-Train manuell auslösen während Vorbereitung). - Mehrere Geräte können auf denselben Account; Token pro Gerät. - Mit dem Stream Deck im Mobile-Modus oder Stream Deck Plus arbeitet das Setup identisch. ## Verfügbare Aktionen (Überblick) Detail-Liste auf `Verfuegbare Aktionen`. Kurz: - Reward triggern - Automation starten - Overlay-Szene wechseln - Sound abspielen (aus Media Library) - StoryQuest-Choice setzen (in laufender Live-Session) - Counter inkrementieren - Hype-Train manuell starten (Test-Modus) ## Token-Verwaltung Unter `/dashboard/tokens` (Routen `/v1/tokens/`) legst du API-Tokens an. Pro Stream Deck (oder pro genutzter Stream-Deck-Software-Instanz) ein eigenes Token. Vorteile: - **Sichtbarkeit**: Du siehst pro Token, wann es zuletzt benutzt wurde. - **Revoke**: Wenn du das Gerät weitergibst oder verlierst, kannst du das Token entziehen, ohne deinen Account zu kompromittieren. - **Scopes**: Tokens haben Berechtigungs-Bereiche; für Stream Deck reicht `streamdeck` als Scope. Das Token kommt einmalig beim Anlegen im Klartext — kopier es ins Plugin, danach ist es nur noch als Suffix sichtbar. ## Voraussetzungen - Stream Deck Software ab v6.x (Elgato). - Chatlix-Plugin installiert (siehe `Setup`-Seite). - Internet-Verbindung auf dem Gerät, das die Stream-Deck-Software laufen lässt. - Chatlix-Account mit Stream-Deck-Berechtigung (in der Regel jeder Account; bei Plan-spezifischen Limits siehe Plan-Seite). ## Was Stream Deck NICHT macht - Keine Local-Macros (komplexe Tastenkombos für deinen Rechner) — dafür nutzt du Stream-Deck-native Aktionen oder ein Macro-Tool. - Keine Live-Voting-Steuerung (Chat-Voting bleibt Chat-getrieben). Du kannst nur explizit eine Choice setzen. - Kein eigenes OBS-Plugin — Szenen-Wechsel laufen über Chatlix → Overlay-Routing, nicht über die OBS-Websocket-API direkt. Wenn du natives OBS willst, nutz die Stream-Deck-eigene OBS-Aktion. ## Sicherheits-Notiz Das API-Token ist sensibel — wer es hat, kann in deinem Namen Aktionen auslösen. Halt es im Stream-Deck-Plugin lokal, schick es nicht per Chat/Discord und teil es nicht in Screenshots der Plugin-Config. # Setup # Setup Dieser Leitfaden bringt dich vom „Stream Deck eingesteckt“ zu „erste Chatlix-Aktion läuft per Tastendruck“. ## 1. Stream Deck Software installieren Falls noch nicht: Lad die Stream Deck Software von Elgato (`https://www.elgato.com/`) und installier sie. Verbinde das Gerät, prüf dass die Tasten reagieren. Die Software erkennt Stream Deck (Original, Mini, XL, Plus, Mobile) automatisch. ## 2. Chatlix-Plugin installieren Im Chatlix-Dashboard auf `/dashboard/streamdeck` klick `« Plugin herunterladen »`. Du bekommst eine `.streamDeckPlugin`-Datei. Doppelklick installiert sie in der Elgato-Software. Nach erfolgreicher Installation siehst du in der Stream Deck Software unter der Aktions-Liste rechts den Bereich „Chatlix“ mit den verfügbaren Chatlix-Aktionen. Alternativ: Über `/v1/streamdeck/plugin` kannst du die aktuellste Plugin-Datei direkt via API ziehen, falls du das automatisiert deployen willst. ## 3. API-Token anlegen Im Chatlix-Dashboard `/dashboard/tokens`: - `« Neues Token »`. - Name: z.B. „Stream Deck Hauptrechner“. - Scope: `streamdeck`. - Anlegen, **Token einmal kopieren** (wird danach nur als Suffix angezeigt). API-Pendant: `POST /v1/tokens/` mit `{"name":"Stream Deck Hauptrechner","scope":"streamdeck"}`. ## 4. Plugin authentifizieren In der Stream Deck Software klick auf eine beliebige Chatlix-Aktion und zieh sie auf einen freien Button. Beim ersten Mal öffnet sich ein Konfig-Panel mit „Token einfügen“: - Token einsetzen. - `« Verbinden »`. - Es prüft die Verbindung gegen `POST /v1/streamdeck/auth`. Bei Erfolg siehst du rechts grün den verbundenen Account-Namen. Das Token wird einmal hinterlegt und gilt dann für alle Chatlix-Aktionen auf dem Gerät; du musst es nicht pro Button neu eingeben. ## 5. Erste Aktion anlegen Wähl als Test die Aktion `« Sound abspielen »`. Im Konfig-Panel: - **Asset**: Klick `« Asset wählen »` und such ein Sound-Asset aus deiner Media Library (z.B. Test-Beep). - **Lautstärke**: 60%. - **Cooldown**: 1 Sekunde. Speichern. Drück die Taste auf dem Stream Deck. Wenn dein OBS mit Chatlix-Overlay läuft, hörst du den Sound. Im Chatlix-Dashboard kannst du parallel auf `/dashboard/streamdeck` sehen, dass die Aktion ausgeführt wurde (Last-Action-Log mit Zeitstempel). ## 6. Buttons strukturieren Stream Deck hat „Folder“-Buttons (Unterordner). Empfehlung: - Erste Seite mit den häufigsten Aktionen (5–10 Buttons). - Folder „Sounds“ mit allen Soundboard-Tasten. - Folder „Overlays“ mit Szenen-Wechseln. - Folder „Quest“ für StoryQuest-Choices, falls du oft im Multi-Mode bist. - Folder „Test“ für gefährliche Aktionen (Hype-Train-Test, Counter-Reset) — eine Stufe weg vom Haupt-Layout, damit du nicht versehentlich drückst. ## 7. Pro Profil eigene Layouts Stream Deck Software unterstützt Profile pro Anwendung. Du kannst z.B. ein Profil „Just Chatting“ mit anderen Chatlix-Aktionen anlegen als „Gameplay“. Profil-Wechsel sind Stream-Deck-nativ, das Plugin macht da nichts Eigenes. ## 8. Mehrere Geräte Wenn du z.B. einen Hauptrechner und einen Mobile-Stream-Deck nutzt: Pro Gerät ein eigenes API-Token anlegen. So kannst du einzelne Geräte revoken, ohne die anderen zu verlieren. ## Troubleshooting - **Plugin nicht in der Liste**: Stream Deck Software neu starten. Falls weiterhin fehlend, Plugin-Datei erneut doppelklicken. - **„Token ungültig“**: Token im Dashboard prüfen (existiert noch? Scope `streamdeck`?). Neu anlegen, im Plugin austauschen. - **Aktion zeigt im Log „PLAN_REQUIRED“**: Einige Aktionen sind plan-gated. Plan-Hinweis im Dashboard prüfen. - **Sound spielt nicht**: Overlay aktiv? Browser-Source in OBS gerade aktualisiert? Im Chatlix-Dashboard `/dashboard/overlays` siehst du den Verbindungs-Status pro Overlay. - **Tasten reagieren verzögert**: Internet-Latenz zwischen Stream-Deck-Rechner und Chatlix prüfen. Normalerweise <200ms; bei 1s+ stimmt etwas auf Netzwerk-Ebene nicht. # Verfuegbare Aktionen # Verfuegbare Aktionen Das Chatlix-Plugin für Stream Deck stellt eine Reihe von Aktionen bereit, die du als Tasten belegen kannst. Jede Aktion hat eigene Konfig-Felder im Stream-Deck-Plugin und ruft serverseitig den entsprechenden Endpoint unter `/v1/streamdeck/`. ## Reward triggern Führt einen Channel-Points-Reward auf deinem Twitch-Kanal aus — als wäre er von einem Zuschauer eingelöst worden. Nützlich zum Testen von Reward-bedingten Automations, oder um in einer Show-Situation gezielt ein Event zu zünden. - **Konfig**: Reward-Auswahl (Liste deiner aktiven Rewards), optional User-Kontext (für Logs). - **Cooldown**: Pro Button frei wählbar. - **Nutzungs-Tipp**: Idealerweise für Test/Demo. Im laufenden Stream sollte das normalerweise der Chat machen. ## Automation starten Löst eine deiner Automations direkt aus, ohne dass ihr normaler Trigger feuert. Hilfreich für Setup-Routinen („Stream-Start-Sequenz“) oder manuelle Spezial-Events. - **Konfig**: Automation-Auswahl, optional Payload (JSON-Mini-Editor) für Variablen. - **Verhalten**: Die Automation läuft ihren Action-Stack ab; Bedingungen werden normal ausgewertet. ## Overlay-Szene wechseln Wechselt das angezeigte Layout in einem deiner Chatlix-Overlays. Funktioniert für Overlays, die mit dem Pro Editor gebaut wurden und mehrere Szenen haben (z.B. „Starting Soon“, „Gameplay“, „BRB“, „Ending“). - **Konfig**: Overlay-Auswahl, Ziel-Szene. - **Übergang**: Falls im Pro Editor konfiguriert, mit Fade/Cut-Animation. - **Wichtig**: Das wechselt **die Chatlix-Overlay-Szene**, nicht OBS-Szenen. Wenn du parallel OBS-Szenen brauchst, kombinier mit der Stream-Deck-OBS-Aktion. ## Sound abspielen Spielt ein Audio-Asset aus deiner Media Library in einem oder allen aktiven Overlays ab. Das ist die Standard-Soundboard-Aktion. - **Konfig**: Asset-Picker (Library), Lautstärke 0–100%, Cooldown, Ziel-Overlay (alle oder einzelnes). - **Cooldown-Hinweis**: Soundboard-Spam vermeiden, mindestens 1s Cooldown pro Button setzen. - **API**: `POST /v1/media-engine/play` mit Asset-ID. ## StoryQuest-Choice setzen Wenn gerade eine StoryQuest-Live-Session läuft, kannst du eine bestimmte Choice manuell setzen — z.B. um ein offensichtlich bevorzugtes Voting frühzeitig durchzudrücken oder um in einer Solo-Show selber die Story zu steuern. - **Konfig**: Quest-Auswahl, Choice-Identifier (Builder zeigt dir die IDs). - **Verhalten**: Setzt die Choice unmittelbar, beendet das laufende Voting, springt zum Ziel-Node. - **Vorsicht**: Im Multi-User-Voting macht der manuelle Choice das Chat-Voting hinfällig. Nutz das mit Bedacht. ## Counter inkrementieren Chatlix führt Counter-Variablen (z.B. „Tode in Dark Souls“, „Witze pro Stream“). Diese Action erhöht einen Counter um 1 (oder den konfigurierten Wert). - **Konfig**: Counter-Auswahl, Inkrement (Standard +1). - **Anzeige**: Counter sind im Overlay als Text-Widget einblendbar, der automatisch aktualisiert. - **Reset**: Über `/dashboard/counters` oder eigene Aktion „Counter setzen“ (manchmal als zweite Action verfügbar). ## Hype-Train manuell starten (Test) Löst lokal einen simulierten Hype-Train aus. Achtung: das ist **nur Test/Simulation** für die Anzeige im Overlay und für Reward-Trigger; es löst keinen echten Twitch-Hype-Train aus. - **Konfig**: Hype-Train-Profil (Dauer, Stufen). - **Verwendung**: Zum Testen, ob deine Hype-Train-Automations korrekt feuern. - **Sicherheits-Hinweis**: Diese Aktion sollte nicht im Live-Stream gedrückt werden, sondern im Setup-Modus. ## API-Routen Alle Aktionen werden vom Plugin gegen Endpunkte unter `/v1/streamdeck/` aufgerufen: - `POST /v1/streamdeck/action/reward` - `POST /v1/streamdeck/action/automation` - `POST /v1/streamdeck/action/scene` - `POST /v1/streamdeck/action/sound` - `POST /v1/streamdeck/action/storyquest-choice` - `POST /v1/streamdeck/action/counter` - `POST /v1/streamdeck/action/hype-train-test` Alle erwarten den Geräte-Token im Header und einen kleinen Payload mit der Aktions-spezifischen Config. Wenn du eigene Tools oder Hotkey-Setups bauen willst (nicht Stream-Deck-basiert), kannst du dieselben Endpunkte direkt aufrufen. ## Logs prüfen Im Dashboard `/dashboard/streamdeck` gibt es eine Aktivitäts-Tabelle mit den letzten Aktionen: Zeitstempel, Aktion, Ziel, Ergebnis (ok/Fehler). Falls eine Aktion nicht wirkt, ist das die erste Anlaufstelle — typisch ist `PLAN_REQUIRED`, `TOKEN_INVALID` oder `TARGET_NOT_FOUND` (z.B. Reward inzwischen gelöscht).