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 die Animation und CSS für das Erscheinungsbild. Das Framework übernimmt Clip-Sichtbarkeit, Medienwiedergabe und Timeline-Synchronisation.
Vorgehen
Bevor HTML geschrieben wird, sollte auf einer hohen Ebene gedacht werden:
- Was — was soll der Betrachter erleben? Identifizieren Sie den narrativen Bogen, die Schlüsselmomente und die emotionalen Höhepunkte.
- Struktur — wie viele Kompositionen, welche sind Sub-Kompositionen vs. Inline, welche Spuren transportieren was (Video, Audio, Overlays, Untertitel).
- Timing — welche Clips steuern die Dauer, wo liegen die Übergänge, wie ist die Taktung.
- Layout — bauen Sie den Endzustand zuerst. Siehe „Layout vor Animation“ unten.
- Animieren — fügen Sie dann Bewegung mit den untenstehenden Regeln hinzu.
Bei kleinen Änderungen (Farbe korrigieren, Timing anpassen, ein Element hinzufügen) direkt zu den Regeln springen.
Visuelle Identität – Prüfpunkt
Prüfen Sie in dieser Reihenfolge:
- Existiert DESIGN.md im Projekt? → Lesen Sie sie. Verwenden Sie deren genaue Farben, Schriften, Bewegungsregeln und die „Was NICHT zu tun ist“-Einschränkungen.
- Existiert visual-style.md? → Lesen Sie sie. Wenden Sie deren
style_prompt_fullund strukturierte Felder an. (Hinweis:visual-style.mdist eine projektspezifische Datei.visual-styles.mdist die Stilbibliothek mit 8 benannten Voreinstellungen – unterschiedliche Dateien.) - Hat der Benutzer einen Stil genannt (z. B. „Swiss Pulse“, „dunkel und technisch“, „Luxusmarke“)? → Lesen Sie visual-styles.md für die 8 benannten Voreinstellungen. Erstellen Sie eine minimale DESIGN.md mit:
## Stil-Prompt(ein Absatz),## Farben(3-5 Hex-Werte mit Rollen),## Typografie(1-2 Schriftfamilien),## Was NICHT zu tun ist(3-5 Anti-Patterns). - Nichts davon? → Stellen Sie 3 Fragen, bevor Sie HTML schreiben:
- Welche Stimmung? (explosiv / kinematografisch / flüssig / technisch / chaotisch / warm)
- Helle oder dunkle Leinwand?
- Gibt es bestimmte Markenfarben, Schriften oder visuelle Referenzen? Generieren Sie dann eine minimale DESIGN.md aus den Antworten.
Jede Komposition muss ihre Farbpalette und Typografie auf eine DESIGN.md, visual-style.md oder eine explizite Benutzeranweisung zurückführen können. Wenn Sie zu #333, #3b82f6 oder Roboto greifen, haben Sie diesen Schritt übersprungen.
Für Bewegungsvorgaben, Größen, Eingangsmuster und Easings folgen Sie der house-style.md. Der Hausstil regelt WIE sich Dinge bewegen. Die DESIGN.md regelt WIE Dinge aussehen.
Layout vor Animation
Positionieren Sie jedes Element dort, wo es sich in seinem sichtbarsten Moment befinden soll – dem Bild, in dem es vollständig eingetreten, korrekt platziert und noch nicht ausgetreten ist. Schreiben Sie dies zuerst als statisches HTML+CSS. Noch kein GSAP.
Warum das wichtig ist: Wenn Sie Elemente in ihrem animierten Startzustand (außerhalb des Bildschirms, skaliert auf 0, Deckkraft 0) positionieren und sie dann an die Position tweenen, von der Sie glauben, dass sie dort landen sollen, raten Sie das endgültige Layout. Überlappungen sind unsichtbar, bis das Video gerendert wird. Indem Sie den Endzustand zuerst erstellen, können Sie Layout-Probleme sehen und beheben, bevor Sie Bewegung hinzufügen.
Der Prozess
- Identifizieren Sie den Heldenframe für jede Szene – den Moment, in dem die meisten Elemente gleichzeitig sichtbar sind. Dies ist das Layout, das Sie bauen.
- Schreiben Sie statisches CSS für diesen Frame. Der
.scene-content-Behälter MUSS die gesamte Szene mitwidth: 100%; height: 100%; padding: Npx;füllen, mitdisplay: flex; flex-direction: column; gap: Npx; box-sizing: border-box. Verwenden Sie Padding, um den Inhalt nach innen zu schieben – NIEMALSposition: absolute; top: Npxauf einem Inhaltscontainer. Absolut positionierte Inhaltscontainer laufen über, wenn der Inhalt höher ist als der verbleibende Platz. Reservieren Sieposition: absolutenur für Dekorationen. - Fügen Sie Eintritte mit
gsap.from()hinzu – animieren Sie VON außerhalb/unsichtbar ZU der CSS-Position. Die CSS-Position ist die Grundwahrheit; der Tween beschreibt den Weg dorthin. - Fügen Sie Austritte mit
gsap.to()hinzu – animieren Sie ZU außerhalb/unsichtbar VON der CSS-Position.
Beispiel
/* scene-content füllt die Szene, Padding positioniert den Inhalt */
.scene-content {
display: flex;
flex-direction: column;
justify-content: center;
width: 100%;
height: 100%;
padding: 120px 160px;
gap: 24px;
box-sizing: border-box;
}
.title {
font-size: 120px;
}
.subtitle {
font-size: 42px;
}
/* Container füllt jede Szenengröße (1920x1080, 1080x1920, etc.).
Padding positioniert den Inhalt. Flex + Gap handhabt Abstände. */
FALSCH — fest codierte Abmessungen und absolute Positionierung:
.scene-content {
position: absolute;
top: 200px;
left: 160px;
width: 1920px;
height: 1080px;
display: flex; /* ... */
}
// Schritt 3: IN diese Positionen animieren
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);
// Schritt 4: VON diesen Positionen AUS animieren
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);
Wenn Elemente sich Raum über die Zeit teilen
Wenn Element A austritt, bevor Element B im selben Bereich eintritt, sollten beide korrekte CSS-Positionen für ihre jeweiligen Heldenframes haben. Die Timeline-Reihenfolge garantiert, dass sie nie visuell koexistieren – aber wenn Sie den Layout-Schritt überspringen, werden Sie den Fall nicht bemerken, wo sie aufgrund eines Timing-Fehlers versehentlich überlappen.
Was als absichtliche Überlappung gilt
Geschichtete Effekte (Glühen hinter Text, Schattenelemente, Hintergrundmuster) und Z-gestapelte Designs (Kartenstapel, Tiefenschichten) sind absichtlich. Der Layout-Schritt dient dazu, unabsichtliche Überlappungen zu erkennen – zwei Überschriften, die aufeinander landen, eine Statistik, die ein Label bedeckt, Inhalt, der aus dem Rahmen läuft.
Datenattribute
Alle Clips
| Attribut | Erforderlich | Werte |
|---|---|---|
id | Ja | Eindeutiger Bezeichner |
data-start | Ja | Sekunden oder Clip-ID-Referenz ("el-1", "intro + 2") |
data-duration | Erforderlich für img/div/compositions | Sekunden. Video/Audio standardmäßig Mediendauer. |
data-track-index | Ja | Ganzzahl. Clips auf derselben Spur können sich nicht überlappen. |
data-media-start | Nein | Versatz in die Quelle (Sekunden) |
data-volume | Nein | 0-1 (Standard 1) |
data-track-index beeinflusst nicht die visuelle Schichtung – verwenden Sie CSS z-index.
Kompositions-Clips
| Attribut | Erforderlich | Werte |
|---|---|---|
data-composition-id | Ja | Eindeutige Kompositions-ID |
data-start | Ja | Startzeit (Root-Komposition: "0" verwenden) |
data-duration | Ja | Hat Vorrang vor der GSAP-Timeline-Dauer |
data-width / data-height | Ja | Pixelmaße (1920x1080 oder 1080x1920) |
data-composition-src | Nein | Pfad zur externen HTML-Datei |
Kompositionsstruktur
Sub-Kompositionen, die via data-composition-src geladen werden, verwenden einen <template>-Wrapper. Standalone-Kompositionen (die Hauptdatei index.html) verwenden KEIN <template> – sie platzieren das data-composition-id-div direkt im <body>. Die Verwendung von <template> bei einer Standalone-Datei versteckt alle Inhalte vor dem Browser und bricht das Rendering.
Sub-Kompositionsstruktur:
<template id="my-comp-template">
<div data-composition-id="my-comp" data-width="1920" data-height="1080">
<!-- Inhalt -->
<style>
[data-composition-id="my-comp"] {
/* Gültigkeitsbereich Styles */
}
</style>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
// Tweens...
window.__timelines["my-comp"] = tl;
</script>
</div>
</template>
Laden in Root: <div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>
Video und Audio
Video muss muted playsinline sein. Audio ist immer ein separates <audio>-Element:
<video
id="el-v"
data-start="0"
data-duration="30"
data-track-index="0"
src="video.mp4"
muted
playsinline
></video>
<audio
id="el-a"
data-start="0"
data-duration="30"
data-track-index="2"
src="video.mp4"
data-volume="1"
></audio>
Timeline-Vertrag
- Alle Timelines starten mit
{ paused: true }– der Player steuert die Wiedergabe - Registrieren Sie jede Timeline:
window.__timelines["<composition-id>"] = tl - Das Framework verschachtelt Sub-Timelines automatisch – fügen Sie sie NICHT manuell hinzu
- Dauer stammt von
data-duration, nicht von 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. Verwenden Sie einen gesetzten PRNG, wenn Sie pseudo-zufällige Werte benötigen (z. B. mulberry32).
GSAP: Animieren Sie nur visuelle Eigenschaften (opacity, x, y, scale, rotation, color, backgroundColor, borderRadius, Transforms). Animieren Sie NICHT visibility, display oder rufen Sie video.play()/audio.play() auf.
Animationskonflikte: Animieren Sie niemals dieselbe Eigenschaft auf demselben Element von mehreren Timelines aus gleichzeitig.
Kein repeat: -1: Timeline mit unendlicher Wiederholung brechen die Capture-Engine. Berechnen Sie die genaue Wiederholungszahl aus der Kompositionsdauer: repeat: Math.ceil(duration / cycleDuration) - 1.
Synchrone Timeline-Erstellung: Erstellen Sie Timelines niemals innerhalb von async/await, setTimeout oder Promises. Die Capture-Engine liest window.__timelines synchron nach dem Laden der Seite. Schriften werden vom Compiler eingebettet, sind also sofort verfügbar – kein Warten auf Schriftladung nötig.
Niemals tun:
- Vergessen Sie die Registrierung von
window.__timelines - Video für Audio verwenden – immer stummgeschaltetes Video + separates
<audio> - Video innerhalb eines getimten Divs verschachteln – einen nicht getimten Wrapper verwenden
data-layerverwenden (data-track-indexverwenden) oderdata-end(data-durationverwenden)- Video-Element-Dimensionen animieren – einen Wrapper-Div animieren
- Play/Pause/Seek auf Medien aufrufen – das Framework besitzt die Wiedergabe
- Einen Behälter der obersten Ebene ohne
data-composition-iderstellen repeat: -1auf einer Timeline oder einem Tween verwenden – immer endliche Wiederholungen- Timelines asynchron erstellen (innerhalb von
async,setTimeout,Promise) gsap.set()auf Clip-Elementen aus späteren Szenen verwenden – sie existieren beim Seitenladen nicht im DOM. Verwenden Sie stattdessentl.set(selector, vars, timePosition)in der Timeline zum oder nach demdata-start-Zeitpunkt des Clips.<br>im Inhaltstext verwenden – erzwungene Zeilenumbrüche berücksichtigen nicht die tatsächliche gerenderte Schriftbreite. Text, der natürlich umbricht + ein<br>erzeugt einen zusätzlichen unerwünschten Umbruch, der zu Überlappungen führt. Lassen Sie Text stattdessen übermax-widthumbrechen. Ausnahme: kurze Anzeigetitel, bei denen jedes Wort absichtlich in einer eigenen Zeile steht (z. B. „DAS\nUNSTERBLICHE\nSPIEL" bei 130px).
Szenenübergänge (Nicht verhandelbar)
Jede mehrszenige Komposition MUSS ALLE dieser Regeln befolgen. Die Verletzung einer einzigen davon führt zu einer defekten Komposition.
- IMMER Übergänge zwischen den Szenen verwenden. Keine Sprungschnitte. Keine Ausnahmen.
- IMMER Eintrittsanimationen in jeder Szene verwenden. Jedes Element wird über
gsap.from()EIN animiert. Kein Element darf vollständig ausgebildet erscheinen. Wenn eine Szene 5 Elemente hat, braucht sie 5 Eintritts-Tweens. - Niemals Austrittsanimationen verwenden, außer in der letzten Szene. Das bedeutet: KEIN
gsap.to(), das Deckkraft auf 0, y außerhalb des Bildschirms, Skalierung auf 0 oder eine andere „Aus“-Animation animiert, bevor ein Übergang ausgelöst wird. Der Übergang IST der Austritt. Der Inhalt der ausgehenden Szene MUSS im Moment, in dem der Übergang beginnt, vollständig sichtbar sein. - Nur letzte Szene: Die letzte Szene kann Elemente ausblenden (z. B. auf Schwarz ausblenden). Dies ist die EINZIGE Szene, in der
gsap.to(..., { opacity: 0 })erlaubt ist.
FALSCH — Austrittsanimation vor Übergang:
// VERBOTEN — dies leert die Szene, bevor der Übergang sie verwenden kann
tl.to("#s1-title", { opacity: 0, y: -40, duration: 0.4 }, 6.5);
tl.to("#s1-subtitle", { opacity: 0, duration: 0.3 }, 6.7);
// Übergang feuert auf leerem Frame
RICHTIG — nur Eintritt, Übergang behandelt den Austritt:
// Szene 1 Eintrittsanimationen
tl.from("#s1-title", { y: 50, opacity: 0, duration: 0.7, ease: "power3.out" }, 0.3);
tl.from("#s1-subtitle", { y: 30, opacity: 0, duration: 0.5, ease: "power2.out" }, 0.6);
// KEINE Austritts-Tweens — Übergang bei 7,2s handhabt den Szenenwechsel
// Szene 2 Eintrittsanimationen
tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0);
Animationsrichtlinien
- Erste Animation um 0,1-0,3 s versetzen (nicht t=0)
- Easing über die Eintritts-Tweens variieren – mindestens 3 verschiedene Easings pro Szene verwenden
- Ein Eintrittsmuster innerhalb einer Szene nicht wiederholen
- Vollbild-lineare Verläufe auf dunklen Hintergründen vermeiden (H.264-Banding – radial oder einfarbig + lokales Glühen verwenden)
- 60px+ Überschriften, 20px+ Fließtext, 16px+ Datenbeschriftungen für gerendertes Video
font-variant-numeric: tabular-numsauf Zahlenspalten
Wenn keine visual-style.md oder Animationsanweisung vorliegt, folgen Sie der house-style.md für ästhetische Vorgaben.
Typografie und Assets
- Schriften: Schreiben Sie einfach die gewünschte
font-familyin CSS – der Compiler bettet unterstützte Schriften automatisch ein. Wenn eine Schrift nicht unterstützt wird, warnt der Compiler. - Fügen Sie
crossorigin="anonymous"zu externen Medien hinzu