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:
- Überprüft, ob Node.js >= 22 und FFmpeg installiert sind (gibt Reparaturanweisungen aus, wenn nicht).
- Installiert das
hyperframes-CLI global (npm install -g hyperframes@>=0.4.2). - Speichert
chrome-headless-shellüber Puppeteer zwischen – erforderlich für qualitativ hochwertiges Rendering über denHeadlessExperimental.beginFrame-Erfassungspfad von Chrome. - Führt
npx hyperframes doctoraus 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:
-
DESIGN.mdim Projektstamm? → Verwende die genauen Farben, Schriftarten, Bewegungsregeln und "Was NICHT zu tun"-Einschränkungen. -
Benutzer hat einen Stil genannt (z. B. "Swiss Pulse", "dark und technisch", "Luxusmarke")? → Generiere 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? → 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.mdaus den Antworten. Jede Komposition muss ihre Palette und Typografie aufDESIGN.mdoder 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 (keinrepeat: -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,setTimeoutoder 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:
- Verwende immer einen Übergang zwischen Szenen – keine harten Schnitte.
- Verwende immer Eintrittsanimationen auf jedem Szenenelement (
gsap.from(...)). - Verwende niemals Austrittsanimationen außer in der letzten Szene – der Übergang IST der Austritt.
- 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 istmuted 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--langnur, um es zu überschreiben. Nicht-englische Phonemisierung erfordert systemweit installiertesespeak-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 inreferences/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 hartentl.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 vontl.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-splitusw.) vianpx hyperframes add. Stimmungs- und Energietabellen findest du inreferences/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 duhyperframes@>=0.4.2verwendest (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ührenpx puppeteer browsers install chrome-headless-shellaus (setup.sh erledigt dies).hyperframes doctormeldet, welche Binärdatei verwendet wird. repeat: -1irgendwo – 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 stattdessentl.set(selector, vars, timePosition)innerhalb der Timeline, bei oder nach demdata-startdes Clips.<br>innerhalb von Inhaltstext – erzwungene Umbrüche kennen die gerenderte Schriftbreite nicht, daher natürlicher Umbruch +<br>verdoppelt die Brüche. Verwendemax-width, damit Text umbrechen kann. Ausnahme: kurze Anzeigetitel, bei denen jedes Wort bewusst auf einer eigenen Zeile steht.- Animieren von
visibilityoderdisplay– GSAP kann diese nicht tweenen. VerwendeautoAlpha(behandelt sowohl Sichtbarkeit als auch Deckkraft). - Aufrufen von
video.play()oderaudio.play()– das Framework besitzt die Wiedergabe. Rufe diese niemals selbst auf. - Asynchrones Erstellen von Timelines – die Erfassungsmaschine liest
window.__timelinessynchron nach dem Laden der Seite. Wickle den Timeline-Aufbau niemals inasync,setTimeoutoder ein Promise. - Eigenständiges
index.htmlin<template>verpackt – verbirgt alle Inhalte vor dem Browser. Nur Unterkompositionen, die überdata-composition-srcgeladen werden, verwenden<template>. - Verwendung von Video für Audio – immer stummgeschaltetes
<video>+ separates<audio>.
Überprüfung
Vor und nach dem Rendern:
- 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). - Animationschoreografie – für neue Kompositionen oder signifikante Animationsänderungen führe die Animationskarte aus.
npx hyperframes initkopiert die Skill-Skripte in das Projekt, daher ist der Pfad projektspezifisch:
Gibt eine einzigenode skills/hyperframes/scripts/animation-map.mjs <komposition-verzeichnis> \ --out <komposition-verzeichnis>/.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. Scanne Zusammenfassungen und Flags – repariere oder begründe jedes. Überspringe bei kleinen Bearbeitungen. - Datei existiert und ist 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 Prüfung: Extrahiere einen Bildausschnitt aus der Mitte der Komposition:
ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png. - 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