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 Erscheinungsbild. Das Framework kümmert sich um Clipsichtbarkeit, Medienwiedergabe und Timeline-Synchronisation.
Ansatz
Discovery (nur für explorative Anfragen)
Bei offenen Anfragen („Erstelle mir ein Produktlaunch-Video“, „Erstelle etwas für unsere Marke“), bei denen der Benutzer sich noch nicht festgelegt hat, verstehe die Absicht, bevor du Farben wählst:
- Zielgruppe – Wer sieht sich das an? Entwickler? Führungskräfte? Allgemeine Verbraucher?
- Plattform – Wo wird es abgespielt? Soziale Medien (15s), Website-Heldenbereich, 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“) überspringe die Discovery.
Erwäge für explorative Anfragen, 2-3 Varianten anzubieten, die sich sinnvoll unterscheiden – nicht nur Farbwechsel, sondern unterschiedliches Tempo, Energieniveaus oder strukturelle Ansätze. Eine sichere/erwartete, eine ambitionierte. Mache dies nicht zur Pflicht – es ist ein Werkzeug, das bei Bedarf verfügbar ist.
Schritt 1: Designsystem
Wenn design.md oder DESIGN.md im Projekt existiert, lies es zuerst (überprüfe beide Schreibweisen – es sind auf Linux unterschiedliche Dateien). 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 ist akzeptabel (YAML-Frontmatter, Prosa, Tabellen – extrahiere einfach die Werte).
Wenn es Schriftarten benennt, die du lokal nicht finden kannst (kein fonts/-Verzeichnis mit .woff2-Dateien, keine integrierte Schriftart), warne den Benutzer vor dem Schreiben von HTML: „design.md gibt die Schriftart [Schriftartname] an, aber es wurden keine Schriftdateien gefunden. Bitte füge .woff2-Dateien zu fonts/ hinzu, oder ich werde auf [nächstgelegene integrierte Alternative] zurückfallen.“
Wenn keine design.md existiert, biete dem Benutzer eine Auswahl an:
- Hat der Benutzer einen Stil oder eine Stimmung genannt? → Lies visual-styles.md für die 8 benannten Voreinstellungen. Wähle die nächstgelegene Übereinstimmung.
- Möchte der Benutzer Optionen visuell durchstöbern? → Führe den Design-Picker aus: Lies references/design-picker.md für den vollständigen Workflow. Dieser liefert eine visuelle Auswahlseite. Der Benutzer konfiguriert Stimmung, Palette, Typografie und Bewegung im Browser, kopiert dann die generierte design.md und fügt sie zurück in die Konversation ein.
- Möchte der Benutzer es überspringen und schnell machen? → Frage: Stimmung, hell oder dunkel, irgendwelche Markenfarben/Schriftarten? Wähle dann eine Palette aus house-style.md.
design.md definiert die Marke. Es definiert keine Videokompositionsregeln. Diese kommen von references/video-composition.md und house-style.md. Verwende Markenfarben in videogeeignetem Maßstab – nicht in Web-UI-Deckkraft.
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 in Bezug auf design.md und house-style.md und erzeugt ein konsistentes Zwischenprodukt, das alle nachgelagerten Agenten auf die gleiche Weise lesen.
Lies references/prompt-expansion.md für den vollständigen Prozess und das Ausgabeformat.
Schritt 3: Plan
Bevor du HTML schreibst, denke auf hohem Niveau:
- 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 transportieren was (Video, Audio, Overlays, Untertitel).
- Rhythmus – Gib deinen Szenenrhythmus vor der Implementierung an. Welche Szenen sind schnelle Treffer, welche sind Ruhepunkte, wo landen Shader, wo liegt der Energiehöhepunkt. Benenne das Muster: schnell-schnell-LANGSAM-schnell-SHADER-Haltepunkt. Lies references/beat-direction.md für Rhythmusvorlagen.
- Timing – Welche Clips bestimmen die Dauer, wo landen Übergänge, wie ist das Tempo.
- Layout – Baue zuerst den Endzustand. Siehe „Layout vor Animation“ unten.
- Animation – Füge dann Bewegung unter Verwendung der folgenden Regeln hinzu.
Baue das, was gefragt wurde. Eine Anfrage nach „einer Titelcard“ ist keine Anfrage nach „einer Titelcard + 3 unterstützenden Szenen + Hintergrundmusik + Untertiteln.“ Jede Szene, jedes Element, jede Tween-Animation sollte sich ihren Platz verdienen. Wenn zusätzliche Szenen oder Elemente das Stück wirklich verbessern würden, schlage sie vor – füge sie nicht einfach hinzu.
Für kleine Bearbeitungen (eine Farbe korrigieren, 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 – der Frame, in dem es vollständig eingetreten, korrekt platziert und noch nicht am Verlassen 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, auf 0 skaliert, Deckkraft 0) und sie dorthin tweenst, wo du denkst, dass sie landen sollten, rätst du das endgültige Layout. Überlappungen sind unsichtbar, bis das Video gerendert wird. Indem du zuerst den Endzustand baust, kannst du Layout-Probleme sehen und beheben, bevor du Bewegung hinzufügst.
Der Prozess
- Identifiziere den Helden-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
.scene-content-Container MUSS die gesamte Szene mitwidth: 100%; height: 100%; padding: Npx;ausfüllen, mitdisplay: flex; flex-direction: column; gap: Npx; box-sizing: border-box. Verwende 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. Reserviereposition: absolutenur für dekorative Elemente. - Füge Eintritte mit
gsap.from()hinzu – animiere VON außerhalb des Bildschirms/unsichtbar ZUR CSS-Position. Die CSS-Position ist die Grundwahrheit; der Tween beschreibt die Reise dorthin. (In Unterkompositionen, die überdata-composition-srcgeladen werden, bevorzugegsap.fromTo()– siehe tragende 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 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 – hartcodierte Abmessungen und absolute Positionierung:
.scene-content {
position: absolute;
top: 200px;
left: 160px;
width: 1920px;
height: 1080px;
display: flex; /* ... */
}
// Schritt 3: Animieren ZU diesen Positionen
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: Animieren VON diesen Positionen WEG
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 den 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 Helden-Frames haben. Die Timeline-Reihenfolge garantiert, dass sie nie visuell koexistieren – aber wenn du den Layout-Schritt überspringst, wirst du den Fall nicht abfangen, in dem sie sich aufgrund eines Timing-Fehlers versehentlich überlappen.
Was als beabsichtigte Überlappung gilt
Geschichtete Effekte (Glow hinter Text, Schattenelemente, Hintergrundmuster) und Z-gestapelte Designs (Kartenstapel, Tiefenschichten) sind beabsichtigt. Der Layout-Schritt dient dazu, unbeabsichtigte Überlappungen abzufangen – zwei Überschriften, die übereinander landen, eine Statistik, die ein Label bedeckt, Inhalt, der außerhalb des Rahmens 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. Standard für Video/Audio ist die Mediendauer. |
data-track-index | Ja | Ganze Zahl. Clips auf derselben Spur können sich nicht überlappen. |
data-media-start | Nein | Trim-Versatz in die Quelle (Sekunden) |
data-volume | Nein | 0-1 (Standard 1) |
data-track-index beeinflusst nicht die visuelle Schichtung – verwende CSS z-index.
Kompositionsclips
| Attribut | Erforderlich | Werte |
|---|---|---|
data-composition-id | Ja | Eindeutige Kompositions-ID |
data-start | Ja | Startzeit (Root-Komposition: verwende "0") |
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 |
data-variable-values | Nein | JSON-Objekt von pro-Instanz-Variablen-Überschreibungen auf einem Sub-Comp-Host |
Auf dem Root-<html>-Element:
| Attribut | Erforderlich | Werte |
|---|---|---|
data-composition-variables | Nein | JSON-Array von deklarierten Variablen (id/type/label/default) – treibt die Studio-Bearbeitungs-UI und stellt Standardwerte für getVariables() bereit |
Kompositionsstruktur
Unterkompositionen, die über data-composition-src geladen werden, verwenden einen <template>-Wrapper. Eigenständige Kompositionen (die main index.html) verwenden NICHT <template> – sie setzen das data-composition-id-div direkt in <body>. Die Verwendung von <template> in einer eigenständigen Datei verbirgt alle Inhalte vor dem Browser und unterbricht das Rendern.
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"] {
/* Bereichsbezogene 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 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>
Variablen (Parametrisierte Kompositionen)
Rendere dieselbe Komposition mit unterschiedlichem Inhalt – Titel, Themenfarbe, Preise, Untertitel – ohne die Quell-HTML zu bearbeiten.
Drei-Schritte-Muster:
- Deklariere Variablen auf dem
<html>-Root der Komposition mitdata-composition-variables. Jeder Eintrag benötigtid,type(einer vonstring,number,color,boolean,enum),labelunddefault. Enum-Einträge benötigen auchoptions: [{value, label}, ...]. - Lies die aufgelösten Werte innerhalb des Skripts der Komposition mit
window.__hyperframes.getVariables(). Gibt das zusammengeführte Ergebnis von deklarierten Standardwerten + pro-Instanz-Überschreibungen + CLI-Überschreibungen zurück. - Überschreibe zur Renderzeit mit
npx hyperframes render --variables '{...}'(Top-Level) oder mitdata-variable-values='{...}'auf dem Host-Element (pro-instance für Sub-Comps).
<!doctype html>
<html
data-composition-variables='[
{"id":"title","type":"string","label":"Titel","default":"Hallo"},
{"id":"theme","type":"enum","label":"Thema","default":"light","options":[
{"value":"light","label":"Hell"},
{"value":"dark","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 { title, theme } = window.__hyperframes.getVariables();
document.getElementById("hero").textContent = title;
document.body.dataset.theme = theme;
</script>
</div>
</body>
</html>
# Dev-Vorschau verwendet deklarierte Standardwerte
npx hyperframes preview
# Rendere mit Überschreibungen
npx hyperframes render --variables '{"title":"Q4 Bericht","theme":"dark"}' --output q4.mp4
# Oder aus einer JSON-Datei
npx hyperframes render --variables-file ./vars.json
Sub-Kompositions-Pro-Instanz-Werte: Die gleiche getVariables() funktioniert innerhalb von Sub-Comps, die über data-composition-src geladen werden. Jedes Host-Element übergibt seine eigenen Werte:
<div
data-composition-id="card-pro"
data-composition-src="compositions/card.html"
data-variable-values='{"title":"Pro","price":"29 €"}'
></div>
<div
data-composition-id="card-enterprise"
data-composition-src="compositions/card.html"
data-variable-values='{"title":"Enterprise","price":"99 €"}'
></div>
Untertitel
Füge Untertitel hinzu, indem du Textelemente innerhalb eines separaten Containers platzierst, der über data-*-Attributen gesteuert wird, typischerweise data-asset="voiceover" oder ähnlich. Das Framework handhabt die Synchronisation.
Medien
Hintergrundvideos / Audio
<video
id="bg-video"
class="clip"
data-start="0"
data-duration="10"
data-track-index="0"
data-volume="0.3"
src="assets/background.mp4"
></video>
Audio-Synchronisation
Für audio-reaktive Animationen verwende die vom Framework bereitgestellten Analyse-Funktionen. (Siehe references/motion-principles.md.)
Übergänge
Füge Szenenübergänge mithilfe der data-transition-Attribute oder benutzerdefiniertem Shader-Code hinzu.
Beispiel: Crossfade
<div class="scene" data-transition="crossfade" data-transition-duration="0.5">
Beispiel: Shader-Übergang
Siehe references/shaders.md.
Ausgabeformat
Das Framework rendert standardmäßig eine MP4-Datei, die über die Befehlszeile oder CI konfiguriert werden kann.
Hinweis: Für Befehle der Entwicklungsschleife (init, lint, inspect, preview, render) siehe hyperframes-cli.
Für die Vorverarbeitung von Assets (Text-to-Speech, Transkription, Hintergrundentfernung) siehe hyperframes-media.