spiritual-dev/explainer-short

Was macht explainer-short?

Erstelle ein kurzes vertikales Erklärvideo: Sprecher in der unteren Hälfte, Bewegungsgrafiken in der oberen Hälfte, große Untertitel-Chips in der Mitte. Ein Clip pro Idee. Theme-Tokens steuern Farbe, Schriftart, Radius und Bewegung, sodass das gleiche Skript warm, monochrom, kontrastreich oder verspielt wirken kann.

Wann verwenden

• Ein 8-30 Sekunden langes vertikales Lehr- oder Produkt-Erklärvideo
• Eine wiederverwendbare HTML/Canvas-Pipeline, die MP4 exportiert
• Austauschbare visuelle Themes ohne Umschreiben des Szenencodes

Layout

+---------------------------+
|   motion / cards (1080)   |
|                           |
|---------------------------|  <- Untertitel-Chip an der Naht
|   presenter crop (960)    |
|                           |
+---------------------------+
         1080 x 1920

Theme-System

Themes liegen in template/themes/*.json (und sample/themes/ für die Demo). Das aktive Theme ist theme.json im Projektordner.

bash template/scripts/use-theme.sh warm          # oder mono | high-contrast | playful
# oder aus einem kopierten Projekt:
bash scripts/use-theme.sh mono

Tokens (CSS-Variablen nach loadTheme):

Token	Rolle
--ink --mute	Text
--bg --bg-hi --bg-lo	Bühnenuntergrund
--surface --surface-2	Karten
--accent --accent-2 --accent-3	Hervorhebungen
--chip-bg --chip-fg	Untertitel-Chip
--radius-card --radius-chip --chip-size	Formen
--headline-weight	Schriftgewicht der Überschrift
--font-sans --font-mono	Schriftart (OFL woff2 in fonts/)

Voreinstellungen: warm (Standard), mono, high-contrast, playful.

Bearbeite eine JSON-Datei, führe use-theme.sh erneut aus, lade neu. Kein Build-Schritt für das Theme selbst.

Schriftart wechseln

1. Lege eine quelloffene woff2 in fonts/ ab und behalte die Lizenzdatei daneben.
2. Setze fonts.sans / fonts.sans_file (und mono) in der Theme-JSON.
3. Passe @font-face in index.html an die neue Datei an, wenn sich der Schriftfamilienname ändert.
4. Rendere einen Standbild-Midframe und überprüfe.

Mitgelieferte Standardeinstellungen: Inter + JetBrains Mono (SIL OFL). Lizenztexte sind unter fonts/ beigelegt.

Schnellstart (Theme-Demo, ohne Talking-Head-Aufnahme)

npm install
node scripts/render_sample.mjs warm
node scripts/render_sample.mjs mono
# Ausgabe: sample/out/<preset>/<preset>.mp4 + Standbilder

Erfordert: Node 18+, systemweites Chrome oder Chromium, ffmpeg.

Vollständige Projekt-Pipeline (eigenständig)

1. Kopiere template/ in einen neuen Projektordner (oder arbeite innerhalb von sample/).
2. Schreibe Szenen in main.js, die window.render(t) aufrufen und CSS-Variablen aus dem Theme verwenden.
3. Optional Talking-Head: Lege eine Aufnahme ab, fülle src/edit.json, führe python3 src/edit.py aus (benötigt numpy + soundfile), dann python3 src/captions.py.
4. Vom Skill-Stammverzeichnis (nach npm install):

PRESET=warm bash template/build.sh
# oder für ein kopiertes Projekt:
SKILL_ROOT=/path/to/explainer-short PRESET=mono bash build.sh
# oder den Renderer direkt aufrufen:
node scripts/render.mjs --dir path/to/project --preset warm --out path/to/project/out/video.mp4

5. Wenn out/voice.wav vorhanden ist, normalisiert python3 mix.py auf etwa -14 LUFS / -1 dBTP und build.sh multiplexed es.

template/scripts/render.mjs wird auch neben die Vorlage kopiert, sodass ein Projekt eine lokale Kopie behalten kann.

Designregeln

1. Eine Idee. Ein Objekt, ein Versprechen, das vor dem Ende eingelöst wird.
2. Lesbar auf Armeslänge. Große Schrift, hoher Kontrast, wenige Wörter auf dem Bildschirm.
3. Untertitel-Chips sind die Stimme. Halte die Hinweise kurz; friere kurz auf dem letzten Wort ein.
4. Theme, nicht hartkodieren. Farben, Radien und Chip-Größe kommen aus Tokens.
5. Geschmacksneutrale Voreinstellung. Warm ist die Standardeinstellung; die Person wählt eine Voreinstellung.

Vor dem Versand prüfen

Bewerte jede Achse mit 0-3. Versende nur, wenn der Mittelwert mindestens 2,3 beträgt. Ein unabhängiger Prüfer bewertet die Hauptdatei.

Achse	Worauf achten
Einfrieren	Letzter Untertitel hält ~0,3-0,5s; kein Schnitt mitten im Wort
Lautstärke	Etwa -14 LUFS integriert (messen mit ffmpeg loudnorm)
True Peak	<= -1 dBTP
Abdeckung	Endframe oder thumbnailOffset ist eine klare Titelkarte
Theme	Tokens angewendet; keine verbleibenden hartkodierten Markenfarben
Klarheit	Ein Fremder versteht den Punkt ohne Audio

Vollständige Bewertungsmatrix: references/review-rubric.md. Sichere Zonen: references/cover.md.

Dateien

Pfad	Rolle
package.json	Deklariert playwright-core
template/	Starter-Projekt (HTML, Theme, Schriftarten, build.sh)
template/themes/	Voreinstellungs-JSON
template/theme.js	loadTheme() -> CSS-Variablen auf :root
sample/	Eigenständige 12s-Theme-Demo
scripts/render.mjs	Headless Frame-Rendering + ffmpeg Mux
scripts/render_sample.mjs	Komfortwrapper für Beispiel-Voreinstellungen
references/	Struktur, Themes, Bewertungsmatrix, Abdeckung, Abschluss
docs/	Vorschaustandbilder aus verifizierten Läufen

Agent-Checkliste

• npm install im Skill-Stammverzeichnis ausgeführt
• Theme-Voreinstellung gewählt (oder warm als Standard)
• theme.json entspricht der Voreinstellung
• Szenen verwenden CSS-Variablen, keine hartkodierten Markenfarben
• Beispiel oder vollständiger Build produziert MP4
• ffprobe bestätigt 1080x1920 und erwartete Dauer
• Standbild-Midframe entspricht der Voreinstellung im Markendesign
• Lautstärke ~ -14 LUFS und True Peak <= -1 dBTP, wenn Audio vorhanden ist
• Bewertungsmatrix-Mittelwert >= 2,3
• Keine persönlichen oder Drittanbieter-Markenreste im Projekt