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. Das Framework übernimmt die Clip-Sichtbarkeit, Medienwiedergabe und
Timeline-Synchronisation.
Attribut-API, Kompositions-/Template-Struktur, Variablen und Medienregeln: references/authoring.md. Lesen Sie es, bevor Sie Ihre erste Kompositions-HTML in einer Sitzung schreiben.
Vorgehensweise
Entdeckung (nur bei explorativen Anfragen)
Bei offenen Anfragen („Erstellen Sie ein Produkt-Launch-Video“), bei denen der Benutzer keine Richtung festgelegt hat, verstehen Sie die Absicht, bevor Sie Farben auswählen: Zielgruppe, Plattform, Priorität (Bewegungsqualität vs. Genauigkeit vs. Geschwindigkeit) und ob der Benutzer Variationen wünscht. Bei Variationen bieten Sie 2–3 an, die sich im Tempo oder in der Struktur unterscheiden – eine sichere, eine ambitionierte – keine Farbwechsel.
Bei spezifischen Anfragen („Fügen Sie eine Titelgrafik hinzu“, „Korrigieren Sie das Timing von Szene 3“) überspringen Sie die Entdeckung.
Schritt 1: Designsystem
Wenn design.md oder DESIGN.md vorhanden ist, lesen Sie es zuerst (beide Schreibweisen – es
handelt sich auf Linux um unterschiedliche Dateien). Es ist die Quelle der Wahrheit für Markenfarben,
Schriftarten und Einschränkungen – verwenden Sie seine exakten Werte. Wenn es Schriftarten benennt,
für die keine .woff2-Dateien in fonts/ vorhanden sind und keine integrierte Entsprechung
vorhanden ist, warnen Sie den Benutzer vor dem Schreiben von HTML.
Wenn keine design.md vorhanden ist, bieten Sie eine Auswahl an:
- Hat der Benutzer einen Stil oder eine Stimmung genannt? Lesen Sie visual-styles.md (8 benannte Voreinstellungen) und wählen Sie die nächstgelegene.
- Visuell stöbern? Führen Sie die Design-Auswahl aus - references/design-picker.md.
- Schnell vorgehen? Fragen Sie nach Stimmung, hell/dunkel, Markenfarben/Schriftarten; wählen Sie eine Palette aus house-style.md.
design.md definiert die Marke, nicht die Videokompositionsregeln. Diese stammen aus references/video-composition.md und house-style.md. Markenfarben in Videogröße, nicht Web-UI-Opazität.
Schritt 2: Prompt-Erweiterung
Wird bei jeder Komposition ausgeführt, außer bei Einzelszenenstücken und trivialen Änderungen – verankert die Absicht an design.md/house-style.md in einem konsistenten Zwischenschritt. Prozess und Format: references/prompt-expansion.md.
Schritt 3: Planen
- Was - Erzählbogen, Schlüsselmomente, emotionale Schwerpunkte.
- Struktur - wie viele Kompositionen, Sub-Kompositionen vs. inline, welche Spuren tragen was.
- Rhythmus - deklarieren Sie den Szenenrhythmus vor der Implementierung (schnell-schnell-LANGSAM-schnell-SHADER-Haltepunkt). Vorlagen: references/beat-direction.md.
- Timing - welche Clips die Dauer bestimmen, wo Übergänge stattfinden.
- Layout - erstellen Sie zuerst den Endzustand (nächster Abschnitt).
- Animieren - fügen Sie dann Bewegung hinzu.
Erstellen Sie, worum gebeten wurde. „Eine Titelgrafik“ ist nicht „eine Titelgrafik + 3 unterstützende Szenen + Musik + Untertitel.“ Schlagen Sie Ergänzungen vor; fügen Sie sie nicht hinzu.
Bei kleinen Änderungen springen Sie direkt zu den Regeln.
Layout vor Animation
Positionieren Sie jedes Element dort, wo es in seinem sichtbarsten Moment sein soll - vollständig eingetreten, korrekt platziert, noch nicht austretend. Schreiben Sie dies zuerst als statisches HTML+CSS. Noch kein GSAP.
Warum: Wenn Sie Elemente in ihrem animierten Startzustand positionieren (außerhalb des Bildschirms, Opazität 0) und in Richtung des vermeintlichen Endzustands tweenen, raten Sie das endgültige Layout, und Überlappungen bleiben bis zum Rendern unsichtbar. Bauen Sie zuerst den Endzustand, dann sind Layout-Fehler sichtbar, bevor Bewegung existiert.
- Identifizieren Sie den Hero-Frame pro Szene - den Moment, in dem die meisten Elemente gleichzeitig sichtbar sind. Erstellen Sie dieses Layout.
- Schreiben Sie statisches CSS dafür.
.scene-contentMUSS die Szene ausfüllen:width: 100%; height: 100%; padding: Npx;mitdisplay: flex; flex-direction: column; gap: Npx; box-sizing: border-box. Padding drückt den Inhalt nach innen - NIEMALSposition: absolute; top: Npxauf einem Inhaltscontainer (er läuft über, wenn der Inhalt wächst). Reservieren Sie absolute Positionierung für dekorative Elemente. - Eingänge mit
gsap.from()- animieren VON außerhalb des Bildschirms ZUR CSS-Position. CSS ist die Grundwahrheit; der Tween ist die Reise. (Sub-Kompositionen, die überdata-composition-srcgeladen werden: bevorzugen Siegsap.fromTo()- siehe references/motion-principles.md.) - Nur letzte Szene: Ausgänge mit
gsap.to(). Alle anderen Szenen enden vollständig sichtbar - der Übergang IST der Ausgang (Übergangsregel 3 unten).
Wenn Element A aussteigt, bevor Element B im selben Bereich eintritt, geben Sie beiden korrekte CSS-Positionen für ihre eigenen Hero-Frames - die Timeline verhindert, dass sie koexistieren, und der Layout-Schritt fängt versehentliche Überlappungen durch Timing-Fehler auf. Absichtliche Schichtung (Glühen hinter Text, Kartenstapel) ist in Ordnung; der Schritt dient dazu, unbeabsichtigte Überlappungen zu erkennen - zwei Überschriften, die kollidieren, eine Statistik, die ein Label bedeckt, Inhalt außerhalb des Frames.
Timeline-Vertrag
- Alle Timelines starten
{ paused: true }- der Player steuert die Wiedergabe - Registrieren Sie jede Timeline:
window.__timelines["<composition-id>"] = tl - Das Framework verschachtelt Unter-Timelines automatisch - fügen Sie sie NICHT manuell hinzu
- Die Dauer ergibt sich aus
data-duration, nicht aus der GSAP-Timeline-Länge - Erstellen Sie niemals leere Tweens, um die Dauer festzulegen
Regeln (Nicht verhandelbar)
Deterministisch: kein Math.random(), Date.now() oder zeitbasierte Logik.
Gesäter PRNG (z. B. mulberry32) für Pseudo-Zufall.
GSAP: animieren Sie nur visuelle Eigenschaften (opacity, x, y, scale,
rotation, color, backgroundColor, borderRadius, Transforms). Animieren Sie niemals
visibility oder display; rufen Sie niemals video.play()/audio.play() auf.
Animationskonflikte: animieren Sie niemals dieselbe Eigenschaft auf demselben Element von mehreren Timelines gleichzeitig.
Kein repeat: -1: unendliche Wiederholungen brechen die Capture-Engine. Berechnen Sie
repeat: Math.ceil(duration / cycleDuration) - 1.
Synchrone Timeline-Konstruktion: erstellen Sie Timelines niemals innerhalb von
async/await, setTimeout oder Promises - die Capture-Engine liest
window.__timelines synchron nach dem Laden. Schriftarten werden vom Compiler eingebettet;
kein Warten auf Schriftarten-Laden.
Niemals tun:
window.__timelines-Registrierung vergessen- Video für Audio verwenden - immer stummgeschaltetes Video + separates
<audio> - Video in einem getakteten Div verschachteln - einen nicht getakteten Wrapper verwenden
data-layerverwenden (data-track-indexverwenden) oderdata-end(data-durationverwenden)- Videoelementabmessungen animieren - einen Wrapper-Div animieren
- play/pause/seek auf Medien aufrufen - Framework besitzt die Wiedergabe
- Einen Top-Level-Container ohne
data-composition-iderstellen repeat: -1auf einer Timeline oder einem Tween verwenden- Timelines asynchron erstellen
gsap.set()auf Clip-Elementen aus späteren Szenen verwenden - sie existieren nicht im DOM beim Seitenladen. Verwenden Sietl.set(selector, vars, timePosition)bei oder nach demdata-startdes Clips.<br>im Inhaltstext verwenden - es stapelt sich mit natürlichem Umbruch und verursacht Überlappungen; stattdessenmax-widthverwenden. Ausnahme: kurze Anzeigetitel absichtlich ein Wort pro Zeile.
Szenenübergänge (Nicht verhandelbar)
Jede Multi-Szenen-Komposition MUSS alle vier befolgen. Die Verletzung einer einzigen ist eine kaputte Komposition.
- IMMER Übergänge zwischen Szenen verwenden. Keine Jump-Cuts.
- IMMER jedes Element IN via
gsap.from()animieren. Nichts erscheint vollständig geformt. Fünf Elemente bedeuten fünf Eingangs-Tweens. - Niemals Ausgangsanimationen verwenden, außer in der letzten Szene. Kein
gsap.to(), das die Opazität verblassen lässt, aus dem Bildschirm bewegt oder auf 0 skaliert, bevor ein Übergang stattfindet - der Übergang IST der Ausgang, und die ausgehende Szene muss vollständig sichtbar sein, wenn er ausgelöst wird. Ein Ausgangs-Tween vor einem Übergang übergibt dem Übergang einen leeren Frame. - Nur die letzte Szene kann Elemente ausblenden.
Übergangsauswahl und -implementierung: references/transitions.md.
Animations-Leitplanken
- Erste Animation um 0,1-0,3s versetzen (nicht bei t=0)
- Eases variieren - mindestens 3 verschiedene Eases pro Szene, kein wiederholtes Eingangsmuster innerhalb einer Szene
- Vollbild-lineare Verläufe auf dunklen Hintergründen vermeiden (H.264-Banding) - radial oder einfarbig + lokalisierter Glow
- 60px+ Überschriften, 20px+ Fließtext, 16px+ Datenbeschriftungen
font-variant-numeric: tabular-numsbei Zahlenspalten
Bearbeiten bestehender Kompositionen
- Tatsächliche Dateien lesen, nicht raten. Die Komposition IST die Spezifikation - extrahieren Sie exakte Hex-Codes, Schriftarten und Easing-Muster aus der Quelle, nicht aus dem Gedächtnis.
- Nur das ändern, was angefordert wurde; Timing nicht betroffener Clips beibehalten.
Ausgabe-Checkliste
Schnell (sofort ausführen, blockieren bei Ergebnissen):
-
npx hyperframes lintundnpx hyperframes validatebestehen beide - Designeinhaltung verifiziert, falls design.md vorhanden
Langsam (parallel ausführen, während die Vorschau präsentiert wird):
-
npx hyperframes inspectbesteht, oder jeder gemeldete Überlauf ist absichtlich markiert - Kontrastwarnungen behandelt
- Animationschoreografie verifiziert (Animationskarten-Skript)
Wie man jede Prüfung ausführt und behebt: references/quality-checks.md.
Referenzindex
Immer lesen für jede neue Komposition:
| Datei | Deckt ab |
|---|---|
| references/authoring.md | data-Attribute, Template-Struktur, Variablen, Video/Audio, Schriftarten/Assets |
| references/video-composition.md | Videomedium-Regeln - diese überschreiben Web-Instinkte |
| references/typography.md | Schriftpaarung, OpenType, Anpassungen für dunkle Hintergründe |
| references/motion-principles.md | Bewegungsdesign, Bildbewegung, tragende GSAP-Regeln |
Auch immer lesen für Multi-Szenen-Kompositionen:
| Datei | Deckt ab |
|---|---|
| references/beat-direction.md | Rhythmus-Vorlagen, Choreografie-Verben, Tiefenschichten |
| references/transitions.md | Übergangsauswahl; Katalog führt zu Implementierungen; Shader-Übergänge befinden sich im @hyperframes/shader-transitions npm-Paket (lesen Sie seinen Quellcode in node_modules) |
Lesen, wenn die Aufgabe es erfordert:
| Datei | Lesen, wenn |
|---|---|
| references/quality-checks.md | Ausführen von inspect/contrast/design/animation-map-Prüfungen |
| references/cli.md | Jeder CLI-Befehl; Build/Render-Fehlerbehebung |
| references/captions.md | Jeder Text, der mit Audio-Timing synchronisiert ist |
| references/transcript-guide.md | Untertitel-seitige Transkriptverarbeitung (CLI-Aufruf befindet sich in media.md) |
| references/dynamic-techniques.md | Dynamische Untertitel-Animation (Karaoke, Slam, Scatter) |
| references/audio-reactive.md | Visuals, die auf Musik/Stimme reagieren |
| references/css-patterns.md | Marker-Hervorhebung (highlight, circle, burst, scribble) |
| references/techniques.md | Planungstechniken pro Beat (11 Muster mit Code) |
| references/narration.md | Voiceover/TTS-Tempo und Skriptstruktur |
| references/media.md | TTS (Kokoro), Transkription (Whisper), Hintergrundentfernung |
| references/prompt-expansion.md | Schritt 2 des Vorgehens |
| references/design-picker.md | Erstellen einer design.md visuell |
| references/from-website.md | Eine Website in ein Video verwandeln |
| references/registry.md | Installieren/Beitragen von Registry-Blöcken (hyperframes add) |
| visual-styles.md | Benutzer nennt einen Stil; Generieren von design.md |
| house-style.md | Ästhetische Standardeinstellungen, wenn keine design.md vorhanden |
| patterns.md | PiP, Titelgrafiken, Diashows |
| data-in-motion.md | Daten, Statistiken, Infografiken |
Laufzeit-Adapter (lesen, wenn die Komposition diese Laufzeit anstelle von GSAP verwendet): waapi, lottie, three, animejs, css-animations, typegpu.