ZardLi1115/zedclaw

HyperFrames

HTML ist die Quelle der Wahrheit für Video. Eine Komposition ist eine HTML-Datei mit data-*-Attributen für das Timing, einer GSAP-Timeline für Animationen und CSS für das Aussehen. Die HyperFrames-Engine erfasst die Seite Frame für Frame und kodiert sie mit FFmpeg in MP4/WebM.

Ergänzung zu manim-video: Verwende manim-video für mathematische/geometrische Erklärungen (Gleichungen, 3B1B-Stil). Verwende hyperframes für Bewegungsgrafiken, Talking-Head mit Untertiteln, Produkttouren, Social-Overlays, Shader-Übergänge und alles, was von echtem Video/Audiomaterial angetrieben wird.

Anwendungsfälle

• Benutzer wünscht ein gerendertes Video aus Text, einem Skript oder einer Website
• Animierte Titelcards, Lower Thirds oder typografische Intros
• Untertitelte Erzählvideos (TTS + Untertitel synchron zur Wellenform)
• Audiovisuelle Effekte (Beat-Synchronisation, Spektrumsbalken, pulsierendes Leuchten)
• Szenenü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 zu einer Videodatei gerendert werden muss

Verwende 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 Vorschau/Rendering 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 ~/.zedclaw/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 (gibt Anweisungen zur Fehlerbehebung, falls nicht).
2. Installiert die hyperframes-CLI global (npm install -g hyperframes@>=0.4.2).
3. Lädt chrome-headless-shell über Puppeteer vor — erforderlich für beste Rendering-Qualität über Chrome's HeadlessExperimental.beginFrame-Erfassungspfad.
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 du Code schreibst, artikuliere auf hoher Ebene:

• Was — Erzählbogen, Schlüsselmomente, emotionale Schwerpunkte
• Struktur — Kompositionen, Spuren (Video/Audio/Overlays), Dauern
• Visuelle Identität — Farben, Schriftarten, Bewegungscharakter (explosiv / kinematisch / 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 visuelle Identität (HARD-GATE). Bevor du IRGENDEINE Komposition 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:

1. DESIGN.md im Projektstamm? → Verwende deren genaue Farben, Schriftarten, Bewegungsregeln und „Was NICHT zu tun“-Einschränkungen.

2. Benutzer hat einen Stil genannt (z. B. „Swiss Pulse“, „dunkel und technisch“, „Luxusmarke“)? → Erstelle eine minimale DESIGN.md mit ## Style Prompt, ## Colors (3-5 Hex-Werte mit Rollen), ## Typography (1-2 Familien), ## What NOT to Do (3-5 Antimuster).

3. Nichts davon? → Stelle 3 Fragen, bevor du HTML schreibst:

   • Stimmung? (explosiv / kinematisch / fließend / technisch / chaotisch / warm)
   • Heller oder dunkler Hintergrund?
   • Gibt es Markenfarben, Schriftarten oder visuelle Referenzen?

   Erstelle dann eine DESIGN.md aus den Antworten. Jede Komposition muss ihre Palette und Typografie auf DESIGN.md oder explizite Benutzervorgaben 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, --video clip.mp4 oder --audio track.mp3, um Medien hinzuzufügen.

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 Inhalte nach innen zu drücken — 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 gut aussieht, füge gsap.from()-Eingänge (zum CSS-Zustand hin 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 (kein repeat: -1 — bricht die Erfassungs-Engine). Berechne: repeat: Math.ceil(duration / cycleDuration) - 1.
• Deterministisch sein — kein Math.random(), Date.now() oder Wanduhrlogik. Verwende einen gesäten PRNG, falls Pseudozufälligkeit benötigt wird.
• Synchron aufgebaut werden — kein async/await, setTimeout oder Promises um die Timeline-Konstruktion.

Siehe references/gsap.md für die GSAP-Kern-API (Tweens, Eases, Stagger, Timelines).

5. Übergänge zwischen Szenen

Mehrszenen-Kompositionen erfordern Übergänge. Regeln:

1. Verwende immer einen Übergang zwischen Szenen — keine Jump Cuts.
2. Verwende immer Eingangsanimationen auf jedem Szenenelement (gsap.from(...)).
3. Verwende niemals Ausgangsanimationen außer in der letzten Szene — der Übergang IST der Ausgang.
4. Die letzte Szene kann ausgeblendet werden.

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, audiovisuelle Effekte, Hervorhebungen

• Audio: immer ein separates <audio>-Element (Video ist muted 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.) — die CLI leitet das Phonemizer-Gebietsschema automatisch ab; übergib --lang nur zum Überschreiben. Nicht-englische Phonemisierung erfordert systemweit installiertes espeak-ng.
• Untertitel: npx hyperframes transcribe narration.wav → wortgenaues Transkript. Wähle einen Stil basierend auf dem Transkript-Ton (Hype / Corporate / Tutorial / Storytelling / Social — siehe Tabelle in references/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 Untertitel-Gruppe MUSS einen harten tl.set(el, { opacity: 0, visibility: "hidden" }, group.end)-Kill nach ihrem Ausgangs-Tween haben — sonst lassen Gruppen später sichtbare Elemente zurück.
• Audiovisuelle Effekte: extrahiere Audio-Bänder (Bass / Mitten / Höhen) vorab und taste sie pro Frame innerhalb der Timeline mit einer for-Schleife von tl.call(draw, [], f / fps) ab — ein einzelner langer Tween reagiert NICHT auf Audio. Bilde Bass → scale (Puls) ab, Höhen → textShadow/boxShadow (Leuchten), Gesamtamplitude → opacity/y/backgroundColor. Vermeide Equalizer-Balken-Klischees — lasse den Inhalt die Optik leiten und das Audio das Verhalten steuern.
• Marker-Hervorhebungen: Hervorhebungs-, Kreis-, Burst-, Scribble-, Sketchout-Effekte für Textbetonung sind deterministisches CSS+GSAP — siehe references/features.md#marker-highlighting. Vollständig durchsuchbar, 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 Crossfade, Zoom Through, Staggered Blocks) oder Shader-Übergängen (flash-through-white, liquid-wipe, cross-warp-morph, chromatic-split usw.) über npx hyperframes add. Stimmungs- und Energietabellen befinden sich in references/features.md#transitions. Mische keine CSS- und Shader-Übergänge in derselben Komposition.

7. Lint, validieren, prüfen, Vorschau, rendern

npx hyperframes lint              # erkennt fehlende data-composition-id, überlappende Spuren, nicht registrierte Timelines
npx hyperframes validate          # WCAG-Kontrastprüfung an 5 Zeitpunkten
npx hyperframes inspect           # visuelle Layout-Prüfung — Ü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     # finale Ausgabe

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-Partner — führt die Seite zu mehreren Zeitpunkten aus und markiert Probleme, die ein statischer Lint nicht sehen 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 aus.

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.

Fehlerquellen

• HeadlessExperimental.beginFrame' wasn't found — Chromium 147+ hat dieses Protokoll entfernt. Stelle sicher, dass du hyperframes@>=0.4.2 verwendest (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) — Render-Vorgänge hängen 120s lang und brechen dann mit Timeout ab. Führe npx puppeteer browsers install chrome-headless-shell aus (setup.sh erledigt dies). hyperframes doctor meldet, welche Binärdatei verwendet wird.
• repeat: -1 irgendwo — bricht die Erfassungs-Engine. Berechne immer eine endliche Wiederholungszahl.
• gsap.set() auf Clipelementen, die später erscheinen — das Element existiert beim Seitenladen nicht. Verwende stattdessen tl.set(selector, vars, timePosition) innerhalb der Timeline, zum oder nach dem data-start des Clips.
• <br> im Inhaltstext — erzwungene Umbrüche kennen die gerenderte Schriftbreite nicht, daher verursachen natürlicher Umbruch + <br> doppelte Umbrüche. Verwende max-width, um Text umbrechen zu lassen. Ausnahme: kurze Anzeigetitel, bei denen jedes Wort bewusst in einer eigenen Zeile steht.
• Animation von visibility oder display — GSAP kann diese nicht tweenen. Verwende autoAlpha (behandelt sowohl Sichtbarkeit als auch Deckkraft).
• Aufruf von video.play() oder audio.play() — das Framework besitzt die Wiedergabe. Rufe diese niemals selbst auf.
• Asynchroner Aufbau von Timelines — die Erfassungs-Engine liest window.__timelines synchron nach dem Seitenladen aus. Wickele die Timeline-Konstruktion niemals in async, setTimeout oder ein Promise.
• Eigenständige index.html in <template> verpackt — verbirgt alle Inhalte vor dem Browser. Nur Sub-Kompositionen, die über data-composition-src geladen werden, verwenden <template>.
• Verwendung von Video für Audio — 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 erkennt strukturelle Probleme, validate erkennt Kontrastprobleme, inspect erkennt visuelle Layout-/Überlaufprobleme — siehe troubleshooting.md, falls Warnungen erscheinen).
2. Animations-Choreographie — für neue Kompositionen oder erhebliche Animationsänderungen führe die Animationskarte aus. npx hyperframes init kopiert die Skill-Skripte in das Projekt, daher ist der Pfad projektlokal:

   node skills/hyperframes/scripts/animation-map.mjs <kompositionsverzeichnis> \
     --out <kompositionsverzeichnis>/.hyperframes/anim-map
   

   Gibt eine einzelne animation-map.json mit Zusammenfassungen pro Tween, ASCII-Gantt-Timeline, Stagger-Erkennung, Dead Zones (>1s ohne Animation), Element-Lebenszyklen und Flags (offscreen, collision, invisible, paced-fast <0.2s, paced-slow >2s) aus. Scanne Zusammenfassungen und Flags — behebe oder rechtfertige jedes. Überspringe bei kleinen Änderungen.
3. Datei existiert + ungleich Null: ls -lh final.mp4.
4. Dauer stimmt mit data-duration überein: ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4.
5. Visuelle Prüfung: extrahiere einen Frame aus der Mitte der Komposition: ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png.
6. 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 dessen Ausgabe an, wenn du Bericht erstattest.

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, Eases, Stagger, Timelines, matchMedia)
• features.md — Untertitel, TTS, audiovisuelle Effekte, Marker-Hervorhebungen, Übergänge (bei Bedarf laden)
• website-to-video.md — 7-Schritte-Capture-to-Video-Workflow
• troubleshooting.md — OpenClaw-Fix, Umgebungsvariablen, häufige Render-Fehler