Communitygithub.com

HyperFrames CLI

Entwickler-Workflow für die HyperFrames-CLI. Verwende dies beim Ausführen von npx hyperframes init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, render, publish, cloud, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts oder remove-background (deprecated Aliase für validate/inspect/layout werden von check abgedeckt) oder bei der Fehlerbehebung in der HyperFrames-Build-/Render-Umgebung. Einstiegspunkt für HeyGen-gehostetes Cloud-Rendering (`hyperframes cloud render / list / get / delete`) und selbstverwaltetes AWS Lambda Rendering (`hyperframes lambda deploy / render / progress / destroy / policies / sites`).

Was ist HyperFrames CLI?

Die HyperFrames CLI ist das zentrale Werkzeug für Entwickler, die mit HyperFrames Video-Compositionen erstellen, rendern und bereitstellen. Sie bietet eine vollständige Kommandozeilen-Schnittstelle für den gesamten Workflow: vom Initialisieren eines Projekts (mit `npx hyperframes init my-video`) über das Schreiben und Linten von HTML-Compositionen (`hyperframes lint`), das Überprüfen auf visuelle und logische Fehler (`hyperframes check`) bis hin zum Vorschauen und Editieren im Studio-Editor (`hyperframes preview`). Der Render-Schritt unterstützt mehrere Varianten: lokales Rendering mit FFmpeg/Chrome (`render`), Cloud-Rendering ohne Infrastruktur über HeyGen (`cloud render`) und verteiltes Rendering auf der eigenen AWS Lambda (`lambda render`). Die CLI enthält umfangreiche Agent-Konventionen für CI/CD-Pipelines, wie JSON-Ausgabe, nicht-interaktiven Modus, CI-Prüfungen mittels `--strict`-Flags und ein Feedback-System (`hyperframes feedback`), um Qualität und Nutzererfahrung zu verbessern. Besonders hervorzuheben ist die Unterstützung für parametrisierte Vorlagen-Renderings mit `--variables`, die Wiederverwendbarkeit durch Asset-IDs in der Cloud und die Integration von Farbkorrektur- und Motion-Verifizierungs-Tools.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sansayan01/finance_app_zo/tree/HEAD/.agents/skills/hyperframes-cli

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht HyperFrames CLI?

Alles läuft über npx hyperframes, sofern die Projektanweisungen keinen lokalen Wrapper vorgeben. Befolge den lokalen Wrapper genau. Erfordert Node.js >= 22 und FFmpeg.

Workflow

  1. Scaffold — npx hyperframes init my-video (oder capture von einer URL). init prüft auch die installierten Skills gegen die aktuellsten auf GitHub und aktualisiert den globalen Satz, falls welche veraltet sind. Das Flag --skip-skills ist vorübergehend deaktiviert (während das skills.sh-Register aufholt), sodass jeder init-Aufruf diese Prüfung durchführt und unsere neuesten Skills unabhängig davon lädt.
  2. Schreiben — HTML-Composition verfassen (siehe Skill hyperframes-core)
  3. Linten — npx hyperframes lint (statisch, schnell — frühzeitig während der Iteration ausführen)
  4. Prüfen — npx hyperframes check (der Browser-Gateway; mit --snapshots für annotierte Frames + Zuschnitte pro Befund)
  5. Vorschau / Bearbeiten — npx hyperframes preview öffnet Studio, den Timeline-Editor, in dem der Benutzer alles manuell bearbeiten kann (nicht nur ansehen). Dort prüfen, dann vor dem Rendern fragen.
  6. Rendern — die Variante wählen:
    • Iterieren: npx hyperframes render --quality draft
    • Liefern: npx hyperframes render --quality high --output out.mp4
    • CI / plattformübergreifende Reproduktion: npx hyperframes render --docker --strict --output out.mp4
    • Cloud, ohne Infrastruktur: npx hyperframes cloud render (HeyGen hostet das Rendern; kein lokales Chrome/FFmpeg/AWS, siehe Cloud unten)
    • Cloud, mit eigener AWS: npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait (siehe Lambda unten)
  7. Feedback melden — nach Überprüfung der Ausgabe einmal pro Aufgabe npx hyperframes feedback --rating <1-5> --comment "..." ausführen (siehe Agenten-Konventionen).

Führe check vor der Vorschau aus. Es führt zuerst den Linter aus (und überspringt den Browser komplett bei Lint-Fehlern) und erledigt dann alles, was die alte Sequenz validate → inspect → snapshot in einer Browser-Sitzung und einem Suchdurchlauf tat: Runtime-Konsolenfehler und fehlgeschlagene Anfragen, Layout-Fehler (Text, der aus Blasen/Containern oder der Leinwand läuft, überlappte Halte, Verdeckungen), Motion-Sidecar-Verifikation (*.motion.json — Eingänge unter Suche, Staffelungsreihenfolge, im Bild, Lebendigkeit) und WCAG-Kontrast. Kontrastfehler sind Fehler und enthalten die gemessenen Vorder-/Hintergrundfarben, das gemessene vs. erforderliche Verhältnis und eine vorgeschlagene konforme Farbe, sodass die meisten Kontrastkorrekturen keinen Screenshot benötigen. Jeder Befund enthält einen Selektor, data-*-Identität, Composition-Quelldatei, Bounding-Box und Zeitstempel — springe direkt zum HTML. Einzelabtastungen werden zu Info herabgestuft; Befunde, die über Abtastungen hinweg bestehen bleiben, setzen den Exit-Code (bei --strict auch Warnungen). validate, inspect und layout funktionieren noch, sind aber deprecated Aliase von Teilen von check.

Bei bewegungsintensiven Arbeiten bevorzugst du eine snapshot-getriebene Iteration und einen *.motion.json-Sidecar — siehe references/lint-validate-inspect.md für die Disziplin und die Bewegungsverifikationsspezifikation. Um agentenverfasste Kandidatenvarianten zu vergleichen, verwende npx hyperframes compare <pfad...> [--at <sek>] [--labels a,b,c] [--out compare.png] [--cols n] [--json], um jede Composition durch ihre eigene Laufzeit zu rendern, ein beschriftetes Blatt zusammenzustellen, es Seite an Seite zu inspizieren und auszuwählen. Für die Farbkorrekturauswahl verwende den farbspezifischen verwandten Befehl npx hyperframes grade-compare --for <frame> --grades grades.json (oder --luts a.cube,b.cube), um jeden Grading-Kandidaten durch die echte WebGL-Grading-Laufzeit in ein beschriftetes PNG zu rendern, bevor der Gewinner ausgewählt wird.

Agenten-Konventionen

Übergreifende Regeln, die für jeden Befehl gelten:

  • --json ist bei jedem Befehl außer render, preview und play-Server-Modi verfügbar. Verwende es für jede Agenten- / CI-Aufrufe der unterstützten Befehle; die Ausgabe enthält einen _meta-Umschlag (CLI-Version, neueste verfügbare, Update-Hinweis). render meldet den Status nur über stdout + Exit-Code — überprüfe den Erfolg mit der Post-Render-Prüfung unten. preview --selection --json und preview --context --json sind die Preview-Ausnahmen: Sie starten keinen Server, sondern fragen die laufende Studio-Sitzung des Benutzers ab und beenden sich.
  • doctor --json wird immer mit Exit-Code 0 beendet, selbst wenn die Umgebung defekt ist. Prüfe das ok-Feld der Nutzlast: npx hyperframes doctor --json | jq -e '.ok' > /dev/null. Dies schützt Pipelines vor CLI-Versionswechseln.
  • Nicht-TTY-Modus wird automatisch erkannt. Wenn stdout kein TTY ist (CI, Agents, gepipete Ausgabe) schaltet die CLI automatisch auf nicht-interaktiv um; init erfordert dann --example. Übergib --non-interactive, um diesen Modus auch auf einem TTY zu erzwingen.
  • CI-Gating beim Rendern: --strict schlägt bei Lint-Fehlern fehl, --strict-all auch bei Warnungen, --strict-variables bei nicht deklarierten --variables-Schlüsseln.
  • Korreliere eine Verifizierungsschleife mit HYPERFRAMES_RUN_ID. Orchestratoren, die die CLI pro Aufgabe/Design-Element steuern, sollten diese Umgebungsvariable einmal pro Arbeitseinheit setzen; jeder Befehlsaufruf hängt sie an die Telemetrie an, und check gibt eine Aufschlüsselung pro Gate aus, was Roundtrips pro Aufgabe messbar macht.
  • Pfade in --json werden geschwärzt — $HOME wird zum wörtlichen $HOME, sodass die Ausgabe sicher in Fehlerberichte und Agentenkontexte eingefügt werden kann.
  • Rendern ist benutzergesteuert. Rendern niemals automatisch, sobald die Prüfungen bestanden sind. Halte bei preview an, teile dem Benutzer mit, dass das Video in Studio bearbeitbar ist, und rendere erst, nachdem er zugestimmt hat.
  • Verwende Studio-Kontext für benutzergesteuerte Bearbeitungen. Wenn der Benutzer „dieses ausgewählte Element", „das, worauf ich geklickt habe", „aktuelle Auswahl" oder Ähnliches sagt, bitte ihn, es in Studio auszuwählen, und führe dann npx hyperframes preview --context --json --context-fields selection aus. Verwende die zurückgegebenen selection.target.hfId / selector, selection.sourceFile, selection.currentTime und selection.thumbnailUrl, um die Bearbeitung zu verankern. Wenn selection null ist und errors.selection.code no-selection ist, bitte den Benutzer, auf das Element zu klicken und den Befehl erneut auszuführen; rate nicht aus Screenshots.
  • Halte Studio-Kontext kompakt. preview --context --json gibt standardmäßig eine kompakte Auswahl zurück. Füge --context-fields selection, --context-fields selection,lint oder --context-fields lint hinzu, um eine Aufblähung des Agentenkontexts zu vermeiden. Verwende --context-detail full nur, wenn du umfangreiche Felder wie berechnete Styles, Inline-Styles oder Textfeld-Metadaten benötigst.
  • Post-Render-Verifizierung. Nachdem render mit Exit-Code 0 zurückgekehrt ist, bestätige, dass die Ausgabedatei existiert und eine plausible Größe hat, bevor du Erfolg meldest: [ -s "$OUTPUT" ] || echo "render produced no output". Die CLI gibt bei Erfolg ◇ <pfad> aus; bei langen Renderings prüfe zusätzlich die Dauer mit ffprobe -i "$OUTPUT" -show_format -v error.
  • Feedback nach einem erfolgreichen Rendern melden. Sobald die Ausgabe verifiziert ist, führe einmal pro Aufgabe npx hyperframes feedback --rating <1-5> --comment "..." aus, um zu melden, wie der Durchlauf verlaufen ist — 5 für sauber, niedriger bei Reibungspunkten. Füge jeden Fehler, Workaround, fehlende Funktion oder verwirrendes Verhalten, auf das du gestoßen bist, in --comment ein. Dies ist der primäre Signalskanal des Projekts; Renderings, die verstummen, lassen die Betreuer blind. Überspringe dies nur, wenn die Telemetrie deaktiviert ist oder der Benutzer abgelehnt hat.
    • Bei einem reproduzierbaren Fehler füge --file-issue hinzu — es veröffentlicht eine minimale Reproduktion des Projekts unter einer öffentlichen URL und öffnet ein vorausgefülltes GitHub-Issue mit deinem Kommentar + Umgebung. Ein Kommentar allein ermöglicht es einem Betreuer fast nie, einen Fehler zu reproduzieren; die veröffentlichte Composition macht den Bericht umsetzbar. Verweise mit --dir <projekt> auf die fehlschlagende Composition, wenn es nicht das aktuelle Verzeichnis ist.
    • Schreibe Fehlerkommentare, die ein Betreuer reproduzieren kann — eine Paraphrase, mit der er nichts anfangen kann, verschwendet den Bericht. Die CLI hängt bereits os/arch/mem/ffmpeg/CLI-Version an, also wiederhole diese nicht; verwende den Kommentar für das, was nur du gesehen hast. Füge bei einem Fehler alle zutreffenden dieser Punkte ein:
      • Exakte Fehlerzeichenfolge, wörtlich (kopiere sie, fasse nicht zusammen) — und ob der Render dennoch eine Ausgabedatei erzeugt hat, stillschweigend auf einen Fallback zurückgegriffen hat (suche nach einer [Render] … re-rendering via screenshot / falling back Logzeile) oder der Prozess ohne Fehler hart beendet wurde (Killed: 9, FATAL … heap, Target closed). „Welcher Timeout / welcher Fehlermodus" ist die nützlichste einzelne Tatsache.
      • Eine minimale Reproduktion: die kleinste Composition (oder nur das fehlerhafte Element + sein CSS), die den Fehler noch zeigt — füge sie im Kommentar ein oder nenne die Datei. Nenne den Auslöser, den du isoliert hast (z.B. „nur wenn der Textknoten font-family: 苹方 verwendet", „nur bei 4K", „nur mit einem <video>-Element").
      • Der genaue Befehl + die Flags, die du ausgeführt hast, und alle gesetzten Umgebungsvariablen (HF_* / PRODUCER_*).
      • Was ist falsch und wo: die Bildnummer oder der Zeitstempel, und der visuelle Defekt (leerer Text, schwarzer Balken unten, falsche Glyphen, eingefrorene Leinwand) im Vergleich zu deiner Erwartung. Ein Screenshot-Pfad, falls du einen gespeichert hast.
      • Wenn es nur manchmal reproduzierbar ist, sage dies und gib die Trefferquote an.

Routenplanung

Was willst du tun…Lese
Ein Projekt anlegen (init, capture, skills)references/init-and-scaffold.md
Korrektheit prüfen (lint, check, snapshot, deprecated validate/inspect)references/lint-validate-inspect.md
Vorschau oder Rendern (preview, play, render, publish)references/preview-render.md
Umgebung diagnostizieren (doctor, browser)references/doctor-browser.md
Cloud-Rendering, HeyGen-gehostet ohne Infrastruktur (cloud render / list / get / delete, auth)references/cloud.md
Cloud-Rendering auf eigener AWS Lambda (lambda deploy / sites / render / progress / destroy / policies)references/lambda.md
Parametrisieren / Vorlagen-Renderings (--variables, --variables-file, --strict-variables, --batch)references/cloud.md + hyperframes-core (variables-and-media.md)
Alles andere (info, upgrade, compositions, docs, benchmark, telemetry, Asset-Vorverarbeitung)references/upgrade-info-misc.md

Skill-übergreifende Übergaben

  • Tailwind-Projekte (init --tailwind) → verwende hyperframes-core (Tailwind-Referenz) vor dem Bearbeiten von Klassen oder Theme-Tokens.
  • Registry-Blöcke/Komponenten (hyperframes add, hyperframes catalog) → verwende hyperframes-registry für Installationspfade, Sub-Composition-Verdrahtung und Snippet-Zusammenführung.
  • Asset-Vorverarbeitung (tts, transcribe, remove-background) → verwende media-use für Stimmauswahl, Whisper-Modellregeln, Untertitel und TTS-zu-Untertitel-Kette.
  • Parametrisierte Renderings (--variables) → deklariert über data-composition-variables auf <html>; siehe hyperframes-core für das vollständige Schema.

Cloud (HeyGen-gehostetes Rendering)

hyperframes cloud render ist der infrastrukturlose Rendering-Pfad: Die CLI zippt dein Projekt, lädt es hoch, rendert es auf HeyGens Cloud und lädt das mp4 herunter. Kein Chrome, kein FFmpeg, kein AWS, und du zahlst pro Guthaben. Dies ist die Standardantwort auf „rendere dies in der Cloud"; greife nur zu Lambda, wenn du bereits AWS besitzt und verteiltes/chunked Rendern benötigst.

npx hyperframes auth login            # einmaliges Anmelden (geteilt mit der `heygen` CLI)
npx hyperframes cloud render          # zippen, hochladen, rendern, herunterladen nach renders/<id>.mp4

Häufige Flags: --composition <html>, --output <pfad>, --quality draft|standard|high, --fps, --resolution 1080p|4k, --format mp4|webm|mov, --aspect-ratio (wird automatisch aus data-width/data-height erkannt). Feuer-und-vergiss mit --no-wait + --callback-url; Wiederholungen sicher machen mit --idempotency-key "$(uuidgen)". Jobs verwalten mit cloud list / cloud get <id> / cloud delete <id>.

Der idiomatische Vorlagen-Workflow ist ein Mal hochladen, mehrfach rendern: rendere ein lokales Projekt einmal, um seine asset_id zu erhalten, und reiche es dann erneut mit verschiedenen --variables gegen dieses Asset ein (überspringt Zip + Upload). Siehe references/cloud.md für den vollständigen Flagsatz, das Authentifizierungsmodell, Webhooks und die Vorlagenschleife.

Variablen (parametrisierte / Vorlagen-Renderings)

Jeder Render (lokal, Cloud oder Lambda) kann deklarierte Vorlagenplätze zur Renderzeit füllen. Deklarationen leben auf der Composition (data-composition-variables); die CLI-Oberfläche ist:

npx hyperframes render --variables '{"title":"Q4 Recap","theme":"dark"}' --output q4.mp4
npx hyperframes render --variables-file ./vars.json --output out.mp4
npx hyperframes render --batch rows.json --output "renders/{name}.mp4" --strict-variables
npx hyperframes cloud render --asset-id asst_abc123 --variables '{"name":"Ada"}'

--strict-variables schlägt den Render bei jedem nicht deklarierten Schlüssel oder Typkonflikt fehl (verwende es in CI). --batch <rows.json> rendert eine Ausgabe pro Datenzeile mit {key}/{index}-Pfadplatzhaltern und schreibt eine manifest.json. Für das vollständige Schema (Typen deklarieren, data-var-src/data-var-text deklarative Bindungen, data-variable-values pro Instanz für Sub-Compositions und Rangfolge) verwende den Skill hyperframes-core (references/variables-and-media.md). Die Cloud-Vorlagenschleife befindet sich in references/cloud.md.

Lambda (Cloud-Rendering)

hyperframes lambda stellt verteiltes Rendering auf AWS Lambda bereit und steuert Renderings von deinem Laptop oder CI aus. End-to-End sind drei Befehle:

npx hyperframes lambda deploy                                             # SAM Stack bereitstellen (Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy                                            # abbauen (S3 Buck

[Der Inhalt wurde aus Gründen der Kürze abgeschnitten; für das vollständige Lambda-Dokument siehe references/lambda.md.]

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

sansayan01/finance_app_zo

Add captions to a talking-head video. ONE catalog (CATALOG.md) of 36 visual identities behind two engines: column-flow (captions composited INTO the scene — matte occlusion + mix-blend; cream/ink/editorial/keynote/documentary/loud/neon/glitch/chrome/velocity) and themed constitutions (anchor/ordnance/terminal/neonsign/stardust/stomp/scoreboard/transit/vhs/arcade/dossier/laser/thunder/hologram/biolume/aurora/spectrum/papercut/popup/chalkboard/graffiti/brush/inkwater/ransom/lastpage/nightcity — e.g. a glyph-decode climax, a neon sign WRITTEN stroke by stroke, or the quiet `anchor` rail default). Route by identity, never by mode. Trigger on "captions/subtitles", "embed/cinematic captions", "VFX captions", "炸/特效/酷炫字幕", a named identity, or top-tier motion-graphics asks. Embedding every word is wrong for most talking-head content — `anchor` is the verbatim default. Runs locally end-to-end (transcribes and mattes the subject itself, no API key). Requires hyperframes and a single-subject clip (multi-shot clips ar...

sansayan01/finance_app_zo

The fallback workflow for authoring or editing any custom HyperFrames composition at any length or format — longer / multi-scene pieces, brand and sizzle reels, montages, title cards, static loops, freeform builds. Use only when no specialized workflow fits the input; routing table at /hyperframes.

sansayan01/finance_app_zo

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

sansayan01/finance_app_zo

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Also covers Tailwind projects and the STORYBOARD.md / SCRIPT.md plan formats. Read before writing composition HTML.

sansayan01/finance_app_zo

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

sansayan01/finance_app_zo

Use when a HyperFrames composition needs seek-safe 2D/3D keyframes, GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth, or `hyperframes keyframes` diagnostics. Don't use for broad scene strategy, brand design, media sourcing, captions, or general video planning.

sansayan01/finance_app_zo

MicroFlow Pro - MFI Staff Portal built with Flutter & Supabase

Verwandte Skills