HyperFrames
HTML ist die Quelle der Wahrheit für Videos. 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 die Sichtbarkeit der Clips, die Medienwiedergabe und die Synchronisierung der Timeline.
Umfassender Geltungsbereich und absorbierte spezifische Workflows
Dieser Skill ist der übergeordnete Skill auf Klassenebene für die Erstellung von HyperFrames-Inhalten. Er deckt die Kompositionsstruktur, das Timing, die Animation, die visuelle Identität, Untertitel, audio-reaktive Visualisierungen und die produktionsreife Szenengestaltung ab. Verwende den Skill hyperframes-cli für die Befehlsreferenz und website-to-hyperframes, wenn das Quellmaterial eine bestehende Website ist. Eng gefasste Notizen für Einzelsitzungen zur Produktion/Fehlerbehebung wurden hier als unterstützende Referenzen herabgestuft.
Unterabschnitt: Fallstricke im Produktionsworkflow
Historische Produktionsnotizen betonten einige Umgebungsfallen, die weiterhin nützlich sind:
- Bevorzuge ASCII-Pfade für Projekt-/Ausgabepfade beim Rendern; Nicht-ASCII-Pfade können Headless-Chrome oder Renderer-Prozesse beschädigen.
- Wenn die MP4-Kodierung unter Conda FFmpeg fehlschlägt, erzwinge System-FFmpeg mit
export PATH=/usr/bin:$PATHoder rendere als WebM als Fallback. - Wenn benutzerdefinierte Timeline-Objekte anstelle von GSAP verwendet werden, müssen sie GSAP-kompatible
duration(),pause()undseek(time)-Methoden bereitstellen. - Wenn das finale Video schwarz oder leer aussieht, überprüfe zuerst, ob ein getimter
.clip-Container ausgeblendet wurde, während nur seine Kinder animiert wurden. Eine Utility-Klasse wie.hidden { display: none; }auf Szenen-Wrappern erzeugt das klassische Fehlermuster: Audio rendert, Hintergrund rendert, aber kein Text/Karten erscheinen jemals, weil die übergeordnete Szene nie in Layout/Paint eintritt. Verstecke getimte Szenen-Wrapper mitopacity: 0oder timeline-gesteuerter Deckkraft anstelle vondisplay: none. - Für kritisches Laufzeit-JS wie GSAP solltest du eine lokale Kopie im Projekt bevorzugen (z.B.
assets/gsap.min.js) anstatt auf Live-CDN-Abrufe während des Renderns angewiesen zu sein. - Füge
<link rel="icon" href="data:,">zu eigenständigen Kompositionen hinzu, um Headless-Browser-Favicon-404-Rauschen zu unterdrücken, wenn kein Favicon Teil des Projekts ist. - Überprüfe visuell, indem du Frames mit FFmpeg extrahierst und Screenshots inspizierst, und verlasse dich nicht nur auf einen erfolgreichen Exit-Code des Renderers.
Herabgestufte Support-Referenzen
references/hyperframes-video-production.mdreferences/hyperframes-workflow.md
Vorgehensweise
Bevor du HTML schreibst, denke auf einer hohen Ebene:
- Was – Was soll der Zuschauer erleben? Identifiziere den narrativen Bogen, die Schlüsselmomente und die emotionalen Beats.
- Struktur – Wie viele Kompositionen, welche davon sind Unterkompositionen vs. inline, welche Tracks transportieren was (Video, Audio, Overlays, Untertitel).
- Timing – Welche Clips bestimmen die Dauer, wo liegen die Übergänge, wie ist das Tempo?
- Layout – Erstelle zuerst den Endzustand. Siehe "Layout vor Animation" unten.
- Animieren – Füge dann Bewegung unter Verwendung der folgenden Regeln hinzu.
Bei kleinen Änderungen (Farbe korrigieren, Timing anpassen, ein Element hinzufügen) überspringe direkt zu den Regeln.
Visuelle Identitätstor
Prüfe in dieser Reihenfolge:
- Existiert DESIGN.md im Projekt? → Lies es. Verwende seine exakten Farben, Schriftarten, Bewegungsregeln und die Einschränkungen unter "Was NICHT zu tun ist".
- Existiert visual-style.md? → Lies es. Wende sein
style_prompt_fullund seine strukturierten Felder an. (Hinweis:visual-style.mdist eine projektspezifische Datei.visual-styles.mdist die Stilbibliothek mit 8 benannten Vorlagen – unterschiedliche Dateien.) - Hat der Benutzer einen Stil genannt (z.B. „Swiss Pulse", "dunkel und technisch", "Luxusmarke")? → Lies visual-styles.md für die 8 benannten Vorlagen. Erstelle eine minimale DESIGN.md mit:
## Style Prompt(ein Absatz),## Farben(3-5 Hex-Werte mit Rollen),## Typografie(1-2 Schriftfamilien),## Was NICHT zu tun ist(3-5 Anti-Patterns). - Nichts davon? → Stelle 3 Fragen, bevor du HTML schreibst:
- Was ist die Stimmung? (explosiv / cineastisch / fließend / technisch / chaotisch / warm)
- Helle oder dunkle Leinwand?
- Gibt es bestimmte Markenfarben, Schriftarten oder visuelle Referenzen? Erstelle dann aus den Antworten eine minimale DESIGN.md.
Jede Komposition muss ihre Palette und Typografie auf eine DESIGN.md, visual-style.md oder eine explizite Benutzervorgabe zurückführen. Wenn du nach #333, #3b82f6 oder Roboto greifst – hast du diesen Schritt übersprungen.
Befolge für Bewegungsvorgaben, Größen, Eintrittsmuster und Easing die house-style.md. Der House-Style regelt, WIE sich Dinge bewegen. Die DESIGN.md regelt, WIE Dinge aussehen.
Layout vor Animation
Positioniere jedes Element dort, wo es zu 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 das wichtig ist: Wenn du Elemente in ihrem animierten Startzustand positionierst (außerhalb des Bildschirms, auf 0 skaliert, Deckkraft 0) und sie dann zu dem Punkt zwischenschaltest, wo sie deiner Meinung nach landen sollten, rätst du das endgültige Layout. Überlappungen sind unsichtbar, bis das Video gerendert wird. Indem du zuerst den Endzustand erstellst, kannst du Layout-Probleme sehen und beheben, bevor du Bewegung hinzufügst.
Der Prozess
- Identifiziere den Heldenframe für jede Szene – den Moment, in dem die meisten Elemente gleichzeitig sichtbar sind. Dies ist das Layout, das du erstellst.
- 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 – NIEMALSposition: absolute; top: Npxauf einem Inhaltscontainer. Absolut positionierte Inhaltscontainer laufen über, wenn der Inhalt höher ist als der verbleibende Platz. Reserviereposition: absoluteausschließlich 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. - 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 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 Inhalt. Flex + Gap handhabt 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: Animiere IN diese Positionen
hl.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: Animiere AUS diesen Positionen
hl.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 austritt, bevor Element B im selben Bereich eintritt, sollten beide korrekte CSS-Positionen für ihre jeweiligen Heldenframes haben. Die Timeline-Reihenfolge garantiert, dass sie nie visuell koexistieren – aber wenn du den Layout-Schritt überspringst, wirst du den Fall nicht erkennen, in dem sie aufgrund eines Timing-Fehlers versehentlich überlappen.
Was als beabsichtigte Überlappung gilt
Geschichtete Effekte (Glühen hinter Text, Schattenelemente, Hintergrundmuster) und Z-Stack-Designs (Kartenstapel, Tiefenschichten) sind beabsichtigt. Beim Layout-Schritt geht es darum, unbeabsichtigte Überlappungen zu erkennen – zwei Überschriften, die übereinander landen, eine Statistik, die ein Label bedeckt, Inhalt, der vom Frame 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 verwendet standardmäßig die Mediendauer. |
data-track-index | Ja | Ganzzahl. Clips im selben Track können sich nicht überlappen. |
data-media-start | Nein | Offset zum Trimmen 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 GSAP-Timeline-Dauer |
data-width / data-height | Ja | Pixelmaße (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-datei index.html) verwenden KEINEN <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 Rendern.
Struktur einer Unterkomposition:
<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 im Stammverzeichnis: <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 separater <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
{ paused: true }– die Player-Steuerung übernimmt die Wiedergabe - Registriere jede Timeline:
window.__timelines["<composition-id>"] = tl - Das Framework verschachtelt Unter-Timelines automatisch – füge sie NICHT manuell hinzu
- Die Dauer stammt von
data-duration, nicht von der GSAP-Timeline-Länge - Erstelle niemals leere Tweens, um die Dauer festzulegen
Regeln (Nicht verhandelbar)
Deterministisch: Kein Math.random(), Date.now() oder zeitbasierte Logik. Verwende einen initiierten PRNG, wenn du pseudo-zufällige Werte benötigst (z.B. mulberry32).
GSAP: Animieren nur visuelle Eigenschaften (opacity, x, y, scale, rotation, color, backgroundColor, borderRadius, Transformationen). Animieren NICHT visibility, display oder rufe video.play()/audio.play() auf.
Animationskonflikte: Animieren niemals dieselbe Eigenschaft auf demselben Element von mehreren Timelines gleichzeitig.
Kein repeat: -1: Sich unendlich wiederholende Timelines unterbrechen die Erfassungs-Engine. Berechne die genaue Wiederholungszahl aus der Kompositionsdauer: repeat: Math.ceil(duration / cycleDuration) - 1.
Synchrone Timeline-Erstellung: Erstelle Timelines niemals innerhalb von async/await, setTimeout oder Promises. Die Erfassungs-Engine liest window.__timelines nach dem Seitenladen synchron. Schriftarten werden vom Compiler eingebettet, sodass sie sofort verfügbar sind – es ist nicht nötig, auf das Laden von Schriftarten zu warten.
Niemals tun:
- Vergessen der
window.__timelines-Registrierung - Video für Audio verwenden – immer stummgeschaltetes Video + separates
<audio> - Video innerhalb eines getimten Divs verschachteln – verwende einen nicht getimten Wrapper
data-layer(verwendedata-track-index) oderdata-end(verwendedata-duration) verwenden- Video-Elementabmessungen animieren – animiere einen Wrapper-Div
- Play/Pause/Seek auf Medien aufrufen – das Framework besitzt die Wiedergabe
- Einen übergeordneten Container ohne
data-composition-iderstellen repeat: -1auf einer Timeline oder einem Tween verwenden – immer endliche Wiederholungen- Timelines asynchron erstellen (innerhalb von
async,setTimeout,Promise) gsap.set()auf Clip-Elementen aus späteren Szenen verwenden – sie existieren beim Laden der Seite nicht im DOM. Verwende stattdessentl.set(selector, vars, timePosition)innerhalb der Timeline zur oder nach derdata-start-Zeit des Clips.<br>im Inhaltstext verwenden – erzwungene Zeilenumbrüche berücksichtigen nicht die tatsächliche gerenderte Schriftbreite. Text, der natürlich umbricht + ein<br>erzeugt einen zusätzlichen unerwünschten Umbruch, der zu Überlappungen führt. Lass Text stattdessen übermax-widthumbrechen. Ausnahme: kurze Anzeigetitel, bei denen jedes Wort bewusst in einer eigenen Zeile steht (z.B. "THE\nIMMORTAL\nGAME" bei 130px).
Szenenübergänge (Nicht verhandelbar)
Jede Mehrszenenkomposition MUSS ALLE diese Regeln befolgen. Die Verletzung auch nur einer davon führt zu einer defekten Komposition.
- Verwende IMMER Übergänge zwischen Szenen. Keine harten Schnitte. Keine Ausnahmen.
- Verwende IMMER Eingangsanimationen für jede Szene. Jedes Element wird via
gsap.from()EINGEANIMIERT. Kein Element darf vollständig ausgebildet erscheinen. Wenn eine Szene...