Communitygithub.com

sairam0424/MindForge

Erstelle HTML-basierte Videokompositionen, animierte Titelcards, Social-Overlays, untertitelte Talking-Head-Videos, audio-reaktive Visualisierungen und Shader-Übergänge mit HyperFrames. HTML ist die alleinige Quelle für das Video. Verwende diesen Skill, wenn der Benutzer ein gerendertes MP4/WebM aus einer HTML-Komposition wünscht, Text/Logos/Diagramme über Medien animieren, mit Audio synchronisierte Untertitel benötigt, TTS-Erzählung oder eine Website in ein Video umwandeln möchte.

Was ist MindForge?

MindForge ist ein KI-Agenten-Skill, der auf dem HyperFrames-Framework basiert und es ermöglicht, Videos aus HTML/CSS/JS-Kompositionen zu erstellen. Der Skill dient als Bindeglied zwischen kreativen HTML-Animationen und der endgültigen Ausgabe als MP4/WebM-Datei, wobei ein Headless-Browser jede Bildsequenz erfasst und FFmpeg zur Kodierung verwendet. Er unterstützt eine breite Palette von Anwendungsfällen, darunter animierte Titelcards, untertitelte Talking-Head-Videos mit TTS, audio-reaktive Visualisierungen, Shader-Übergänge zwischen Szenen und die Umwandlung von Websites in Video-Promos. Der Workflow umfasst die Planung einer visuellen Identität, das Erstellen statischer Layouts (Hero-Frames), das Hinzufügen von GSAP-Animationen, das Einbinden von Audio/Untertiteln und das anschließende Linten, Validieren und Rendern. Eine wichtige Voraussetzung ist die Installation von Node.js >= 22, FFmpeg und die Vorspeicherung von Chrome Headless Shell über Puppeteer für eine zuverlässige Wiedergabetreue. Der Skill ist als Ergänzung zu `manim-video` für mathematische Animationen konzipiert und eignet sich ideal für Bewegungsgrafiken, Produkt-Touren, Social-Media-Overlays und interaktive HTML-basierte Videoproduktionen für Entwickler und Content-Ersteller.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sairam0424/MindForge/tree/HEAD/.agent/skills/hyperframes

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

HyperFrames

HTML ist die alleinige Quelle für das Video. Eine Komposition ist eine HTML-Datei mit data-*-Attributen für das Timing, einer GSAP-Timeline für die Animation und CSS für das Erscheinungsbild. Die HyperFrames-Engine erfasst die Seite Bild für Bild und kodiert sie mit FFmpeg in MP4/WebM.

Ergänzung zu manim-video: Verwende manim-video für mathematische/geometrische Erklärvideos (Gleichungen, 3B1B-Stil). Verwende hyperframes für Bewegungsgrafiken, Talking-Head mit Untertiteln, Produkt-Touren, Social-Overlays, Shader-Übergänge und alles, was von echten Video-/Audiomedien angetrieben wird.

Wann verwenden

  • Der Benutzer fragt nach einem gerenderten Video aus Text, einem Skript oder einer Website
  • Animierte Titelcards, untere Drittel oder typografische Einleitungen
  • Untertitelte Erzählvideos (TTS + Untertitel synchron zur Wellenform)
  • Audio-reaktive Visualisierungen (Beatsynchronisation, Spektrumbalken, pulsierendes Leuchten)
  • Szenenübergänge (Crossfade, Wipe, Shader-Warp, Flash-Through-White)
  • Social-Overlays (Instagram/TikTok/YouTube-Stil)
  • Website-zu-Video-Pipeline (eine URL erfassen, einen Promo erstellen)
  • Jede HTML/CSS/JS-Animation, die deterministisch in eine Videodatei gerendert werden muss

Verwende diesen Skill nicht für:

  • Reine Mathematik-/Gleichungsanimation (→ manim-video)
  • Bildgenerierung oder Memes (→ meme-generation, Bildmodelle)
  • Live-Videokonferenzen oder Streaming

Kurzreferenz

npx hyperframes init my-video               # Projektstruktur anlegen
cd my-video
npx hyperframes lint                        # Vor Vorschau/Rendering validieren
npx hyperframes preview                     # Live-Reload-Browser-Vorschau (Port 3002)
npx hyperframes render --output final.mp4   # Rendern in MP4
npx hyperframes doctor                      # Umgebungsprobleme diagnostizieren

Render-Flags: --quality draft|standard|high · --fps 24|30|60 · --format mp4|webm · --docker (reproduzierbar) · --strict.

Vollständige CLI-Referenz: references/cli.md.

Einrichtung (einmalig)

bash "$(dirname "$(find ~/.agent/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"

Das Skript:

  1. Überprüft, ob Node.js >= 22 und FFmpeg installiert sind (gibt Reparaturanweisungen aus, wenn nicht).
  2. Installiert das hyperframes-CLI global (npm install -g hyperframes@>=0.4.2).
  3. Speichert chrome-headless-shell über Puppeteer zwischen – erforderlich für qualitativ hochwertiges Rendering über den HeadlessExperimental.beginFrame-Erfassungspfad von Chrome.
  4. Führt npx hyperframes doctor aus und meldet das Ergebnis.

Siehe references/troubleshooting.md, wenn die Einrichtung fehlschlägt.

Vorgehensweise

1. Vor dem Schreiben von HTML planen

Bevor Code geschrieben wird, sollten auf hoher Ebene folgende Punkte geklärt werden:

  • Was – Erzählbogen, Schlüsselmomente, emotionale Höhepunkte
  • Struktur – Kompositionen, Spuren (Video/Audio/Overlays), Dauern
  • Visuelle Identität – Farben, Schriftarten, Bewegungscharakter (explosiv / filmisch / fließend / technisch)
  • Hero-Frame – für jede Szene der Moment, in dem die meisten Elemente gleichzeitig sichtbar sind. Dies ist das statische Layout, das zuerst erstellt wird.

Gate der visuellen Identität (HARD-GATE). Bevor irgendeine Kompositions-HTML geschrieben wird, muss eine visuelle Identität definiert sein. Schreibe KEINE Kompositionen mit Standard- oder generischen Farben (#333, #3b82f6, Roboto sind Anzeichen, dass dieser Schritt übersprungen wurde). Überprüfe in dieser Reihenfolge:

  1. DESIGN.md im Projektstamm? → Verwende die genauen Farben, Schriftarten, Bewegungsregeln und "Was NICHT zu tun"-Einschränkungen.

  2. Benutzer hat einen Stil genannt (z. B. "Swiss Pulse", "dark und technisch", "Luxusmarke")? → Generiere eine minimale DESIGN.md mit ## Style Prompt, ## Colors (3-5 Hex mit Rollen), ## Typography (1-2 Familien), ## What NOT to Do (3-5 Anti-Patterns).

  3. Nichts davon? → Stelle 3 Fragen, bevor HTML geschrieben wird:

    • Stimmung? (explosiv / filmisch / fließend / technisch / chaotisch / warm)
    • Helle oder dunkle Leinwand?
    • Irgendwelche Markenfarben, Schriftarten oder visuellen Referenzen?

    Generiere dann eine DESIGN.md aus den Antworten. Jede Komposition muss ihre Palette und Typografie auf DESIGN.md oder eine explizite Benutzeranweisung zurückführen.

2. Grundgerüst erstellen

npx hyperframes init my-video --non-interactive

Vorlagen: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph. Übergib --example <name> zur Auswahl, --video clip.mp4 oder --audio track.mp3 zum Einbetten von Medien.

3. Layout vor Animation

Schreibe zuerst das statische HTML+CSS für den Hero-Frame – noch kein GSAP. Der .scene-content-Container muss die Szene ausfüllen (width:100%; height:100%; padding:Npx) mit display:flex + gap. Verwende Padding, um Inhalte nach innen zu schieben – verwende niemals position: absolute; top: Npx auf einem Inhaltscontainer (Inhalte laufen über, wenn sie höher als der verbleibende Platz sind).

Erst wenn der Hero-Frame richtig aussieht, füge gsap.from()-Eintritte (zu CSS-Position hin animieren) und gsap.to()-Austritte (von dieser Position weg animieren) hinzu.

Siehe references/composition.md für das vollständige Datenattribut-Schema und die Kompositionsregeln.

4. Mit GSAP animieren

Jede Komposition muss:

  • Ihre Timeline registrieren: window.__timelines["<composition-id>"] = tl
  • Pausiert starten: gsap.timeline({ paused: true }) – der Player steuert die Wiedergabe
  • Endliche repeat-Werte verwenden (kein repeat: -1 – bricht die Erfassungsmaschine). Berechne: repeat: Math.ceil(dauer / zyklusDauer) - 1.
  • Deterministisch sein – kein Math.random(), Date.now() oder Wall-Clock-Logik. Verwende einen gesetzten PRNG, wenn du Pseudozufälligkeit benötigst.
  • Synchron aufbauen – kein async/await, setTimeout oder Promises um den Timeline-Aufbau.

Siehe references/gsap.md für die grundlegende GSAP-API (Tweens, Eases, Stagger, Timelines).

5. Übergänge zwischen Szenen

Kompositionen mit mehreren Szenen erfordern Übergänge. Regeln:

  1. Verwende immer einen Übergang zwischen Szenen – keine harten Schnitte.
  2. Verwende immer Eintrittsanimationen auf jedem Szenenelement (gsap.from(...)).
  3. Verwende niemals Austrittsanimationen außer in der letzten Szene – der Übergang IST der Austritt.
  4. Die letzte Szene kann ausblenden.

Verwende npx hyperframes add <übergangsname>, um Shader-Übergänge zu installieren (flash-through-white, liquid-wipe usw.). Vollständige Liste: npx hyperframes add --list.

6. Audio, Untertitel, TTS, audio-reaktiv, Hervorhebung

  • Audio: immer ein separates <audio>-Element (Video ist muted playsinline).
  • TTS: npx hyperframes tts "Skripttext" --voice af_nova --output narration.wav. Liste der Stimmen mit --list. Der erste Buchstabe der Stimmen-ID kodiert die Sprache (a/b=Englisch, e=Spanisch, f=Französisch, j=Japanisch, z=Mandarin usw.) – das CLI leitet das Phonemizer-Locale automatisch ab; übergib --lang nur, um es zu überschreiben. Nicht-englische Phonemisierung erfordert systemweit installiertes espeak-ng.
  • Untertitel: npx hyperframes transcribe narration.wav → Worttranskript. Wähle einen Stil basierend auf dem Tonfall des Transkripts (Hype / Corporate / Tutorial / Storytelling / Social – siehe Tabelle in references/features.md). Sprachregel: Verwende niemals .en-Whisper-Modelle, es sei denn, das Audio ist nachweislich Englisch – .en übersetzt nicht-englisches Audio anstatt es zu transkribieren. Jede Untertitelgruppe MUSS einen harten tl.set(el, { opacity: 0, visibility: "hidden" }, group.end)-Kill nach ihrem Austritts-Tween haben – sonst bleiben Gruppen sichtbar und überschneiden sich mit späteren.
  • Audio-reaktive Visualisierungen: Extrahiere vorab Audio-Bänder (Bass / Mitten / Höhen) und taste sie bildweise innerhalb der Timeline mit einer for-Schleife von tl.call(draw, [], f / fps) ab – ein einzelner langer Tween reagiert NICHT auf Audio. Bilde Bass → scale (Puls), Höhen → textShadow/boxShadow (Glühen), Gesamtamplitude → opacity/y/backgroundColor. Vermeide Equalizer-Balken-Klischees – lass den Inhalt die Visualisierung leiten und das Audio ihr Verhalten steuern.
  • Marker-Hervorhebung: Hervorhebungs-, Kreis-, Burst-, Scribble-, Sketchout-Effekte zur Texthervorhebung sind deterministisches CSS+GSAP – siehe references/features.md#marker-highlighting. Vollständig suchbar, keine animierten SVG-Filter.
  • Szenenübergänge: Jede Komposition mit mehreren Szenen MUSS Übergänge verwenden (keine harten Schnitte). Wähle aus CSS-Primitiven (Push-Slide, Blur-Crossfade, Zoom-Through, gestaffelte Blöcke) oder Shader-Übergängen (flash-through-white, liquid-wipe, cross-warp-morph, chromatic-split usw.) via npx hyperframes add. Stimmungs- und Energietabellen findest du in references/features.md#transitions. Mische keine CSS- und Shader-Übergänge in derselben Komposition.

7. Linten, validieren, inspizieren, Vorschau, rendern

npx hyperframes lint              # erkennt fehlende data-composition-id, überlappende Spuren, nicht registrierte Timelines
npx hyperframes validate          # WCAG-Kontrastprüfung zu 5 Zeitpunkten
npx hyperframes inspect           # visuelle Layoutprüfung – Überlauf, Elemente außerhalb des Frames, verdeckter Text
npx hyperframes preview           # Live-Browser-Vorschau
npx hyperframes render --quality draft --output draft.mp4    # schnelle Iteration
npx hyperframes render --quality high --output final.mp4     # endgültige Auslieferung

hyperframes validate tastet Hintergrundpixel hinter jedem Textelement ab und warnt bei Kontrastverhältnissen unter 4,5:1 (bzw. 3:1 für großen Text). hyperframes inspect ist der Layout-Begleiter – führt die Seite zu mehreren Zeitpunkten aus und meldet Probleme, die ein statisches Lint nicht erkennen kann (eine Untertitel, die erst bei 4,5s über den sicheren Bereich hinausläuft, eine Karte, die überläuft, wenn ihr Titel die längste Variante ist, ein Element, das hinter einem Übergangs-Shader landet). Führe inspect besonders bei Kompositionen mit Sprechblasen, Karten, Untertiteln oder enger Typografie durch.

8. Website-zu-Video (wenn der Benutzer eine URL angibt)

Verwende den 7-Schritte-Capture-to-Video-Workflow in references/website-to-video.md: Capture → DESIGN.md → SCRIPT.md → Storyboard → Komposition → Rendern → Ausliefern.

Fallstricke

  • HeadlessExperimental.beginFrame' wurde nicht gefunden – Chromium 147+ hat dieses Protokoll entfernt. Stelle sicher, dass du hyperframes@>=0.4.2 verwendest (erkennt automatisch und fällt auf Screenshot-Modus zurück). Notausstieg: export PRODUCER_FORCE_SCREENSHOT=true. Siehe hyperframes#294 und references/troubleshooting.md.
  • System-Chrome (nicht chrome-headless-shell) – Rendervorgänge hängen für 120s und brechen dann mit Timeout ab. Führe npx puppeteer browsers install chrome-headless-shell aus (setup.sh erledigt dies). hyperframes doctor meldet, welche Binärdatei verwendet wird.
  • repeat: -1 irgendwo – bricht die Erfassungsmaschine. Berechne immer eine endliche Wiederholungszahl.
  • gsap.set() auf Clip-Elementen, die später eintreten – das Element existiert beim Laden der Seite nicht. Verwende stattdessen tl.set(selector, vars, timePosition) innerhalb der Timeline, bei oder nach dem data-start des Clips.
  • <br> innerhalb von Inhaltstext – erzwungene Umbrüche kennen die gerenderte Schriftbreite nicht, daher natürlicher Umbruch + <br> verdoppelt die Brüche. Verwende max-width, damit Text umbrechen kann. Ausnahme: kurze Anzeigetitel, bei denen jedes Wort bewusst auf einer eigenen Zeile steht.
  • Animieren von visibility oder display – GSAP kann diese nicht tweenen. Verwende autoAlpha (behandelt sowohl Sichtbarkeit als auch Deckkraft).
  • Aufrufen von video.play() oder audio.play() – das Framework besitzt die Wiedergabe. Rufe diese niemals selbst auf.
  • Asynchrones Erstellen von Timelines – die Erfassungsmaschine liest window.__timelines synchron nach dem Laden der Seite. Wickle den Timeline-Aufbau niemals in async, setTimeout oder ein Promise.
  • Eigenständiges index.html in <template> verpackt – verbirgt alle Inhalte vor dem Browser. Nur Unterkompositionen, die über data-composition-src geladen werden, verwenden <template>.
  • Verwendung von Video für Audio – immer stummgeschaltetes <video> + separates <audio>.

Überprüfung

Vor und nach dem Rendern:

  1. Lint + Validieren + Inspizieren bestanden: npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect (Lint erkennt strukturelle Probleme, Validieren erkennt Kontrastprobleme, Inspizieren erkennt visuelle Layout-/Überlaufprobleme – siehe troubleshooting.md, falls Warnungen auftreten).
  2. Animationschoreografie – für neue Kompositionen oder signifikante Animationsänderungen führe die Animationskarte aus. npx hyperframes init kopiert die Skill-Skripte in das Projekt, daher ist der Pfad projektspezifisch:
    node skills/hyperframes/scripts/animation-map.mjs <komposition-verzeichnis> \
      --out <komposition-verzeichnis>/.hyperframes/anim-map
    
    Gibt eine einzige animation-map.json mit Zusammenfassungen pro Tween, ASCII-Gantt-Timeline, Stagger-Erkennung, Totzonen (>1s ohne Animation), Elementlebenszyklen und Flags (offscreen, collision, invisible, paced-fast <0,2s, paced-slow >2s) aus. Scanne Zusammenfassungen und Flags – repariere oder begründe jedes. Überspringe bei kleinen Bearbeitungen.
  3. Datei existiert und ist nicht Null: ls -lh final.mp4.
  4. Dauer stimmt mit data-duration überein: ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4.
  5. Visuelle Prüfung: Extrahiere einen Bildausschnitt aus der Mitte der Komposition: ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png.
  6. Audio vorhanden, falls erwartet: ffprobe -v error -show_streams -select_streams a -of default=nw=1:nk=1 final.mp4 | head -1.

Wenn hyperframes render fehlschlägt, führe npx hyperframes doctor aus und hänge seine Ausgabe beim Melden an.

Referenzen

  • composition.md – Datenattribute, Timeline-Vertrag, nicht verhandelbare Regeln, Typografie-/Asset-Regeln
  • cli.md – alle CLI-Befehle (init, capture, lint, validate, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark)
  • gsap.md – GSAP-Kern-API für HyperFrames (Tweens, Eases, Stagger, Timelines, matchMedia)
  • features.md – Untertitel, TTS, audio-reaktiv, Marker-Hervorhebung, Übergänge (bei Bedarf laden)
  • website-to-video.md – 7-Schritte-Capture-to-Video-Workflow
  • troubleshooting.md – OpenClaw-Fix, Umgebungsvariablen, häufige Renderfehler

Verwandte Skills