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 verwaltet die Sichtbarkeit von Clips, die Medienwiedergabe und die Zeitleistensynchronisation.
Open Design Integration (tragend für diese Oberfläche)
Wenn dieses Skill innerhalb von Open Design ausgeführt wird (d.h. $OD_PROJECT_DIR ist gesetzt), ist der Ausgabefluss festgelegt: Nur das gerenderte .mp4 sollte im Projektstamm landen. Kompositionsquelldateien (hyperframes.json, meta.json, index.html, Assets) gehören in ein verstecktes Cache-Verzeichnis, damit sie die Dateiansicht des Benutzers oder die „erstellte Dateien“-Chips des Chats nicht überladen.
Render-Workflow innerhalb von OD – Schnellpfad:
Für die meisten OD-Anfragen („Testvideo“, „5s Produkt-Enthüllung“, „Demo-Clip“) schreiben Sie NICHT die Komposition HTML von Grund auf neu. Verwenden Sie HyperFrames‘ integriertes Gerüst und bearbeiten Sie nur das, was die Eingabeaufforderung tatsächlich ändert. Der Weg „von Grund auf neu“ kostet Minuten an Modellausgabe und stille Chat-Tool-Zeit; der Gerüstweg kostet Sekunden.
# 1. Wähle einen versteckten Cache-Slot. Punkt-Präfix → OD‘s Projektdateiliste überspringt ihn, sodass die Quelldateien den Chat nie überladen.
COMP_REL=".hyperframes-cache/$(date +%s)-$(openssl rand -hex 2)"
COMP="$OD_PROJECT_DIR/$COMP_REL"
# 2. Hole ein sofort renderbares Gerüst (hyperframes.json, meta.json, index.html mit GSAP CDN + window.__timelines.main bereits registriert). Dies läuft in Ihrer Shell – reines Dateikopieren, kein Chrome, kein Netzwerk außerhalb des npx-Caches.
npx hyperframes init "$COMP" --example blank --skip-skills --non-interactive
# 3. Bearbeite NUR $COMP/index.html – ändere `data-duration` am Root, wenn du eine andere als die Standardlänge benötigst, tausche den Platzhalter-Farbpalette in <style>, füge 1–3 Clip-<div>s für Text/Bilder hinzu und hänge die passenden GSAP-Tweens in den bestehenden `window.__timelines["main"] = gsap.timeline({paused:true})`-Block an. Halte die Änderungen minimal; das Gerüst ist bereits gültig.
# 4. Starte das Rendern über den OD-Daemon. Führe NICHT `npx hyperframes render` von dieser Shell aus – der Daemon führt es für Sie in einem nicht-sandboxierten Prozess aus. (Viele Agent-CLIs, insbesondere Claude Code, kapseln Bash in macOS sandbox-exec, unter dem Puppeteers Chrome-Subprozess während der Bildaufnahme hängen bleibt. Der Daemon-Prozess ist nicht sandboxiert, sodass Renderings zuverlässig abgeschlossen werden.)
#
# Der Dispatcher gibt innerhalb von ~1s ein {taskId} zurück; treibe das Rendern zum Abschluss, indem du "$OD_NODE_BIN" "$OD_BIN" media wait <taskId>-Aufrufe in einer Schleife ausführst.
# Jeder Aufruf long-pollt bis zu 25s (weit unter dem Standard-30s-Limit Ihres Shell-Tools) und beendet mit 0/2/5, um fertig/laufend/fehlgeschlagen zu signalisieren.
out=$("$OD_NODE_BIN" "$OD_BIN" media generate \
--project "$OD_PROJECT_ID" \
--surface video \
--model hyperframes-html \
--output "<descriptive-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=$("$OD_NODE_BIN" "$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-~30s-Limit des Agent-Shell-Tools niemals ausgelöst wird. Fortschrittszeilen von HF (Capturing frame N/M) werden während der Schleife live auf stderr gestreamt. Wenn das Rendern abgeschlossen ist, ist die letzte stdout-Zeile {"file": { "name": "<output>", "size": …, "kind": "video", … }} – zitiere file.name in deiner Antwort, damit der Benutzer weiß, was erstellt wurde.
Überspringe das Visual Identity Gate innerhalb von OD. Der HARD-GATE-Abschnitt unten (unter „Ansatz“) weist dich an, DESIGN.md / visual-style.md zu lesen oder anzuhalten 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 Design-System-Ebene – der Benutzer hat seine visuelle Richtung zum Zeitpunkt der Projekterstellung gewählt. Für einen OD-Test-Render: Standardmäßig: dunkle Leinwand (#0b0b0f), ein warmer Akzent (#ffb76b), ein kühler Akzent (#7da4ff), zurückhaltende Bewegung. Frage nur nach stilistischen Eingaben, wenn die Eingabeaufforderung des Benutzers zu vage ist, um überhaupt ein Thema zu wählen (sehr selten).
Wann das Gerüst übersprungen und von Grund auf neu geschrieben werden soll: nur, wenn der Benutzer explizit etwas verlangt, das die leere Vorlage offensichtlich nicht hosten kann (z.B. Multi-Kompositions-Timelines, audio-reaktive Overlays, Untertitel, die mit einer bereits generierten TTS-Spur synchronisiert sind). Für alles andere ist init + Bearbeitung der Standardweg.
Die leichteren HF-Unterbefehle, die du weiterhin von deiner eigenen Shell aus ausführen kannst (sie benötigen kein Chrome):
npx hyperframes lint "$COMP"– Komposition vor dem Versand validierennpx hyperframes transcribe <audio>– Untertitel generierennpx hyperframes tts <text>– Erzählung generieren
Reserviere den Daemon-Dispatcher für render/inspect/preview (alles, was Chrome benötigt).
Rufe NICHT "$OD_NODE_BIN" "$OD_BIN" 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 Projektstamm ab; OD‘s Dateiauflistung scannt rekursiv und der Benutzer würde drei unzusammenhängende Dateien im Chat sehen.
Für CLI-Optionen jenseits von render (lint, preview, transcribe, tts, inspect, benchmark) rufe sie direkt von deinem Shell-Tool auf, wenn die Aufgabe es erfordert (z.B. generiere TTS-Audio in den Cache, bevor du es in der Komposition referenzierst).
Ansatz
Bevor du HTML schreibst, denke auf hohem Niveau:
- Was – was soll der Betrachter erleben? Identifiziere den narrativen Bogen, Schlüsselmomente und emotionale Schläge.
- Struktur – wie viele Kompositionen, welche sind Unterkompositionen vs. Inline, welche Spuren tragen was (Video, Audio, Overlays, Untertitel).
- Timing – welche Clips treiben die Dauer, wo landen Übergänge, wie ist das Tempo.
- Layout – erstelle den Endzustand zuerst. Siehe „Layout vor Animation“ unten.
- Animieren – füge dann Bewegung unter Verwendung der Regeln unten hinzu.
Für kleine Bearbeitungen (Farbe korrigieren, Timing anpassen, ein Element hinzufügen) gehe direkt zu den Regeln.
Visual Identity Gate
Überprüfe in dieser Reihenfolge:
- DESIGN.md existiert im Projekt? → Lies es. Verwende seine exakten Farben, Schriftarten, Bewegungsregeln und „Was NICHT zu tun ist“-Einschränkungen.
- visual-style.md existiert? → Lies es. Wende seine
style_prompt_fullund strukturierten Felder an. (Hinweis:visual-style.mdist eine projektspezifische Datei.visual-styles.mdist die Stilbibliothek mit 8 benannten Voreinstellungen – andere 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). - Nichts davon? → Stelle 3 Fragen, bevor du HTML schreibst:
- Welche Stimmung? (explosiv / filmisch / fließend / technisch / chaotisch / warm)
- Helle oder dunkle Leinwand?
- Irgendwelche spezifischen Markenfarben, Schriftarten oder visuellen Referenzen? Generiere dann aus den Antworten eine minimale DESIGN.md.
Jede Komposition muss ihre Farbpalette und Typografie auf eine DESIGN.md, visual-style.md oder explizite Benutzeranweisung zurückführen. Wenn du nach #333, #3b82f6 oder Roboto greifst – du hast diesen Schritt übersprungen.
Für Bewegungsstandards, Größenanpassung, Eintrittsmuster und Easing – folge house-style.md. Der Haus-Stil regelt WIE sich Dinge bewegen. Die DESIGN.md regelt WIE Dinge aussehen.
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 austretend ist. Schreibe dies zuerst als statisches HTML+CSS. Noch kein GSAP.
Warum das wichtig ist: Wenn du Elemente in 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 drücken – 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 Dekorationselemente. - Füge Eintritte mit
gsap.from()hinzu – animiere VON außerhalb/unsichtbar ZUR CSS-Position. Die CSS-Position ist die Grundwahrheit; der Tween beschreibt die Reise, um dorthin zu gelangen. - Füge Austritte mit
gsap.to()hinzu – animiere ZU außerhalb/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 Maße 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 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 nebeneinander existieren – aber wenn du den Layout-Schritt überspringst, wirst du den Fall nicht abfangen, in dem sie aufgrund eines Timing-Fehlers versehentlich überlappen.
Was als absichtliche Überlappung gilt
Überlagerte Effekte (Glühen hinter Text, Schattenelemente, Hintergrundmuster) und Z-Stapel-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 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/comp | Sekunden. Video/Audio standardmäßig auf Mediendauer. |
data-track-index | Ja | Ganzzahl. Clips auf 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 (root-Komposition: verwende „0“) |
data-duration | Ja | Hat Vorrang vor GSAP-Timeline-Dauer |
data-width / data-height | Ja | Pixelmaße (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 Haupt-index.html) verwenden KEIN <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 unterbricht das Rendern.
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"] {
/* 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 Root: <div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="4"></div>