HyperFrames CLI
Alles läuft über npx hyperframes – es sei denn, die Projektanweisungen geben einen lokalen Wrapper vor. Befolge den lokalen Wrapper genau. Erfordert Node.js >= 22 und FFmpeg.
Arbeitsablauf
- Gerüst erstellen —
npx hyperframes init my-video(odercapturevon einer URL) - Schreiben — HTML-Komposition verfassen (siehe das Skill
hyperframes-core) - Prüfen —
npx hyperframes lint - Validieren —
npx hyperframes validate(Laufzeitfehler + Kontrast) - Visuell inspizieren —
npx hyperframes inspect - Vorschau —
npx hyperframes previewöffnet Studio, den Timeline-Editor, in dem die Benutzer*in alles manuell bearbeiten kann (nicht nur ansehen). Dort prüfen, dann vor dem Rendern fragen. - Rendern — die Variante auswä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 Komposition in einem Headless-Chrome und meldet Laufzeit-Konsolenfehler sowie WCAG-Kontrastprobleme. inspect durchsucht die Timeline und meldet Text, der aus Blasen/Containern oder der Leinwand überläuft – und, wenn eine *.motion.json-Beilage vorhanden ist, überprüft es die Bewegungsabsicht (Eingänge feuern unter Suche, Staffelreihenfolge, im Rahmen, Lebendigkeit) gegen dieselbe durchsuchte Timeline.
Bei bewegungsintensiver Arbeit sind Snapshot-gesteuerte Iteration und eine *.motion.json-Beilage zu bevorzugen – 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 für jeden Befehl verfügbar, außerrender,previewundplay. Verwende es für jeden Agenten-/CI-Aufruf der unterstützten Befehle; die Ausgabe enthält einen_meta-Umschlag (CLI-Version, neueste verfügbare Version, Aktualisierungshinweise).rendermeldet den Status nur über stdout + Exit-Code – überprüfe 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. Prüfe auf dasok-Feld der Nutzlast: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, weitergeleitete Ausgabe) schaltet die CLI automatisch in den nicht-interaktiven Modus 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-variablesschlägt bei nicht deklarierten--variables-Schlüsseln fehl. - Pfade in
--jsonwerden redigiert –$HOMEwird zum wörtlichen$HOME, sodass die Ausgabe sicher in Fehlerberichte und Agenten-Kontexte eingefügt werden kann. - Rendern ist benutzergesteuert. Rendere nie automatisch, sobald die Prüfungen bestanden sind. Halte bei
previewan, teile der Benutzer*in mit, dass das Video in Studio bearbeitet werden kann, und rendere erst, nachdem sie es genehmigt hat. - Post-Render-Überprüfung. Nachdem
rendermit Exit-Code 0 beendet wurde, bestätige, dass die Ausgabedatei existiert und eine plausible Größe hat, bevor du den Erfolg meldest:[ -s "$OUTPUT" ] || echo "render produced no output". Die CLI gibt bei Erfolg◇ <path>aus; bei langen Rendern überprüfe zusätzlich die Dauer mitffprobe -i "$OUTPUT" -show_format -v error.
Routing
| Gewünschte Aktion | Lese |
|---|---|
Ein Projekt einrichten (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 |
Diagnose der Umgebung (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-ü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-Verkabelung und Snippet-Zusammenführung. - Asset-Vorverarbeitung (
tts,transcribe,remove-background) → verwendehyperframes-mediafür Sprachauswahl, Whisper-Modellregeln, Untertitel und TTS-zu-Untertitel-Kette. - Parametrisierte Render-Vorgänge (
--variables) → deklariert viadata-composition-variablesauf<html>; siehehyperframes-corefür das vollständige Schema.
Lambda (Cloud-Rendering)
hyperframes lambda stellt verteiltes Rendering auf AWS Lambda bereit und steuert Render-Vorgänge von deinem Laptop oder von CI aus. Der End-to-End-Prozess besteht aus 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 # abbauen (S3-Bucket bleibt erhalten)
Verwende Lambda, wenn ein Render-Vorgang zu lang / zu groß für einen einzelnen Host ist (mehrminütige Videos, 4K, große parallele Batches) und du AWS-Anmeldedaten konfiguriert hast. Für den Entwicklungs-Loop bleibe beim lokalen render.
Siehe references/lambda.md für Voraussetzungen, alle 6 Unterbefehle (deploy, sites create, render, progress, destroy, policies), IAM-Richtlinienvalidierung, Zustandsdateien sowie Kosten-/Bereinigungsregeln.
Mindestabschluss-Schranke
Statische Schranken
npx hyperframes lint
npx hyperframes validate
Füge inspect für layoutkritische Arbeiten und render --strict in CI hinzu, um bei Lint-Fehlern fehlzuschlagen.
Visueller Rauchtest – erforderlich, wenn das Projekt Sub-Compositions verwendet
lint / validate / inspect bewerten jede Komposition isoliert. Sie laden niemals index.html und montieren Sub-Compositions via data-composition-src, daher können sie keine dateiübergreifenden Montagefehler erkennen (siehe hyperframes-core → references/sub-compositions.md, „Häufige Fallstricke“). Die einzige Schranke, die sie erkennt, ist eine, die tatsächlich index.html lädt und die Timeline durchsucht.
Verwende hyperframes snapshot – es lädt das Projekt genauso wie render (übt also denselben Montagepfad aus), erfasst aber nur die von dir angeforderten Zeitstempel, sodass es Sekunden statt eines vollständigen Render-Vorgangs dauert:
# Einen Frame am Mittelpunkt jeder Sub-Composition 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 Szenen-spezifische Zielsetzung 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 mit dem Szenenplan.
Pro-Frame-Warnsignale (jedes entspricht einem bestimmten, von den statischen Schranken nicht erkannten Fehlermodus):
| Was du siehst | Ursache |
|---|---|
| Text erscheint winzig + ohne Styling in der oberen linken Ecke | <style>-Block blieb in <head> außerhalb von <template> (Fallstrick 1) – kein CSS erreicht das Live-DOM |
| SVG/Icon-Elemente auf Leinwandgröße aufgeblasen | Gleiche Ursache – keine Breiten-/Höhenbeschränkungen angewendet |
| Hero-Element der Szene fehlt vollständig; nur Hintergrund + Wasserzeichen sichtbar | Host-ID ≠ Vorlagen-ID (Fallstrick 2) – Timeline wurde nie ausgeführt, Frame im Anfangszustand erfasst |
Der 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 benutzerseitige endgültige Render-Vorgang ist ein separater Durchlauf mit npx hyperframes render.