Was macht HyperFrames CLI?
Führe Befehle als npx hyperframes ... aus, sofern die Projektanweisungen keinen Wrapper bereitstellen. Befolge den Wrapper, falls vorhanden. Die CLI erfordert Node.js 22 oder neuer und FFmpeg.
Entwicklungszyklus
- Gerüst:
npx hyperframes init <Projekt>oder eine Seite erfassen. Im Nicht-TTY-Modus übergib--non-interactive --example=<Name>. - Autor: Schreibe die Komposition mit
/hyperframes-core. - Schnelles Feedback beim Bearbeiten: Führe
npx hyperframes lintnach dem ersten HTML-Durchlauf und nach strukturellen Änderungen aus. - Führe das finale Gate aus: Führe
npx hyperframes checkaus; es führt lint vor dem Öffnen des Browsers erneut aus. Füge keinen redundanten eigenständigen lint-Aufruf hinzu. Füge--snapshotsfür kommentierte Übersichtsbilder und zum Auffinden von Ausschnitten hinzu. - Überprüfe Unterkompositionen: Wenn
index.htmldata-composition-srceinbindet, erfasse Zwischenschnappschüsse und überprüfe jede eingebundene Szene. - Öffne die finale Studio-Vorschau: Führe
npx hyperframes previewaus, übergib dem Benutzer die Timeline-Projekt-URL und frage, ob überarbeitet oder gerendert werden soll. - Rendere nur nach Freigabe: Verwende Entwurfsqualität für Iterationen und hohe Qualität für die Auslieferung.
- Überprüfe die Ausgabe: Stelle sicher, dass die Datei existiert, nicht leer ist und eine plausible Dauer hat.
# Schnelle Iterationsprüfung; bei Bedarf während des Authorings wiederholen.
npx hyperframes lint
# Erforderliches finales Gate; enthält 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 Suchdurchlauf, um Laufzeitfehler, fehlgeschlagene Anfragen, Layout, *.motion.json-Assertions und WCAG-Kontrast zu prüfen. Dauerhafte Befunde blockieren den Exit-Code; vorübergehende Ein- oder Ausgangsbefunde sind informativ. Verwende --strict, um Warnungen zu blockieren. validate, inspect und layout bleiben aus Kompatibilitätsgründen Aliase, sollten aber nicht in neuen Anweisungen oder Skripten vorkommen.
Zwei verschiedene Vorschauoberflächen
Verwechsle diese Zustände nicht:
| Oberfläche | Wann sie geöffnet werden darf | Zweck |
|---|---|---|
| Storyboard-Board | Vor Kompositionsprüfungen, nur wenn storyboard: yes | Überprüfung der Planungskarten und Drahtgitterskizzen. Öffne ?view=storyboard#project/<Name>. |
| Finale Kompositionsvorschau | Nach bestandenem check | Überprüfung der zusammengebauten Timeline vor dem Rendern. Öffne #project/<Name>. |
Das frühe Board ist keine Freigabe des finalen Videos. Rendering erfordert immer die finale Freigabe, wie in hyperframes-core/references/review-loop.md definiert.
Rauchtest für Unterkompositionen
Statische Prüfungen können nicht jeden Einbettungsfehler erkennen. Wenn das Projekt Unterkompositionen verwendet, erfasse mindestens einen sichtbaren Mittelpunkt für jeden Host-Slot:
npx hyperframes snapshot --at <t1>,<t2>,<t3>
Behandle winzigen ungestylten Inhalt, leinwandgroße Symbole, fehlende Hero-Elemente oder Timeout bei der Timeline-Registrierung als renderverschlechternde Einbettungsfehler. Siehe hyperframes-core/references/sub-compositions.md für die entsprechenden Korrekturen.
Agentenkonventionen
-
Bevorzuge
--jsonfür Agenten- und CI-Aufrufe. Servermodusrender,previewundplayliefern keine normale JSON-Ausgabe;preview --selection --jsonundpreview --context --jsonsind Ausnahmen im Abfragemodus. -
doctor --jsonbeendet sich immer mit Exit-Code 0. Prüfe auf sein Payload:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
Der Nicht-TTY-Modus ist automatisch.
initerfordert dort--example; verwende--non-interactive, um deterministisches Verhalten auf einem TTY zu erzwingen. -
Verwende eine
HYPERFRAMES_RUN_IDfür alle Befehle im selben Verifizierungszyklus. -
Verwende
--strict,--strict-allund--strict-variables, wenn die entsprechenden Warnungen, Variablen oder CI-Bedingungen das Rendern blockieren müssen. -
JSON-Pfade redigieren das Home-Verzeichnis als
$HOME; versuche nicht, die Redaktion rückgängig zu machen. -
Rendere niemals nur, weil Prüfungen bestanden wurden. Halte bei der finalen Vorschau an und warte auf Freigabe.
Studio-gesteuerte Bearbeitungen
Wenn der Benutzer sich auf „dieses Element“ oder die aktuelle Auswahl bezieht, frage Studio ab, anstatt zu raten:
npx hyperframes preview --context --json --context-fields selection
Verwende selection.target.hfId, wenn verfügbar, andernfalls seinen Selektor und die Quelldatei. Wenn das Ergebnis no-selection meldet, bitte den Benutzer, auf das Element zu klicken und den Befehl erneut auszuführen. Fordere nur die benötigten Kontextausschnitte an; verwende --context-detail full nur für berechnete Stile oder bearbeitbare Textmetadaten. Vollständiges Verhalten und Fehlercodes befinden 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 |
| Reproduzierbarer Container-Render | npx hyperframes render --docker --strict --output out.mp4 |
| Lokaler variablengetriebener Batch-Render | npx hyperframes render --batch rows.json --output "renders/{name}.mp4" |
| HeyGen-gehostetes Null-Infrastruktur-Render | npx hyperframes cloud render |
| Selbstverwalteter verteilter AWS-Render | npx hyperframes lambda render <Projekt> --width 1920 --height 1080 --wait |
| Selbstverwalteter verteilter GCP-Render | npx hyperframes cloudrun render <Projekt> --width 1920 --height 1080 --wait |
Verwende Cloud-Rendering, wenn der Benutzer gehostetes Rendering ohne lokales Chrome, FFmpeg oder AWS wünscht. Verwende Lambda nur, wenn AWS-Besitz Anforderung ist. Verwende Cloud Run nur, wenn GCP-Besitz Anforderung ist. Lies die passende Referenz, bevor du einen Cloud-Pfad ausführst.
Nach der Überprüfung eines erfolgreichen Renderings sende einen Feedback-Bericht, es sei denn, Telemetrie ist deaktiviert oder der Benutzer hat abgelehnt:
npx hyperframes feedback --rating <0-10> --comment "<spezifisches Ergebnis oder Reibung>"
Halte sauberes Lauffeedback kurz. Erfasse bei Fehlern oder Reibungen ein Reproduktionspaket, bevor du es einreichst; sende nicht nur eine Symptomzusammenfassung. Füge den wiederholbaren Befehl und das Arbeitsverzeichnis, erwartetes vs. tatsächliches Verhalten, genauen Fehler, ob die Ausgabe abgeschlossen/zurückgefallen/fehlgeschlagen ist, Workaround und Reproduktionsprojektstatus hinzu. Wenn das Problem nicht reproduziert werden konnte, sage das und füge dennoch den letzten fehlgeschlagenen Befehl und die Logs bei. Verwende --file-issue nur mit Zustimmung: Es veröffentlicht eine minimale Reproduktion auf eine öffentliche URL. Das erforderliche Paketformat und den Datenschutzhinweis findest du in references/preview-render.md.
Lies die passende Referenz, bevor du einen Befehl ausführst
Die folgenden Referenzen und zugehörigen Fähigkeiten sind verbindliche Befehlsverträge, keine optionale Hintergrundlektüre. Bevor du einen Befehl in der Tabelle ausführst, lies die entsprechende Zeile.
| Bedarf | Referenz |
|---|---|
init, capture, skills | references/init-and-scaffold.md |
lint, check, Motion-Seitendateien, snapshot | references/lint-validate-inspect.md |
compare, grade-compare, variablengetriebenes 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 lies auch /hyperframes-core → references/variables-and-media.md. Für hyperframes add und hyperframes catalog verwende /hyperframes-registry. Vor hyperframes present lies /slideshow; vor hyperframes keyframes lies /hyperframes-keyframes. Für TTS, Transkription, Untertitel oder Hintergrundentfernungsoptionen verwende /media-use.
Die spezialisierten Befehle sind absichtlich von ihren zugehörigen Workflows dokumentiert:
npx hyperframes present <Projekt-Verzeichnis> --port 3004 --no-open
npx hyperframes beats <Projekt-Verzeichnis> --json
npx hyperframes keyframes <Projekt-Verzeichnis> --json
present dient ein navigierbares Deck mit Präsentator- und Publikumssynchronisation. beats ist das eigenständige Studio-Beat-Raster-Werkzeug, definiert in references/beats.md. keyframes liefert suchsichere Animations- und Bewegungspfad-Diagnosen.