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).initprüft auch die installierten Fertigkeiten gegen die neuesten auf GitHub und aktualisiert das globale Set, falls welche veraltet sind. Das Flag--skip-skillsist derzeit neutralisiert (vorübergehend, während sich das skills.sh-Register aufholt), daher führt jedesinitdiese Prüfung durch und zieht unsere neuesten Fertigkeiten unabhängig davon. - Schreiben — HTML-Komposition verfassen (siehe Fertigkeit
hyperframes-core) - Linten —
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 fragen. - Rendern — die Variante auswählen:
- Iterieren:
npx hyperframes render --quality draft - Ausliefern:
npx hyperframes render --quality high --output out.mp4 - CI / hostü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 vor der Vorschau lint, validate und inspect aus. lint erfasst 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 sucht durch die Timeline und meldet Text, der aus Blasen/Containern oder über die Leinwand hinausläuft – und, wenn ein *.motion.json-Sidecar vorhanden ist, überprüft es die Bewegungsabsicht (Entrances, die unter Suche feuern, Stagger-Reihenfolge, im Rahmen, Lebendigkeit) gegen dieselbe gesuchte Timeline.
Bei bewegungsintensiven Arbeiten bevorzugen Sie Snapshot-getriebene Iteration und einen *.motion.json-Sidecar – siehe references/lint-validate-inspect.md für die Disziplin und die Spezifikation der Bewegungsverifizierung.
Agenten-Konventionen
Übergreifende Regeln, die für jeden Befehl gelten:
--jsonist bei jedem Befehl verfügbar, außer beirender,previewundplay. Verwenden Sie es für jede Agenten-/CI-Ausführung der unterstützten Befehle; die Ausgabe enthält einen_meta-Umschlag (CLI-Version, neueste verfügbare Version, Update-Hinweise).rendermeldet 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. Prüfen Sie auf dasok-Feld der Nutzlast:npx hyperframes doctor --json | jq -e '.ok' > /dev/null. Dies schützt Pipelines vor CLI-Release-Churn.- Der 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. Ü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 geschwärzt –$HOMEwird zum literalen$HOME, sodass die Ausgabe sicher in Fehlerberichte und Agenten-Kontexte eingefügt werden kann. - Rendern ist benutzergesteuert. Rendern Sie niemals automatisch, sobald die Prüfungen bestanden sind. Halten Sie bei
previewan, teilen Sie dem Benutzer mit, dass das Video im Studio bearbeitet werden kann, und rendern Sie erst nach seiner Zustimmung. - Post-Render-Verifizierung. Nachdem
rendermit Exit 0 zurückkehrt, bestätigen Sie, dass die Ausgabedatei existiert und eine plausible Größe hat, bevor Sie Erfolg melden:[ -s "$OUTPUT" ] || echo "render produced no output". Die CLI gibt◇ <path>bei Erfolg aus; bei langen Renderings überprüfen Sie zusätzlich die Dauer mitffprobe -i "$OUTPUT" -show_format -v error.
Weiterleitung
| Wenn Sie... | Lesen Sie |
|---|---|
Ein Projekt aus Scaffold 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 |
Die Umgebung diagnostizieren (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 |
Fertigkeitsübergreifende Übergaben
- Tailwind-Projekte (
init --tailwind) → verwenden Siehyperframes-core(Tailwind-Referenz), bevor Sie Klassen oder Theme-Token bearbeiten. - Registry-Blöcke/-Komponenten (
hyperframes add,hyperframes catalog) → verwenden Siehyperframes-registryfür Installationspfade, Sub-Kompositions-Verdrahtung 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>; siehehyperframes-corefür das vollständige Schema.
Lambda (Cloud-Rendering)
hyperframes lambda stellt verteiltes Rendering auf AWS Lambda bereit und steuert Renderings von Ihrem 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-Bucket bleibt erhalten)
Verwenden Sie Lambda, wenn ein Rendering zu lang / zu groß für einen Host ist (mehrminütige Videos, 4K, große parallele Batches) und Sie AWS-Anmeldeinformationen konfiguriert haben. Für die Entwicklungsloop-Iteration 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 sowie Kosten-/Bereinigungsregeln.
Mindestabnahmeschranke
Statische Schranken
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 bewerten jede Komposition isoliert. Sie laden niemals index.html und hängen Sub-Kompositionen über data-composition-src ein, daher können sie dateiübergreifende Mount-Fehler nicht abfangen (siehe hyperframes-core → references/sub-compositions.md, „Häufige Fallstricke"). Die einzige Schranke, die sie abfängt, ist eine, die tatsächlich index.html lädt und die Timeline durchsucht.
Verwenden Sie hyperframes snapshot – es lädt das Projekt auf die gleiche Weise wie render (übt also denselben Mount-Pfad aus), erfasst jedoch nur die von Ihnen angeforderten Zeitstempel, sodass es Sekunden statt eines vollständigen Renderings dauert:
# Ein 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, wenn Sie keine Szenen-fokussierte Zielsetzung benötigen, eine gleichmäßig verteilte Stichprobe:
npx hyperframes snapshot --frames 9
Die Ausgabe landet in snapshots/frame-NN-at-Xs.png. Überprüfen Sie jedes Bild gegen den Szenenplan.
Pro-Bild-Warnsignale (jedes zeigt auf eine bestimmte Fehlerart, die die statischen Schranken übersehen):
| Was Sie sehen | Ursache |
|---|---|
| Text erscheint winzig + ohne Styling in der oberen linken Ecke | <style>-Block blieb im <head> außerhalb des <template> (Fallstrick 1) – kein CSS erreichte das live DOM |
| SVG/Icon-Elemente auf Leinwandgröße aufgeblasen | Gleiches wie oben – keine Breiten-/Höhenbeschränkungen angewendet |
| Helden-Element der Szene fehlt vollständig; nur Hintergrund + Wasserzeichen sichtbar | Host-Id ≠ Template-Id (Fallstrick 2) – Timeline wurde nie ausgeführt, Bild im Ausgangszustand erfasst |
Der Snapshot-Befehl protokolliert Sub-composition timelines not registered after 45000ms | Fallstrick 2 – direkte Bestätigung |
snapshots/ kann nach der Überprüfung gelöscht werden; der benutzergerichtete endgültige Render ist ein separater Durchlauf mit npx hyperframes render.