HyperFrames CLI
Alles läuft über npx hyperframes, es sei denn, die Projektanweisungen geben einen lokalen Wrapper vor. Befolgen Sie den lokalen Wrapper genau. Erfordert Node.js >= 22 und FFmpeg.
Arbeitsablauf
- Scaffold –
npx hyperframes init my-video(odercapturevon einer URL) - Schreiben – Authoring der HTML-Komposition (siehe den Skill
hyperframes-core) - Lint –
npx hyperframes lint - Validieren –
npx hyperframes validate(Laufzeitfehler + Kontrast) - Visuelle Inspektion –
npx hyperframes inspect - Vorschau –
npx hyperframes previewöffnet Studio, den Zeitleisten-Editor, in dem der Benutzer alles manuell bearbeiten kann (nicht nur ansehen). Dort prüfen, dann vor dem Rendern fragen. - Render – Wählen Sie die Variante:
- 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 Spuren und nicht registrierte Zeitachsen. validate lädt die Komposition in Headless-Chrome und meldet Laufzeitkonsolenfehler sowie WCAG-Kontrastprobleme. inspect sucht durch die Zeitleiste 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 (Eingänge, die beim Suchen ausgelöst werden, Staffelungsreihenfolge, im Bild, Lebendigkeit) anhand dieser gesuchten Zeitleiste.
Für bewegungsintensive Arbeit bevorzugen Sie snapshot-getriebene Iteration und eine *.motion.json-Begleitdatei – siehe references/lint-validate-inspect.md für die Disziplin und die Spezifikation zur Bewegungsüberprüfung.
Agentenkonventionen
Querschnittsregeln, die für jeden Befehl gelten:
--jsonist für jeden 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 – ü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. Sperren Sie 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, Agents, weitergeleitete Ausgabe) schaltet 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-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. - Das Rendern ist benutzergesteuert. Rendern Sie niemals automatisch, sobald die Prüfungen bestanden sind. Halten Sie bei der Vorschau an, teilen Sie dem Benutzer mit, dass das Video in Studio bearbeitet werden kann, und rendern Sie erst, nachdem er zugestimmt hat.
- Überprüfung nach dem Rendern. Nachdem
rendermit Exit-Code 0 beendet wurde, bestätigen Sie vor der Erfolgsmeldung, dass die Ausgabedatei existiert und eine plausible Größe hat:[ -s "$OUTPUT" ] || echo "render produced no output". Die CLI gibt bei Erfolg◇ <path>aus; bei langen Rendern überprüfen Sie die Dauer zusätzlich mitffprobe -i "$OUTPUT" -show_format -v error.
Routing
| Um folgendes zu tun … | Lesen Sie |
|---|---|
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 |
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 |
Skills-Ü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-Verkabelung und Snippet-Zusammenführung. - Asset-Vorverarbeitung (
tts,transcribe,remove-background) → verwenden Siehyperframes-mediafür Sprachauswahl, Whisper-Modell-Regeln, Untertitel und die TTS-zu-Untertitel-Kette. - Parametrisierte Renderings (
--variables) → deklariert überdata-composition-variablesauf<html>; vollständiges Schema inhyperframes-core.
Lambda (Cloud-Rendering)
hyperframes lambda stellt verteiltes Rendering auf AWS Lambda bereit und steuert Renderings von Ihrem Laptop oder Ihrer CI aus. Der End-to-End-Prozess umfasst 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 den Entwicklungszyklus 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.
Minimales Abschluss-Gate
Statische Gates
npx hyperframes lint
npx hyperframes validate
Fügen Sie inspect für layoutkritische Arbeiten und render --strict in CI hinzu, um bei Lint-Fehlern fehlzuschlagen.
Visueller Smoke-Test – erforderlich, wenn das Projekt Unterkompositionen verwendet
lint / validate / inspect bewerten jede Komposition isoliert. Sie laden niemals index.html und mounten Unterkompositionen ü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 Zeitleiste durchsucht.
Verwenden Sie hyperframes snapshot – es lädt das Projekt auf die gleiche Weise wie render (verwendet also denselben Mount-Pfad), erfasst aber nur die von Ihnen angeforderten Zeitstempel, sodass es Sekunden statt eines vollständigen Renderings dauert:
# Erfassen Sie einen Frame am Mittelpunkt jeder Unterkomposition.
# Mittelpunkte = data-start + data-duration/2 für jeden Host-Slot in index.html.
npx hyperframes snapshot --at <t1>,<t2>,<t3>,...
# Oder, wenn kein Szenen-Targeting erforderlich ist, eine gleichmäßig verteilte Stichprobe:
npx hyperframes snapshot --frames 9
Die Ausgabe landet in snapshots/frame-NN-at-Xs.png. Prüfen Sie jeden Frame gegen den Szenenplan.
Rote Flaggen pro Frame (jede entspricht einem bestimmten Fehlermodus, den die statischen Gates übersehen):
| Was Sie sehen | Ursache |
|---|---|
| Text erscheint winzig + unformatiert in der oberen linken Ecke | <style>-Block in <head> außerhalb von <template> belassen (Fallstrick 1) – kein CSS erreichte Live-DOM |
| SVG/Icon-Elemente auf Leinwandgröße aufgeblasen | Gleiche Ursache – keine width/height-Beschränkungen angewendet |
| Das Helden-Element der Szene fehlt vollständig; nur Hintergrund + Wasserzeichen sichtbar | Host-id ≠ template-id (Fallstrick 2) – Zeitleiste lief nie, Frame im Anfangszustand erfasst |
Der Snapshot-Befehl protokolliert Sub-composition timelines not registered after 45000ms | Fallstrick 2 – direkte Bestätigung |
snapshots/ kann nach dem Begutachten gelöscht werden; das benutzerseitige finale Rendering ist ein separater Durchlauf mit npx hyperframes render.