HyperFrames CLI
Alles läuft über npx hyperframes, sofern die Projektanweisungen keinen lokalen Wrapper vorgeben. Halten Sie sich genau an den lokalen Wrapper. Erfordert Node.js >= 22 und FFmpeg.
Workflow
- Scaffold —
npx hyperframes init my-video(odercapturevon einer URL) - Schreiben — HTML-Komposition verfassen (siehe Skill
hyperframes-core) - Lint —
npx hyperframes lint - Validieren —
npx hyperframes validate(Laufzeitfehler + Kontrast) - Visuelle Inspektion —
npx hyperframes inspect - Vorschau —
npx hyperframes preview - Rendern — Variante wählen:
- Iterieren:
npx hyperframes render --quality draft - Ausliefern:
npx hyperframes render --quality high --output out.mp4 - CI / plattformübergreifende Reproduktion:
npx hyperframes render --docker --strict --output out.mp4 - Cloud (lang / groß):
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait(siehe Lambda unten)
- Iterieren:
Führen Sie lint, validate und inspect vor preview aus. lint erkennt fehlende data-composition-id, überlappende Tracks und nicht registrierte Timelines. validate lädt die Komposition in Headless Chrome und meldet Laufzeit-Konsolenfehler sowie WCAG-Kontrastprobleme. inspect durchsucht die Timeline und meldet Text, der aus Blasen/Containern oder über die Leinwand hinausläuft – und, wenn eine *.motion.json-Beilage vorhanden ist, wird die Bewegungsabsicht (Entrances, die beim Seek feuern, Stagger-Reihenfolge, im Frame, Lebendigkeit) anhand derselben durchsuchten Timeline überprüft.
Bei bewegungsintensiven Arbeiten bevorzugen Sie snapshot-gesteuerte Iterationen und eine *.motion.json-Beilage – siehe references/lint-validate-inspect.md für die Disziplin und die Spezifikation der Bewegungsüberprüfung.
Agentenkonventionen
Übergreifende Regeln, die für jeden Befehl gelten:
--jsonist bei jedem Befehl verfügbar außerrender,previewundplay. Verwenden Sie es für jeden Agenten-/CI-Aufruf der unterstützten Befehle; die Ausgabe enthält einen_meta-Umschlag (CLI-Version, neueste verfügbare Version, Update-Hinweis).rendermeldet den Status nur über stdout + Exit-Code – überprüfen Sie den Erfolg mit der Post-Render-Prüfung unten;preview/playsind Server, kein JSON.doctor --jsonbeendet sich immer mit 0, selbst wenn die Umgebung defekt ist. Entscheiden Sie anhand desok-Felds im Payload:npx hyperframes doctor --json | jq -e '.ok' > /dev/null. Dies schützt Pipelines vor CLI-Release-Änderungen.- Nicht-TTY-Modus wird automatisch erkannt. Wenn
stdoutkein TTY ist (CI, Agenten, gepipte Ausgabe), schaltet die CLI automatisch auf nicht-interaktiv um;initerfordert dann--example. Übergeben Sie--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-variablesschlägt bei nicht deklarierten--variables-Schlüsseln fehl. - Pfade in
--jsonwerden redigiert –$HOMEwird zum literalen$HOME, sodass die Ausgabe sicher in Fehlerberichte und Agentenkontexte eingefügt werden kann. - Post-Render-Überprüfung. Nachdem
rendermit Exit 0 zurückgekehrt ist, bestätigen Sie, dass die Ausgabedatei existiert und eine plausible Größe hat, bevor Sie den Erfolg melden:[ -s "$OUTPUT" ] || echo "render produced no output". Die CLI gibt bei Erfolg◇ <path>aus; bei langen Renderings überprüfen Sie zusätzlich die Dauer mitffprobe -i "$OUTPUT" -show_format -v error.
Routing
| Wenn Sie … | Lesen Sie |
|---|---|
Ein Projekt scafolden möchten (init, capture, skills) | references/init-and-scaffold.md |
Korrektheit prüfen möchten (lint, validate, inspect, snapshot) | references/lint-validate-inspect.md |
Vorschauen oder rendern möchten (preview, play, render, publish) | references/preview-render.md |
Die Umgebung diagnostizieren möchten (doctor, browser) | references/doctor-browser.md |
Cloud-Rendering auf AWS Lambda möchten (lambda deploy / sites / render / progress / destroy / policies) | references/lambda.md |
Alles andere (info, upgrade, compositions, docs, benchmark, telemetry, Asset-Vorverarbeitung) | references/upgrade-info-misc.md |
Skill-übergreifende Übergaben
- Tailwind-Projekte (
init --tailwind) → verwenden Siehyperframes-core(Tailwind-Referenz), bevor Sie Klassen oder Theme-Tokens bearbeiten. - Registry-Blöcke/-Komponenten (
hyperframes add,hyperframes catalog) → verwenden Siehyperframes-registryfür Installationspfade, Sub-Kompositionsverdrahtung und Snippet-Zusammenführung. - Asset-Vorverarbeitung (
tts,transcribe,remove-background) → verwenden Siehyperframes-mediafür Sprachauswahl, Whisper-Modellregeln, Untertitel und TTS-zu-Untertitel-Kette. - Parametrisierte Renderings (
--variables) → deklariert überdata-composition-variablesauf<html>; vollständiges Schema siehehyperframes-core.
Lambda (Cloud-Rendering)
hyperframes lambda stellt verteiltes Rendering auf AWS Lambda bereit und steuert Renderings von Ihrem Laptop oder CI aus. End-to-End in drei Befehlen:
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 # Abbau (S3-Bucket bleibt erhalten)
Verwenden Sie Lambda, wenn ein Rendering zu lang / zu groß für einen einzelnen Host ist (mehrminütige Videos, 4K, große parallele Batches) und Sie AWS-Anmeldedaten konfiguriert haben. Für die Entwicklungsschleife bleiben Sie beim lokalen render.
Siehe references/lambda.md für Voraussetzungen, alle 6 Unterbefehle (deploy, sites create, render, progress, destroy, policies), IAM-Richtlinienvalidierung, Zustandsdateien und Kosten-/Bereinigungsregeln.
Minimales Abschluss-Gate
Statische Gates
npx hyperframes lint
npx hyperframes validate
Fügen Sie inspect für layoutempfindliche Arbeiten und render --strict in CI hinzu, um bei Lint-Fehlern fehlzuschlagen.
Visueller Rauchtest – erforderlich, wenn das Projekt Sub-Kompositionen verwendet
lint / validate / inspect werten jede Komposition isoliert aus. Sie laden niemals index.html und montieren Sub-Kompositionen über data-composition-src, daher können sie keine dateiübergreifenden Mount-Fehler abfangen (siehe hyperframes-core → references/sub-compositions.md, „Häufige Fallstricke“). Das einzige Gate, das sie abfängt, lädt tatsächlich index.html und sucht die Timeline.
Verwenden Sie hyperframes snapshot – es lädt das Projekt genauso wie render (übt also denselben Mount-Pfad aus), erfasst aber nur die von Ihnen angeforderten Zeitstempel, sodass es Sekunden statt eines vollständigen Renderings dauert:
# Einzelnes Bild am Mittelpunkt jeder Sub-Komposition erfassen.
# Mittelpunkte = data-start + data-duration/2 für jeden Host-Slot in index.html.
npx hyperframes snapshot --at <t1>,<t2>,<t3>,...
# Oder, falls keine zielszenenspezifische Ansteuerung nötig ist, eine gleichmäßig verteilte Stichprobe:
npx hyperframes snapshot --frames 9
Die Ausgabe landen in snapshots/frame-NN-at-Xs.png. Überprüfen Sie jedes Bild auf den Szenenplan.
Bild-für-Bild-Warnsignale (jedes entspricht einem bestimmten Fehlermodus, den die statischen Gates nicht abfangen):
| Was Sie sehen | Grundursache |
|---|---|
| Text erscheint winzig + ohne Styling in der oberen linken Ecke | <style>-Block blieb in <head> außerhalb von <template> (Fallstrick 1) – kein CSS erreichte das Live-DOM |
| SVG/Icon-Elemente auf Leinwandgröße aufgeblasen | Gleiches wie oben – keine width/height-Beschränkungen angewendet |
| Hero-Element der Szene fehlt vollständig; nur Hintergrund + Wasserzeichen sichtbar | Host-ID ≠ Template-ID (Fallstrick 2) – Timeline lief nie, Bild zum Anfangszeitpunkt erfasst |
Snapshot-Befehl protokolliert Sub-composition timelines not registered after 45000ms | Fallstrick 2 – direkte Bestätigung |
snapshots/ kann nach der Sichtprüfung gelöscht werden; der endgültige, benutzersichtige Render ist ein separater Durchlauf mit npx hyperframes render.