Communitygithub.com

HyperFrames

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

Was ist HyperFrames?

HyperFrames ist eine leistungsstarke KI-Agenten-Fertigkeit zum Rendern von MP4- und WebM-Videos aus HTML-Kompositionen. Es nutzt HTML als Quelle der Wahrheit, wobei `data-*`-Attribute das Timing steuern, eine GSAP-Timeline die Animation definiert und CSS das visuelle Erscheinungsbild festlegt. Die Engine erfasst die Seite Frame für Frame und kodiert sie mit FFmpeg in ein Video. Die Fertigkeit eignet sich ideal für Motion-Graphics, Kamerafahrten vor dem Sprecher mit Untertiteln, Produkt-Touren, Social-Media-Overlays und alle anderen durch Video/Audio-Medien gesteuerten Inhalte. Sie ergänzt `manim-video`, das für mathematische/geometrische Erklärungen optimiert ist. HyperFrames unterstützt Claude Code, Cursor und Codex und bietet einen umfassenden CLI-Workflow von der Projekterstellung über das Layout, die Animation mit GSAP, das Hinzufügen von Szenenübergängen, Audio und Untertiteln bis hin zum endgültigen Rendering mit verschiedenen Qualitätsstufen.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nastechresearch/nastech-agent/tree/HEAD/optional-skills/creative/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 die Animation und CSS für das Erscheinungsbild. Die HyperFrames-Engine erfasst die Seite Frame für Frame und kodiert sie mit FFmpeg in MP4/WebM.

Ergänzung zu manim-video: Verwenden Sie manim-video für mathematische/geometrische Erklärungen (Gleichungen, 3B1B-Stil). Verwenden Sie hyperframes für Bewegungsgrafiken, Kamerafahrten vor dem Sprecher mit Untertiteln, Produkttouren, Social-Media-Overlays, Shader-Übergänge und alles, was von echtem Video/Audio-Medienmaterial gesteuert wird.

Wann verwenden

  • Benutzer fordert ein gerendertes Video aus Text, einem Skript oder einer Website an
  • Animierte Titelcards, Einblendungen oder typografische Intros
  • Untertitelte Erzählvideos (TTS + Untertitel synchron zur Wellenform)
  • Audio-reaktive Visuals (Beat-Synchronisation, Spektrumbalken, pulsierendes Leuchten)
  • Szene-zu-Szene-Übergänge (Überblendung, Wisch, Shader-Warp, Flash-Through-White)
  • Social-Media-Overlays (Instagram/TikTok/YouTube-Stil)
  • Website-zu-Video-Pipeline (URL erfassen, Werbevideo erstellen)
  • Jede HTML/CSS/JS-Animation, die deterministisch in eine Videodatei gerendert werden muss

Verwenden Sie diese Fertigkeit nicht für:

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

Kurzreferenz

npx hyperframes init my-video               # Ein Projekt anlegen
cd my-video
npx hyperframes lint                        # Vor der Vorschau/Wiedergabe validieren
npx hyperframes preview                     # Live-Reload-Vorschau (langlebiger Server, Port 3002)
npx hyperframes render --output final.mp4   # Als MP4 rendern
npx hyperframes doctor                      # Probleme in der Umgebung diagnostizieren

preview ist ein langlebiger Next.js-Server, der Chrome-Render-Worker offen hält. Stoppen Sie ihn immer, wenn Sie fertig sind (siehe Bereinigung) – ein vergessener Preview hält untätige chrome-headless-shell-Worker am Leben, die auf Hosts ohne GPU (WSL, Container, CI) über Software-WebGL (swiftshader) jeweils einen CPU-Kern dauerhaft auslasten.

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 ~/.nastech/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 Korrekturanweisungen an, falls nicht).
  2. Installiert die hyperframes-CLI global (npm install -g hyperframes@>=0.4.2).
  3. Lädt chrome-headless-shell über Puppeteer vorab in den Cache – erforderlich für die beste Rendering-Qualität über den HeadlessExperimental.beginFrame-Erfassungspfad von Chrome.
  4. Führt npx hyperframes doctor aus und meldet das Ergebnis.

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

Vorgehensweise

1. Vor dem Schreiben von HTML planen

Bevor Sie Code schreiben, artikulieren Sie auf hoher Ebene:

  • 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 Sie zuerst erstellen.

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

  1. DESIGN.md im Projektstamm? → Verwenden Sie dessen genaue Farben, Schriftarten, Bewegungsregeln und „Was man NICHT tun sollte“-Einschränkungen.

  2. Benutzer hat einen Stil genannt (z.B. „Swiss Pulse“, „dunkel und technisch“, „Luxusmarke“)? → Generieren Sie ein minimales DESIGN.md mit ## Stil-Eingabeaufforderung, ## Farben (3-5 Hex mit Rollen), ## Typografie (1-2 Familien), ## Was man NICHT tun sollte (3-5 Anti-Patterns).

  3. Keines der oben genannten? → Stellen Sie 3 Fragen, bevor Sie HTML schreiben:

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

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

2. Gerüst

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 Medienmaterial einzubetten.

3. Layout vor 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 Padding, um den 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ügen Sie gsap.from()-Eingänge (animieren zu der CSS-Position) und gsap.to()-Ausgänge (animieren von dieser) 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 Erfassungs-Engine). Berechnen: repeat: Math.ceil(duration / cycleDuration) - 1.
  • Deterministisch sein – kein Math.random(), Date.now() oder Wanduhr-Logik. Verwenden Sie einen gesäten PRNG, wenn Sie Pseudozufä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 harten Schnitte.
  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 usw.). Vollständige Liste: npx hyperframes add --list.

6. Audio, Untertitel, TTS, Audio-Reaktivität, Hervorhebung

  • Audio: immer ein separates <audio>-Element (Video ist muted playsinline).
  • TTS: npx hyperframes tts "Skripttext" --voice af_nova --output narration.wav. Listen Sie Stimmen mit --list auf. Der erste Buchstabe der Stimmen-ID kodiert die Sprache (a/b=Englisch, e=Spanisch, f=Französisch, j=Japanisch, z=Mandarin usw.) – die CLI ermittelt automatisch das Phonemizer-Gebietsschema; übergeben Sie --lang nur zum Überschreiben. Die Phonemisierung für nicht-englische Sprachen erfordert die systemweite Installation von espeak-ng.
  • Untertitel: npx hyperframes transcribe narration.wav → Transkript auf Wortebene. Wählen Sie den Stil basierend auf dem Transkript-Ton (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 einen harten tl.set(el, { opacity: 0, visibility: "hidden" }, group.end)-Kill nach ihrem Ausgangs-Tween haben – sonst werden Gruppen für spätere sichtbar.
  • Audio-reaktive Visuals: Extrahiere Audio-Bänder vorab (Bass / Mitten / Höhen) und sample pro Frame innerhalb der Timeline mit einer for-Schleife von tl.call(draw, [], f / fps) – ein einzelner langer Tween reagiert NICHT auf Audio. Mappen Sie Bass → scale (Puls), Höhen → textShadow/boxShadow (Leuchten), Gesamtamplitude → opacity/y/backgroundColor. Vermeiden Sie Equalizer-Balken-Klischees – lassen Sie den Inhalt die Visuals leiten und das Audio deren Verhalten steuern.
  • Marker-Hervorhebung: Hervorhebungs-, Kreis-, Burst-, Scribble-, Sketchout-Effekte zur 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 harten Schnitte). Wählen Sie aus CSS-Primitiven (Push-Slide, Blur-Überblendung, Zoom-Through, gestaffelte Blöcke) oder Shader-Übergängen (flash-through-white, liquid-wipe, cross-warp-morph, chromatic-split usw.) über npx hyperframes add. Stimmungs- und Energie-Tabellen finden Sie in references/features.md#übergänge. 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 Spuren, nicht registrierte Timelines
npx hyperframes validate          # WCAG-Kontrastprüfung zu 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     # finale Ausgabe

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-seitige Begleiter – führt die Seite zu mehreren Zeitstempeln aus und markiert Probleme, die ein statischer Lint nicht sehen kann (eine Bildunterschrift, 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ühren Sie inspect besonders bei Kompositionen mit Sprechblasen, Karten, Bildunterschriften oder enger Typografie aus.

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

Verwenden Sie den 7-Schritte-Workflow zur Erfassung von Website zu Video in references/website-to-video.md: Erfassung → DESIGN.md → SCRIPT.md → Storyboard → Komposition → Rendern → Ausliefern.

Bereinigung

render ist einmalig (Worker beenden sich, wenn es fertig ist). preview ist nicht – es führt einen Hintergrund-Next.js-Server aus, der Chrome-Worker resident hält, bis Sie ihn stoppen. Lassen Sie niemals einen laufen: Auf Hosts ohne GPU belegt der Swiftshader-Prozess jedes untätigen Workers einen CPU-Kern, und ein über Tage offener Preview stapelt mehrere auf.

Stoppen Sie eine Vorschau, wenn der Benutzer mit der Überprüfung fertig ist (oder bevor Sie eine neue starten):

pkill -f "hyperframes.*preview"     # der Studio-Server (gibt Port 3002 frei)
pkill -f chrome-headless-shell      # seine Render-Worker; nur sicher, wenn nichts anderes sie verwendet

Wenn Sie unsicher sind, ob andere Tools chrome-headless-shell verwenden, überprüfen Sie zuerst: pgrep -af chrome-headless-shell. Stellen Sie einen festgefahrenen Host (viele untätige Worker, die CPU drehen) auf die gleiche Weise wieder her – siehe references/troubleshooting.md.

Fallstricke

  • preview laufen lassen – es ist ein langlebiger Server, der Chrome-Worker hält; auf WSL/Containern/CI drehen diese untätigen Worker jeweils einen CPU-Kern (Software-WebGL). Stoppen Sie ihn, wenn Sie fertig sind – siehe Bereinigung.

  • 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 den 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 lang und geben dann eine Zeitüberschreitung. Führen Sie npx puppeteer browsers install chrome-headless-shell aus (setup.sh erledigt dies). hyperframes doctor meldet, welches Binärprogramm verwendet wird.

  • repeat: -1 irgendwo – unterbricht die Erfassungs-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, am oder nach dem data-start des Clips.

  • <br> innerhalb von Inhaltstext – erzwungene Umbrüche kennen die gerenderte Schriftbreite nicht, daher erzeugt natürlicher Umbruch + <br> doppelte Umbrüche. Verwenden Sie max-width, um Text umbrechen zu lassen. Ausnahme: kurze Anzeigetitel, bei denen jedes Wort absichtlich in einer eigenen Zeile steht.

  • Animieren von visibility oder display – GSAP kann diese nicht tweenen. 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 Erfassungs-Engine liest window.__timelines synchron nach dem Laden der Seite. Wickeln Sie die Timeline-Konstruktion niemals in async, setTimeout oder ein Promise.

  • Eigenständiges index.html in <template> verpackt – verbirgt den gesamten Inhalt vor dem Browser. Nur Unterkompositionen, die über data-composition-src geladen werden, verwenden <template>.

  • Video für Audio verwenden – 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 erfasst strukturelle Probleme, Validate erfasst Kontrast, Inspect erfasst visuelle Layout/Überlaufprobleme – siehe troubleshooting.md, wenn Warnungen erscheinen).
  2. Animations-Choreografie – führen Sie für neue Kompositionen oder signifikante Animationsänderungen die Animationskarte aus. npx hyperframes init kopiert die Fertigkeitsskripte in das Projekt, daher ist der Pfad projektspezifisch:
    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-Diagramm, Stagger-Erkennung, toten Zonen (>1s ohne Animation), Elementlebenszyklen und Flags (offscreen, collision, invisible, paced-fast <0.2s, paced-slow >2s) aus. Scannen Sie Zusammenfassungen und Flags – beheben oder begründen Sie jedes. Überspringen Sie dies bei kleinen Bearbeitungen.
  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=noprint_wrappers=1:nokey=1 final.mp4 && cat composition/index.html | grep -oP 'data-duration=\"\K[0-9.]+'.

Haftungsausschluss: Dies ist eine maschinelle Übersetzung einer KI-Fertigkeit. Die Funktionalität und das Verhalten der Fertigkeit sind identisch mit der englischen Originalversion.

Verwandte Skills