HyperFrames
HyperFrames ist ein HTML-zu-MP4-Renderer (Apache 2.0). Kompositionen sind einfache HTML-Dateien mit den Attributen data-start, data-duration, data-track-index; der Renderer steuert einen Headless-Chrome frame-genau durch die Timeline und leitet die Frames an FFmpeg weiter. Die Fähigkeit hyperframes-prompt-builder ist der Einstiegspunkt des Marketing-Engine-Dispatchers; diese Fähigkeit enthält die Autoren-Regeln.
Wann aufrufen
- Ein Stück wird (über
PROVIDERS.mdoder mittelsprovider_override.video: hyperframesim Frontmatter) an den HyperFrames-Provider weitergeleitet. - Die Aufgabe ist
motion-typography,data-viz-reel,programmatic-shortoder eine beliebige Komposition, die eine deterministische Ausgabe aus deklarierten Variablen benötigt (z. B. wöchentliches KPI-Reel, das mit neuen Zahlen unverändert neu gerendert wird). - Ein genehmigtes Standbild (Quote-Card, Karussell-Slide) soll ohne Änderung des typografischen Systems zu einem kurzen Bewegtbildstück aufgewertet werden.
- Der Orchestrator benötigt ein neurenderbares Artefakt: gleiche Komposition, andere
--variables, byte-identische Baseline.
Eingaben
composition_id: string. Kurzer Slug, der für das Projektverzeichnis unddata-composition-idverwendet wird.aspect:9:16|1:1|16:9|4:5.duration_seconds: integer. Gesamtlänge der Komposition.scenes: array. Jede Szene:{ id, start_s, duration_s, role: "hook" | "body" | "cta", copy?, asset_ref? }.design_tokens: object. Markenfarben, primäre/sekundäre Schriftfamilien, Abstandsskala. Stammen ausclients/<slug>/design.md, falls vorhanden.variables: array, optional. Deklarierte Parameter, die Aufrufer zur Renderzeit überschreiben können:{ id, type, label, default }.assets: object, optional.{ video?, audio?, images[] }– lokale Pfade unterhalb des Projekts.output_dir: string. Pfad, in den der Renderer die MP4 schreibt (standardmäßigoutputs/<client>/<date>/<piece-id>/).
Ablauf
- Zuerst den Markenkontext lesen. Lade
clients/<active-client>/design.md(oder die übergebenen Design-Tokens). Weigere dich, HTML zu schreiben, bevor die Tokens bekannt sind – greife nur dann auf die Repository-Standards zurück, wenn der Kunde keine hat. - Den narrativen Bogen laut planen (Szenen, Rhythmus, Übergänge, Beat), bevor das Markup geschrieben wird. Hook in den ersten 1,5 s, Body, CTA am Ende.
- Layout vor Animation. Schreibe zuerst das endgültige On-Screen-Layout – positioniere Elemente dort, wo sie enden. Animiere in diese Positionen mit
gsap.from(); nur die letzte Szene darfgsap.to()-Ausgänge verwenden. - Das HTML erstellen. Das Wurzel-
<html>trägtdata-composition-id,data-width,data-height. Jeder Clip trägtid,data-start,data-duration,data-track-index. Parametrisiere mitdata-composition-variables(JSON-Array auf<html>); zur Laufzeit mitwindow.__hyperframes.getVariables()auslesen. - Jede Timeline pausiert registrieren.
const tl = gsap.timeline({ paused: true }); window.__timelines["<id>"] = tl;– das Framework steuert die Wiedergabe. Keine Endlosschleifen, keinMath.random(), keine zeitbasierte Logik, keine asynchrone Timeline-Erstellung. - Übergänge zwischen jeder Szene. Keine harten Schnitte. Verwende die katalogisierten Übergänge (Fade, Wipe, Masked, Shader), die im übergeordneten
references/transitions.mdaufgelistet sind. - Video und Audio.
<video>muss stumm sein; Audio lebt in einem separaten<audio>-Element auf eigener Spur. - Lokal validieren mit
npx hyperframes lint, dannnpx hyperframes inspect(Textüberlauf, Container-Clipping). Nur rendern, wenn beide Tests bestanden sind. Dies wird an die Fähigkeithyperframes-clidelegiert. - Das Manifest ausgeben. Schreibe
manifest.jsonneben die MP4 mit{ composition_id, aspect, duration_seconds, variables_resolved, lint_pass, inspect_pass, render_settings }. Erforderlich durch die Definition of Done inCLAUDE.md.
Ausgaben
project_path: string. Pfad zum HyperFrames-Projektverzeichnis.composition_html: string. Der erstellteindex.html-Inhalt (oder der Pfad dorthin unterproject_path).render_args: object. Die Flags, die annpx hyperframes renderübergeben werden (--fps,--quality,--variables,--strict).expected_artifact: string. Der MP4-Pfad, der nach dem Rendern unteroutput_direrscheint.cost_estimate_usd: number. Lokales Rendern – nur Rechenzeit; melde 0 für DRY_RUN, andernfalls Schätzung aus--workers× Dauer.
Nicht verhandelbare Regeln
- Jedes Element hat eine Eingangsanimation (
gsap.from()). - Alle Timelines starten pausiert und sind unter
window.__timelinesregistriert. - Kein
Math.random(), keinDate.now()in der Kompositionslogik, kein setTimeout-gesteuertes Animieren. - Videospuren stumm; niemals Audio in
<video>einbetten. - Kunden-Kopien niemals direkt in das Markup einbauen, wenn sie eine Variable sein könnten – in
data-composition-variablesdeklarieren, damit dieselbe Komposition für neue Stücke neu gerendert werden kann. - Niemals eine gerenderte MP4 unter
outputs/bearbeiten; stattdessenhyperframes rendererneut ausführen.
Beispiele
Beispiel 1: wöchentliches KPI-Reel (programmatic-short)
Eingabe: { composition_id: "kpi-weekly-w21", aspect: "9:16", duration_seconds: 12, scenes: [{ id: "hook", start_s: 0, duration_s: 2, role: "hook", copy: "Semana 21" }, { id: "metric", start_s: 2, duration_s: 8, role: "body" }, { id: "cta", start_s: 10, duration_s: 2, role: "cta", copy: "Veja o detalhamento" }], variables: [{ id: "leads", type: "number", label: "Novos leads", default: 0 }, { id: "delta_pct", type: "number", label: "Variação %", default: 0 }] }
Ausgabe: ein Projekt unter outputs/<client>/<date>/kpi-weekly-w21/, dessen index.html die beiden numerischen Variablen ausliest und animiert; render_args.--variables löst sie pro Stück auf.
Beispiel 2: Motion-Quote-Card (motion-typography)
Eingabe: { composition_id: "quote-marcos-2026-05", aspect: "1:1", duration_seconds: 6, scenes: [{ id: "main", start_s: 0, duration_s: 6, role: "body", copy: "Coloque a sua marca onde os olhos já estão." }] }
Ausgabe: eine kinetische Typografie-Komposition, die die Typografie-Paarung des aktiven Kunden respektiert, mit maskiertem Texteingang und sanftem Halten des letzten Frames.
Fehlermodi
- Fehlende
design.mdund keine Design-Tokens übergeben: anhalten und nachfragen. Keine Farbpalette erfinden. npx hyperframes lintmeldet Fehler (fehlendesdata-composition-id, überlappende Spuren, nicht registrierte Timelines): Render blockieren, bis behoben.npx hyperframes inspectmeldet Textüberlauf in einer Szene: Layout umfließen dem Verkleinern der Schrift unter das Systemminimum vorziehen.- Audiospur länger als die
duration_secondsder Komposition: Audio trimmen, niemalsduration_secondsverlängern, um es anzupassen. - Komposition verwendet
Math.random()oder Wanduhrzeit: vor dem Render in eine deklarierte Variable oder einen gesäten deterministischen Generator umwandeln.
Verwandte Fähigkeiten
hyperframes-cli: lint-, inspect-, preview-, render-Befehle. Wird immer nach dem Authoring aufgerufen.hyperframes-prompt-builder: Marketing-Engine-Spezialist, der eine Stück-Briefing in die von dieser Fähigkeit erwartete Eingabeform übersetzt; aufgerufen vonvideo-prompt-builder, wenn die Matrix aufhyperframesauflöst.video-prompt-builder: generischer Dispatcher.qa-tech-specs: Validiert die gerenderte MP4 gegen Plattform-Spezifikationen (Seitenverhältnis, Dauer, Safe Areas).compliance-<active client>: Läuft nach dem Rendern gegen das gerenderte Artefakt und die aus den Variablen aufgelöste On-Screen-Kopie.
Referenz zum übergeordneten Skill
Kompletter übergeordneter Skill (Kompositionsmuster, Übergangskatalog, Audio-Reaktivität, Untertitel, Data-in-Motion): https://github.com/wesleysimplicio/hyperframes/tree/main/skills/hyperframes