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 die Darstellung. Das Framework übernimmt die Sichtbarkeit von Clips, die Medienwiedergabe und die Synchronisation der Timeline.
Ansatz
Entdeckung (nur für explorative Anfragen)
Bei offenen Anfragen ("Mach mir ein Produktlaunch-Video", "Erstell etwas für unsere Marke"), bei denen der Benutzer sich noch nicht auf eine Richtung festgelegt hat, verstehen Sie die Absicht, bevor Sie Farben auswählen:
- Zielgruppe – Wer sieht sich das an? Entwickler? Führungskräfte? Allgemeine Verbraucher?
- Plattform – Wo wird es abgespielt? Soziales (15s), Website-Hero, Produktdemo, intern?
- Priorität – Was ist am wichtigsten? Bewegungsqualität? Inhaltsgenauigkeit? Markentreue? Geschwindigkeit?
- Varianten – Möchte der Benutzer Optionen oder einen einzigen besten Versuch?
Bei spezifischen Anfragen ("Füge eine Titelcard hinzu", "Korrigiere das Timing in Szene 3") überspringen Sie die Entdeckung.
Erwägen Sie bei explorativen Anfragen, 2-3 Varianten anzubieten, die sich sinnvoll unterscheiden – nicht nur Farbwechsel, sondern unterschiedliche Tempi, Energieniveaus oder strukturelle Ansätze. Eine sichere/erwartete, eine ambitionierte. Erzwingen Sie dies nicht – es ist ein Werkzeug, das bei Bedarf eingesetzt wird.
Schritt 1: Designsystem
Wenn design.md oder DESIGN.md im Projekt existiert, lesen Sie es zuerst (überprüfen Sie beide Schreibweisen – es sind auf Linux unterschiedliche Dateien). Es ist die Quelle der Wahrheit für Markenfarben, Schriftarten und Einschränkungen. Verwenden Sie dessen genaue Werte – erfinden Sie keine Farben oder ersetzen Sie Schriftarten. Jedes Format funktioniert (YAML-Frontmatter, Prosa, Tabellen – extrahieren Sie einfach die Werte).
Wenn es Schriftarten nennt, die Sie lokal nicht finden können (kein fonts/-Verzeichnis mit .woff2-Dateien, keine integrierte Schriftart), warnen Sie den Benutzer vor dem Schreiben von HTML: "design.md spezifiziert [Schriftartname], aber es wurden keine Schriftdateien gefunden. Bitte fügen Sie .woff2-Dateien zum fonts/-Verzeichnis hinzu, oder ich falle auf [nächstgelegene integrierte Alternative] zurück."
Wenn keine design.md existiert, bieten Sie dem Benutzer eine Auswahl:
- Hat der Benutzer einen Stil oder eine Stimmung genannt? → Lesen Sie visual-styles.md für die 8 benannten Voreinstellungen. Wählen Sie die nächstgelegene Übereinstimmung.
- Möchten Sie Optionen visuell durchstöbern? → Führen Sie den Design-Picker aus: Lesen Sie references/design-picker.md für den vollständigen Workflow. Dies liefert eine visuelle Auswahlseite. Der Benutzer konfiguriert Stimmung, Palette, Typografie und Bewegung im Browser, kopiert dann das generierte design.md und fügt es zurück in das Gespräch ein.
- Möchten Sie überspringen und schnell vorgehen? → Fragen Sie: Stimmung, hell oder dunkel, irgendwelche Markenfarben/Schriftarten? Wählen Sie dann eine Palette aus house-style.md.
design.md definiert die Marke. Es definiert keine Videokompositionsregeln. Diese stammen aus references/video-composition.md und house-style.md. Verwenden Sie Markenfarben in einer für Video geeigneten Größenordnung – nicht in der Deckkraft von Web-Oberflächen.
Schritt 2: Prompt-Erweiterung
Führen Sie dies immer bei jeder Komposition durch (außer bei Ein-Szenen-Stücken und trivialen Bearbeitungen). Dieser Schritt verankert die Absicht des Benutzers an design.md und house-style.md und erzeugt ein konsistentes Zwischenprodukt, das jeder nachgelagerte Agent auf die gleiche Weise liest.
Lesen Sie references/prompt-expansion.md für den vollständigen Prozess und das Ausgabeformat.
Schritt 3: Plan
Denken Sie vor dem Schreiben von HTML auf hohem Niveau:
- Was – Was soll der Betrachter erleben? Identifizieren Sie den narrativen Bogen, die Schlüsselmomente und die emotionalen Schläge.
- Struktur – Wie viele Kompositionen, welche sind Unterkompositionen vs. Inline, welche Spuren transportieren was (Video, Audio, Overlays, Untertitel).
- Rhythmus – Geben Sie Ihren Szenen-Rhythmus vor der Implementierung an. Welche Szenen sind schnelle Treffer, welche sind Haltepunkte, wo landen Shader, wo erreicht die Energie ihren Höhepunkt. Nennen Sie das Muster: schnell-schnell-LANGSAM-schnell-SHADER-Halt. Lesen Sie references/beat-direction.md für Rhythmusvorlagen.
- Timing – Welche Clips bestimmen die Dauer, wo liegen die Übergänge, wie ist das Tempo.
- Layout – Bauen Sie zuerst den Endzustand. Siehe "Layout vor Animation" unten.
- Animieren – Fügen Sie dann Bewegung mit den folgenden Regeln hinzu.
Bauen Sie, wonach gefragt wurde. Eine Anfrage nach "einer Titelcard" ist keine Anfrage nach "einer Titelcard + 3 unterstützenden Szenen + Hintergrundmusik + Untertiteln." Jede Szene, jedes Element, jedes Tween sollte seinen Platz verdienen. Wenn zusätzliche Szenen oder Elemente das Stück tatsächlich verbessern würden, schlagen Sie sie vor – fügen Sie sie nicht hinzu.
Für kleine Bearbeitungen (Farbe korrigieren, Timing anpassen, ein Element hinzufügen) springen Sie direkt zu den Regeln.
Layout vor Animation
Positionieren Sie jedes Element dort, wo es an seinem sichtbarsten Moment sein sollte – dem Frame, in dem es vollständig eingetreten, korrekt platziert und noch nicht verlassen wird. Schreiben Sie dies zuerst als statisches HTML+CSS. Noch kein GSAP.
Warum das wichtig ist: Wenn Sie Elemente in ihrem animierten Startzustand positionieren (außerhalb des Bildschirms, auf 0 skaliert, Deckkraft 0) und sie dorthin tweenen, wo Sie glauben, dass sie landen sollen, raten Sie die endgültige Anordnung. Überlappungen sind unsichtbar, bis das Video gerendert wird. Indem Sie zuerst den Endzustand bauen, können Sie Layout-Probleme sehen und beheben, bevor Sie eine Bewegung hinzufügen.
Der Prozess
- Identifizieren Sie den Helden-Frame 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-Container MUSS die gesamte Szene mitwidth: 100%; height: 100%; padding: Npx;unddisplay: flex; flex-direction: column; gap: Npx; box-sizing: border-boxausfüllen. Verwenden Sie Padding, um Inhalt nach innen zu drücken – NIEMALSposition: absolute; top: Npxauf einem Inhaltscontainer. Absolut positionierte Inhaltscontainer laufen über, wenn der Inhalt höher als der verbleibende Platz ist. Reservieren Sieposition: absolutenur für dekorative Elemente. - Fügen Sie Eingänge mit
gsap.from()hinzu – animieren Sie VON außerhalb des Bildschirms/unsichtbar ZUR CSS-Position. Die CSS-Position ist die Grundwahrheit; das Tween beschreibt die Reise dorthin. (In Unterkompositionen, die überdata-composition-srcgeladen werden, bevorzugen Siegsap.fromTo()– siehe lasttragende GSAP-Regeln in references/motion-principles.md.) - Fügen Sie Ausgänge mit
gsap.to()hinzu – animieren Sie ZU außerhalb des Bildschirms/unsichtbar VON der CSS-Position.
Beispiel
/* scene-content füllt die Szene aus, 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 den Abstand. */
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: AUS diesen Positionen 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 über die Zeit einen Raum teilen
Wenn Element A verlässt, bevor Element B im selben Bereich eintritt, sollten beide korrekte CSS-Positionen für ihre jeweiligen Helden-Frames haben. Die Timeline-Reihenfolge stellt sicher, dass sie nie visuell koexistieren – aber wenn Sie den Layout-Schritt überspringen, werden Sie den Fall nicht bemerken, wenn sie aufgrund eines Timing-Fehlers versehentlich überlappen.
Was als beabsichtigte Überlappung gilt
Geschichtete Effekte (Glühen hinter Text, Schattenelemente, Hintergrundmuster) und Z-gestapelte Designs (Kartenstapel, Tiefenschichten) sind beabsichtigt. Beim Layout-Schritt geht es darum, unbeabsichtigte Überlappungen zu erkennen – zwei Überschriften, die aufeinander landen, eine Statistik, die ein Etikett bedeckt, Inhalt, der aus dem Rahmen läuft.
Datenattribute
Alle Clips
| Attribut | Erforderlich | Werte |
|---|---|---|
id | Ja | Eindeutige Kennung |
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 auf Mediendauer. |
data-track-index | Ja | Ganzzahl. Clips auf derselben Spur können sich nicht überlappen. |
data-media-start | Nein | Trim-Offset in 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 (Hauptkomposition: "0" verwenden) |
data-duration | Ja | Hat Vorrang vor der GSAP-Timeline-Dauer |
data-width / data-height | Ja | Pixelabmessungen (1920x1080 oder 1080x1920) |
data-composition-src | Nein | Pfad zur externen HTML-Datei |
Kompositionsstruktur
Unterkompositionen, die über data-composition-src geladen werden, verwenden einen <template>-Wrapper. Eigenständige Kompositionen (die Haupt-index.html) verwenden KEIN <template> – sie setzen das data-composition-id-div direkt in <body>. Die Verwendung von <template> bei einer eigenständigen Datei verbirgt alle Inhalte vor dem Browser und bricht das Rendering.
Unterkompositionsstruktur:
<template id="my-comp-template">
<div data-composition-id="my-comp" data-width="1920" data-height="1080">
<!-- Inhalt -->
<style>
[data-composition-id="my-comp"] {
/* skalierte Stile */
}
</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 der Wurzel: <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 - Jede Timeline registrieren:
window.__timelines["<composition-id>"] = tl - Das Framework verschachtelt Unter-Timelines automatisch – NICHT manuell hinzufügen
- Die Dauer stammt von
data-duration, nicht von der GSAP-Timeline-Länge - Nie leere Tweens erstellen, um die Dauer festzulegen
Regeln (Nicht verhandelbar)
Deterministisch: Kein Math.random(), Date.now() oder zeitbasierte Logik. Verwenden Sie einen gesäten PRNG, wenn Sie pseudo-zufällige Werte benötigen (z.B. mulberry32).
GSAP: Nur visuelle Eigenschaften animieren (opacity, x, y, scale, rotation, color, backgroundColor, borderRadius, Transformationen). Nicht visibility, display animieren oder video.play()/audio.play() aufrufen.
Animationskonflikte: Niemals dieselbe Eigenschaft am selben Element von mehreren Timelines gleichzeitig animieren.
Kein repeat: -1: Unendlich wiederholte Timelines zerstören die Erfassungs-Engine. Berechnen Sie die genaue Wiederholungsanzahl aus der Kompositionsdauer: repeat: Math.ceil(duration / cycleDuration) - 1.
Synchrone Timeline-Konstruktion: Niemals Timelines innerhalb von async/await, setTimeout oder Promises bauen. Die Erfassungs-Engine liest window.__timelines synchron nach dem Laden der Seite. Schriftarten werden vom Compiler eingebettet, sind also sofort verfügbar – kein Warten auf das Laden von Schriftarten nötig.
Niemals tun:
window.__timelines-Registrierung vergessen- Video für Audio verwenden – immer stummgeschaltetes Video + separates
<audio> - Video in einem zeitgesteuerten div verschachteln – einen nicht zeitgesteuerten Wrapper verwenden
data-layerverwenden (data-track-indexverwenden) oderdata-end(data-durationverwenden)- Video-Elementabmessungen animieren – einen Wrapper-div animieren
- Play/Pause/Seek auf Medien aufrufen – das Framework besitzt die Wiedergabe
- Einen Container der obersten Ebene ohne
data-composition-iderstellen repeat: -1auf einer Timeline oder einem Tween verwenden – immer endliche Wiederholungen- Timelines asynchron bauen (innerhalb von
async,setTimeout,Promise) gsap.set()auf Clip-Elementen von späteren Szenen verwenden – sie existieren nicht im DOM beim Laden der Seite. Verwenden Sie stattdessentl.set(selector, vars, timePosition)innerhalb der Timeline zu oder nach derdata-start-Zeit des Clips.<br>in Inhaltstext verwenden – erzwungene Zeilenumbrüche berücksichtigen nicht die tatsächliche gerenderte Schriftbreite. Text, der auf natürliche Weise umbricht + ein<br>erzeugt einen zusätzlichen unerwünschten Umbruch, was zu Überlappungen führt. Lassen Sie den Text stattdessen übermax-widthumbrechen. Ausnahme: kurze Anzeigetitel, bei denen jedes Wort absichtlich auf einer eigenen Zeile steht (z.B. "THE\nIMMORTAL\nGAME" bei 130px).
Szenenübergänge (Nicht verhandelbar)
Jede Multiszenen-Komposition MUSS ALLE diese Regeln befolgen. Die Verletzung einer einzigen von ihnen ist eine kaputte Komposition.
- **
…