Kingly-Agency/deadzone

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 Erscheinungsbild. 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ärvideos (Gleichungen, 3B1B-Stil). Verwende hyperframes für Bewegungsgrafiken, Talking-Head mit Untertiteln, Produkttouren, Social-Overlays, Shader-Übergänge und alles, was von echten Video-/Audiomedien gesteuert wird.

Wann verwenden

• Der Nutzer wünscht ein gerendertes Video aus Text, einem Skript oder einer Website
• Animierte Titelcards, Lower Thirds oder typografische Intros
• Besprochenes Erzählvideo (TTS + Untertitel synchron zur Wellenform)
• Audio-reaktive Visualisierungen (Beatsync, Spektrumbalken, pulsierendes Leuchten)
• Szenenübergänge (Überblendung, Wischeffekt, Shader-Warp, Flash-Through-White)
• Social-Overlays (Instagram/TikTok/YouTube-Stil)
• Website-zu-Video-Pipeline (Erfasse eine URL, erstelle einen Werbefilm)
• Jede HTML/CSS/JS-Animation, die deterministisch zu einer Videodatei gerendert werden muss

Verwende diesen Skill 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 aufsetzen
cd my-video
npx hyperframes lint                        # Vor Vorschau/Rendering validieren
npx hyperframes preview                     # Live-Neuladung im Browser (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:

1. Überprüft, ob Node.js >= 22 und FFmpeg installiert sind (druckt Korrekturanweisungen, falls nicht).
2. Installiert die hyperframes-CLI global (npm install -g hyperframes@>=0.4.2).
3. Cached chrome-headless-shell über Puppeteer vor – 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.

Verfahren

1. Planen vor dem Schreiben von HTML

Bevor Code geschrieben wird, auf hoher Ebene Folgendes artikulieren:

• Was – Erzählbogen, Schlüsselmomente, emotionale Schwerpunkte
• Struktur – Kompositionen, Spuren (Video/Audio/Overlays), Dauern
• Visuelle Identität – Farben, Schriftarten, Bewegungscharakter (explosiv / cineastisch / 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.

Visuelle Identitätsprüfung (HARTE PRÜFUNG). Bevor eine 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). In dieser Reihenfolge prüfen:

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

2. Der Nutzer hat einen Stil genannt (z. B. „Swiss Pulse“, „dunkel und technisch“, „Luxusmarke“)? → Erstelle eine minimale DESIGN.md mit ## Style Prompt, ## Colors (3-5 Hex mit Rollen), ## Typography (1-2 Familien), ## Was nicht zu tun (3-5 Anti-Patterns).

3. Keines der oben genannten? → Stelle vor dem Schreiben von HTML 3 Fragen:

   • Stimmung? (explosiv / cineastisch / fließend / technisch / chaotisch / warm)
   • Helle oder dunkle Leinwand?
   • Gibt es Markenfarben, Schriftarten oder visuelle Referenzen?

   Erstelle dann aus den Antworten eine DESIGN.md. Jede Komposition muss ihre Palette und Typografie auf DESIGN.md oder eine explizite Nutzeranweisung 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. Mit --example <name> eine auswählen, mit --video clip.mp4 oder --audio track.mp3 Medien hinzufü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 ausfüllen (width:100%; height:100%; padding:Npx) mit display:flex + gap. Verwende 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üge gsap.from()-Eingänge (zur CSS-Position animieren) und gsap.to()-Ausgänge (davon weg animieren) hinzu.

Siehe references/composition.md für das vollständige Datenattributschema 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 (kein repeat: -1 – zerstört die Erfassungs-Engine). Berechnen: repeat: Math.ceil(Dauer / Zyklusdauer) - 1.
• Deterministisch sein – kein Math.random(), Date.now() oder Wanduhrlogik. Verwende einen gesetzten PRNG, falls Pseudo-Zufälligkeit benötigt wird.
• Synchron aufgebaut sein – 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

Kompositionen mit mehreren Szenen erfordern Übergänge. Regeln:

1. Verwende immer einen Übergang zwischen Szenen – keine Sprungschnitte.
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, etc.). Vollständige Liste: npx hyperframes add --list.

6. Audio, Untertitel, TTS, audio-reaktiv, Hervorhebung

• Audio: immer ein separates <audio>-Element (Video ist muted playsinline).
• TTS: npx hyperframes tts "Skripttext" --voice af_nova --output narration.wav. Stimmen mit --list auflisten. Der erste Buchstabe der Stimmen-ID kodiert die Sprache (a/b=Englisch, e=Spanisch, f=Französisch, j=Japanisch, z=Mandarin, etc.) – die CLI erkennt das Phonemizer-Gebietsschema automatisch; --lang nur zum Überschreiben übergeben. Die Phonemisierung in anderen Sprachen erfordert systemweit installiertes espeak-ng.
• Untertitel: npx hyperframes transcribe narration.wav → Transkript auf Wortebene. Wähle einen Stil passend zum 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 bestätigt Englisch – .en übersetzt nicht-englisches Audio anstatt es zu transkribieren. Jede Untertitel-Gruppe MUSS nach ihrem Exit-Tween einen harten tl.set(el, { opacity: 0, visibility: "hidden" }, group.end)-Kill haben – sonst bleiben Gruppen für spätere sichtbar.
• Audio-reaktive Visualisierungen: Extrahiere vorab Audiobänder (Bass / Mitten / Höhen) und taste 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), Höhen → textShadow/boxShadow (Glühen), Gesamtamplitude → opacity/y/backgroundColor ab. Vermeide Equalizer-Balken-Klischees – lass den Inhalt die Visualisierung leiten, das Audio ihr Verhalten steuern.
• Marker-Hervorhebung: Hervorhebung, Kreis, Burst, Kritzelei, 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 Komposition mit mehreren Szenen MUSS Übergänge verwenden (keine Sprungschnitte). Wähle aus CSS-Primitiven (Push-Slide, Unschärfe-Überblendung, Zoom-Through, gestaffelte Blöcke) oder Shader-Übergängen (flash-through-white, liquid-wipe, cross-warp-morph, chromatic-split, etc.) über npx hyperframes add. Stimmungs- und Energie-Tabellen befinden sich in references/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 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 das Layout-Pendant – durchläuft die Seite zu mehreren Zeitpunkten und markiert Probleme, die ein statischer Linter nicht sieht (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 Shader-Übergang 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-Erfassungs-zu-Video-Workflow in references/website-to-video.md: Erfassen → DESIGN.md → SCRIPT.md → Storyboard → Komposition → Rendern → Ausliefern.

Fallstricke

• 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). Escape-Hatch: export PRODUCER_FORCE_SCREENSHOT=true. Siehe hyperframes#294 und references/troubleshooting.md.
• System-Chrome (nicht chrome-headless-shell) – Renderings hängen 120s und werden dann mit Timeout beendet. Führe npx puppeteer browsers install chrome-headless-shell aus (setup.sh macht das). hyperframes doctor meldet, welche Binärdatei verwendet wird.
• repeat: -1 irgendwo – zerstört die Erfassungs-Engine. Berechne immer eine endliche Wiederholungsanzahl.
• gsap.set() auf Clip-Elementen, die später eintreten – das Element existiert beim Laden der Seite nicht. Verwende stattdessen tl.set(selector, vars, timePosition) innerhalb der Timeline, zum oder nach dem data-start des Clips.
• <br> innerhalb von Inhaltstext – erzwungene Umbrüche kennen die Breite der gerenderten Schriftart nicht, daher verursacht 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.
• Animieren von visibility oder display – GSAP kann diese nicht tweenen. Verwende autoAlpha (behandelt sowohl Sichtbarkeit als auch Deckkraft).
• Aufrufen von video.play() oder audio.play() – das Framework besitzt die Wiedergabe. Rufe diese niemals selbst auf.
• Asynchrones Erstellen von Timelines – die Erfassungs-Engine liest window.__timelines synchron nach dem Laden der Seite. Wickle die Timeline-Konstruktion nie in async, setTimeout oder ein Promise ein.
• Eigenständige 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>.

Verifikation

Vor und nach dem Rendern:

1. Lint + Validate + Inspect bestehen: 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 auftreten).
2. Animations-Choreografie – bei neuen Kompositionen oder signifikanten Animationsänderungen die Animationskarte ausführen. npx hyperframes init kopiert die Skill-Skripte in das Projekt, daher ist der Pfad projektspezifisch:

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

   Gibt eine einzelne animation-map.json aus mit Zusammenfassungen pro Tween, ASCII-Gantt-Diagramm, 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 rechtfertige jedes. Überspringe bei kleinen Änderungen.
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=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.

Falls hyperframes render fehlschlägt, führe npx hyperframes doctor aus und füge die Ausgabe bei der Meldung bei.

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, Eases, Stagger, Timelines, matchMedia)
• features.md – Untertitel, TTS, audio-reaktiv, Marker-Hervorhebung, Übergänge (bei Bedarf laden)
• website-to-video.md – 7-Schritte-Erfassungs-zu-Video-Workflow
• troubleshooting.md – OpenClaw-Fix, Umgebungsvariablen, häufige Renderfehler