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.
Workflow
- 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 Skills veraltet sind. Das Flag--skip-skillsist derzeit deaktiviert (vorübergehend, während das skills.sh-Register aufholt), sodass jederinit-Aufruf diese Prüfung durchführt und unsere neuesten Skills unabhängig davon lädt. - 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 – die 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 einem Headless-Chrome und meldet Laufzeit-Konsolenfehler sowie WCAG-Kontrastprobleme. inspect durchsucht die Timeline und meldet Text, der aus Blasen/Containern oder von der Leinwand läuft – und, wenn eine *.motion.json-Sidecar-Datei vorhanden ist, überprüft es die Bewegungsabsicht (Eingänge beim Suchen, Stagger-Reihenfolge, im Rahmen, Lebendigkeit) anhand derselben gesuchten Timeline.
Für bewegungsintensive Arbeit bevorzuge snapshot-getriebene Iteration und eine *.motion.json-Sidecar – siehe references/lint-validate-inspect.md für die Disziplin und die Bewegungsspezifikation.
Agenten-Konventionen
Querschnittsregeln, die für jeden Befehl gelten:
--jsonist bei jedem Befehl verfügbar außerrender,previewundplay. Verwende es für jede Agenten-/CI-Invokation 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 – verifiziere den Erfolg mit der Post-Render-Prüfung unten;preview/playsind Server, kein JSON.doctor --jsonbeendet sich immer mit 0, selbst wenn die Umgebung fehlerhaft ist. Entscheide anhand desok-Feldes im Payload:npx hyperframes doctor --json | jq -e '.ok' > /dev/null. Dies schützt Pipelines vor CLI-Release-Änderungen.- Nicht-TTY-Modus wird automatisch erkannt. Wenn
stdoutkein TTY ist (CI, Agenten, Pipe-Ausgabe), wechselt die CLI automatisch in den nicht-interaktiven Modus;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-variablesbei nicht deklarierten Schlüsseln in--variables. - Pfade in
--jsonwerden redigiert –$HOMEwird zum literalen$HOME, sodass die Ausgabe sicher in Bug-Reports und Agenten-Kontext eingefügt werden kann. - Rendern ist benutzergesteuert. Niemals automatisch rendern, sobald die Prüfungen bestanden sind. Bei
previewpausieren, dem Benutzer mitteilen, dass das Video in Studio bearbeitbar ist, und erst nach seiner Zustimmung rendern. - Post-Render-Verifikation. Nachdem
rendermit Exit-Code 0 zurückkehrt, prüfe, ob die Ausgabedatei existiert und eine plausible Größe hat, bevor du Erfolg meldest:[ -s "$OUTPUT" ] || echo "render produced no output". Die CLI gibt bei Erfolg◇ <Pfad>aus; bei langen Render-Vorgängen zusätzlich die Dauer mitffprobe -i "$OUTPUT" -show_format -v errorüberprüfen.
Routing
| Wenn du … | Lies |
|---|---|
Ein Projekt gerüsten möchtest (init, capture, skills) | references/init-and-scaffold.md |
Korrektheit prüfen möchtest (lint, validate, inspect, snapshot) | references/lint-validate-inspect.md |
Eine Vorschau anzeigen oder rendern möchtest (preview, play, render, publish) | references/preview-render.md |
Die Umgebung diagnostizieren möchtest (doctor, browser) | references/doctor-browser.md |
AWS Lambda Cloud Render verwenden möchtest (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), bevor du Klassen oder Theme-Tokens 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-Modell-Regeln, Untertitel und TTS-zu-Untertitel-Kette. - Parametrisierte Render-Vorgänge (
--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 Render-Vorgänge von deinem Laptop oder CI aus. Der End-to-End-Ablauf 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-Anmeldeinformationen konfiguriert hast. Für die Entwicklungsschleife 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 Fertigstellungs-Gate
Statische Gates
npx hyperframes lint
npx hyperframes validate
Füge inspect für layout-sensitive Arbeiten und render --strict in CI hinzu, um bei Lint-Fehlern zu scheitern.
Visueller Smoke-Test – erforderlich, wenn das Projekt Sub-Compositions verwendet
lint / validate / inspect bewerten jede Composition isoliert. Sie laden niemals index.html und mounten Sub-Compositions über 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.
Verwende hyperframes snapshot – es lädt das Projekt auf die gleiche Weise wie render (übt also denselben Mount-Pfad aus), erfasst aber nur die von dir angeforderten Zeitstempel, sodass es Sekunden statt eines vollständigen Rendervorgangs dauert:
# Einen Frame in der Mitte 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 szenenspezifische Zielsetzung benötigt wird, ein gleichmäßig verteiltes Sample:
npx hyperframes snapshot --frames 9
Die Ausgabe landet in snapshots/frame-NN-at-Xs.png. Prüfe jeden Frame gegen den Szenenplan.
Pro-Frame-Warnsignale (jedes entspricht einem bestimmten Fehlermodus, den die statischen Gates nicht erkennen):
| Was du siehst | Ursache |
|---|---|
| Text erscheint winzig + ungestylt 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 width/height-Einschrä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 bei initialem Zustand erfasst |
Snapshot-Befehl protokolliert Sub-composition timelines not registered after 45000ms | Fallstrick 2 – direkte Bestätigung |
snapshots/ kann nach der Prüfung gelöscht werden; der benutzersichtige finale Render ist ein separater Durchlauf mit npx hyperframes render.