HyperFrames CLI
Alles läuft über npx hyperframes, sofern die Projektanweisungen keinen lokalen Wrapper vorgeben. Befolgen Sie 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 Fähigkeiten gegen die neuesten auf GitHub und aktualisiert das globale Set, falls welche veraltet sind. Das Flag--skip-skillsist derzeit neutralisiert (vorübergehend, während das skills.sh-Register aufholt), daher führt jedesinitdiese Prüfung durch und lädt unsere neuesten Fähigkeiten unabhängig davon. - Schreiben — HTML-Composition verfassen (siehe Skill
hyperframes-core) - Linten —
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 der Benutzer alles manuell bearbeiten kann (nicht nur ansehen). Dort prüfen, dann vor dem Rendern fragen. - 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 der Vorschau aus. lint erkennt fehlende data-composition-id, überlappende Tracks und nicht registrierte Timelines. validate lädt die Composition in einem headless Chrome und meldet Laufzeitkonsolenfehler sowie WCAG-Kontrastprobleme. inspect durchsucht die Timeline und meldet Text, der aus Blasen/Containern oder der Leinwand überläuft – und, wenn eine *.motion.json-Begleitdatei vorhanden ist, überprüft es die Bewegungsabsicht (Entrances, die beim Suchen auslösen, Staffelungsreihenfolge, im Frame, Lebendigkeit) gegen dieselbe durchsuchte Timeline.
Bei bewegungsintensiven Arbeiten bevorzugen Sie eine snapshot-getriebene Iteration und eine *.motion.json-Begleitdatei – siehe references/lint-validate-inspect.md für die Disziplin und die Bewegungsverifikationsspezifikation.
Agentenkonventionen
Übergreifende Regeln, die für jeden Befehl gelten:
--jsonist für jeden Befehl außerrender,previewundplayverfügbar. 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, Update-Hinweis).rendermeldet den Status nur über stdout + Exit-Code – überprüfen Sie den Erfolg mit dem Post-Render-Check 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 isoliert Pipelines von CLI-Release-Änderungen.- 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-Gate für Render:
--strictschlägt bei Lint-Fehlern fehl,--strict-allauch bei Warnungen,--strict-variablesbei nicht deklarierten--variables-Schlüsseln. - Pfade in
--jsonwerden redigiert –$HOMEwird zum literal$HOME, sodass die Ausgabe sicher in Fehlerberichte und Agentenkontexte eingefügt werden kann. - Render ist benutzergesteuert. Rendern Sie niemals automatisch, sobald die Prüfungen bestanden sind. Halten Sie bei
previewan, teilen Sie dem Benutzer mit, dass das Video in Studio bearbeitet werden kann, und rendern Sie erst, nachdem er zugestimmt hat. - Post-Render-Überprüfung. Nachdem
rendermit Exit-Code 0 zurückkehrt, bestätigen Sie, dass die Ausgabedatei existiert und eine plausible Größe hat, bevor Sie den Erfolg melden:[ -s "$OUTPUT" ] || echo "render hat keine Ausgabe erzeugt". Die CLI gibt bei Erfolg◇ <path>aus; für lange Renderings prüfen Sie auch die Dauer mitffprobe -i "$OUTPUT" -show_format -v error.
Routen
| Ziel… | Lesen |
|---|---|
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 Render (preview, play, render, publish) | references/preview-render.md |
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 |
Fähigkeitsü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, Verschaltung von Sub-Compositions und Zusammenführung von Snippets. - Asset-Vorverarbeitung (
tts,transcribe,remove-background) → verwenden Siehyperframes-mediafür Sprachauswahl, Whisper-Modellregeln, Untertitel und TTS-zu-Untertitel-Kette. - Parametrisierte Renderings (
--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 Renderings von Ihrem Laptop oder CI aus. Ende-zu-Ende 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. Bleiben Sie für die Entwicklungsiteration 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 layout-sensitive Arbeiten und render --strict im 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 mounten Sub-Compositions via data-composition-src, daher können sie keine dateiü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.
Verwenden Sie hyperframes snapshot – es lädt das Projekt auf die gleiche Weise wie render (es durchläuft also denselben Mount-Pfad), erfasst aber nur die von Ihnen angeforderten Zeitstempel, daher dauert es Sekunden statt eines vollständigen Renderings:
# Erfasst einen Frame am Mittelpunkt 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 Sie keine zielszenenweise Zielerfassung 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 jeden Frame mit dem Szenenplan.
Pro-Frame-Alarmzeichen (jedes kennzeichnet eine spezifische Fehlerart, die die statischen Gates übersehen):
| Was Sie sehen | Grundursache |
|---|---|
| Text erscheint winzig + unformatiert 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 – keine Breiten-/Höhenbeschränkungen angewendet |
| Helden-Element der Szene fehlt vollständig; nur Hintergrund + Wasserzeichen sichtbar | Host-id ≠ template id (Fallstrick 2) – Timeline lief nie, Frame zum Ausgangszustand erfasst |
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 endgültige, benutzerseitige Render ist ein separater Durchlauf mit npx hyperframes render.