HyperFrames CLI
Alles läuft über npx hyperframes, sofern die Projektanweisungen keinen lokalen Wrapper vorgeben. Halte dich genau an den lokalen Wrapper. Erfordert Node.js >= 22 und FFmpeg.
Arbeitsablauf
- Scaffold —
npx hyperframes init my-video(odercapturevon einer URL) - Schreiben — HTML-Composition authoring (siehe Skill
hyperframes-core) - Lint —
npx hyperframes lint - Validieren —
npx hyperframes validate(Laufzeitfehler + Kontrast) - Visuelle Inspektion —
npx hyperframes inspect - Vorschau —
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 nachfragen. - 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ühre lint, validate und inspect vor der Vorschau aus. lint erkennt fehlende data-composition-id, überlappende Tracks und nicht registrierte Timelines. validate lädt die Composition in headless Chrome und meldet Laufzeit-Fehler in der Konsole sowie WCAG-Kontrastprobleme. inspect durchsucht die Timeline und meldet Text, der aus Blasen/Containern herausläuft oder über die Leinwand hinausgeht – und, wenn ein *.motion.json-Sidecar vorhanden ist, überprüft es die Bewegungsabsicht (Eingänge, die beim Suchen auslösen, Stagger-Reihenfolge, im Bild, Lebendigkeit) gegen dieselbe durchsuchte Timeline.
Für bewegungsintensive Arbeit bevorzuge Snapshot-basierte Iteration und ein *.motion.json-Sidecar – siehe references/lint-validate-inspect.md für die Disziplin und die Spezifikation zur Bewegungsüberprüfung.
Agenten-Konventionen
Übergreifende Regeln, die für jeden Befehl gelten:
--jsonist bei jedem Befehl außerrender,previewundplayverfügbar. Verwende es für jede Agenten-/CI-Invokation der unterstützten Befehle; die Ausgabe enthält einen_meta-Umschlag (CLI-Version, letzte verfügbare Version, Update-Hinweis).rendermeldet den Status nur über stdout + Exit-Code – überprüfe den Erfolg mit der untenstehenden Prüfung nach dem Rendern;preview/playsind Server, kein JSON.doctor --jsonbeendet sich immer mit 0, auch wenn die Umgebung defekt ist. Prüfe dasok-Feld des Payloads:npx hyperframes doctor --json | jq -e '.ok' > /dev/null. Dies schützt Pipelines vor CLI-Versionsänderungen.- Nicht-TTY-Modus wird automatisch erkannt. Wenn
stdoutkein TTY ist (CI, Agenten, gepipte Ausgabe) wechselt die CLI automatisch in den nicht-interaktiven Modus;initerfordert dann--example. Verwende--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. - Pfade in
--jsonwerden redigiert –$HOMEwird zum wörtlichen$HOME, sodass die Ausgabe sicher in Fehlerberichte und Agenten-Kontexte eingefügt werden kann. - Das Rendern wird durch den Benutzer freigegeben. Starte niemals automatisch das Rendern, sobald die Prüfungen bestanden sind. Halte bei
previewan, teile dem Benutzer mit, dass das Video in Studio bearbeitet werden kann, und rendere erst nach seiner Zustimmung. - Überprüfung nach dem Rendern. Nachdem
rendermit Exit-Code 0 beendet wurde, bestätige, dass die Ausgabedatei existiert und eine plausible Größe hat, bevor der Erfolg gemeldet wird:[ -s "$OUTPUT" ] || echo "render produced no output". Die CLI gibt bei Erfolg◇ <Pfad>aus; bei langen Renderings überprüfe zusätzlich die Dauer mitffprobe -i "$OUTPUT" -show_format -v error.
Weiterleitung
| Was möchtest du tun… | Lese |
|---|---|
Ein Projekt erstellen (init, capture, skills) | references/init-and-scaffold.md |
Korrektheit prüfen (lint, validate, inspect, snapshot) | references/lint-validate-inspect.md |
Vorschau oder Rendern (preview, play, render, publish) | references/preview-render.md |
Umgebung diagnosticieren (doctor, browser) | references/doctor-browser.md |
Cloud-Rendering auf AWS Lambda (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-Übergaben
- Tailwind-Projekte (
init --tailwind) → verwendehyperframes-core(Tailwind-Referenz), bevor du Klassen oder Theme-Token bearbeitest. - Registry-Blöcke/Komponenten (
hyperframes add,hyperframes catalog) → verwendehyperframes-registryfür Installationspfade, Sub-Composition-Verkabelung und Snippet-Zusammenführung. - Asset-Vorverarbeitung (
tts,transcribe,remove-background) → verwendehyperframes-mediafür Sprachauswahl, Whisper-Modellregeln, Untertitel und TTS-zu-Untertitel-Kette. - Parametrisierte Renderings (
--variables) → deklariert überdata-composition-variablesauf<html>; siehehyperframes-corefür das vollständige Schema.
Lambda (Cloud-Rendering)
hyperframes lambda stellt verteiltes Rendering auf AWS Lambda bereit und steuert Renderings von deinem Laptop oder CI aus. Der vollständige Ablauf umfasst 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-Bucket bleibt erhalten)
Verwende Lambda, wenn ein Rendering zu lang / zu groß für einen Host ist (mehrminütige Videos, 4K, große parallele Batches) und AWS-Anmeldeinformationen konfiguriert sind. Für den Entwicklungsloop bleibe 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üge inspect für layout-sensible Arbeiten und render --strict in CI hinzu, um bei Lint-Fehlern zu scheitern.
Visueller Rauchtest – erforderlich, wenn das Projekt Sub-Compositions verwendet
lint / validate / inspect bewerten jede Composition isoliert. Sie laden niemals index.html und hängen Sub-Compositions über data-composition-src ein, daher können sie keine geräteübergreifenden Mount-Fehler erkennen (siehe hyperframes-core → references/sub-compositions.md, „Häufige Fallstricke“). Das einzige Gate, das sie erkennt, ist eines, das tatsächlich index.html lädt und die Timeline durchsucht.
Verwende hyperframes snapshot – es lädt das Projekt auf die gleiche Weise wie render (übt also den gleichen Mount-Pfad), erfasst aber nur die von dir angeforderten Zeitstempel, sodass es Sekunden statt eines vollständigen Renderings dauert:
# Erfasse einen Frame in der Mitte jeder Sub-Composition.
# Mittelpunkte = data-start + data-duration/2 für jeden Host-Slot in index.html.
npx hyperframes snapshot --at <t1>,<t2>,<t3>,...
# Oder, wenn keine Szenen-fokussierte Auswahl nötig ist, eine gleichmäßig verteilte Stichprobe:
npx hyperframes snapshot --frames 9
Die Ausgabe landet in snapshots/frame-NN-at-Xs.png. Überprüfe jeden Frame visuell anhand des Szenenplans.
Pro-Frame-Warnsignale (jedes zeigt auf einen bestimmten Fehlermodus, den die statischen Gates übersehen):
| Was du siehst | Ursache |
|---|---|
| Text erscheint winzig + ungestylt in der oberen linken Ecke | <style>-Block blieb im <head> außerhalb von <template> (Fallstrick 1) – kein CSS erreichte das Live-DOM |
| SVG/Icon-Elemente auf Leinwandgröße aufgeblasen | Gleiche Ursache wie oben – keine Breiten-/Höhenbeschränkungen angewendet |
| Hero-Element der Szene fehlt vollständig; nur Hintergrund + Wasserzeichen sichtbar | Host-id ≠ Template-id (Fallstrick 2) – Timeline wurde nie ausgeführt, Frame im Anfangszustand erfasst |
Snapshot-Befehl protokolliert Sub-composition timelines not registered after 45000ms | Fallstrick 2 – direkte Bestätigung |
snapshots/ kann nach dem visuellen Überprüfen gelöscht werden; das endgültige, benutzerseitige Rendering erfolgt in einem separaten Durchlauf mit npx hyperframes render.