HyperFrames CLI
Kapselt npx hyperframes für die Marketing-Engine-Pipeline. Erfordert Node.js >= 22 und FFmpeg im Pfad (Überprüfung mit npx hyperframes doctor). Alle Befehle werden standardmäßig im DRY_RUN-sicheren Modus ausgeführt – die Lint-/Inspect-Durchläufe haben keine externen Aufrufe; nur render schreibt eine MP4-Datei.
Wann aufrufen
- Unmittelbar nachdem
hyperframes-prompt-builderein Projekt unteroutputs/<client>/<date>/<piece-id>/erstellt hat. - Immer wenn eine Komposition vor der Veröffentlichung validiert werden muss (
lint+inspect). - Für die lokale Vorschau während der Iteration an einem Stück (
preview). - Für den finalen Render, der das Artefakt erzeugt, das vom Veröffentlichungsschritt aufgenommen wird (
render). - Zur Umgebungsfehlerbehebung, wenn der Render fehlschlägt (
doctor,browser,info).
Eingaben
project_path: Zeichenkette. Pfad zum HyperFrames-Projekt (mussindex.htmlundcomposition.jsonenthalten).mode:"lint" | "inspect" | "preview" | "render" | "doctor".render_opts: Objekt, optional, nur fürmode = "render". Erkannte Schlüssel:fps: 24 | 30 | 60 (Standard 30).quality:"draft" | "standard" | "high"(Standard"standard"; während der Iteration"draft"verwenden).format:"mp4" | "webm"(Standard"mp4").variables: Objekt. JSON-Objekt, das nach Variablen-ID gruppiert ist und die Standardwerte vondata-composition-variablesüberschreibt.strict: Boolescher Wert. Bildet auf--strictab. Standardmäßigtruein der Pipeline – Render bei Lint-Fehlern abbrechen.strict_variables: Boolescher Wert. Bildet auf--strict-variablesab. Standardmäßigtruefür Piece-Läufe.workers: Ganzzahl 1-8 oder"auto". Standard"auto".output: Zeichenkette. Ausgabedateipfad innerhalb vonoutputs/<client>/<date>/<piece-id>/.
Ablauf
- Umgebung überprüfen beim ersten Start einer Sitzung:
npx hyperframes doctor. Fehlendes FFmpeg oder Chrome als hartes Hindernis melden – nicht versuchen zu rendern. - Lint.
npx hyperframes lint <project_path> --json. Alle Fehler der Stufeerrorals Hindernisse behandeln. Warnungen werden an den Orchestrator weitergegeben; der Bediener entscheidet. - Inspect.
npx hyperframes inspect <project_path> --json. Gemeldete Textüberläufe oder Canvas-Eskapaden vor dem Render beheben. Wenn der Überlauf für einen Ein-/Ausgang beabsichtigt ist, das Element mitdata-layout-allow-overflowmarkieren (oder den Vorfahren für dekorative Elemente mitdata-layout-ignore) – die Regel nicht global unterdrücken. - Preview (nur Bediener).
npx hyperframes preview <project_path> --port <port>. Die Studio-Projekt-URL (http://localhost:<port>/#project/<project-name>) zurückgeben, nicht den Quellpfadindex.html. - Render.
npx hyperframes render <project_path>mit den Flags ausrender_opts. Das--variables-Argument ausrender_opts.variablesmit einem einzeiligen JSON-String erstellen. Für Piece-Läufe immer--strictund--strict-variablesübergeben. - Ausgabe überprüfen. Nach dem Render prüfen, ob die MP4 existiert und nicht null ist. In
data/video-usage.jsonlprotokollieren mit{ ts, provider: "hyperframes", composition_id, render_args, duration_seconds, file_bytes, latency_ms }.
Ausgaben
lint:{ pass: boolean, errors: [...], warnings: [...] }.inspect:{ pass: boolean, findings: [...] }.render:{ artifact_path: string, duration_s: number, file_bytes: number, render_ms: number }.preview:{ url: string }.
Befehlsspickzettel
npx hyperframes init <name> # Gerüst erstellen (einmal pro Stück vom Prompt-Builder verwendet)
npx hyperframes lint <path> # Markup validieren
npx hyperframes inspect <path> # Layout-/Überlaufprüfung
npx hyperframes preview <path> --port 3017 # Lokale Entwicklung
npx hyperframes render <path> \
--fps 30 --quality standard --strict --strict-variables \
--variables '{"leads":42,"delta_pct":12}' \
--output outputs/<client>/<date>/<piece-id>/final.mp4
npx hyperframes doctor # Umgebungsprüfung
npx hyperframes info # Versions-/Umgebungsdetails
Nicht verhandelbare Regeln
- Niemals ohne einen bestandenen
lint- undinspect-Durchlauf rendern. Die Pipeline hat keinen Wiederherstellungspfad für eine fehlerhafte Komposition. - Niemals einen Lint- oder Inspect-Befund global unterdrücken – das Markup korrigieren oder das spezifische Element mit
data-layout-allow-overflow/data-layout-ignoreauf die Whitelist setzen. - Bei Stücken mit deklarierten Variablen immer
--strict-variablesübergeben. Ein Tippfehler in einer Variablen-ID muss laut scheitern, nicht stillschweigend auf den Standardwert zurückfallen. - Für finale Auslieferungs-Render:
--quality high. Für Iterationsschleifen:--quality draft, um Rechenleistung zu sparen. - Asset-Vorverarbeitung (
tts,transcribe,remove-background) liegt außerhalb des Rahmens dieser Fähigkeit – diese über eine zukünftigehyperframes-media-Fähigkeit aufrufen, anstatt sie hier einzubetten.
Fehlermodi
doctormeldet fehlendes FFmpeg oder Chrome: über die Setup-Anweisungen des Projekts installieren; keine Umgehung.renderschlägt fehl mitunknown variable: ein über--variablesübergebener Schlüssel ist nicht indata-composition-variablesdeklariert. Markup korrigieren oder die Überschreibung entfernen.renderüberschreitet das Wandzeit-Budget:--qualityaufstandardreduzieren oder die Komposition in Unterkompositionen aufteilen und über--workersparallelisieren.- Ausgabe-MP4 hat null Bytes:
doctorerneut ausführen; fast immer ein Chrome-Absturz während der Aufnahme.
Verwandte Fähigkeiten
hyperframes: Kompositionserstellungsregeln; erzeugt das Projekt, das diese Fähigkeit validiert und rendert.hyperframes-prompt-builder: Brief → Kompositionsspezifikation; läuft vor dieser Fähigkeit.qa-tech-specs: Läuft nach dieser Fähigkeit gegen das gerenderte MP4, um Plattformspezifikationen zu validieren.
Upstream-Referenz
Vollständige Upstream-Fähigkeit (jedes Flag, Fehlerbehebungsmatrix, parametrisierte Render): https://github.com/wesleysimplicio/hyperframes/tree/main/skills/hyperframes-cli