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 Animation und CSS für das Aussehen. Das Framework verwaltet die Sichtbarkeit von Clips, die Medienwiedergabe und die Zeitleistensynchronisation.
Ansatz
Entdeckung (nur für explorative Anfragen)
Bei offenen Anfragen ("Erstelle mir ein Produktlaunch-Video", "Erstelle etwas für unsere Marke"), bei denen der Benutzer noch keine Richtung festgelegt hat, verstehe die Absicht, bevor Farben ausgewählt werden:
- Zielgruppe – Wer sieht sich das an? Entwickler? Führungskräfte? Allgemeine Verbraucher?
- Plattform – Wo wird es abgespielt? Sozial (15s), Website-Hero, Produktdemo, Intern?
- Priorität – Was ist am wichtigsten? Bewegungsqualität? Inhaltsgenauigkeit? Markentreue? Geschwindigkeit?
- Variationen – Möchte der Benutzer Optionen oder einen einzigen besten Versuch?
Bei spezifischen Anfragen ("Füge eine Titelgrafik hinzu", "Korrigiere das Timing von Szene 3") überspringe die Entdeckung.
Bei explorativen Anfragen erwäge, 2-3 Variationen anzubieten, die sich sinnvoll unterscheiden – nicht nur Farbwechsel, sondern unterschiedliche Tempi, Energieniveaus oder strukturelle Ansätze. Eine sichere/erwartete, eine ambitionierte. Erzwinge dies nicht – es ist ein Werkzeug, das bei Bedarf zur Verfügung steht.
Schritt 1: Designsystem
Wenn design.md oder DESIGN.md im Projekt existiert, lies es zuerst (überprüfe beide Schreibweisen – es sind unterschiedliche Dateien unter Linux). Es ist die Quelle der Wahrheit für Markenfarben, Schriftarten und Einschränkungen. Verwende seine exakten Werte – erfinde keine Farben oder ersetze Schriftarten. Jedes Format funktioniert (YAML-Frontmatter, Prosa, Tabellen – extrahiere einfach die Werte).
Wenn darin Schriftarten genannt werden, die du lokal nicht finden kannst (kein fonts/-Verzeichnis mit .woff2-Dateien, keine integrierte Schriftart), warne den Benutzer, bevor du HTML schreibst: "design.md spezifiziert [Schriftartname], aber es wurden keine Schriftdateien gefunden. Bitte füge .woff2-Dateien zu fonts/ hinzu, oder ich verwende als Fallback die nächstgelegene [nächstgelegene integrierte Alternative]."
Wenn keine design.md existiert, biete dem Benutzer eine Wahl an:
- Benutzer hat einen Stil oder eine Stimmung genannt? → Lese visual-styles.md für die 8 benannten Voreinstellungen. Wähle die nächstgelegene Übereinstimmung.
- Möchte visuell Optionen durchstöbern? → Führe den Design-Auswähler aus: Lese references/design-picker.md für den vollständigen Workflow. Dies dient einer visuellen 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öchte schnell überspringen? → Frage: Stimmung, hell oder dunkel, irgendwelche Markenfarben/-schriftarten? Wähle dann eine Palette aus house-style.md.
design.md definiert die Marke. Es definiert nicht die Videokompositionsregeln. Diese stammen aus references/video-composition.md und house-style.md. Verwende Markenfarben in einer videogerechten Skala – nicht in Web-UI-Opazität.
Schritt 2: Prompt-Erweiterung
Führe dies immer bei jeder Komposition durch (außer bei Ein-Szenen-Stücken und trivialen Bearbeitungen). Dieser Schritt verankert die Absicht des Benutzers gegenüber design.md und house-style.md und erzeugt einen konsistenten Zwischenschritt, den alle nachgelagerten Agenten auf die gleiche Weise lesen.
Lese references/prompt-expansion.md für den vollständigen Prozess und das Ausgabeformat.
Schritt 3: Plan
Bevor HTML geschrieben wird, denke auf hoher Ebene:
- Was – Was soll der Betrachter erleben? Identifiziere den narrativen Bogen, die Schlüsselmomente und die emotionalen Schläge.
- Struktur – Wie viele Kompositionen, welche sind Unterkompositionen vs. inline, welche Spuren tragen was (Video, Audio, Overlays, Untertitel).
- Rhythmus – Erkläre deinen Szenenrhythmus vor der Implementierung. Welche Szenen sind schnelle Treffer, welche sind Halte, wo landen Shader, wo liegt der Energiehöhepunkt. Benenne das Muster: schnell-schnell-LANGSAM-schnell-SHADER-halten. Lese references/beat-direction.md für Rhythmusvorlagen.
- Timing – Welche Clips bestimmen die Dauer, wo liegen Übergänge, wie ist das Tempo.
- Layout – Baue zuerst den Endzustand. Siehe "Layout vor Animation" unten.
- Animieren – Füge dann Bewegung mit den untenstehenden Regeln hinzu.
Baue das, was gefragt wurde. Eine Anfrage nach "einer Titelgrafik" ist keine Anfrage nach "einer Titelgrafik + 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, schlage sie vor – füge sie nicht einfach hinzu.
Bei kleinen Bearbeitungen (eine Farbe korrigieren, das Timing anpassen, ein Element hinzufügen) überspringe direkt zu den Regeln.
Layout vor Animation
Positioniere jedes Element dort, wo es in seinem sichtbarsten Moment sein sollte – dem Frame, in dem es vollständig eingetreten, korrekt platziert und noch nicht im Austritt ist. Schreibe dies zuerst als statisches HTML+CSS. Noch kein GSAP.
Warum dies wichtig ist: Wenn du Elemente in ihrem animierten Startzustand positionierst (außerhalb des Bildschirms, skaliert auf 0, Deckkraft 0) und sie dann per Tween dorthin bringst, wo du denkst, dass sie landen sollen, rätst du das endgültige Layout. Überlappungen bleiben bis zum Rendern des Videos unsichtbar. Indem du zuerst den Endzustand baust, kannst du Layout-Probleme sehen und beheben, bevor du Bewegung hinzufügst.
Der Prozess
- Identifiziere den heroischen Frame für jede Szene – den Moment, in dem die meisten Elemente gleichzeitig sichtbar sind. Dies ist das Layout, das du baust.
- Schreibe statisches CSS für diesen Frame. Der Container
.scene-contentMUSS die gesamte Szene mitwidth: 100%; height: 100%; padding: Npx;unddisplay: flex; flex-direction: column; gap: Npx; box-sizing: border-boxausfüllen. Verwende Padding, um den Inhalt nach innen zu verschieben – Verwende NIEMALSposition: absolute; top: Npxauf einem Inhaltscontainer. Absolut positionierte Inhaltscontainer laufen über, wenn der Inhalt höher ist als der verbleibende Platz. Behalteposition: absolutenur für dekorative Elemente vor. - Füge Eintritte mit
gsap.from()hinzu – animiere 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, bevorzugegsap.fromTo()– siehe lasttragende GSAP-Regeln in references/motion-principles.md.) - Füge Austritte mit
gsap.to()hinzu – animiere ZU außerhalb des Bildschirms/unsichtbar VON der CSS-Position.
Beispiel
/* scene-content füllt die Szene, padding positioniert Inhalt */
.scene-content {
display: flex;
flex-direction: column;
justify-content: center;
width: 100%;
height: 100%;
padding: 120px 160px;
gap: 24px;
box-sizing: border-box;
}
.titel {
font-size: 120px;
}
.untertitel {
font-size: 42px;
}
/* Container füllt jede Szenengröße (1920x1080, 1080x1920, etc.).
Padding positioniert Inhalt. Flex + Gap übernimmt Abstände. */
FALSCH – hartcodierte Abmessungen und absolute Positionierung:
.scene-content {
position: absolute;
top: 200px;
left: 160px;
width: 1920px;
height: 1080px;
display: flex; /* ... */
}
// Schritt 3: Animiere IN diese Positionen
tl.from(".titel", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".untertitel", { 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: Animiere RAUS aus diesen Positionen
tl.to(".titel", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".untertitel", { 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 denselben 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 heroischen Frames haben. Die Zeitachsen-Reihenfolge garantiert, dass sie nie gleichzeitig sichtbar sind – aber wenn du den Layout-Schritt überspringst, wirst du den Fall nicht abfangen, in dem sie aufgrund eines Timing-Fehlers versehentlich überlappen.
Was als beabsichtigte Überlappung zählt
Geschichtete Effekte (Glühen hinter Text, Schattenelemente, Hintergrundmuster) und Z-Stack-Designs (Kartenstapel, Tiefenschichten) sind beabsichtigt. Der Layout-Schritt dient dazu, unbeabsichtigte Überlappungen abzufangen – zwei Überschriften, die aufeinander landen, eine Statistik, die ein Label bedeckt, Inhalt, der über den 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/comps | Sekunden. Video/Audio standardmäßig die Mediendauer. |
data-track-index | Ja | Ganze Zahl. Clips auf derselben Spur können sich nicht überlappen. |
data-media-start | Nein | Trim-Offset in die Quelle (Sekunden) |
data-volume | Nein | 0-1 (Standard 1) |
data-track-index beeinflusst nicht die visuelle Schichtung – verwende CSS z-index.
Kompositions-Clips
| Attribut | Erforderlich | Werte |
|---|---|---|
data-composition-id | Ja | Eindeutige Kompositions-ID |
data-start | Ja | Startzeit (Root-Komposition: verwende "0") |
data-duration | Ja | Überschreibt die Dauer der GSAP-Timeline |
data-width / data-height | Ja | Pixelmaße (1920x1080 oder 1080x1920) |
data-composition-src | Nein | Pfad zu externer HTML-Datei |
data-variable-values | Nein | JSON-Objekt mit instanzspezifischen Variablen-Überschreibungen auf einem Sub-Comp-Host |
Auf dem Root <html>-Element:
| Attribut | Erforderlich | Werte |
|---|---|---|
data-composition-variables | Nein | JSON-Array deklarierter Variablen (id/type/label/default) – treibt die Studio-Bearbeitungs-UI und bietet Standardwerte für getVariables() |
Kompositionsstruktur
Unterkompositionen, die über data-composition-src geladen werden, verwenden einen <template>-Wrapper. Eigenständige Kompositionen (die Hauptdatei index.html) verwenden KEINEN <template> – sie setzen das data-composition-id-Div direkt in <body>. Die Verwendung von <template> bei einer eigenständigen Datei verbirgt den gesamten Inhalt vor dem Browser und unterbricht das Rendering.
Unterkompositionsstruktur:
<template id="mein-comp-template">
<div data-composition-id="mein-comp" data-width="1920" data-height="1080">
<!-- Inhalt -->
<style>
[data-composition-id="mein-comp"] {
/* Gültige 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["mein-comp"] = tl;
</script>
</div>
</template>
Laden in der Wurzel: <div id="el-1" data-composition-id="mein-comp" data-composition-src="compositions/mein-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>
Variablen (Parametrisierte Kompositionen)
Rendere dieselbe Komposition mit unterschiedlichem Inhalt – Titel, Themenfarbe, Preise, Untertitel – ohne das Quell-HTML zu bearbeiten.
Drei-Schritt-Muster:
- Deklariere Variablen auf dem
<html>-Root der Komposition mitdata-composition-variables. Jeder Eintrag benötigtid,type(eins vonstring,number,color,boolean,enum),labelunddefault. Enum-Einträge benötigen auchoptions: [{value, label}, ...]. - Lese die aufgelösten Werte im Skript der Komposition mit
window.__hyperframes.getVariables(). Gibt das zusammengeführte Ergebnis der deklarierten Standardwerte + instanzspezifischen Überschreibungen + CLI-Überschreibungen zurück. - Überschreibe zur Rendering-Zeit mit
npx hyperframes render --variables '{...}'(oberste Ebene) oder mitdata-variable-values='{...}'auf dem Host-Element (instanzspezifisch für Sub-Kompositionen).
<!doctype html>
<html
data-composition-variables='[
{"id":"titel","type":"string","label":"Titel","default":"Hallo"},
{"id":"thema","type":"enum","label":"Thema","default":"hell","options":[
{"value":"hell","label":"Hell"},
{"value":"dunkel","label":"Dunkel"}
]}
]'
>
<body>
<div data-composition-id="root" data-width="1920" data-height="1080">
<h1 id="hero" class="clip" data-start="0" data-duration="3"></h1>
<script>
const { titel, thema } = window.__hyperframes.getVariables();
document.getElementById("hero").textContent = titel;
document.body.dataset.thema = thema;
</script>
</div>
</body>
</html>
# Entwicklungsvorschau verwendet deklarierte Standardwerte
npx hyperframes preview
# Rendern mit Überschreibungen
npx hyperframes render --variables '{"titel":"Q4-Bericht","thema":"dunkel"}' --output q4.mp4
# Oder aus einer JSON-Datei
npx hyperframes render --variables-file ./vars.json
Werte pro Instanz in Unterkompositionen: Dasselbe getVariables() funktioniert in Sub-Kompositionen, die über data-composition-src geladen werden. Jedes Host-Element übergibt seine eigenen Werte:
<div
data-composition-id="karte-pro"
data-composition-src="compositions/karte.html"
data-variable-values='{"titel":"Pro","preis":"29€"}'
></div>
<div
data-composition-id="karte-enterprise"
data-composition-src="compositions/karte.html"
data-variable-values='{"titel":"Enterprise","preis":"99€"}'
></div>