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 frame-by-frame und kodiert sie mit FFmpeg als MP4/WebM.
Ergänzung zu manim-video: Verwende manim-video für mathematische/geometrische Erklärvideos (Gleichungen, 3B1B-Stil). Verwende hyperframes für Motion-Graphics, Talking-Head-Videos mit Untertiteln, Produkttouren, Social-Overlays, Shader-Übergänge und alles, was von echten Video-/Audio-Medien angetrieben wird.
Wann verwenden
- Der Nutzer wünscht ein gerendertes Video aus Text, einem Skript oder einer Website
- Animierte Titelcards, Lower Thirds oder typografische Intros
- Captioned Narration (TTS + Untertitel synchron zur Wellenform)
- Audiovisuelle Effekte (Beat-Sync, Spektrum-Balken, pulsierendes Glühen)
- Szene-zu-Szene-Übergänge (Crossfade, Wipe, Shader Warp, Flash-Through-White)
- Social-Overlays (Instagram/TikTok/YouTube-Stil)
- Website-zu-Video-Pipeline (URL erfassen, Promo produzieren)
- Jede HTML/CSS/JS-Animation, die deterministisch in eine Videodatei gerendert werden muss
Verwende diesen Skill nicht für:
- Reine Mathe-/Gleichungs-Animationen (→
manim-video) - Bilderzeugung oder Memes (→
meme-generation, Bildmodelle) - Live-Videokonferenzen oder Streaming
Kurzreferenz
npx hyperframes init my-video # Projekt anlegen
cd my-video
npx hyperframes lint # Vor Vorschau/Rendering validieren
npx hyperframes preview # Live-Browser-Vorschau (Port 3002)
npx hyperframes render --output final.mp4 # Als MP4 rendern
npx hyperframes doctor # Umgebungsprobleme diagnostizieren
Renderflags: --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 (druckt Korrekturanleitungen, wenn nicht).
- Installiert die
hyperframes-CLI global (npm install -g hyperframes@>=0.4.2). - Pre-cached
chrome-headless-shellüber Puppeteer — erforderlich für die beste Rendering-Qualität über ChromesHeadlessExperimental.beginFrame-Erfassungspfad. - Führt
npx hyperframes doctoraus und zeigt das Ergebnis an.
Siehe references/troubleshooting.md, falls die Einrichtung fehlschlägt.
Vorgehensweise
1. Planen vor dem Schreiben von HTML
Bevor du Code anfasst, artikuliere auf hoher Ebene:
- Was — Erzählbogen, Schlüsselmomente, emotionale Höhepunkte
- Struktur — Kompositionen, Tracks (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 du zuerst baust.
Gate für die visuelle Identität (HARD-GATE). Bevor du IRGENDEIN Kompositions-HTML schreibst, muss eine visuelle Identität definiert sein. Schreibe KEINE Kompositionen mit Standard- oder generischen Farben (#333, #3b82f6, Roboto sind Anzeichen dafür, dass dieser Schritt übersprungen wurde). Überprüfe in dieser Reihenfolge:
-
DESIGN.mdim Projekt-Root? → Verwende deren exakte Farben, Schriftarten, Bewegungsregeln und „Was NICHT zu tun ist“-Einschränkungen. -
Nutzer hat einen Stil genannt (z.B. „Swiss Pulse“, „dunkel und technisch“, „Luxusmarke“)? → Erstelle ein minimales
DESIGN.mdmit## Style Prompt,## Farben(3-5 Hex-Werte mit Rollen),## Typografie(1-2 Familien),## Was NICHT zu tun ist(3-5 Anti-Patterns). -
Keines der oben genannten? → Stelle 3 Fragen, bevor du HTML schreibst:
- Stimmung? (explosiv / filmisch / fließend / technisch / chaotisch / warm)
- Heller oder dunkler Hintergrund?
- Gibt es Markenfarben, Schriftarten oder visuelle Referenzen?
Erstelle dann ein
DESIGN.mdaus den Antworten. Jede Komposition muss ihre Palette und Typografie aufDESIGN.mdoder eine explizite Anweisung des Nutzers zurückführen.
2. Projektgerü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>, um eine auszuwählen, oder --video clip.mp4 / --audio track.mp3, um Medien einzufügen.
3. Layout vor der 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 Inhalt nach innen zu schieben — 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 (animiere zur CSS-Position) und gsap.to()-Ausgänge (animiere von der Position) hinzu.
Siehe references/composition.md für das vollständige Daten-Attribut-Schema und die Kompositionsregeln.
4. Mit GSAP animieren
Jede Komposition muss:
- Ihre Timeline registrieren:
window.__timelines["<Kompositions-ID>"] = tl - Pausiert starten:
gsap.timeline({ paused: true })— der Player steuert die Wiedergabe - Endliche
repeat-Werte verwenden (keinrepeat: -1— zerstört die Erfassungs-Engine). Berechne:repeat: Math.ceil(dauer / zyklusDauer) - 1. - Deterministisch sein — kein
Math.random(),Date.now()oder Wanduhr-Logik. Verwende einen gesäten PRNG, falls du Pseudozufall benötigst. - Synchron aufgebaut werden — kein
async/await,setTimeoutoder Promises rund um den Timeline-Aufbau.
Siehe references/gsap.md für die Kern-GSAP-API (Tweens, Easings, Stagger, Timelines).
5. Übergänge zwischen Szenen
Kompositionen mit mehreren Szenen erfordern Übergänge. Regeln:
- Verwende immer einen Übergang zwischen Szenen — keine Jump Cuts.
- Verwende immer Eingangsanimationen auf jedem Szenenelement (
gsap.from(...)). - Verwende niemals Ausgangsanimationen außer in der letzten Szene — der Übergang IST der Ausgang.
- Die letzte Szene darf ausblenden.
Verwende npx hyperframes add <Übergangsname>, um Shader-Übergänge zu installieren (flash-through-white, liquid-wipe, etc.). Vollständige Liste: npx hyperframes add --list.
6. Audio, Untertitel, TTS, audiovisuelle Effekte, 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. Die erste Ziffer der Stimmen-ID kodiert die Sprache (a/b=Englisch,e=Spanisch,f=Französisch,j=Japanisch,z=Mandarin, etc.) — die CLI erkennt automatisch das Phonemizer-Locale; übergib--langnur zum Überschreiben. Nicht-englische Phonemisierung erfordert systemweit installiertesespeak-ng. - Untertitel:
npx hyperframes transcribe narration.wav→ wortgenaues Transkript. Wähle den Stil entsprechend 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 erhalten. - Audiovisuelle Effekte: Extrahiere vorab Audiobänder (Bass / Mitten / Höhen) und taste pro Frame innerhalb der Timeline mit einer
for-Schleife vontl.call(draw, [], f / fps)ab — ein einzelner langer Tween reagiert NICHT auf Audio. Ordne Bass →scale(Puls), Höhen →textShadow/boxShadow(Glühen), Gesamtamplitude →opacity/y/backgroundColorzu. Vermeide Equalizer-Balken-Klischees — lass den Inhalt das Visuelle leiten, das Audio sein Verhalten steuern. - Marker-Hervorhebung: Hervorheben, Einkreisen, Aufplatzen, Gekritzel, Skizzieren zur Textbetonung ist 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 Jump Cuts). 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, etc.) übernpx hyperframes add. Stimmungs- und Energie-Tabellen leben inreferences/features.md#transitions. Mische keine CSS- und Shader-Übergänge in derselben Komposition.
7. Linten, validieren, inspizieren, vorschauen, rendern
npx hyperframes lint # erkennt fehlende data-composition-id, überlappende Tracks, nicht registrierte Timelines
npx hyperframes validate # WCAG-Kontrast-Prüfung zu 5 Zeitstempeln
npx hyperframes inspect # visuelles Layout-Audit — Überlauf, Off-Frame-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 # finale 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 der Layout-Begleiter — führt die Seite zu mehreren Zeitstempeln aus und meldet Probleme, die ein statischer Lint nicht sehen kann (eine Bildunterschrift, die nur bei 4.5s über den sicheren Bereich ragt, 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 (wenn der Nutzer eine URL angibt)
Verwende 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+ entfernte dieses Protokoll. 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) — Renderings hängen 120s und brechen dann mit Timeout ab. Führenpx puppeteer browsers install chrome-headless-shellaus (setup.sh erledigt dies).hyperframes doctormeldet, welches Binary verwendet wird. repeat: -1irgendwo — zerstört die Erfassungs-Engine. Berechne immer einen endlichen Repeat-Wert.gsap.set()auf Clips-Elementen, die später eintreten — das Element existiert beim Laden der Seite nicht. Verwende stattdessen innerhalb der Timelinetl.set(selector, vars, timePosition)entweder bei oder nach demdata-startdes Clips.<br>innerhalb von Inhaltstext — erzwungene Umbrüche kennen die gerenderte Schriftbreite nicht, daher bewirkt natürlicher Umbruch +<br>einen doppelten Umbruch. Verwendemax-width, um Text umbrechen zu lassen. Ausnahme: kurze Anzeigetitel, bei denen jedes Wort absichtlich in einer eigenen Zeile steht.- Animation von
visibilityoderdisplay— GSAP kann diese nicht tweenen. VerwendeautoAlpha(behandelt sowohl Sichtbarkeit als auch Deckkraft). - Aufruf von
video.play()oderaudio.play()— das Framework besitzt die Wiedergabe. Rufe diese niemals selbst auf. - Asynchroner Timeline-Aufbau — die Erfassungs-Engine liest
window.__timelinessynchron nach dem Laden der Seite. Wickle den Timeline-Aufbau niemals inasync,setTimeoutoder eine Promise. - Eigenständiges
index.htmlin<template>verpackt — verbirgt allen Inhalt vor dem Browser. Nur Unterkompositionen, die überdata-composition-srcgeladen werden, verwenden<template>. - Video für Audio verwenden — immer stummgeschaltetes
<video>+ separates<audio>.
Verifikation
Vor und nach dem Rendern:
- Lint + Validate + Inspect bestanden:
npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect(Lint erfasst Strukturprobleme, Validate Kontraste, Inspect visuelle Layout-/Überlaufprobleme — siehe troubleshooting.md, falls Warnungen erscheinen). - Animations-Choreographie — für neue Kompositionen oder signifikante Änderungen der Animation führe die Animationskarte aus.
npx hyperframes initkopiert die Skill-Skripte in das Projekt, sodass der Pfad projektspezifisch ist:
Gibt eine einzelnenode skills/hyperframes/scripts/animation-map.mjs <Kompositionsverzeichnis> \ --out <Kompositionsverzeichnis>/.hyperframes/anim-mapanimation-map.jsonaus mit 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 — behebe oder rechtfertige jedes. Überspringe bei kleinen Bearbeitungen. - 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 wenn 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 hänge die Ausgabe bei der Meldung an.
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, Easings, Stagger, Timelines, matchMedia)
- features.md — Untertitel, TTS, audiovisuelle Effekte, Marker-Hervorhebung, Übergänge (auf Abruf laden)
- website-to-video.md — 7-Schritte-Capture-to-Video-Workflow
- troubleshooting.md — OpenClaw-Fix, Umgebungsvariablen, häufige Renderfehler