📡 OBS Plugin + 🎛 StreamDeck

WebSocket-Bridge zwischen OBS/StreamDeck und Codenull Backend. Hardware Control für den Stream.

💡 Zwei Module, eine Verbindung

📡 OBS Plugin

Custom OBS Plugin (oder Lua Script) das eine WebSocket-Verbindung zu Codenull herstellt. OBS → Backend: Scene/Source Status, Stream Info. Backend → OBS: Scene Switch, Source Toggle, Filter Control.

  • Bidirektionale Kommunikation
  • OBS Events → Workflow Trigger
  • Workflow Actions → OBS Control
  • Custom Docks im OBS Panel

🎛 StreamDeck Plugin

Elgato StreamDeck Plugin das über Codenull API kommuniziert. Hardware-Buttons für: Scene Switch, Timer Control, Clip erstellen, Sound abspielen, Custom Actions.

  • API-Key Auth (kein OAuth nötig)
  • Konfigurierbare Actions pro Button
  • Visual Feedback (Icons, Status)
  • Multi-Action Support
🏗 Architektur
🎛 StreamDeck
HTTP API Calls
→
Codenull API
ORPC + API Key
↔
Redis
Events + Jobs
↔
WS Events
WebSocket Hub
↔
📡 OBS Plugin
WebSocket Client
StreamDeck → API (Request/Response) · OBS ↔ WebSocket (Bidirektional, Real-Time)

OBS: WebSocket Client

OBS Plugin verbindet sich zu wss://ws.codenull.de. Auth per API-Key im Header. Persistent Connection mit Auto-Reconnect.

StreamDeck: HTTP API

StreamDeck Plugin macht REST Calls zu https://media.codenull.de/rpc/.... API-Key Auth. Kein WebSocket nötig — Request/Response reicht.

Shared: Workflow Actions

Beide nutzen dieselben Workflow Actions. StreamDeck-Button = "Execute Action X". OBS Event = Workflow Trigger. Alles über die Engine.

📡 OBS Plugin — Detail

Was OBS sendet und was es empfängt

OBS → Codenull (Events)

SEND obs.scene.changed
{ scene: "Gaming", prev: "Just Chatting" }
SEND obs.streaming.started
{ output: "srt://stream.codenull.de:8890" }
SEND obs.streaming.stopped
{ duration: 7234 }
SEND obs.recording.started
{ path: "D:/recordings/2026-03-18.mkv" }
SEND obs.source.muted
{ source: "Mikrofon", muted: true }
SEND obs.source.visibility
{ source: "Webcam", visible: false }
SEND obs.stats
{ fps: 60, cpu: 12.3, kbps: 6000, dropped: 0 }

→ Alles = Workflow Trigger

Scene Switch → Auto-Mute Mic. Stream Start → Discord Notification. Recording Stop → Auto-Upload. CPU > 80% → Alert.

Codenull → OBS (Commands)

RECV obs.scene.switch
{ scene: "BRB Screen" }
RECV obs.source.toggle
{ source: "Webcam", visible: true }
RECV obs.source.mute
{ source: "Desktop Audio", muted: true }
RECV obs.filter.toggle
{ source: "Webcam", filter: "Blur", enabled: true }
RECV obs.source.settings
{ source: "Text", settings: { text: "BRB 5min" } }
RECV obs.transition.trigger
{ transition: "Stinger", duration: 500 }
RECV obs.screenshot
{ source: "Game Capture", format: "png" }

→ Alles = Workflow Action

Donation > €50 → Scene Switch zu "Thank You" für 10s. Raid > 100 → Stinger Transition. Chat Command → Toggle Webcam.

🔧 OBS Plugin — Implementation

→ OBS Bridge im Codenull Client

Die OBS Bridge läuft als Background Service im Codenull Client (ehemals Desktop Editor). Der Client wird zu einer vollwertigen Streaming-Companion App umgebaut. Die Bridge hält zwei WebSocket-Verbindungen: eine zu OBS (ws://localhost:4455 via obs-websocket-js) und eine zu Codenull (wss://ws.codenull.de). Events werden bidirektional weitergeleitet.

OBS ←obs-websocket→ Codenull Client (Bun Background Service) ←WebSocket→ Codenull Backend

🖥 Codenull Client (ehemals Desktop Editor)

Rename + Erweiterung. Der Client wird zur zentralen Streaming-Companion App:

Codenull Client (Electrobun) ├── Editor UI — Video/Audio Player + Clip Export (wie jetzt) ├── Settings — API Key, OBS Verbindung, Auto-Start └── Background Service ├── OBS Bridge — obs-websocket ↔ Codenull WS ├── Tray Icon — Status: Connected / Disconnected / Error └── Auto-Start — Startet mit Windows, immer verbunden
📋 OBS Custom Docks

Browser Docks die in OBS eingebettet werden (View → Docks → Custom Browser Docks)

📋 Events Filter ▾
Follow NewViewer123 2s
Sub T1 xXGamerXx 15s
€25 DankDonator 1m
Raid 87 FriendlyStr 3m
⏱ Timers + New
🏆 Subathon 04:23:12
⏱ Stream 02:34:56
💀 Deaths 42
🎬 Quick Actions
💬 Chat Twitch
Mod1: Willkommen!
xXGamer: GG das war nice
Sub42: LUL LUL LUL
📊 Viewer Stats
👁 Viewers 234
📈 Peak 312
💬 Chat/min 18
👤 New Follows +23
🎨 Overlay
🔔 Alerts
💬 Chat Widget
📊 Sub Goal
6 Docks als Browser Panels in OBS. URLs: https://codenull.de/obs/{dock}?token=xxx · Auth per API-Key Token
🎛 StreamDeck Plugin — Detail

Hardware-Buttons für alle Codenull Actions

Button Actions

🎬 Scene

  • Switch Scene
  • Toggle Source
  • Mute/Unmute

⏱ Timer

  • Start/Stop/Pause
  • Counter +/-
  • Subathon Toggle

🎬 Media

  • Create Clip
  • Screenshot
  • Play Sound

💬 Chat

  • Send Message
  • Run Command
  • Clear Chat

🔔 Overlay

  • Toggle Widget
  • Test Alert
  • Mute Alerts

⚡ Custom

  • Execute Workflow
  • HTTP Request
  • Multi-Action

StreamDeck Preview

🎮Gaming
💬Chat
☕BRB
🔴END
🎵Music
🔇Mute Mic
📷Webcam
✂️Clip
📸Screen
🔔Test Alert
⏱Timer
💀Death +1
🏆Subathon
📊Goal
⚡Custom

Visual Feedback

Buttons zeigen Status: Mic Muted = rotes Icon, Scene Active = grüner Rand, Timer laufend = Countdown auf Button, Subathon = verbleibende Zeit.

🔧 StreamDeck — Implementation

Elgato SDK

  • StreamDeck SDK v6 (JavaScript/TypeScript)
  • Plugin läuft als Node.js Prozess
  • Property Inspector: Konfiguration per Button
  • Dynamic Images: Icon-Updates basierend auf Status
  • @elgato/streamdeck npm Package

Codenull API Client

  • API-Key aus Admin Panel (Settings → API Keys)
  • HTTP Calls zu ORPC Endpoints
  • Optional: WebSocket für Live-Status Updates
  • Retry + Error Handling
  • Shared Types mit Backend (@codenull/shared)
🔑 API-Key System (Shared)

Für OBS Bridge + StreamDeck + externe Integrationen

apiKey id text PK userId text FK // Owner name text // "OBS Bridge", "StreamDeck", "Custom Integration" key text unique // cnk_xxxxxxxxxxxxxxxx (hashed in DB) permissions text[] // ["obs.scene.switch", "timer.*", "clip.create"] lastUsedAt timestamp? expiresAt timestamp? // null = never expires isActive boolean createdAt timestamp

🔐 Scoped Permissions

Jeder Key hat nur die Rechte die er braucht. OBS Bridge: obs.*. StreamDeck: obs.*, timer.*, clip.create. Kein Master-Key nötig.

🔄 Key Management

Erstellen, Rotieren, Löschen im Admin Panel (Settings → API Keys). Letzter Zugriff wird geloggt. Ablaufdatum optional.

📊 Usage Tracking

Requests pro Key zählen. Rate Limiting pro Key (z.B. 100 req/min). Anomalie-Erkennung bei ungewöhnlich vielen Requests.

✅ Entscheidungen

Geklärt am 2026-03-18

1. OBS Bridge im Codenull Client

Kein separates Plugin, kein Lua, kein C++. Die OBS Bridge ist ein Background Service im Codenull Client (Electrobun). Nutzt obs-websocket-js. Tray Icon zeigt Verbindungsstatus. Auto-Start mit Windows.

2. Alle StreamDeck Modelle

Standard (15 Keys), Mini (6 Keys), XL (32 Keys), Plus (8 Keys + 4 Dials + Touchscreen), Mobile App. Elgato SDK v6 unterstützt alle Modelle mit einem Plugin.

3. 6 OBS Docks

Events, Timers, Quick Actions, Chat, Viewer Stats, Overlay Control. Alle als Browser Docks über codenull.de/obs/{dock}?token=xxx. Auth per API-Key.

4. Desktop Editor → Codenull Client

Rename der App. Der Client wird zur zentralen Streaming-Companion App: Editor + OBS Bridge + Tray + Auto-Start. Ein Installer für alles.

Codenull Platform · OBS Plugin + StreamDeck Module Planning · 2026-03-18