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.
Integration in Open Design (tragend für diese Oberfläche)
Wenn dieses Skill in Open Design läuft (d.h. $OD_PROJECT_DIR gesetzt ist), ist der Ausgabefluss festgelegt: Nur die gerenderte .mp4-Datei soll im Projektstammverzeichnis landen. Kompositionsquellendateien (hyperframes.json, meta.json, index.html, Assets) gehören in ein verstecktes Cache-Verzeichnis, damit sie die Dateiansicht des Benutzers oder die "produzierte Dateien"-Chips des Chats nicht überladen.
Render-Workflow innerhalb von OD – schneller Pfad:
Für die meisten OD-Anfragen ("Testvideo", "5-Sekunden-Produktvorstellung", "Demo-Clip") NICHT die Kompositions-HTML von Grund auf neu schreiben. Verwende das integrierte HyperFrames-Gerüst und bearbeite nur das, was die Eingabeaufforderung tatsächlich ändert. Der "von Grund auf neu erstellen"-Pfad kostet Minuten an Modellausgabe und stille Chat-Tool-Zeit; der Gerüst-Pfad kostet Sekunden.
# 1. Wähle einen versteckten Cache-Slot. Dotfile-Präfix → ODs Projektdatei-
# Auflistung überspringt es, sodass die Quelldateien den Chat nie überladen.
COMP_REL=".hyperframes-cache/$(date +%s)-$(openssl rand -hex 2)"
COMP="$OD_PROJECT_DIR/$COMP_REL"
# 2. Ein sofort renderbares Gerüst abrufen (hyperframes.json,
# meta.json, index.html mit GSAP CDN + window.__timelines.main
# bereits registriert). Das läuft in deiner Shell – reiner Dateikopier-
# vorgang, kein Chrome, kein Netzwerk außer dem npx-Cache.
npx hyperframes init "$COMP" --example blank --skip-skills --non-interactive
# 3. Bearbeite NUR $COMP/index.html – ändere `data-duration` auf dem Root-
# Element, wenn du eine andere als die Standardlänge benötigst, tausche die
# Platzhalter-Palette in <style>, füge 1–3 Clip-<div>s für Text/Bilder hinzu
# und füge die passenden GSAP-Tweens innerhalb des vorhandenen
# `window.__timelines["main"] = gsap.timeline({paused:true})`-Blocks an.
# Halte die Bearbeitungen minimal; das Gerüst ist bereits gültiges HF.
# 4. Starte den Render über den OD-Daemon. Führe NICHT `npx hyperframes
# render` in dieser Shell aus – der Daemon führt es für dich in einem
# unsandboxten Prozess aus. (Viele Agenten-CLIs, insbesondere Claude Code,
# wrappen Bash im macOS-Sandbox-exec, bei dem Puppeteers Chrome-Unterprozess
# während der Frame-Erfassung hängen bleibt. Der Daemon-Prozess ist
# unsandboxt, sodass Renderings zuverlässig abgeschlossen werden.)
#
# Der Dispatcher kehrt in ~1s mit einem {taskId} zurück; treibe das
# Rendering mit einer Schleife von `od media wait <taskId>`-Aufrufen
# zur Vollendung. Jeder Aufruf long-polt bis zu 25s (deutlich unter dem
# Standard-30s-Limit deines Shell-Tools) und beendet sich mit 0/2/5 für
# fertig/laufend/fehlgeschlagen.
out=$(node "$OD_BIN" media generate \
--project "$OD_PROJECT_ID" \
--surface video \
--model hyperframes-html \
--output "<deskriptiver-name>.mp4" \
--composition-dir "$COMP_REL")
ec=$?
task_id=$(printf '%s\n' "$out" | tail -1 | jq -r '.taskId // empty')
since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // 0')
while [ "$ec" -eq 2 ] && [ -n "$task_id" ]; do
out=$(node "$OD_BIN" media wait "$task_id" --since "$since")
ec=$?
since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // '"$since")
done
["$ec" -ne 0 ] && { echo "$out" >&2; exit "$ec"; }
Jeder generate- und jeder wait-Aufruf dauert maximal ~25s, sodass das Standard-Limit von ~30s des Agent-Shell-Tools nie ausgelöst wird. Fortschrittszeilen von HF (Capturing frame N/M) werden live während der Schleife nach stderr gestreamt. Wenn das Rendering abgeschlossen ist, ist die letzte stdout-Zeile {"file": { "name": "<output>", "size": …, "kind": "video", … }} – zitiere file.name in deiner Antwort, damit der Benutzer weiß, was produziert wurde.
Überspringe das Visual Identity Gate innerhalb von OD. Der HARD-GATE-Abschnitt unten (unter "Vorgehensweise") sagt dir, DESIGN.md / visual-style.md zu lesen oder zu stoppen und 3 Stimmungsfragen zu stellen, bevor du eine Komposition schreibst. Dieses Gate gilt für eigenständige HF-Projekte. OD-Projekte haben bereits ihre eigene Designsystem-Ebene – der Benutzer hat seine visuelle Richtung bei der Projekterstellung gewählt. Für einen OD-Test-Render standardmäßig auf: dunkle Leinwand (#0b0b0f), einen warmen Akzent (#ffb76b), einen kühlen Akzent (#7da4ff), zurückhaltende Bewegung. Frage nur nach stilistischen Eingaben, wenn die Eingabeaufforderung des Benutzers zu vage ist, um überhaupt ein Thema auszuwählen (sehr selten).
Wann das Gerüst übersprungen und von Grund auf neu geschrieben werden sollte: nur, wenn der Benutzer explizit etwas anfordert, das die leere Vorlage eindeutig nicht hosten kann (z.B. Multi-Kompositions-Timelines, audio-reaktive Overlays, Untertitel synchronisiert zu einer TTS-Spur, die sie bereits generiert haben). Für alles andere ist Init + Bearbeiten der Standardpfad.
Die leichteren HF-Unterbefehle, die du weiterhin in deiner eigenen Shell ausführen KANNST (sie benötigen kein Chrome zum Starten):
npx hyperframes lint "$COMP"– Komposition vor dem Versand validierennpx hyperframes transcribe <audio>– Untertitel generierennpx hyperframes tts <text>– Vertonung generieren
Reserviere den Daemon-Dispatch für render/inspect/preview (alles, was Chrome benötigt).
Rufe NICHT od media generate --model hyperframes-html auf – dieser Dispatcher-Pfad gibt absichtlich einen 400 (AGENT_RENDERED) zurück. HyperFrames wird von dir direkt über npx gerendert.
Lege NICHT hyperframes.json / meta.json / index.html im Projektstammverzeichnis ab; die Dateilistung von OD durchsucht rekursiv und der Benutzer würde drei unabhängige Dateien im Chat sehen.
Für CLI-Optionen neben render (lint, preview, transcribe, tts, inspect, benchmark) rufe sie direkt von deinem Shell-Tool auf, wenn die Aufgabe dies rechtfertigt (z.B. generiere TTS-Audio in den Cache, bevor du es in der Komposition referenzierst).
Vorgehensweise
Bevor du HTML schreibst, denke auf hoher Ebene:
- Was – was soll der Betrachter erleben? Identifiziere den narrativen Bogen, die Schlüsselmomente und die emotionalen Beats.
- Struktur – wie viele Kompositionen, welche sind Unterkompositionen vs. inline, welche Spuren transportieren was (Video, Audio, Overlays, Untertitel).
- Timing – welche Clips bestimmen die Dauer, wo liegen die Übergänge, wie ist das Tempo.
- Layout – baue zuerst den Endzustand. Siehe "Layout vor Animation" unten.
- Animieren – füge dann Bewegung nach den folgenden Regeln hinzu.
Für kleine Bearbeitungen (eine Farbe korrigieren, Timing anpassen, ein Element hinzufügen) springe direkt zu den Regeln.
Visual Identity Gate
Überprüfe in dieser Reihenfolge:
- DESIGN.md existiert im Projekt? → Lies sie. Verwende ihre genauen Farben, Schriftarten, Bewegungsregeln und "Was NICHT zu tun ist"-Einschränkungen.
- visual-style.md existiert? → Lies sie. Wende ihren
style_prompt_fullund die strukturierten Felder an. (Hinweis:visual-style.mdist eine projektspezifische Datei.visual-styles.mdist die Stilbibliothek mit 8 benannten Voreinstellungen – unterschiedliche Dateien.) - Benutzer hat einen Stil genannt (z. B. "Swiss Pulse", "dunkel und technisch", "Luxusmarke")? → Lies visual-styles.md für die 8 benannten Voreinstellungen. Generiere eine minimale DESIGN.md mit:
## Style Prompt(ein Absatz),## Colors(3-5 Hex-Werte mit Rollen),## Typography(1-2 Schriftfamilien),## What NOT to Do(3-5 Anti-Patterns). - Keines der oben genannten? → Stelle 3 Fragen, bevor du HTML schreibst:
- Wie ist die Stimmung? (explosiv / kinematografisch / fließend / technisch / chaotisch / warm)
- Helle oder dunkle Leinwand?
- Irgendwelche spezifischen Markenfarben, Schriftarten oder visuellen Referenzen? Generiere dann eine minimale DESIGN.md aus den Antworten.
Jede Komposition muss ihre Palette und Typografie auf eine DESIGN.md, visual-style.md oder explizite Benutzeranweisung zurückführen können. Wenn du nach #333, #3b82f6, oder Roboto greifst – hast du diesen Schritt übersprungen.
Für Bewegungsstandards, Größenanpassung, Eingangsmuster und Easing – folge house-style.md. Der House-Style kümmert sich darum, WIE sich Dinge bewegen. Die DESIGN.md kümmert sich darum, WIE Dinge aussehen.
Layout vor Animation
Positioniere jedes Element so, wie es an seinem sichtbarsten Moment sein sollte – dem 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 das wichtig ist: Wenn du Elemente an ihrem animierten Startzustand (außerhalb des Bildschirms, auf 0 skaliert, Deckkraft 0) positionierst 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 den Endzustand zuerst 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;füllen, mitdisplay: flex; flex-direction: column; gap: Npx; box-sizing: border-box. Verwende Padding, um 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. Reserviereposition: absolutenur für dekorative Elemente. - Füge Eingänge 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, um dorthin zu gelangen. - 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 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: 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 hinaus 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 Platz ü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, erkennst du den Fall nicht, in dem sie aufgrund eines Timing-Fehlers versehentlich überlappen.
Was als beabsichtigte Überlappung gilt
Geschichtete Effekte (Glow 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 aus dem 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/Komposition | Sekunden. Video/Audio standardmäßig Mediendauer. |
data-track-index | Ja | Ganzzahl. Clips mit 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.
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 GSAP-Timeline-Dauer |
data-width / data-height | Ja | Pixelabmessungen (1920x1080 oder 1080x1920) |
data-composition-src | Nein | Pfad zu externer HTML-Datei |
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 den gesamten Inhalt vor dem Browser und bricht das Rendering.
Unterkompositionsstruktur:
<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>
Video
…
[gekürzt für die Übersetzung]