HyperFrames
HTML ist die Quelle der Wahrheit für Video. Eine Komposition ist eine HTML-Datei mit data-*-Attributen für Timing, einer GSAP-Timeline für Animation und CSS für das Aussehen. Das Framework kümmert sich um Clip-Sichtbarkeit, Medienwiedergabe und Timeline-Synchronisation.
Ansatz
Discovery (nur bei explorativen Anfragen)
Bei offenen Anfragen („Erstelle ein Video für die Produkteinführung“, „Erstelle etwas für unsere Marke“), bei denen der Benutzer noch keine Richtung festgelegt hat, verstehe die Absicht, bevor du Farben auswählst:
- Zielgruppe – Wer sieht das? Entwickler? Führungskräfte? Allgemeine Verbraucher?
- Plattform – Wo wird es abgespielt? Social Media (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 Titelkarte hinzu“, „Korrigiere das Timing in Szene 3“) überspringe die Discovery.
Bei explorativen Anfragen kannst du 2-3 Variationen anbieten, die sich sinnvoll unterscheiden – nicht nur Farbwechsel, sondern unterschiedliches Tempo, Energieniveaus oder strukturelle Ansätze. Eine sichere/erwartete, eine ambitionierte. Erzwinge dies nicht – 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 – auf Linux sind es 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 funktioniert (YAML-Frontmatter, Prosa, Tabellen – extrahiere einfach die Werte).
Wenn es Schriftarten benennt, die du nicht lokal finden kannst (kein fonts/-Verzeichnis mit .woff2-Dateien, keine integrierte Schriftart), warne den Benutzer, bevor du HTML schreibst: „design.md gibt die Schriftart [Schriftartname] an, aber es wurden keine Schriftartdateien gefunden. Bitte füge .woff2-Dateien zu fonts/ hinzu, oder ich weiche auf [nächstgelegene integrierte Alternative] aus.“
Wenn keine design.md existiert, biete dem Benutzer eine Wahl:
- Hat der Benutzer einen Stil oder eine Stimmung genannt? → Lies visual-styles.md für die 8 benannten Presets. Wähle die nächste Ü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. Dies liefert eine visuelle Picker-Seite. 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.
- Möchte der Benutzer ü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 videogerechter Skalierung – 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 an design.md und house-style.md und erzeugt ein konsistentes Zwischenprodukt, das jeder nachgelagerte Agent auf die gleiche Weise liest.
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 Schwerpunkte.
- Struktur – Wie viele Kompositionen, welche sind Subkompositionen vs. inline, welche Spuren tragen was (Video, Audio, Overlays, Untertitel).
- Rhythmus – Gib deinen Szenenrhythmus vor der Implementierung an. Welche Szenen sind schnelle Treffer, welche sind Haltepunkte, wo landen Shader, wo ist der Energiehöhepunkt. Benenne das Muster: schnell-schnell-LANGSAM-schnell-SHADER-Halt. 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.
- Animieren – Füge dann Bewegung mit den folgenden Regeln hinzu.
Baue, worum gebeten wurde. Eine Anfrage für „eine Titelkarte“ ist keine Anfrage für „eine Titelkarte + 3 unterstützende Szenen + Hintergrundmusik + Untertitel.“ Jede Szene, jedes Element, jeder 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 (Farbe korrigieren, Timing anpassen, ein Element hinzufügen) springe direkt zu den Regeln.
Layout vor Animation
Positioniere jedes Element dort, wo es in seinem sichtbarsten Moment sein soll – 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 zu der Position tweenst, von der du denkst, dass sie landen sollen, rätst du das endgültige Layout. Überlappungen sind unsichtbar, bis das Video gerendert wird. Indem du zuerst den Endzustand baust, kannst du Layoutprobleme 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;unddisplay: flex; flex-direction: column; gap: Npx; box-sizing: border-boxausfüllen. Verwende Padding, um Inhalt nach innen zu schieben – verwende NIEMALSposition: absolute; top: Npxauf einem Inhaltscontainer. Absolut positionierte Inhaltscontainer laufen über, wenn der Inhalt größer ist als der verbleibende Platz. 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 Bodenwahrheit; der Tween beschreibt die Reise dorthin. (In Subkompositionen, 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 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 usw.).
Padding positioniert Inhalt. Flex + Gap kümmert sich um 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: 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 den Raum über die Zeit teilen
Wenn Element A ausfritt, 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 erwischen, 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-übereinander gestapelte Designs (Kartenstapel, Tiefenschichten) sind beabsichtigt. Der Layout-Schritt dient dazu, unbeabsichtigte Überlappungen zu erkennen – zwei Überschriften, die übereinander landen, eine Statistik, die ein Label 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/Kompositionen | Sekunden. Video/Audio standardmäßig auf Mediendauer. |
data-track-index | Ja | Ganzzahl. Clips 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 – verwende CSS z-index.
Kompositionsclips
| Attribut | Erforderlich | Werte |
|---|---|---|
data-composition-id | Ja | Eindeutige Kompositions-ID |
data-start | Ja | Startzeit (Stammkomposition: "0") |
data-duration | Ja | Überschreibt die GSAP-Timeline-Dauer |
data-width / data-height | Ja | Pixelabmessungen (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 Stamm-<html>-Element:
| Attribut | Erforderlich | Werte |
|---|---|---|
data-composition-variables | Nein | JSON-Array deklarierter Variablen (id/type/label/default) – steuert die Studio-Bearbeitungs-UI und liefert Standardwerte für getVariables() |
Kompositionsstruktur
Subkompositionen, die über data-composition-src geladen werden, verwenden einen <template>-Wrapper. Eigenständige Kompositionen (das Hauptindex.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.
Subkompositionsstruktur:
<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 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>
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 der
<html>-Wurzel der Komposition mitdata-composition-variables. Jeder Eintrag benötigtid,type(eine 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 aus deklarierten Standardwerten + instanzspezifischen Überschreibungen + CLI-Überschreibungen zurück. - Überschreibe zur Renderzeit mit
npx hyperframes render --variables '{...}'(oberste Ebene) oder mitdata-variable-values='{...}'auf dem Host-Element (instanzspezifisch für Subkompositionen).
<!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>
# Entwicklungsvorschau verwendet deklarierte Standardwerte
npx hyperframes preview
# Mit Überschreibungen rendern
npx hyperframes render --variables '{"title":"Q4-Bericht","theme":"dark"}' --output q4.mp4
# Oder aus einer JSON-Datei
npx hyperframes render --variables-file ./vars.json
Instanzspezifische Werte für Subkompositionen: Dasselbe getVariables() funktioniert innerhalb von Subkompositionen, 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":"Kontakt"}'
></div>
Spuren
Spuren sind parallele Ebenen innerhalb einer Komposition. Clips auf derselben Spur (data-track-index) können sich zeitlich nicht überlappen – die Plattform erzwingt dies. Clips auf verschiedenen Spuren laufen parallel. Verwendungszwecke: separate Spuren für Voiceover, Hintergrundmusik, Soundeffekte, zwei sich nicht überlappende Erzählblöcke in derselben Spur.
Bildmaterial
Videoclips benötigen data-media-start für Beschneidung. data-duration ist hierfür nicht erforderlich – Audio-/Videoclips dauern standardmäßig so lange wie ihre Quelle, es sei denn, es wird eine Dauer angegeben. data-media-start legt die Versatzmarke in der Quelldatei fest, sodass ein 4-Sekunden-Clip auf Sekunde 3 des Quellvideos starten kann.
Hintergrundmusik
Standardmäßig berücksichtigt. Wenn ein Video Hintergrundmusik benötigt, wähle eine aus dem Projektverzeichnis oder der öffentlichen Bibliothek. Kein Audio ohne explizite Anforderung – unerwünschte Musik ist aufdringlicher als unerwünschte visuelle Effekte.
Texthervorhebung (Marker-Sweeps, handgezeichnete Kreise, Scribbles, Burst-Linien, Sketchout)
Verwende Pseudo-Elemente (::before, ::after) und CSS-Animationen oder SMIL (SVG-Animation). Schreibe einen SVG-Textpfad und animiere die stroke-dashoffset-Eigenschaft des Pfads, um Handzeichnungen zu simulieren. Verwende einen Clip-Pfad, um einen Hervorhebungs-Sweep zu erzeugen.
Warum Pseudoelemente und kein zusätzliches DOM: Hervorhebungen sollten kein Seitenlayout verschieben. Pseudoelemente existieren visuell über dem Inhalt, ohne den Fluss zu beeinflussen.
Beispiel – Marker-Sweep:
<h1 class="highlight-text">Dieser Text wird markiert</h1>
<style>
.highlight-text {
position: relative;
display: inline-block;
}
.highlight-text::after {
content: '';
position: absolute;
left: -5px;
right: -5px;
bottom: 0;
height: 40%;
background: rgba(255, 230, 0, 0.4);
z-index: -1;
transform-origin: left;
animation: sweep 0.6s ease-out forwards;
transform: scaleX(0);
}
@keyframes sweep {
to { transform: scaleX(1); }
}
</style>
Shader
Ein Shader ist ein <canvas>-Element, das von einer WebGL2-Fragment-Shader-Quelle angetrieben wird. Standardmäßig befindet sich der Shader in Echtzeit und läuft im Browser, während er in ein Video gerendert wird. Verwende data-duration, um die Shader-Dauer zu steuern, und data-media-start für Offsets.
Shader werden als Clip implementiert – kein separater Kompositionstyp. Jeder Fragment-Shader ist ein Szenen-Clip mit eigenem Timing und kann auf einer Spur mit anderen Clips gemischt werden.
<canvas
class="clip"
id="glow-shader"
data-start="0"
data-duration="4"
data-track-index="1"
data-shader-fragment="
precision highp float;
uniform float u_time;
uniform vec2 u_resolution;
uniform float u_progress;
void main() {
vec2 uv = gl_FragCoord.xy / u_resolution;
float pulse = sin(u_time * 3.0 + uv.x * 10.0) * 0.5 + 0.5;
gl_FragColor = vec4(uv.x, pulse, uv.y, 1.0);
}
"
></canvas>
Verfügbare Uniforms: u_time (Sekunden seit Shader-Start), u_resolution (Pixelgröße), u_progress (0-1, normalisierte Shader-Position innerhalb data-duration), u_mouse (Mausposition während Browser-Vorschau).
Shader-Übergänge
<canvas
class="clip"
id="wipe-transition"
data-start="4"
data-duration="1"
data-track-index="1"
data-transition="true"
data-transition-from="#scene-before"
data-shader-fragment="
precision highp float;
uniform float u_progress;
uniform sampler2D u_from;
uniform sampler2D u_to;
void main() {
vec2 uv = gl_FragCoord.xy / u_resolution;
// u_from samplen, dann bei fortschreitendem Fortschritt nach u_to überblenden
vec4 a = texture2D(u_from, uv);
vec4 b = texture2D(u_to, uv);
float mask = smoothstep(0.0, 1.0, u_progress);
gl_FragColor = mix(a, b, mask);
}
"
></canvas>
data-transition="true" teilt dem Renderer mit, dass dieser Clip die Render-Zieltextur von data-transition-from auf die aktuelle Szene überblenden soll. Der Shader hat Zugriff auf u_from (der vorherige gerenderte Frame) und u_to (das aktuelle Szenen-Ergebnis). Der Shader bestimmt, wie der Übergang aussieht.
Untertitel
Standardmäßig kein Untertitel-Overlay. Wenn Untertitel benötigt werden, platziere ein div.clip mit data-track-index, das immer sichtbar ist (unter halbtransparentem Farbverlauf-Hintergrund), und verwende GSAP, um Textzeilen nach dem Rhythmus der Sprachausgabe ein- und auszublenden.
<div id="captions" class="clip" data-start="0" data-duration="20" data-track-index="2">
<div class="caption-line" id="line-1">Willkommen zu unserer Demo</div>
<div class="caption-line" id="line-2">Heute zeigen wir eine Funktion</div>
</div>
<style>
#captions {
position: absolute;
bottom: 80px;
left: 50%;
transform: translateX(-50%);
text-align: center;
width: 80%;
z-index: 100;
}
.caption-line {
font-size: 28px;
color: white;
text-shadow: 0 2px 8px rgba(0,0,0,0.8);
opacity: 0;
}
</style>
<script>
tl.to("#line-1", { opacity: 1, duration: 0.2 }, 0.5);
tl.to("#line-1", { opacity: 0, duration: 0.2 }, 3.5);
tl.to("#line-2", { opacity: 1, duration: 0.2 }, 3.7);
tl.to("#line-2", { opacity: 0, duration: 0.2 }, 7.5);
</script>
Variablemapping
Verwende Pfeile und Variablemapping nicht, um eine Variable in einem Datenattribut zuzuweisen. Deklariere stattdessen eine data-variable-values-Eigenschaft auf dem Host-Element und lies die Variable innerhalb der Komposition.
Nein:
<div data-composition-src="card.html" data-title="Mein Titel" data-price="29">
Ja:
<div data-composition-src="card.html" data-variable-values='{"title":"Mein Titel","price":"29"}'>
Wichtig: Variablen in Subkompositions-Hosts müssen mit data-variable-values als gültiges JSON deklariert werden. Undeklarierte zufällige data-*-Attribute werden nicht an die Subkomposition weitergegeben.
Ausgabe generieren
Nachdem alle Kompositions-HTML-Dateien geschrieben wurden:
- Initialisiere das Projekt –
npx hyperframes init(erstellthyperframes.json, falls nicht vorhanden) - Lint –
npx hyperframes lint(Suchliste nach Problemen) - Vorschau –
npx hyperframes preview(startet lokalen Server und öffnet Browser) - Rendern –
npx hyperframes render --output final.mp4
Optional: --variables für Überschreibungen, --quality high für bessere Ausgabe. Für CLI-Details, siehe hyperframes-cli.
Renderreihenfolge: Rufe die CLI vom Projektstammverzeichnis aus auf. Der Renderer findet alle Kompositionen anhand ihrer data-composition-id im HTML, löst Subkompositionsreferenzen auf, lädt das design.md und rendert den vollständigen Frame-Baum.