HyperFrames
HTML ist die Quelle der Wahrheit für Video. Eine Komposition ist eine HTML-Datei mit data-*-Attributen für Timing, einer GSAP-Timeline für Animationen und CSS für das Aussehen. Die HyperFrames-Engine erfasst die Seite Bild für Bild und codiert sie mit FFmpeg in MP4/WebM.
Ergänzung zu manim-videos: Verwende manim-video für mathematische/geometrische Erklärungen (Gleichungen, 3B1B-Stil). Verwende hyperframes für Bewegtgrafiken, Sprechervideos mit Untertiteln, Produkt-Touren, Social-Overlays, Shader-Übergänge und alles, was von echten Video-/Audiomedien gesteuert wird.
Wann verwenden
- Benutzer wünscht ein gerendertes Video aus Text, einem Skript oder einer Website
- Animierte Titelcards, Lower Thirds oder typografische Intros
- Video mit gesprochener Erzählung und Untertiteln (TTS + Untertitel synchron zur Wellenform)
- Audio-reaktive Visuals (Beat-Sync, Spektrumbalken, pulsierendes Leuchten)
- Szenenübergänge (Überblendung, Wisch, Shader-Warp, Durch-Blitz-zu-Weiß)
- Social-Overlays (Instagram/TikTok/YouTube-Stil)
- Website-zu-Video-Pipeline (URL erfassen, Promo produzieren)
- Jede HTML/CSS/JS-Animation, die deterministisch zu einer Videodatei gerendert werden muss
Verwende dieses 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 Vorschau/Render validieren
npx hyperframes preview # Live-Reload-Browservorschau (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 (gibt ggf. Korrekturanweisungen aus).
- Installiert die
hyperframes-CLI global (npm install -g hyperframes@>=0.4.2). - Lädt
chrome-headless-shellüber Puppeteer vor – erforderlich für beste Renderqualität über den ChromeheadlessExperimental.beginFrame-Capture-Pfad. - Führt
npx hyperframes doctoraus und meldet das Ergebnis.
Siehe references/troubleshooting.md, falls die Einrichtung fehlschlägt.
Vorgehensweise
1. Planung vor dem Schreiben von HTML
Bevor du Code anfasst, lege auf hoher Ebene Folgendes fest:
- Was — Handlungsbogen, Schlüsselmomente, emotionale Höhepunkte
- Struktur — Kompositionen, Spuren (Video/Audio/Overlays), Dauern
- Visuelle Identität — Farben, Schriftarten, Bewegungscharakter (explosiv / kinematisch / fließend / technisch)
- Hero-Frame — pro Szene der Moment, in dem die meisten Elemente gleichzeitig sichtbar sind. Dies ist das statische Layout, das du zuerst erstellst.
Visuelle-Identität-Gate (HARD-GATE). Bevor du IRGENDEINE Kompositions-HTML schreibst, 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). Prüfe in dieser Reihenfolge:
-
DESIGN.mdim Projektstamm? → Verwende deren genaue Farben, Schriftarten, Bewegungsregeln und "Was NICHT tun"-Einschränkungen. -
Benutzer hat einen Stil genannt (z. B. "Swiss Pulse", "dark and techy", "luxury brand") → 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 vor dem Schreiben von HTML 3 Fragen:
- Stimmung? (explosiv / kinematisch / fließend / technisch / chaotisch / warm)
- Heller oder dunkler Hintergrund?
- Gibt es Markenfarben, Schriftarten oder visuelle Referenzen?
Generiere dann aus den Antworten eine
DESIGN.md. Jede Komposition muss ihre Palette und Typografie aufDESIGN.mdoder 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. Verwende --example <name>, um eine auszuwählen, oder --video clip.mp4 bzw. --audio track.mp3, um Medien einzubringen.
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 füllen (width:100%; height:100%; padding:Npx) mit display:flex + gap. Verwende Padding, um Inhalt nach innen zu drücken – niemals position: absolute; top: Npx auf einem Inhaltscontainer (Inhalt läuft über, wenn er höher als der verbleibende Platz ist).
Erst wenn der Hero-Frame richtig aussieht, füge gsap.from()-Eingänge (Animate zu der CSS-Position) und gsap.to()-Ausgänge (Animiere von ihr) 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– zerstört die Capture-Engine). Berechne:repeat: Math.ceil(dauer / zyklusdauer) - 1. - Deterministisch sein – kein
Math.random(),Date.now()oder Wanduhrlogik. Verwende einen gesetzten PRNG, falls Pseudozufall benötigt wird. - Synchron aufgebaut werden – kein
async/await,setTimeoutoder Promises um den Timeline-Aufbau herum.
Siehe references/gsap.md für die GSAP-Kern-API (Tweens, Easing, Stagger, Timelines).
5. Übergänge zwischen Szenen
Mehrszenen-Kompositionen erfordern Übergänge. Regeln:
- Verwende IMMER einen Übergang zwischen Szenen – keine Jump Cuts.
- Verwende IMMER Eingangsanimationen für jedes Szenenelement (
gsap.from(...)). - Verwende NIEMALS Ausgangsanimationen außer in der letzten Szene – der Übergang IST der Ausgang.
- 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 Sprach-ID kodiert die Sprache (a/b=Englisch,e=Spanisch,f=Französisch,j=Japanisch,z=Mandarin usw.) – die CLI leitet das Phonemizer-Gebietsschema automatisch ab; verwende--langnur zum Überschreiben. Nicht-englische Phonemisierung erfordert systemweit installiertesespeak-ng. - Untertitel:
npx hyperframes transcribe narration.wav→ Transkript auf Wortebene. Wähle den Stil basierend auf dem Ton 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 Ausgangs-Tween haben – sonst bleiben Gruppen sichtbar in späteren hängen. - Audio-reaktive Visuals: Extrahiere vorab Audio-Bänder (Bass / Mitten / Höhen) und mustere pro Frame innerhalb der Timeline mit einer
for-Schleife vontl.call(draw, [], f / fps)– ein einzelner langer Tween reagiert NICHT auf Audio. Bilde Bass →scale(Puls), Höhen →textShadow/boxShadow(Glühen), Gesamtamplitude →opacity/y/backgroundColorab. Vermeide Equalizer-Balken-Klischees – lass den Inhalt die Visualisierung leiten, das Audio sein Verhalten steuern. - Marker-Stil-Hervorhebung: Hervorhebungs-, Kreis-, Burst-, Kritzel-, Skizzen-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 Mehrszenen-Komposition MUSS Übergänge verwenden (keine Jump Cuts). Wähle aus CSS-Primitiven (Push-Slide, Blur-Überblendung, Zoom-Durch, gestaffelte Blöcke) oder Shader-Übergängen (
flash-through-white,liquid-wipe,cross-warp-morph,chromatic-splitusw.) übernpx hyperframes add. Stimmungs- und Energie-Tabellen finden sich 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-Kontrast-Audit zu 5 Zeitstempeln
npx hyperframes inspect # Visuelles Layout-Audit – Überlauf, außerhalb des Frames liegende Elemente, 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 samplet Hintergrundpixel hinter jedem Textelement und warnt bei Kontrastverhältnissen unter 4,5:1 (bzw. 3:1 für großen Text). hyperframes inspect ist das Layout-Seitenstück – führt die Seite zu mehreren Zeitstempeln aus und meldet Probleme, die ein statischer Lint nicht sehen kann (eine Untertitel, die nur 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 aus.
8. Website-zu-Video (falls der Benutzer eine URL angibt)
Verwende den 7-Schritte-Capture-zu-Video-Workflow in references/website-to-video.md: Capturen → DESIGN.md → SCRIPT.md → Storyboard → Komposition → Rendern → Ausliefern.
Fallstricke
HeadlessExperimental.beginFrame' wasn't found– Chromium 147+ hat dieses Protokoll entfernt. Stelle sicher, dass duhyperframes@>=0.4.2verwendest (erkennt automatisch und fällt auf Screenshot-Modus zurück). Notluke:export PRODUCER_FORCE_SCREENSHOT=true. Siehe hyperframes#294 und references/troubleshooting.md.- System-Chrome (nicht
chrome-headless-shell) – Render-Vorgänge hängen 120s lang und brechen dann mit Timeout ab. Führenpx puppeteer browsers install chrome-headless-shellaus (setup.sh macht das).hyperframes doctormeldet, welche Binärdatei verwendet wird. repeat: -1irgendwo – zerstört die Capture-Engine. Berechne immer eine endliche Wiederholungsanzahl.gsap.set()auf Clip-Elementen, die später erscheinen – das Element existiert beim Seitenladen nicht. Verwende stattdessentl.set(selector, vars, timePosition)innerhalb der Timeline, zum oder nach demdata-startdes Clips.<br>in Inhalts-Text – erzwungene Umbrüche kennen die gerenderte Schriftbreite nicht, daher verursacht natürlicher Umbruch +<br>Doppelumbrüche. Verwendemax-width, um Text umbrechen zu lassen. Ausnahme: kurze Anzeigetitel, bei denen jedes Wort bewusst in einer eigenen Zeile steht.- Animieren von
visibilityoderdisplay– GSAP kann diese nicht tweenen. VerwendeautoAlpha(handhabt sowohl Sichtbarkeit als auch Deckkraft). - Aufruf von
video.play()oderaudio.play()– das Framework steuert die Wiedergabe. Rufe diese niemals selbst auf. - Asynchroner Timeline-Aufbau – die Capture-Engine liest
window.__timelinessynchron nach dem Seitenladen. Wickle den Timeline-Aufbau niemals inasync,setTimeoutoder ein Promise. - Eigenständiges
index.html, eingewickelt in<template>– verbirgt alle Inhalte vor dem Browser. Nur Unter-Kompositionen, die überdata-composition-srcgeladen werden, verwenden<template>. - Verwendung von Video für Audio – verwende immer stummgeschaltetes
<video>+ separates<audio>.
Verifizierung
Vor und nach dem Rendern:
- Lint + Validate + Inspect bestehen:
npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect(Lint erfasst strukturelle Probleme, Validate erfasst Kontraste, Inspect erfasst visuelle Layout-/Überlauf-Probleme – siehe troubleshooting.md, falls Warnungen auftauchen). - Animations-Choreografie – bei neuen Kompositionen oder signifikanten Animationsänderungen die Animations-Map ausführen.
npx hyperframes initkopiert die Skill-Skripte in das Projekt, daher ist der Pfad projektspezifisch:
Erzeugt 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, toten Zonen (>1s ohne Animation), Element-Lebenszyklen und Flags (offscreen,collision,invisible,paced-fast<0,2s,paced-slow>2s). Scanne Zusammenfassungen und Flags – korrigiere oder begründe jedes. Überspringe bei kleinen Ä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 Prüfung: Extrahiere einen Frame 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.
Falls hyperframes render fehlschlägt, führe npx hyperframes doctor aus und füge dessen Ausgabe beim Melden bei.
Referenzen
- composition.md – Datenattribute, Timeline-Vertrag, nicht verhandelbare 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, Easing, Stagger, Timelines, matchMedia)
- features.md – Untertitel, TTS, audio-reaktiv, Marker-Hervorhebung, Übergänge (bei Bedarf laden)
- website-to-video.md – 7-Schritte-Capture-zu-Video-Workflow
- troubleshooting.md – OpenClaw-Fix, Umgebungsvariablen, häufige Render-Fehler