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:
- Überprüft, ob Node.js >= 22 und FFmpeg installiert sind (zeigt Korrekturanweisungen an, falls nicht).
- Installiert die
hyperframes-CLI global (npm install -g hyperframes@>=0.4.2). - Lädt
chrome-headless-shellüber Puppeteer vorab in den Cache – erforderlich für die beste Rendering-Qualität über denHeadlessExperimental.beginFrame-Erfassungspfad von Chrome. - Führt
npx hyperframes doctoraus 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:
-
DESIGN.mdim Projektstamm? → Verwenden Sie dessen genaue Farben, Schriftarten, Bewegungsregeln und „Was man NICHT tun sollte“-Einschränkungen. -
Benutzer hat einen Stil genannt (z.B. „Swiss Pulse“, „dunkel und technisch“, „Luxusmarke“)? → Generieren Sie ein minimales
DESIGN.mdmit## Stil-Eingabeaufforderung,## Farben(3-5 Hex mit Rollen),## Typografie(1-2 Familien),## Was man NICHT tun sollte(3-5 Anti-Patterns). -
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 aufDESIGN.mdoder 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 (keinrepeat: -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,setTimeoutoder 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:
- Verwenden Sie IMMER einen Übergang zwischen Szenen – keine harten Schnitte.
- Verwenden Sie IMMER Eingangsanimationen für jedes Szenenelement (
gsap.from(...)). - Verwenden Sie NIEMALS Ausgangsanimationen außer in der letzten Szene – der Übergang IST der Ausgang.
- 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 istmuted playsinline). - TTS:
npx hyperframes tts "Skripttext" --voice af_nova --output narration.wav. Listen Sie Stimmen mit--listauf. 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--langnur zum Überschreiben. Die Phonemisierung für nicht-englische Sprachen erfordert die systemweite Installation vonespeak-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 inreferences/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 hartentl.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 vontl.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-splitusw.) übernpx hyperframes add. Stimmungs- und Energie-Tabellen finden Sie inreferences/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
-
previewlaufen 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 Siehyperframes@>=0.4.2verwenden (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 Sienpx puppeteer browsers install chrome-headless-shellaus (setup.sh erledigt dies).hyperframes doctormeldet, welches Binärprogramm verwendet wird. -
repeat: -1irgendwo – 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 stattdessentl.set(selector, vars, timePosition)innerhalb der Timeline, am oder nach demdata-startdes Clips. -
<br>innerhalb von Inhaltstext – erzwungene Umbrüche kennen die gerenderte Schriftbreite nicht, daher erzeugt natürlicher Umbruch +<br>doppelte Umbrüche. Verwenden Siemax-width, um Text umbrechen zu lassen. Ausnahme: kurze Anzeigetitel, bei denen jedes Wort absichtlich in einer eigenen Zeile steht. -
Animieren von
visibilityoderdisplay– GSAP kann diese nicht tweenen. Verwenden SieautoAlpha(behandelt sowohl Sichtbarkeit als auch Deckkraft). -
Aufrufen von
video.play()oderaudio.play()– das Framework besitzt die Wiedergabe. Rufen Sie diese niemals selbst auf. -
Asynchrones Erstellen von Timelines – die Erfassungs-Engine liest
window.__timelinessynchron nach dem Laden der Seite. Wickeln Sie die Timeline-Konstruktion niemals inasync,setTimeoutoder ein Promise. -
Eigenständiges
index.htmlin<template>verpackt – verbirgt den gesamten Inhalt vor dem Browser. Nur Unterkompositionen, die überdata-composition-srcgeladen werden, verwenden<template>. -
Video für Audio verwenden – immer stummgeschaltetes
<video>+ separates<audio>.
Überprüfung
Vor und nach dem Rendern:
- 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). - Animations-Choreografie – führen Sie für neue Kompositionen oder signifikante Animationsänderungen die Animationskarte aus.
npx hyperframes initkopiert die Fertigkeitsskripte in das Projekt, daher ist der Pfad projektspezifisch:
Gibt eine einzelnenode skills/hyperframes/scripts/animation-map.mjs <composition-dir> \ --out <composition-dir>/.hyperframes/anim-mapanimation-map.jsonmit 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. - Datei existiert + nicht null:
ls -lh final.mp4. - 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.