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 die Sichtbarkeit von Clips, die Medienwiedergabe und die Zeitsynchronisation.
Vorgehensweise
Entdeckungsphase (nur für explorative Anfragen)
Bei offenen Anfragen ("Erstelle ein Produkt-Launch-Video", "Kreiere etwas für unsere Marke"), bei denen sich der Nutzer noch nicht auf eine Richtung festgelegt hat, solltest du zuerst die Absicht verstehen, bevor du Farben auswählst:
- Zielgruppe – Wer sieht sich das an? Entwickler? Führungskräfte? Allgemeine Verbraucher?
- Plattform – Wo wird es abgespielt? Social Media (15s), Website-Hero, Produkt-Demo, intern?
- Priorität – Was ist am wichtigsten? Bewegungsqualität? Inhaltsgenauigkeit? Markentreue? Geschwindigkeit?
- Variationen – Möchte der Nutzer Optionen oder einen einzigen besten Versuch?
Bei spezifischen Anfragen ("Füge eine Titelcard hinzu", "Korrigiere das Timing in Szene 3") überspringe die Entdeckungsphase.
Bei explorativen Anfragen solltest du in Betracht ziehen, 2-3 Variationen anzubieten, die sich sinnvoll unterscheiden – nicht nur Farbwechsel, sondern unterschiedliches Tempo, Energielevel oder strukturelle Ansätze. Eine sichere/erwartete, eine ambitionierte. Das ist kein Muss – es ist ein Werkzeug, das bei Bedarf eingesetzt werden kann.
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 die exakten Werte – erfinde keine Farben und ersetze keine Schriftarten. Jedes Format ist in Ordnung (YAML-Frontmatter, Prosa, Tabellen – extrahiere einfach die Werte).
Wenn darin Schriftarten genannt werden, die du lokal nicht findest (kein fonts/-Verzeichnis mit .woff2-Dateien, keine integrierte Schriftart), warne den Nutzer, bevor du HTML schreibst: "design.md gibt [Schriftartname] an, aber es wurden keine Schriftartdateien gefunden. Bitte füge .woff2-Dateien zu fonts/ hinzu, oder ich werde auf [die nächstgelegene integrierte Alternative] zurückfallen."
Wenn keine design.md existiert, biete dem Nutzer eine Auswahl an:
- Hat der Nutzer einen Stil oder eine Stimmung genannt? → Lies visual-styles.md für die 8 benannten Presets. Wähle die nächstgelegene Übereinstimmung.
- Möchte der Nutzer visuell stöbern? → Führe den Design-Picker aus: Lies references/design-picker.md für den vollständigen Workflow. Dies dient eine visuelle Auswahlseite aus. Der Nutzer konfiguriert Stimmung, Palette, Typografie und Bewegung im Browser, kopiert dann die generierte design.md und fügt sie zurück in das Gespräch.
- Möchte der Nutzer 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 aus references/video-composition.md und house-style.md. Verwende Markenfarben in einer für Videos geeigneten Größenordnung – nicht in der Deckkraft einer Web-UI.
Schritt 2: Prompt-Erweiterung (Prompt Expansion)
Wird immer bei jeder Komposition ausgeführt (außer bei Ein-Szenen-Stücken und trivialen Bearbeitungen). Dieser Schritt verankert die Absicht des Nutzers in Bezug auf design.md und house-style.md und erzeugt ein konsistentes Zwischenergebnis, 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: Planung
Bevor du HTML schreibst, denke auf einer hohen Ebene:
- Was – Was soll der Zuschauer erleben? Identifiziere den erzählerischen Bogen, die Schlüsselmomente und die emotionalen Höhepunkte.
- Struktur – Wie viele Kompositionen, welche sind Unterkompositionen vs. inline, welche Spuren tragen was (Video, Audio, Overlays, Untertitel).
- Rhythmus – Lege deinen Szenenrhythmus fest, bevor du ihn implementierst. Welche Szenen sind schnelle Hits, welche sind Halte, wo landen Shader, wo ist der Energiehöhepunkt. Benenne das Muster: schnell-schnell-LANGSAM-schnell-SHADER-halten. 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 mit den folgenden Regeln hinzu.
Baue, worum gebeten wurde. Eine Anfrage nach "einer Titelcard" ist keine Anfrage nach "einer Titelcard + 3 unterstützenden Szenen + Hintergrundmusik + Untertiteln." Jede Szene, jedes Element, jeder Tween sollte seinen Platz verdienen. Wenn zusätzliche Szenen oder Elemente das Stück wirklich verbessern würden, schlage sie vor – füge sie nicht einfach hinzu.
Bei kleinen Änderungen (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 Begriff ist, auszutreten. 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 sie deiner Meinung nach landen sollen, errä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 ausfüllen, indem erwidth: 100%; height: 100%; padding: Npx;mitdisplay: flex; flex-direction: column; gap: Npx; box-sizing: border-boxverwendet. Verwende Padding, um Inhalt nach innen zu drücken – 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 Eingänge mit
gsap.from()hinzu – animiere VON außerhalb des Bildschirms/unsichtbar ZU der CSS-Position. Die CSS-Position ist die Grundwahrheit; der Tween beschreibt die Reise dorthin. (In Unterkompositionen, die überdata-composition-srcgeladen werden, bevorzugegsap.fromTo()– siehe die tragenden GSAP-Regeln in references/motion-principles.md.) - Füge Ausgänge 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: In diese Positionen hinein 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 heraus 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 austritt, bevor Element B im selben Bereich eintritt, sollten beide korrekte CSS-Positionen für ihre jeweiligen Helden-Frames haben. Die zeitliche Reihenfolge garantiert, dass sie nie visuell koexistieren – aber wenn du den Layout-Schritt überspringst, wirst du den Fall nicht bemerken, dass sie sich 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 aufeinanderlanden, eine Statistik, die ein Label bedeckt, Inhalt, der vom Bildrand abgeschnitten wird.
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 | Schnittversatz in der 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 (Hauptkomposition: verwende "0") |
data-duration | Ja | Hat Vorrang vor der Dauer der GSAP-Timeline |
data-width / data-height | Ja | Pixel-Abmessungen (1920x1080 oder 1080x1920) |
data-composition-src | Nein | Pfad zu einer externen HTML-Datei |
data-variable-values | Nein | JSON-Objekt mit instanzspezifischen Variablenüberschreibungen auf einem Sub-Comp-Host |
Auf dem Wurzel-<html>-Element:
| Attribut | Erforderlich | Werte |
|---|---|---|
data-composition-variables | Nein | JSON-Array deklarierter Variablen (id/type/label/default) – treibt die Bearbeitungs-UI im Studio und stellt Standardwerte für getVariables() bereit |
Kompositionsstruktur
Sub-Kompositionen, die über data-composition-src geladen werden, verwenden einen <template>-Wrapper. Eigenständige Kompositionen (die Haupt-index.html) verwenden KEIN <template> – sie platzieren das data-composition-id-div direkt im <body>. Die Verwendung von <template> in einer eigenständigen Datei verbirgt den gesamten Inhalt vor dem Browser und unterbricht das Rendering.
Struktur einer Sub-Komposition:
<template id="my-comp-template">
<div data-composition-id="my-comp" data-width="1920" data-height="1080">
<!-- Inhalt -->
<style>
[data-composition-id="my-comp"] {
/* bereichsspezifische 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 im 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 das Quell-HTML zu bearbeiten.
Drei-Schritt-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 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 Sub-Kompositionen).
<!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>
# Entwicklervorschau 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
Instanzspezifische Werte für Sub-Kompositionen: dasselbe getVariables() funktioniert innerhalb von Sub-Kompositionen, 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>
Medienattribute (Video / Audio)
| Attribut | Erforderlich | Werte |
|---|---|---|
data-src | Ja | Pfad zur Mediendatei, URL oder base64-URI |
data-format | Nein | Medienformat ("mp4", "webm", "wav", "mp3") |
data-media-start | Nein | Schnittversatz in der Quelle (Sekunden) |
data-media-end | Nein | Stoppzeit in der Quelle (Sekunden) |
data-volume | Nein | 0-1 (Standard 1) |
data-muted | Nein | "true" um Video-Audio stummzuschalten (Standard falsch) |
data-loop | Nein | "true" um die Wiedergabe zu loopen (Standard falsch) |
Leinwand-Clips: Jede id mit einem <canvas> als Kind verwendet data-start, data-duration, data-track-index. Schreibe die Leinwandlogik innerhalb des Clips.
Audio-Reaktivität: Füge data-audio-reactive="true" auf jedem Element hinzu, das auf Audioanalyse reagieren soll. Verwende window.__hyperframes.getAudioData() in einem Skript:`
const audioData = window.__hyperframes.getAudioData();
// Gibt ein Objekt zurück: { waveform: Float32Array(1024), frequency: Float32Array(1024), rms: number, peak: number, zcr: number }
Text-to-Speech: Füge ein Attribut data-tts="Text, der gesprochen werden soll" auf einem Element hinzu (unterstützt vom hyperframes-media Skill).
Umgang mit Sub-Kompositionen
Jede Sub-Komposition (geladen über data-composition-src) wird in ihrem eigenen <template> definiert. Sie hat ihre eigene GSAP-Timeline, die in das window.__timelines-Objekt eingetragen wird.
Leistungsoptimierung für große Zusammensetzungen:
<script>
// Lazy-Erstellung der Timeline
let tl;
document.addEventListener("DOMContentLoaded", () => {
tl = gsap.timeline({ paused: true });
// Mit Versatz für optimiertes Timing tweenen
tl.from(".elem", { opacity: 0, y: 20, duration: 0.5 }, 0);
window.__timelines["main-comp"] = tl;
});
</script>
Bereichsspezifische Styles: Verwende immer [data-composition-id="meine-comp-id"] als CSS-Selektor-Präfix, um Stil-Lecks zwischen Kompositionen zu verhindern.
Animationsregeln
Prinzipien
- Vertikale zentrierte Basis – Der
.scene-content-Container zentriert vertikal und horizontal mitdisplay: flex; align-items: center; - Padding für Atemraum – Verwende Padding auf
.scene-content, niemals feste Positionierung von Kindern - Layout zuerst, Animation später – Bringe jeden Helden-Frame zuerst mit statischem HTML+CSS ins Gleichgewicht
- Bewusste Szenenübergänge – Verwende CSS-Übergänge oder GPU-beschleunigte GSAP-Eigenschaften (
transform,opacity) für flüssige Animationen - Minimiere Layout-Verschiebungen – Keine Änderungen an
width/height/top/left– verwendetransform
Timing-Struktur
const tl = gsap.timeline({ paused: true });
tl.from(".hero-title", { y: 80, opacity: 0, duration: 0.8, ease: "power4.out" }, 0);
tl.from(".hero-subtitle", { y: 40, opacity: 0, duration: 0.6, ease: "power3.out" }, 0.4);
tl.from(".cta-button", { scale: 0.8, opacity: 0, duration: 0.5, ease: "back.out(1.7)" }, 0.8);
tl.to(".hero-title", { y: -60, opacity: 0, duration: 0.5, ease: "power2.in" }, 3.5);
tl.to(".hero-subtitle", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3.7);
tl.to(".cta-button", { opacity: 0, duration: 0.3 }, 3.9);
Übergänge zwischen Szenen
Verwende den data-transition-Attributsatz auf dem abgehenden Clip:
| Attribut | Erforderlich | Werte |
|---|---|---|
data-transition-type | Ja | "crossfade", "wipe-left", "wipe-right", "wipe-up", "wipe-down", "reveal", "shader" |
data-transition-duration | Nein | Sekunden (Standard 0,5) |
data-transition-direction | Nein | "in" (Standard) oder "out" – ob der Effekt auf das eingehende oder ausgehende Element angewendet wird |
Shader-Übergang: Erfordert, dass du einen benutzerdefinierten Canvas-Shader definierst. Füge ein <canvas> mit einer benannten id innerhalb des Clips hinzu und referenziere es:
<div class="clip" data-start="2" data-duration="3" data-track-index="1" data-transition-type="shader" data-transition-duration="1">
<canvas id="shader-canvas" class="transition-shader"></canvas>
<div class="scene-content">
<!-- Inhalt -->
</div>
<script>
// Canvas-Shader-Logik
const canvas = document.getElementById("shader-canvas");
const ctx = canvas.getContext("2d");
// ... WebGL-Shader-Code
</script>
</div>
Vergleichstabelle zwischen verschiedenen Videotypen
| Aspekt | Social (15s) | Website-Hero | Produkt-Demo | Intern |
|---|---|---|---|---|
| Dauer | 15-30s | 30-60s | 60-120s | 2-5min |
| Tempo | Schnell, viele Schnitte | Gemäßigt, atmosphärisch | Informativ, schrittweise | Ausführlich, erklärend |
| Schriftgröße | Groß (90-140px) | Mittel (60-100px) | Klein (40-60px) | Klein (30-50px) |
| Untertitel | Erforderlich, fett | Optional, subtil | Erforderlich, klar | Optional |
| Übergänge | Wipe, schnell | Crossfade, weich | Reveal, informativ | Crossfade, ruhig |
| Audio-Reaktivität | Hoch (Beat-Sync) | Mittel (Atmosphäre) | Niedrig (Fokus auf Inhalt) | Niedrig |
Fehlerbehebung und häufige Probleme
| Problem | Ursache | Lösung |
|---|---|---|
| Video wird nicht abgespielt | data-src fehlt oder falscher Pfad | Überprüfe den Dateipfad und das Format |
| Animation wird nicht angezeigt | GSAP-Timeline nicht in window.__timelines registriert | Stelle sicher, dass window.__timelines["id"] = tl; vorhanden ist |
| Layout-Überlappungen | Feste Positionierung anstelle von Flexbox verwendet | Verwende scene-content mit Flexbox und Padding |
| Ton ist zu leise oder stumm | data-volume nicht gesetzt oder data-muted="true" | Setze data-volume="1" und entferne data-muted |
| Sub-Komposition unsichtbar | <template> in einer eigenständigen Datei verwendet | Entferne <template>-Wrapper – Hauptkompositionen brauchen ihn nicht |
| CSS-Stile lecken | Kein bereichsspezifischer Selektor verwendet | Verwende [data-composition-id="..."] als Präfix für alle Stile |
| Leinwand-Clip stumm | Audio nicht mit Canvas-Element verknüpft | Verwende ein separates Audio-Element mit data-src für die Audioquelle |
| Render-Skript-Ausführungsreihenfolge | Skripte werden asynchron in Sub-Kompositionen geladen | Verwende document.addEventListener("DOMContentLoaded", ...), um Timeline-Code zu umschließen |
Auftragsabwicklung
Dateien, die zuvor erstellt wurden: Wenn du bereits eine index.html erstellt hast, bearbeite sie, anstatt eine neue zu erstellen. Wenn das Projekt keine house-style.md, sondern nur die erstellte index.html hat, lies sie nicht. Beziehe dich nur auf vorhandene Designsysteme.
Zu erstellende/zu bearbeitende Dateien:
index.html– die Hauptvideokompositioncompositions/*.html– Sub-Kompositionen für wiederverwendbare Szenen oder Komponentendesign.md– falls erstellt oder bereitgestellt, das Designsystem
Sprache: Verwende Englisch für IDs (id="hero-title"), Klassennamen (class="clip"), Datenattribute und Skriptvariablen. Verwende die vom Nutzer angeforderte Sprache für Textelemente (Überschriften, Untertitel, Fließtext).
Verwandte Skills
- hyperframes-cli – Dev-Loop-CLI-Befehle: init, lint, inspect, preview, render
- hyperframes-media – Asset-Vorverarbeitung: tts, transcribe, remove-background