Communitygithub.com

HyperFrames

Rendern Sie MP4/WebM-Videos aus HTML-Kompositionen.

Was ist HyperFrames?

HyperFrames ist ein KI-Agenten-Skill, der HTML als Quelle der Wahrheit für Videoproduktion nutzt. Eine Komposition ist eine HTML-Datei mit `data-*`-Attributen für das Timing, einer GSAP-Timeline für Animationen und CSS für das Erscheinungsbild. Die Engine erfasst die Seite Bild für Bild und kodiert sie mit FFmpeg in MP4/WebM. Der Skill eignet sich besonders für Bewegungsgrafiken, Sprachaufnahmen mit Untertiteln, Produkttouren, Social-Media-Overlays und Shader-Übergänge. Er ist eine Ergänzung zum `manim-video`-Skill (für mathematische Animationen) und wird über die CLI `npx hyperframes` bedient. Zu den wichtigsten Funktionen gehören die Unterstützung von TTS (Text-to-Speech), Untertiteltranskription, audio-reaktive Visualisierungen, Szenenübergänge und ein strenger visueller Identitäts-Gate-Prozess vor der Erstellung von Kompositionen. Der Skill läuft unter Node.js >= 22 und FFmpeg und nutzt Chrome Headless Shell für qualitativ hochwertige Rendering.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/jgilb17/jpg/tree/HEAD/.claude/skills/hyperframes

In Ihrer bevorzugten KI fragen

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

Dokumentation

Was macht HyperFrames?

HTML ist die Quelle der Wahrheit für Videos. Eine Komposition ist eine HTML-Datei mit data-*-Attributen für das Timing, einer GSAP-Timeline für Animationen 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: Verwenden Sie manim-video für mathematische/geometrische Erklärvideos (Gleichungen, 3B1B-Stil). Verwenden Sie hyperframes für Bewegungsgrafiken, Sprecherkopf mit Untertiteln, Produkttouren, Social-Media-Overlays, Shader-Übergänge und alles, was von echten Video-/Audiomedien gesteuert wird.

Wann verwenden

  • Benutzer fordert ein gerendertes Video aus Text, einem Skript oder einer Website an.
  • Animierte Titelcards, Lower Thirds oder typografische Intros.
  • Erzähltes Video mit Untertiteln (TTS + synchronisierte Untertitel zur Wellenform).
  • Audio-reaktive Bilder (Beatsynchronisation, Spektrumbalken, pulsierendes Leuchten).
  • Szenenübergänge (Crossfade, Wischen, Shader Warp, Flash-through-White).
  • Social-Media-Overlays (Instagram/TikTok/YouTube-Stil).
  • Website-zu-Video-Pipeline (eine URL erfassen, ein Promo-Video erstellen).
  • Jede HTML/CSS/JS-Animation, die deterministisch in eine Videodatei gerendert werden muss.

Verwenden Sie diesen Skill nicht für:

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

Kurzreferenz

npx hyperframes init my-video               # Projekt erstellen
cd my-video
npx hyperframes lint                        # Vor der Vorschau/Wiedergabe validieren
npx hyperframes preview                     # Live-Reload-Browser-Vorschau (Port 3002)
npx hyperframes render --output final.mp4   # In MP4 rendern
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 ~/.hermes/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 (zeigt bei Bedarf Reparaturanweisungen an).
  2. Installiert die hyperframes-CLI global (npm install -g hyperframes@>=0.4.2).
  3. Cached chrome-headless-shell über Puppeteer vor – erforderlich für qualitativ hochwertiges Rendering über den HeadlessExperimental.beginFrame-Capture-Pfad von Chrome.
  4. Führt npx hyperframes doctor aus und meldet das Ergebnis.

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

Vorgehen

1. Planen Sie, bevor Sie HTML schreiben

Bevor Sie Code schreiben, legen Sie auf hoher Ebene fest:

  • Was – Erzählbogen, Schlüsselmomente, emotionale Höhepunkte.
  • Struktur – Kompositionen, Spuren (Video/Audio/Overlays), Dauern.
  • Visuelle Identität – Farben, Schriftarten, Bewegungscharakter (explosiv / cineastisch / 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 Sie zuerst erstellen.

Gate der visuellen Identität (HARD-GATE). Bevor Sie EINE Kompositions-HTML schreiben, MUSS eine visuelle Identität definiert sein. Schreiben Sie KEINE Kompositionen mit Standard- oder generischen Farben (#333, #3b82f6, Roboto sind Anzeichen, dass dieser Schritt übersprungen wurde). Überprüfen Sie in dieser Reihenfolge:

  1. Existiert DESIGN.md im Projektstamm? → Verwenden Sie die genauen Farben, Schriftarten, Bewegungsregeln und „Was NICHT zu tun ist“-Einschränkungen.

  2. Hat der Benutzer einen Stil genannt (z. B. „Swiss Pulse“, „dark and techy“, „Luxusmarke“)? → Generieren Sie 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? → Stellen Sie 3 Fragen, bevor Sie HTML schreiben:

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

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

2. Gerü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. Übergeben Sie --example <name>, um eine auszuwählen, --video clip.mp4 oder --audio track.mp3, um Medien hinzuzufügen.

3. Layout vor der Animation

Schreiben Sie 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. Verwenden Sie Innenabstände, um Inhalt nach innen zu schieben – niemals position: absolute; top: Npx auf einem Inhaltscontainer (Inhalt läuft über, wenn er größer als der verbleibende Platz ist).

Erst wenn der Hero-Frame richtig aussieht, fügen Sie gsap.from()-Eingänge (zur CSS-Position animieren) und gsap.to()-Ausgänge (davon 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 – unterbricht die Capture-Engine). Berechnen Sie: repeat: Math.ceil(duration / cycleDuration) - 1.
  • Deterministisch sein – kein Math.random(), Date.now() oder Wanduhr-Logik. Verwenden Sie einen gesäten Zufallszahlengenerator (PRNG), wenn Sie Pseudo-Zufälligkeit benötigen.
  • Synchron aufbauen – kein async/await, setTimeout oder Promises um die Timeline-Konstruktion.

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

5. Übergänge zwischen Szenen

Mehrszenen-Kompositionen erfordern Übergänge. Regeln:

  1. Verwenden Sie immer einen Übergang zwischen Szenen – keine Sprungschnitte.
  2. Verwenden Sie immer Eingangsanimationen für jedes Szenenelement (gsap.from(...)).
  3. Verwenden Sie niemals Ausgangsanimationen außer in der letzten Szene – der Übergang IST der Ausgang.
  4. Die letzte Szene kann ausgeblendet werden.

Verwenden Sie npx hyperframes add <transition-name>, um Shader-Übergänge zu installieren (flash-through-white, liquid-wipe, etc.). Vollständige Liste: npx hyperframes add --list.

6. Audio, Untertitel, TTS, audio-reaktive Effekte, Hervorhebungen

  • Audio: immer ein separates <audio>-Element (Video ist muted playsinline).
  • TTS: npx hyperframes tts "Skripttext" --voice af_nova --output narration.wav. Stimmen auflisten mit --list. Der erste Buchstabe der Stimmen-ID kodiert die Sprache (a/b=Englisch, e=Spanisch, f=Französisch, j=Japanisch, z=Mandarin, etc.) – die CLI leitet das Phonemizer-Gebietsschema automatisch ab; übergeben Sie --lang nur zum Überschreiben. Nicht-englische Phonemisierung erfordert systemweit installiertes espeak-ng.
  • Untertitel: npx hyperframes transcribe narration.wav → wortgenaues Transkript. Wählen Sie den Stil aus dem Transkriptton (Hype / Corporate / Tutorial / Storytelling / Social – siehe Tabelle in references/features.md). Sprachregel: Verwenden Sie niemals .en-Whisper-Modelle, es sei denn, das Audio ist nachweislich Englisch – .en übersetzt nicht-englisches Audio anstatt es zu transkribieren. Jede Untertitelgruppe MUSS nach ihrem Ausgangs-Tween einen harten tl.set(el, { opacity: 0, visibility: "hidden" }, group.end)-Kill haben – sonst werden Gruppen sichtbar in spätere hineinlaufen.
  • Audio-reaktive Grafiken: Extrahieren Sie vorab Audiobänder (Bass / Mitten / Höhen) und sampeln Sie pro Frame innerhalb der Timeline mit einer for-Schleife von tl.call(draw, [], f / fps) – ein einzelner langer Tween reagiert NICHT auf Audio. Ordnen Sie Bass → scale (Puls), Höhen → textShadow/boxShadow (Glühen), Gesamtamplitude → opacity/y/backgroundColor zu. Vermeiden Sie Equalizer-Balken-Klischees – lassen Sie den Inhalt die visuelle Gestaltung leiten und das Audio sein Verhalten steuern.
  • Markerartige Hervorhebungen: Hervorhebungs-, Kreis-, Burst-, Scribble-, Sketchout-Effekte für Textbetonung sind deterministisches CSS+GSAP – siehe references/features.md#marker-highlighting. Vollständig suchbar, keine animierten SVG-Filter.
  • Szenenübergänge: Jede mehrszenige Komposition MUSS Übergänge verwenden (keine Sprungschnitte). Wählen Sie 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, etc.) über npx hyperframes add. Stimmungs- und Energie-Tabellen finden Sie in references/features.md#transitions. Mischen Sie keine CSS- und Shader-Übergänge in derselben Komposition.

7. Lint, Validieren, Inspizieren, Vorschau, Rendern

npx hyperframes lint              # Erkennt fehlende data-composition-id, überlappende Tracks, nicht registrierte Timelines
npx hyperframes validate          # WCAG-Kontrastprüfung bei 5 Zeitstempeln
npx hyperframes inspect           # Visuelles Layout-Audit – Ü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 sampelt Hintergrundpixel hinter jedem Textelement und warnt bei Kontrastverhältnissen unter 4,5:1 (oder 3:1 für großen Text). hyperframes inspect ist das Layout-seitige Gegenstück – führt die Seite zu mehreren Zeitpunkten aus und kennzeichnet Probleme, die ein statischer Lint nicht sehen kann (eine Bildunterschrift, die den sicheren Bereich erst bei 4,5s umwickelt, eine Karte, die überläuft, wenn ihr Titel die längste Variante ist, ein Element, das hinter einem Übergangs-Shader landet). Führen Sie inspect besonders bei Kompositionen mit Sprechblasen, Karten, Bildunterschriften oder enger Typografie durch.

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

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

Fallstricke

  • HeadlessExperimental.beginFrame' wurde nicht gefunden – Chromium 147+ hat dieses Protokoll entfernt. Stellen Sie sicher, dass Sie hyperframes@>=0.4.2 verwenden (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) – Rendering hängt 120s lang und bricht dann mit Timeout ab. Führen Sie npx puppeteer browsers install chrome-headless-shell aus (setup.sh erledigt dies). hyperframes doctor meldet, welche Binärdatei verwendet wird.
  • repeat: -1 irgendwo – unterbricht die Capture-Engine. Berechnen Sie immer eine endliche Wiederholungsanzahl.
  • gsap.set() auf Clip-Elementen, die später eintreten – das Element existiert beim Seitenladen nicht. Verwenden Sie stattdessen tl.set(selector, vars, timePosition) innerhalb der Timeline, zum oder nach dem data-start des Clips.
  • <br> innerhalb von Inhaltstext – erzwungene Umbrüche kennen die gerenderte Schriftbreite nicht, daher verdoppelt natürlicher Zeilenumbruch + <br> die Umbrüche. Verwenden Sie max-width, damit Text umbrechen kann. Ausnahme: kurze Anzeigetitel, bei denen jedes Wort bewusst in einer eigenen Zeile steht.
  • Animieren von visibility oder display – GSAP kann diese nicht animieren. Verwenden Sie autoAlpha (behandelt sowohl Sichtbarkeit als auch Deckkraft).
  • Aufrufen von video.play() oder audio.play() – das Framework besitzt die Wiedergabe. Rufen Sie diese niemals selbst auf.
  • Asynchrones Erstellen von Timelines – die Capture-Engine liest window.__timelines synchron nach dem Seitenladen. Wickeln Sie die Timeline-Konstruktion niemals in async, setTimeout oder ein Promise.
  • Eigenständiges index.html, eingewickelt in <template> – versteckt den gesamten Inhalt vor dem Browser. Nur Unterkompositionen, die über data-composition-src geladen werden, verwenden <template>.
  • Verwenden von Video für Audio – immer stummgeschaltetes <video> + separates <audio>.

Überprüfung

Vor und nach dem Rendern:

  1. Lint + Validate + Inspect bestanden: npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect (Lint erkennt strukturelle Probleme, Validate erkennt Kontrastprobleme, Inspect erkennt visuelle Layout-/Überlaufprobleme – siehe troubleshooting.md, wenn Warnungen erscheinen).
  2. Animationschoreografie – führen Sie für neue Kompositionen oder signifikante Animationsänderungen die Animationskarte aus. npx hyperframes init kopiert die Skill-Skripte in das Projekt, daher ist der Pfad projektlokal:
    node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
      --out <composition-dir>/.hyperframes/anim-map
    
    Gibt eine einzelne 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. Scannen Sie Zusammenfassungen und Flags – korrigieren oder begründen Sie jedes. Überspringen Sie kleine Änderungen.
  3. Datei existiert + 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 Überprüfung: Extrahieren Sie einen Frame aus der Mitte der Komposition: ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png.
  6. Audio vorhanden, wenn 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ühren Sie npx hyperframes doctor aus und fügen Sie die Ausgabe bei, wenn Sie einen Fehler melden.

Referenzen

  • composition.md – Datenattribute, Timeline-Vertrag, unverhandelbare Regeln, Typografie-/Asset-Regeln
  • cli.md – jeder CLI-Befehl (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 – Bildunterschriften, 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 Render-Fehler

Verwandte Skills