OBS Overlay · Einbau-Anleitung · v1.0

Ehre Overlay

Drei Sammelkarten deiner Gäste fliegen flachliegend ins Bild, richten sich auf, mischen sich und verschwinden in den Ecken. Ausgelöst per Chat-Befehl. Einzelne Karten als Shoutout.

In fünf Minuten fertig

Ordner entpacken und irgendwohin legen (Desktop ist völlig okay).
Kartenbilder in medien/friends legen – Dateiname = Kanalname.
Server-starten doppelklicken (Windows: läuft unsichtbar im Hintergrund, macOS: Fenster offen lassen).
In OBS eine Browser-Quelle mit der URL aus Schritt 4 anlegen.
Im Chat !ehre tippen.

1 · Was im Paket liegt

Ehre-Overlay.dc.html	Das Overlay. Diese Datei kommt in OBS.
support.js	Laufzeit. Muss immer neben dem Overlay liegen.
medien/friends/	Hier kommen deine Sammelkarten hinein.
Server-starten.vbs	Startet den lokalen Server (Windows), unsichtbar im Hintergrund.
Server-beenden.bat	Beendet den Server wieder (Windows).
Server-starten-Mac.command	Startet den lokalen Server (macOS).
Sammelkarten-Prompt	Vorlage, um passende Karten für deine Gäste erstellen zu lassen.
LIESMICH.txt	Die Kurzfassung dieser Anleitung.

Der ganze Ordner bleibt zusammen. Verschiebe einzelne Dateien nicht heraus – das Overlay findet sonst seine Laufzeit und seine Karten nicht. Nutzt du noch weitere Overlays (z. B. Dalli-Klick oder Say-Cheese), braucht jedes seinen eigenen Ordner – niemals die Dateien mehrerer Overlays in einen gemeinsamen Ordner mischen, sonst überschreiben sich gleichnamige Dateien. Die Ordner nebeneinander liegen zu haben (z. B. alle zusammen in einem Ordner „Meine Overlays") ist dagegen problemlos.

2 · Karten vorbereiten

Jede Karte ist ein Bild in medien/friends. Erlaubt sind PNG, JPG, WEBP, GIF und AVIF.

Dateiname = Kanalname. Aus beispielkanal.png wird der Shoutout !sk beispielkanal. Groß-/Kleinschreibung, Unterstriche und Punkte sind egal.
Format: Hochkant im Verhältnis 500 : 740 (ca. 1 : 1,48). Empfohlene Exportgröße 1000 × 1480 px – dann bleibt die Karte auch auf großen Screens scharf.
Andere Seitenverhältnisse gehen auch. Das Overlay skaliert jedes Bild proportional in den Rahmen ein, nichts wird verzerrt oder beschnitten. Eine quadratische Karte erscheint dadurch nur kleiner als eine hochkantige.
PNG mit Transparenz funktioniert und sieht bei ausgestanzten Kartenformen am besten aus.
Dateigröße pro Karte gern unter 1 MB – das Overlay lädt vor jeder Animation nach.

Neue Karten einfach hineinlegen. Der Ordner wird beim Start und vor jedem einzelnen Aufruf neu eingelesen – kein Neustart, keine Liste pflegen. Solange der Ordner leer ist, zeigt das Overlay drei schlichte Beispielkarten, damit du die Animation trotzdem testen kannst.

3 · Den lokalen Server starten (Pflicht)

Warum das nötig ist: Das Overlay liest seinen Kartenordner selbst aus. Als „Lokale Datei“ (file://) verbietet der Browser in OBS genau das aus Sicherheitsgründen – es kämen nie Karten an. Deshalb läuft das Overlay über eine lokale Adresse, die nur auf deinem Rechner existiert. Nichts davon geht ins Internet.

Windows: Doppelklick auf Server-starten.vbs. macOS: Rechtsklick auf Server-starten-Mac.command → Öffnen (beim ersten Mal, wegen der Gatekeeper-Warnung).

Windows: Der Server startet unsichtbar im Hintergrund, es erscheint kein Fenster. Zum Beenden: Server-beenden.bat doppelklicken. Ob der Server läuft, steht in server-log.txt im selben Ordner. macOS: Es öffnet sich ein Fenster mit einer Zeile wie Serving HTTP on … – dieses Fenster muss während des Streams offen bleiben, Minimieren ist okay, schließen nicht.

Windows: Es muss nichts installiert werden – die nötige Laufzeit liegt schon im Ordner runtime bei. Von Hand geht es genauso – Terminal im Paket-Ordner öffnen und eingeben:

runtime\node.exe server.js

macOS: braucht einmalig Node.js (LTS-Version von nodejs.org). Fehlt es, öffnet das Startskript die Download-Seite von selbst. Das Terminal-Fenster des Skripts bleibt während des Streams offen.

4 · In OBS einrichten

Quellen → + → Browser → Name z. B. „Ehre“.
Häkchen „Lokale Datei“ NICHT setzen. Stattdessen die URL eintragen.
Breite 1920, Höhe 1080.
Benutzerdefiniertes CSS: leer lassen. Der Hintergrund ist schon transparent.
„Quelle beim Unsichtbarwerden abschalten“ aus – sonst reißt die Chat-Verbindung ab.
„Browser-Quelle beim Szenenwechsel neu laden“ ebenfalls aus.
Die Quelle über Gameplay/Kamera legen und auf die ganze Leinwand ziehen.

Die URL – deinen Kanalnamen einsetzen:

http://localhost:8080/Ehre-Overlay.dc.html?channel=DEINKANAL&demo=0&status=0

Zum Einrichten und Testen lohnt es sich, demo=0&status=0 zunächst weglassen: dann läuft die Animation alle 20 Sekunden von allein und unten links steht, wie viele Karten gefunden wurden. Für den Livebetrieb beide wieder setzen.

Parameter	Bedeutung
channel=	Dein Twitch-Kanal, dessen Chat gelesen wird. Pflicht, sonst reagiert kein Befehl.
demo=0	Schaltet die Vorschau-Dauerschleife ab. Im Livebetrieb setzen.
status=0	Versteckt die Statuszeile unten links.
folder=	Anderer Kartenordner, z. B. `folder=medien/staffel2`.
cmd=	Eigener Dreier-Befehl statt `!ehre`.
sk=	Eigener Shoutout-Befehl statt `!sk`.
hold=	Standzeit der Karten in Sekunden (Standard 7).
cooldown=	Sperrzeit zwischen zwei Aufrufen in Sekunden (Standard 20, `0` = aus).

5 · Befehle im Chat

!ehre Drei zufällige Karten, komplette Animation mit Mischen.

!sk kanalname Eine bestimmte Karte, mittig, ohne Mischen. Groß-/Kleinschreibung, ein @ davor und ein voller twitch.tv-Link sind egal.

Findet das Overlay keine passende Datei, passiert nichts – die Statuszeile nennt den Grund. Ein Cooldown von 20 Sekunden verhindert Spam; Mods und Broadcaster umgehen ihn. Das Overlay liest den Chat anonym mit – kein Login, kein Token, keine Bot-Anbindung nötig.

6 · Testen ohne Chat

Rechtsklick auf die Quelle in OBS → Interagieren. In diesem Fenster:
Taste G – Dreier-Animation sofort auslösen.
Taste S – zufällige Einzelkarte auslösen.
Alternativ die URL einfach im normalen Browser öffnen: gleiche Tasten, bequemeres Vorschauen.

7 · Wenn etwas nicht klappt

Alles bleibt schwarz/leer	Server nicht gestartet oder über `Server-beenden.bat` beendet? Neu starten. Oder in OBS war „Lokale Datei“ angehakt – Häkchen weg, URL eintragen.
„keine Karten gefunden – Beispiel“	Der Ordner `medien/friends` ist leer oder liegt woanders. Er muss direkt neben dem Overlay liegen.
Port 8080 ist belegt	Ein anderes Programm blockiert den Port. Dieses beenden und den Server neu starten (Windows: `server.js` hat den Port fest auf 8080 eingestellt).
„runtime\node.exe fehlt“ (Windows)	Der Ordner wurde nicht vollständig entpackt. Die ZIP-Datei erneut komplett entpacken.
„Node.js wurde nicht gefunden“ (macOS)	Node.js (LTS) von nodejs.org installieren (Schritt 3) und das Startskript erneut doppelklicken.
Chat-Befehl tut nichts	Steht `?channel=` in der URL und stimmt der Name? Die Statuszeile zeigt den verbundenen Kanal. Sonst läuft evtl. noch der Cooldown.
Ordner-Auslesen klappt nicht	Manche Server liefern kein Verzeichnis-Listing. Dann eine `friends.json` in den Kartenordner legen: `["kanal1.png", "kanal2.png"]`. Die hat Vorrang.
Karte wirkt klein	Das Bild ist nicht hochkant. Auf 1000 × 1480 px zuschneiden.

8 · Ablauf der Animation

Karten kommen flachliegend von unten heran (2,6 s) → richten sich auf (0,9 s) → stehen 7 s → mischen sich einmal (1,3 s) → verschwinden blitzschnell in drei verschiedene Ecken (0,6 s). Gesamt rund 13 Sekunden. Beim Einzel-Shoutout entfällt das Mischen.

Dieses Overlay wird kostenlos angeboten. Nutzen, anpassen und weitergeben ist ausdrücklich erlaubt – gern mit einem Hinweis auf die Herkunft. Es gibt keine Garantie und keinen Support-Anspruch. Für die Bilder in deinem Kartenordner bist du selbst verantwortlich.