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:
- Überprüft, ob Node.js >= 22 und FFmpeg installiert sind (zeigt bei Bedarf Reparaturanweisungen an).
- Installiert die
hyperframes-CLI global (npm install -g hyperframes@>=0.4.2). - Cached
chrome-headless-shellüber Puppeteer vor – erforderlich für qualitativ hochwertiges Rendering über denHeadlessExperimental.beginFrame-Capture-Pfad von Chrome. - Führt
npx hyperframes doctoraus 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:
-
Existiert
DESIGN.mdim Projektstamm? → Verwenden Sie die genauen Farben, Schriftarten, Bewegungsregeln und „Was NICHT zu tun ist“-Einschränkungen. -
Hat der Benutzer einen Stil genannt (z. B. „Swiss Pulse“, „dark and techy“, „Luxusmarke“)? → Generieren Sie eine minimale
DESIGN.mdmit## Style Prompt,## Colors(3-5 Hex mit Rollen),## Typography(1-2 Familien),## What NOT to Do(3-5 Anti-Patterns). -
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 aufDESIGN.mdoder 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 (keinrepeat: -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,setTimeoutoder 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:
- Verwenden Sie immer einen Übergang zwischen Szenen – keine Sprungschnitte.
- Verwenden Sie immer Eingangsanimationen für jedes Szenenelement (
gsap.from(...)). - Verwenden Sie niemals Ausgangsanimationen außer in der letzten Szene – der Übergang IST der Ausgang.
- 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 istmuted 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--langnur zum Überschreiben. Nicht-englische Phonemisierung erfordert systemweit installiertesespeak-ng. - Untertitel:
npx hyperframes transcribe narration.wav→ wortgenaues Transkript. Wählen Sie den Stil aus dem Transkriptton (Hype / Corporate / Tutorial / Storytelling / Social – siehe Tabelle inreferences/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 hartentl.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 vontl.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/backgroundColorzu. 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.) übernpx hyperframes add. Stimmungs- und Energie-Tabellen finden Sie inreferences/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 Siehyperframes@>=0.4.2verwenden (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 Sienpx puppeteer browsers install chrome-headless-shellaus (setup.sh erledigt dies).hyperframes doctormeldet, welche Binärdatei verwendet wird. repeat: -1irgendwo – 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 stattdessentl.set(selector, vars, timePosition)innerhalb der Timeline, zum oder nach demdata-startdes Clips.<br>innerhalb von Inhaltstext – erzwungene Umbrüche kennen die gerenderte Schriftbreite nicht, daher verdoppelt natürlicher Zeilenumbruch +<br>die Umbrüche. Verwenden Siemax-width, damit Text umbrechen kann. Ausnahme: kurze Anzeigetitel, bei denen jedes Wort bewusst in einer eigenen Zeile steht.- Animieren von
visibilityoderdisplay– GSAP kann diese nicht animieren. Verwenden SieautoAlpha(behandelt sowohl Sichtbarkeit als auch Deckkraft). - Aufrufen von
video.play()oderaudio.play()– das Framework besitzt die Wiedergabe. Rufen Sie diese niemals selbst auf. - Asynchrones Erstellen von Timelines – die Capture-Engine liest
window.__timelinessynchron nach dem Seitenladen. Wickeln Sie die Timeline-Konstruktion niemals inasync,setTimeoutoder ein Promise. - Eigenständiges
index.html, eingewickelt in<template>– versteckt den gesamten Inhalt vor dem Browser. Nur Unterkompositionen, die überdata-composition-srcgeladen werden, verwenden<template>. - Verwenden von Video für Audio – immer stummgeschaltetes
<video>+ separates<audio>.
Überprüfung
Vor und nach dem Rendern:
- 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). - Animationschoreografie – führen Sie für neue Kompositionen oder signifikante Animationsänderungen die Animationskarte aus.
npx hyperframes initkopiert die Skill-Skripte in das Projekt, daher ist der Pfad projektlokal:
Gibt eine einzelnenode skills/hyperframes/scripts/animation-map.mjs <composition-dir> \ --out <composition-dir>/.hyperframes/anim-mapanimation-map.jsonmit 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. - Datei existiert + nicht Null:
ls -lh final.mp4. - Dauer stimmt mit
data-durationüberein:ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4. - Visuelle Überprüfung: Extrahieren Sie einen Frame aus der Mitte der Komposition:
ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png. - 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