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
- Scaffold —
npx hyperframes init my-video(odercapturevon einer URL).initprüft auch die installierten Skills gegen die aktuellsten auf GitHub und aktualisiert den globalen Satz, falls welche veraltet sind. Das Flag--skip-skillsist vorübergehend deaktiviert (während das skills.sh-Register aufholt), sodass jederinit-Aufruf diese Prüfung durchführt und unsere neuesten Skills unabhängig davon lädt. - Schreiben — HTML-Composition verfassen (siehe Skill
hyperframes-core) - Linten —
npx hyperframes lint(statisch, schnell — frühzeitig während der Iteration ausführen) - Prüfen —
npx hyperframes check(der Browser-Gateway; mit--snapshotsfür annotierte Frames + Zuschnitte pro Befund) - 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. - 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)
- Iterieren:
- 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:
--jsonist bei jedem Befehl außerrender,previewundplay-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).rendermeldet den Status nur über stdout + Exit-Code — überprüfe den Erfolg mit der Post-Render-Prüfung unten.preview --selection --jsonundpreview --context --jsonsind die Preview-Ausnahmen: Sie starten keinen Server, sondern fragen die laufende Studio-Sitzung des Benutzers ab und beenden sich.doctor --jsonwird immer mit Exit-Code 0 beendet, selbst wenn die Umgebung defekt ist. Prüfe dasok-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
stdoutkein TTY ist (CI, Agents, gepipete Ausgabe) schaltet die CLI automatisch auf nicht-interaktiv um;initerfordert dann--example. Übergib--non-interactive, um diesen Modus auch auf einem TTY zu erzwingen. - CI-Gating beim Rendern:
--strictschlägt bei Lint-Fehlern fehl,--strict-allauch bei Warnungen,--strict-variablesbei 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, undcheckgibt eine Aufschlüsselung pro Gate aus, was Roundtrips pro Aufgabe messbar macht. - Pfade in
--jsonwerden geschwärzt —$HOMEwird 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
previewan, 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 selectionaus. Verwende die zurückgegebenenselection.target.hfId/selector,selection.sourceFile,selection.currentTimeundselection.thumbnailUrl, um die Bearbeitung zu verankern. Wennselectionnullist underrors.selection.codeno-selectionist, bitte den Benutzer, auf das Element zu klicken und den Befehl erneut auszuführen; rate nicht aus Screenshots. - Halte Studio-Kontext kompakt.
preview --context --jsongibt standardmäßig eine kompakte Auswahl zurück. Füge--context-fields selection,--context-fields selection,lintoder--context-fields linthinzu, um eine Aufblähung des Agentenkontexts zu vermeiden. Verwende--context-detail fullnur, wenn du umfangreiche Felder wie berechnete Styles, Inline-Styles oder Textfeld-Metadaten benötigst. - Post-Render-Verifizierung. Nachdem
rendermit 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 mitffprobe -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 —5für sauber, niedriger bei Reibungspunkten. Füge jeden Fehler, Workaround, fehlende Funktion oder verwirrendes Verhalten, auf das du gestoßen bist, in--commentein. 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-issuehinzu — 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 backLogzeile) 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.
- 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
- Bei einem reproduzierbaren Fehler füge
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) → verwendehyperframes-core(Tailwind-Referenz) vor dem Bearbeiten von Klassen oder Theme-Tokens. - Registry-Blöcke/Komponenten (
hyperframes add,hyperframes catalog) → verwendehyperframes-registryfür Installationspfade, Sub-Composition-Verdrahtung und Snippet-Zusammenführung. - Asset-Vorverarbeitung (
tts,transcribe,remove-background) → verwendemedia-usefür Stimmauswahl, Whisper-Modellregeln, Untertitel und TTS-zu-Untertitel-Kette. - Parametrisierte Renderings (
--variables) → deklariert überdata-composition-variablesauf<html>; siehehyperframes-corefü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.]