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.
Arbeitsablauf
- Gerüst erstellen —
npx hyperframes init my-video(odercapturevon einer URL).initprüft auch die installierten Skills gegen die neuesten auf GitHub und aktualisiert den globalen Satz, falls welche veraltet sind. Das Flag--skip-skillsist derzeit neutralisiert (vorübergehend, während das skills.sh-Register aufholt), sodass jedeinitdiese Prüfung durchführt und unsere neuesten Skills unabhängig davon herunterlädt. - Schreiben — HTML-Komposition verfassen (siehe den Skill
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 wä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 erkennt fehlende data-composition-id, überlappende Spuren und nicht registrierte Timelines. validate lädt die Komposition in einem 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 eine *.motion.json-Begleitdatei vorhanden ist, überprüft es die Bewegungsabsicht (Eingänge, die bei der Suche feuern, Staffelungsreihenfolge, im Rahmen, Lebendigkeit) anhand derselben durchsuchten Timeline.
Bevorzugen Sie bei bewegungsintensiven Arbeiten eine snapshot-gesteuerte Iteration und eine *.motion.json-Begleitdatei – siehe references/lint-validate-inspect.md für die Disziplin und die Bewegungsspezifikation.
Agentenkonventionen
Querschnittsregeln, die für jeden Befehl gelten:
--jsonist bei jedem Befehl außerrender,previewundplayverfügbar. Verwenden Sie es für jede Agenten-/CI-Aufrufung 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 – verifizieren 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 dasok-Feld der Nutzlast:npx hyperframes doctor --json | jq -e '.ok' > /dev/null. Dies schützt Pipelines vor CLI-Versionswechseln.- Der Nicht-TTY-Modus wird automatisch erkannt. Wenn
stdoutkein TTY ist (CI, Agenten, gepipeete Ausgabe) schaltet das 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-variablesbei nicht deklarierten--variables-Schlüsseln. - Pfade in
--jsonwerden redigiert –$HOMEwird zum wörtlichen$HOME, sodass die Ausgabe sicher in Fehlerberichte und Agentenkontexte eingefügt werden kann. - Rendern ist benutzergesteuert. Nie automatisch rendern, sobald die Prüfungen bestanden sind. Bei der Vorschau anhalten, dem Benutzer mitteilen, dass das Video in Studio bearbeitbar ist, und nur rendern, nachdem er zugestimmt hat.
- Post-Render-Verifizierung. Nachdem
rendermit Exit-Code 0 beendet wurde, 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". Das CLI gibt bei Erfolg◇ <Pfad>aus; bei langen Rendern zusätzlich die Dauer mitffprobe -i "$OUTPUT" -show_format -v errorüberprüfen.
Routing
| Gewünschte Aktion | Lesen |
|---|---|
Projekt gerüsten (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 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 |
Skill-Übergaben
- Tailwind-Projekte (
init --tailwind) →hyperframes-core(Tailwind-Referenz) vor dem Bearbeiten von Klassen oder Theme-Tokens verwenden. - Registry-Blöcke/Komponenten (
hyperframes add,hyperframes catalog) →hyperframes-registryfür Installationspfade, Sub-Komposition-Verdrahtung und Snippet-Zusammenführung verwenden. - Asset-Vorverarbeitung (
tts,transcribe,remove-background) →hyperframes-mediafür Sprachauswahl, Whisper-Modellregeln, Untertitel und TTS-zu-Untertitel-Kette verwenden. - Parametrisierte Renderings (
--variables) → deklariert überdata-composition-variablesauf<html>; siehehyperframes-corefür das vollständige Schema.
Lambda (Cloud-Rendering)
hyperframes lambda stellt verteiltes Rendern 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 Entwicklungsiteration 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.
Mindestabschluss-Gatter
Statische Gatter
npx hyperframes lint
npx hyperframes validate
Fügen Sie 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-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 Montagefehler erkennen (siehe hyperframes-core → references/sub-compositions.md, „Häufige Fallstricke“). Das einzige Gatter, 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 (übt also denselben Montagepfad aus), erfasst aber nur die von Ihnen angeforderten Zeitstempel, dauert also Sekunden statt eines vollständigen Renderings:
# 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 keine zielszenische Ausrichtung erforderlich ist, 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 mit dem Szenenplan.
Bild-für-Bild-Warnsignale (jedes zeigt auf einen bestimmten Fehlermodus, den die statischen Gatter übersehen):
| Was Sie sehen | Ursache |
|---|---|
| Text erscheint winzig und 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 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, Bild im 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; das benutzerseitige endgültige Rendern ist ein separater Durchlauf mit npx hyperframes render.