Direkt zum Hauptinhalt

StreamDeck Grundlagen

Wichtige Korrektur vorweg: Chatlix hat kein installierbares Elgato-Plugin (kein .sdPlugin, kein Store-Eintrag). Was in Code und Dashboard „StreamDeck" heißt, ist eine generische Bearer-Token-API für Hardware-Decks und Automatisierungs-Tools (Elgato Stream Deck, Loupedeck, Touch Portal) sowie die Backend-Anbindung der Chatlix Mobile Deck iOS-App. Du richtest die Verbindung selbst über eine generische HTTP-Request-Aktion in deiner Deck-Software ein — nicht über ein fertiges Chatlix-Icon-Paket. Diese Seite beschreibt, was die Funktion wirklich ist und wie die Teile zusammenspielen.

Wie das Dashboard die Funktion nennt

Im Chatlix-Dashboard heißt die Seite offiziell „Macros & Stream-Deck", erreichbar unter /dashboard/streamdeck (Component ). Im Menü steht sie unter dem Label „Macros & Stream-Deck" mit Untertitel „Hardware-Buttons" und ist an den Pro-Tier gebunden (kein Free-Feature). Die Seite hat fünf Tabs:

  • ⚡ Macros — One-Click-Sequenzen. Vier Built-ins (BRB, Hype, Raid Incoming, Stream Start) werden beim ersten Aufruf automatisch angelegt.
  • 🎞️ Timelines — Verkettung mehrerer Schritte (Sound, Szenenwechsel, Timer, …) hinter einem einzigen Trigger.
  • 🔑 Hardware-Tokens — hier legst du die Bearer-Tokens für Stream Deck/Loupedeck/Touch Portal/eigene Tools an.
  • 🎛️ OBS Quick — Schnellzugriff auf Scene/Audio/Media/Hotkey-Aktionen direkt aus dieser Seite; für die volle OBS-Steuerung (Filter, Recording-Timer, Audio-Mute pro Source) gibt es die separate Seite /dashboard/obs-control.
  • 📋 Verlauf — Action-Log der letzten 30 Aktionen (OBS- und Deck-Aktionen gemeinsam).

Macros bündeln dabei OBS + Overlay + Lighting + Sounds in einer Aktion; Timelines verketten mehrere solcher Schritte hintereinander. Reine OBS-Steuerung ohne Macro-Kontext gehört auf /dashboard/obs-control, nicht auf diese Seite.

Zwei Zugriffswege

Es gibt technisch zwei getrennte Pfade, die serverseitig auf denselben Dispatch-Kern laufen:

  • Bearer-Pfad (/v1/streamdeck/…): externe Hardware (Stream Deck, Loupedeck, Touch Portal), Browser-Extensions oder die Mobile-App rufen mit Authorization: Bearer <token> auf. Das ist der Weg, den diese Wiki-Sektion primär beschreibt.
  • Control-Deck-Pfad (/v1/control-deck/buttons/{id}/execute): Session-Auth, für Buttons, die du direkt im Chatlix-Dashboard anlegst und dort persistierst (Web-Buttons statt physischer Hardware). Praktisch, wenn du keine eigene Hardware hast, aber trotzdem Ein-Klick-Aktionen willst.

Warum serverseitige Aktionen

Im Gegensatz zu einem reinen lokalen Stream-Deck-Setup (das nur lokale OBS-Websocket-Calls macht) läuft die Chatlix-Aktion über den Server:

  • Funktioniert unabhängig davon, ob OBS lokal auf demselben Rechner läuft wie die Deck-Software — solange Chatlix Connect mit OBS verbunden ist.
  • Mehrere Geräte können denselben Account nutzen; jedes Gerät bekommt sein eigenes Token.
  • Aktionen werden geloggt (Tab „Verlauf"), inklusive Fehlerursache und Dauer — nachvollziehbar auch Tage später.

Plan-Voraussetzung

  • Macros & Stream-Deck ist ein Pro-Tier-Feature. Auf niedrigeren Plänen siehst du die Seite ggf. gar nicht im Menü oder bekommst beim Anlegen eines Tokens einen Plan-Hinweis.
  • Token-Kontingent ist plan-gestaffelt: Free = 0 Tokens, Pro = 3 Tokens, Studio = 10 Tokens (plan_features.streamdeck_tokens_max). Wenn du mehrere Geräte anbinden willst (Hauptrechner, Laptop, Mobile), zähl das vorher durch.
  • Manche Aktionen (siehe Verfuegbare Aktionen) verlangen zusätzlich den Token-Scope full statt macros — das ist unabhängig vom Plan, sondern eine reine Scope-Frage beim Token selbst.

Token-Verwaltung

Im Tab Hardware-Tokens auf /dashboard/streamdeck (API: GET/POST /v1/streamdeck/tokens, DELETE /v1/streamdeck/tokens/{id}) legst du pro Gerät ein eigenes Token an. Zwei Scopes stehen zur Wahl:

  • macros — reicht für Macro-Trigger und Soundboard-Wiedergabe.
  • full — enthält macros implizit, zusätzlich Panic-Mode, Test-Alerts, Moderations-Aktionen (Ban/Timeout/Clear/Slow-Mode) und OBS-Steuerung über den Deck-Pfad.

Wichtige Eigenschaften:

  • Server speichert nur sha256(token) — das Klartext-Token siehst du nur einmal beim Erstellen. Verloren = neues Token erzeugen, altes widerrufen.
  • TTL 365 Tage. last_used_at und use_count werden bei jedem Call aktualisiert — du siehst also, ob ein Token überhaupt noch benutzt wird.
  • Rate-Limit: 5 Requests/Sekunde pro Token (eigener Redis-Bucket je Token, kein gemeinsames Limit über alle Tokens eines Accounts).

Was Macros & Stream-Deck NICHT macht

  • Kein fertiges Elgato-Icon-Set — du konfigurierst eine generische HTTP-Request-Aktion in deiner Deck-Software selbst (siehe Setup-Seite für ein konkretes Beispiel).
  • Kein Channel-Points-Reward-Trigger, kein StoryQuest-Choice-Setzen, kein Counter-Inkrement und kein „echter" simulierter Hype-Train über diese API — diese Aktionen existieren in der API schlicht nicht (siehe Verfuegbare Aktionen für die reale Liste).
  • Lighting, TTS-Sprachausgabe und Cinematics laufen bewusst nicht direkt über diesen Weg, sondern nur über die Automation-Engine — Details ebenfalls auf der Aktionen-Seite.

Sicherheits-Notiz

Das Bearer-Token ist sensibel — wer es hat, kann in deinem Namen Sounds abspielen, Macros auslösen und bei Scope full sogar Chat moderieren (Ban/Timeout/Clear) und OBS steuern. Halt es lokal in der Deck-Software, teil es nicht per Chat/Discord und nicht in Screenshots. Bei Verdacht auf Kompromittierung: Token im Tab „Hardware-Tokens" sofort löschen und neu erzeugen.

Weiterführend: Setup für die Schritt-für-Schritt-Einrichtung, Verfuegbare Aktionen für die vollständige, code-geprüfte Endpoint-Liste.