HyperFrames CLI – Videostudio

HyperFrames CLI

Befehle als npx hyperframes ... ausführen, sofern die Projektanweisungen keinen Wrapper bereitstellen. Wenn ein Wrapper vorhanden ist, diesen verwenden. Die CLI benötigt Node.js 22 oder neuer und FFmpeg.

Entwicklungsschleife

1. Gerüst erstellen: npx hyperframes init <projekt> oder eine Website erfassen. Im Nicht-TTY-Modus --non-interactive --example=<name> übergeben.
2. Autor: die Komposition mit /hyperframes-core schreiben.
3. Schnelles Feedback während der Bearbeitung: npx hyperframes lint nach dem ersten HTML-Durchlauf und nach strukturellen Änderungen ausführen.
4. Das finale Gate ausführen: npx hyperframes check ausführen; es führt lint vor dem Öffnen des Browsers erneut aus. Keinen redundanten, separaten lint-Aufruf voranstellen. --snapshots für kommentierte Übersichtsbilder und zur Ermittlung von Bildausschnitten hinzufügen.
5. Sub-Kompositionen inspizieren: Wenn index.html data-composition-src einbindet, Zwischen-Snapshots erfassen und jede eingebundene Szene inspizieren.
6. Die finale Studio-Vorschau öffnen: npx hyperframes preview ausführen, die Timeline-Projekt-URL dem Benutzer übergeben und fragen, ob überarbeitet oder gerendert werden soll.
7. Nur nach Genehmigung rendern: Entwurfsqualität für Iterationen und hohe Qualität für die Auslieferung verwenden.
8. Die Ausgabe überprüfen: Bestätigen, dass die Datei existiert, nicht leer ist und eine plausible Dauer aufweist.

# Schnelle Iterationsprüfung; bei Bedarf während der Autorenschaft wiederholen.
npx hyperframes lint

# Erforderliches finales Gate; beinhaltet lint.
npx hyperframes check
npx hyperframes preview
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format out.mp4

check führt zuerst lint aus, verwendet dann eine Browsersitzung und einen Seek-Durchlauf, um Laufzeitfehler, fehlgeschlagene Anfragen, Layout, *.motion.json-Assertions und WCAG-Kontrast zu prüfen. Beständige Befunde blockieren den Exit-Code; vorübergehende Eintritts- oder Austrittsbefunde sind informativ. --strict verwenden, um Warnungen als blockierend zu kennzeichnen. validate, inspect und layout bleiben aus Kompatibilitätsgründen als Aliase bestehen, dürfen aber in neuen Anweisungen oder Skripten nicht verwendet werden.

Zwei verschiedene Vorschauoberflächen

Diese Zustände nicht verwechseln:

Oberfläche	Wann sie geöffnet werden kann	Zweck
Storyboard-Tafel	Vor Kompositionsprüfungen, nur wenn storyboard: yes	Planungskarten und Drahtmodellskizzen prüfen. Öffnen unter ?view=storyboard#project/<name>.
Finale Kompositionsvorschau	Nach bestandenem check	Die zusammengebaute Timeline vor dem Rendern prüfen. Öffnen unter #project/<name>.

Die frühe Tafel ist keine Genehmigung des endgültigen Videos. Rendering erfordert immer die finale Freigabe, wie in hyperframes-core/references/review-loop.md definiert.

Sub-Kompositions-Smoke-Test

Statische Prüfungen können nicht jeden Einbettungsfehler erkennen. Wenn das Projekt Sub-Kompositionen verwendet, mindestens einen sichtbaren Mittelpunkt für jeden Host-Slot erfassen:

npx hyperframes snapshot --at <t1>,<t2>,<t3>

Kleine, unformatierte Inhalte, canvasgroße Symbole, fehlende Hero-Elemente oder Timeout bei der Timeline-Registrierung als rendertblockierende Einbettungsfehler behandeln. Siehe hyperframes-core/references/sub-compositions.md für die entsprechenden Korrekturen.

Agenten-Konventionen

• --json für Agenten- und CI-Aufrufe bevorzugen. Server-Modus render, preview und play liefern keine normale JSON-Ausgabe; preview --selection --json und preview --context --json sind Ausnahmen im Abfragemodus.

• doctor --json beendet sich immer mit Exit-Code 0. Auf der Nutzlast basieren:

  npx hyperframes doctor --json | jq -e '.ok' >/dev/null
  

• Der Nicht-TTY-Modus ist automatisch. init erfordert dort --example; --non-interactive verwenden, um deterministisches Verhalten auf einem TTY zu erzwingen.

• Eine einzige HYPERFRAMES_RUN_ID für alle Befehle im selben Verifizierungszyklus verwenden.

• --strict, --strict-all und --strict-variables verwenden, wenn die entsprechenden Warnungen, Variablen oder CI-Bedingungen das Rendern blockieren müssen.

• JSON-Pfade redigieren das Home-Verzeichnis als $HOME; nicht versuchen, die Redaktion rückgängig zu machen.

• Niemals nur rendern, weil die Prüfungen bestanden sind. Bei der finalen Vorschau pausieren und auf Genehmigung warten.

Studio-gesteuerte Bearbeitungen

Wenn der Benutzer sich auf „dieses Element“ oder die aktuelle Auswahl bezieht, Studio abfragen anstatt zu raten:

npx hyperframes preview --context --json --context-fields selection

selection.target.hfId verwenden, wenn verfügbar, andernfalls dessen Selektor und Quelldatei. Wenn das Ergebnis no-selection meldet, den Benutzer bitten, auf das Element zu klicken und den Befehl erneut auszuführen. Nur die benötigten Kontextausschnitte anfordern; --context-detail full nur für berechnete Styles oder bearbeitbare Textmetadaten verwenden. Vollständiges Verhalten und Fehlercodes finden sich in references/preview-render.md.

Render-Optionen

Bedarf	Befehl
Schnelle lokale Iteration	npx hyperframes render --quality draft
Finale lokale Auslieferung	npx hyperframes render --quality high --output out.mp4
Reproduzierbares Container-Rendering	npx hyperframes render --docker --strict --output out.mp4
Lokales variablengesteuertes Batch-Rendering	npx hyperframes render --batch rows.json --output "renders/{name}.mp4"
HeyGen-gehostetes Null-Infrastruktur-Rendering	npx hyperframes cloud render
Selbstverwaltetes verteiltes AWS-Rendering	npx hyperframes lambda render <projekt> --width 1920 --height 1080 --wait
Selbstverwaltetes verteiltes GCP-Rendering	npx hyperframes cloudrun render <projekt> --width 1920 --height 1080 --wait

Cloud-Rendering verwenden, wenn der Benutzer gehostetes Rendering ohne lokales Chrome, FFmpeg oder AWS wünscht. Lambda nur verwenden, wenn AWS-Besitz eine Anforderung ist. Cloud Run nur verwenden, wenn GCP-Besitz eine Anforderung ist. Vor der Ausführung eines Cloud-Pfads die entsprechende Referenz lesen.

Nach der Überprüfung eines erfolgreichen Renderings einen Feedback-Bericht senden, sofern Telemetrie nicht deaktiviert ist oder der Benutzer widersprochen hat:

npx hyperframes feedback --rating <0-10> --comment "<spezifisches Ergebnis oder Problem>"

Feedback für saubere Durchläufe kurz halten. Bei Fehlern oder Problemen ein Reproduktionspaket erfassen, bevor es gesendet wird; nicht nur eine Zusammenfassung der Symptome senden. Den wiederholbaren Befehl und das Arbeitsverzeichnis, das erwartete vs. tatsächliche Verhalten, die genaue Fehlermeldung, ob die Ausgabe abgeschlossen/zurückgefallen/fehlgeschlagen ist, den Workaround und den Status des Reproduktionsprojekts angeben. Bei einer Bewertung ≤ 7, die einen visuellen Fehler beschreibt (schwarzer Bildschirm, Flimmern, korrupte Ausgabe, falscher Frame, leere Ausgabe, andere visuelle Anomalie), zusätzlich einen COMPOSITION_STRUCTURE:-Block einfügen – eine datenschutzschonende strukturelle Anatomie (Elementzählung + Vorhandensein von Attributen + Timeline-Form), damit die Maintainer ohne die Kompositions-ZIP Mustererkennung gegen bekannte Fehlerfamilien durchführen können. Agenten füllen dies automatisch über den Composition-Census-Helfer aus; der menschliche Benutzer füllt es nicht von Hand aus. Wenn sich das Problem nicht erneut reproduzieren ließ, dies angeben und dennoch den letzten fehlgeschlagenen Befehl und die Logs beifügen. --file-issue nur mit Zustimmung verwenden: Es veröffentlicht eine minimale Reproduktion unter einer öffentlichen URL. Das erforderliche Paketformat und die Datenschutzwarnung finden sich in references/preview-render.md.

Vor der Ausführung eines Befehls die passende Referenz lesen

Die folgenden Referenzen und zugehörigen Skills sind verbindliche Befehlsverträge, keine optionale Hintergrundlektüre. Vor der Ausführung eines Befehls in der Tabelle die entsprechende Zeile lesen.

Bedarf	Referenz
init, capture, skills	references/init-and-scaffold.md
lint, check, Motion-Seitendateien, snapshot	references/lint-validate-inspect.md
compare, grade-compare, variablengesteuertes render --batch	references/compare-and-batch.md
beats für das Studio-Beat-Raster eines bestehenden Projekts	references/beats.md
preview, play, render, publish, Studio-Kontext, Feedback	references/preview-render.md
doctor, Browser-Verwaltung	references/doctor-browser.md
auth, HeyGen-gehostetes Cloud-Rendering und Vorlagenvariablen	references/cloud.md
AWS-Lambda-Bereitstellung und -Rendering	references/lambda.md
Google Cloud Run-Bereitstellung und -Rendering	references/cloudrun.md
info, upgrade, compositions, docs, benchmark, Telemetrie, Medienvorverarbeitung	references/upgrade-info-misc.md

Für Kompositionsvariablen auch /hyperframes-core → references/variables-and-media.md lesen. Für hyperframes add und hyperframes catalog /hyperframes-registry verwenden. Vor hyperframes present /slideshow lesen; vor hyperframes keyframes /hyperframes-keyframes lesen. Für TTS, Transkription, Untertitel oder Hintergrundentfernung /media-use verwenden.

Die spezialisierten Befehle sind bewusst in ihren eigenen Workflows dokumentiert:

npx hyperframes present <projekt-verz> --port 3004 --no-open
npx hyperframes beats <projekt-verz> --json
npx hyperframes keyframes <projekt-verz> --json

present dient ein navigierbares Deck mit Präsentatoren- und Publikumssynchronisation aus. beats ist das eigenständige Studio-Beat-Raster-Dienstprogramm, definiert in references/beats.md. keyframes liefert seek-sichere Animations- und Bewegungspfad-Diagnosen.