HyperFrames CLI
Führe Befehle als npx hyperframes ... aus, es sei denn, die Projektanweisungen geben einen Wrapper vor. Befolge den Wrapper, wenn vorhanden. Die CLI erfordert Node.js 22 oder neuer und FFmpeg.
Entwicklungsschleife
- Gerüst:
npx hyperframes init <projekt>(zentriert leer). Oder nimm eine Seite auf. Übergib--example=<name>nur, um von einem benannten Beispiel zu starten. - Finde den Move: Wenn die Anfrage ein Asset, einen Ton, ein Bild, eine Stimme oder eine schnelle visuelle Bearbeitung benennt, löse sie über
/media-useauf, bevor du einen Plan vorschlägst. Andernfalls suche vor der manuellen Erstellung einer Bewegung nach einem Primitiv, das sie bereits ausführt:npx hyperframes catalog --query "Zeige eine Überschrift Zeile für Zeile an". Frage nach dem gewünschten Effekt und nicht nach dem Mechanismus, den du im Kopf hast. Installiere mitnpx hyperframes add <name>(siehe/hyperframes-registry). Nur von Hand erstellen, wenn nichts passt. - Erstelle: Schreibe die Komposition mit
/hyperframes-core. Um zu erfahren, was sich auf der Timeline eines Projekts befindet (Tracks, Clips, Start, Ende, was abgespielt wird), führenpx hyperframes timeline --jsonaus, anstattindex.htmlund jede Unterkompositionsdatei zu lesen: Verschachtelte Zeilen tragen absolute Haupt-Timeline-absStart/absEndund ihre besitzendefile, nicht nur ihre lokale, pro-Unterkompositions-Zeit. Bevorzuge--jsongegenüber der Textform; es kostet weniger Token bei gleicher oder besserer Korrektheit. Siehereferences/upgrade-info-misc.mdfür Einzeiler, die häufige Fragen beantworten, ohne die gesamte Ausgabe zu lesen. - Hole schnelles Feedback während der Bearbeitung: 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 erneut aus, bevor der Browser geöffnet wird. Hänge keinen redundanten eigenständigen lint-Aufruf davor. Füge--snapshotsfür kommentierte Übersichtsbilder und das Auffinden von Zuschneidungen hinzu. - Überprüfe Unterkompositionen: Wenn
index.htmldata-composition-srcverwendet, nimm Mittelpunkts-Snapshots auf und überprüfe jede eingebundene Szene. - Öffne die finale Studio-Vorschau: Führe
npx hyperframes preview --backgroundaus, überprüfe, ob die URL HTTP 200 zurückgibt, übergebe die Timeline-Projekt-URL an den Benutzer und frage, ob überarbeitet oder gerendert werden soll. Halte sie am Leben, bis die Überprüfung abgeschlossen ist. - Rendere nur nach Genehmigung: Verwende
--quality draftwährend der Iteration,--quality looksfür die erste echte Kodierung (CLI-Standard) und--quality deliveryfür die endgültige Auslieferung. - Überprüfe die Ausgabe: Bestätige, dass die Datei existiert und nicht leer ist. Lies die zweite Zeile der Render-Zusammenfassung (
beginframevsscreenshot, GPU, Phasen-Timings).screenshot+software gpuauf Linux ist der langsame Pfad.ffprobe -v error -show_format -show_streamsund vergleiche die Dauer (und fps, falls im Brief festgelegt) mit dem rootdata-duration.
Verbindliche Querverweise für Creator-Edits
- Bevor du einen Zoom, Punch-In/Punch-Out, Reframe, Kamerabewegung oder eine Keyframe-Bewegung erstellst oder diagnostizierst, lies zuerst
/hyperframes-keyframes. - Vor
hyperframes keyframeslies/hyperframes-keyframes; der Befehl zeigt Animationstrajektorien an und diagnostiziert keine Clip-Schnitte. - Für einen Schnitt, Trim, Splice, Neuordnung oder eine Quell-Timing-Bearbeitung lies
/hyperframes-coreund verwende dessen Clip/Timeline-Vertrag. - Für Ein-/Ausblendung, Überblendung, Track-Gain, Lautstärkeautomatisierung, Ducking, Voiceover-Cut oder FX auf platziertem Audio lies
/hyperframes-audio. Lade Core zusammen damit, wenn sich Clip-Platzierung oder Bild-Timing ebenfalls ändern. - Eine Anfrage, die ein Asset, einen Ton, ein Bild, eine Stimme oder eine schnelle visuelle Bearbeitung benennt, wird über
/media-useaufgelöst, bevor ein Plan vorgeschlagen wird. Kopiere Creator-Edit-Markup aus/hyperframes-core→references/creator-editing-recipes.md.
# Schnelle Iterationsprüfung; nach Bedarf während der Erstellung wiederholen.
npx hyperframes lint
# Erforderliches finales Gate; beinhaltet lint.
npx hyperframes check
npx hyperframes preview --background
npx hyperframes render --quality looks --output out.mp4
test -s out.mp4
ffprobe -v error -show_format -show_streams out.mp4
check führt zuerst lint aus, verwendet dann eine Browser-Sitzung und einen Seek-Durchlauf, um Laufzeitfehler, fehlgeschlagene Anfragen, Layout, *.motion.json-Assertions und WCAG-Kontrast zu überprüfen. Dauerhafte Befunde blockieren den Exit-Code; vorübergehende Eingangs- oder Ausgangsbefunde sind informativ. Verwende --strict, um Warnungen zu blockieren. validate, inspect und layout bleiben aus Kompatibilitätsgründen Aliase, dürfen aber nicht in neuen Anweisungen oder Skripten erscheinen.
Vorschau vor dem Rendern
Öffne die finale Kompositionsvorschau (#project/<name>) erst, nachdem check bestanden wurde, um die zusammengestellte Timeline zu überprüfen. Der Plan im Chat und das storyboard.html-Skizzenblatt sind keine Genehmigung des finalen Videos. Das Rendern erfordert immer die endgültige Genehmigung, die in hyperframes/references/review-loop.md definiert ist.
Unterkompositions-Smoke-Test
Statische Audits können nicht jeden Mount-Fehler erkennen. Wenn das Projekt Unterkompositionen verwendet, erfasse mindestens einen sichtbaren Mittelpunkt für jeden Host-Slot:
npx hyperframes snapshot --at <t1>,<t2>,<t3>
Behandle winzige, ungestylte Inhalte, canvasgroße Symbole, fehlende Hero-Elemente oder Timeout bei der Timeline-Registrierung als renderblockierende Mount-Fehler. Siehe hyperframes-core/references/sub-compositions.md für die entsprechenden Korrekturen.
Agenten-Konventionen
-
Suche im Katalog, bevor du eine Bewegung von Hand schreibst.
npx hyperframes catalog --query "<der Beat, in einfachem Englisch>". Die Suche ist vollständig lokal: Es gibt keine gehostete Stufe, kein Konto und der Abfragetext wird nie irgendwohin gesendet. Standardmäßig sortiert sie nach gemeinsamem Vokabular mit dem Namen, Titel, der Beschreibung und den Tags des Elements, was jede Formulierung übersieht, die nicht die eigene Wortwahl des Katalogs wiederverwendet. Füge--on-devicehinzu, um stattdessen nach Bedeutung zu sortieren (siehe die Offline-Stufe unten). -
Frage auf Englisch, auch wenn das Video nicht auf Englisch ist. Beide Stufen indizieren einen englischen Katalog, daher erzeugt eine Abfrage in einer anderen Schrift keine durchsuchbaren Begriffe und liefert nichts zurück. Beschreibe den Move auf Englisch; der Text auf dem Bildschirm bleibt in der Sprache, die das Video benötigt.
No searchable words in querybedeutet genau das und ist keine fehlende Komponente, also melde es nicht als Kataloglücke. -
Lies, welche Stufe geantwortet hat; leite es nie aus den Ergebnissen ab. Mit
--jsonenthält der Umschlagquery,tier(on-deviceoderwords),tier_detail,dropped,unindexed,shown,totalundresults, plustop_score, wenn die antwortende Stufe eine erzeugt, undwarnings, wenn eine Stufe angefordert wurde und nicht ausgeführt werden konnte, oder wenn eine Suche nichts zurückgegeben hat und eine bessere Stufe noch auf die Zustimmung von jemandem wartet. Ein schwaches Ergebnis beiwordsist zu erwarten; das gleiche Ergebnis beion-deviceist ein Fehler.top_scoreist nur für On-Device und hat keinen Schwellenwert dahinter: Der Ranker gibt für jede Abfrage den gesamten Katalog in einer bestimmten Reihenfolge zurück, also lies es als Hinweis und nicht als Bestehen oder Nichtbestehen. -
droppedundunindexedsind entgegengesetzte Verzerrungen zwischen dem Registry und dem On-Device-Index, und eine Umformulierung der Abfrage behebt keines von beiden.droppedzählt die Namen, die diese Registry nicht installieren kann, sodass die stärksten Übereinstimmungen diejenigen sind, die verloren gehen.unindexedzählt Registry-Moves, die der Index überhaupt nicht sehen kann, was keine Abfrage jemals zurückgeben kann. Die Registry zu aktualisieren ist die Antwort auf keines von beiden: Ihr Manifest hat eine 24h-TTL und heilt sich selbst, während die Vektoren ein separat veröffentlichtes Artefakt sind, das in~/.hyperframes/catalog/abgerufen wird. Die erneute Ausführung mit--on-deviceruft diesen Index erneut ab, wennunindexedüber Null liegt, also ist dies das Mittel, das dem Benutzer an die Hand gegeben wird. Eine reine Überabdeckungsverzerrung (droppedüber Null, währendunindexedNull ist) löst den erneuten Abruf nicht aus; das Leeren von~/.hyperframes/catalog/ist der einzige Ausweg aus diesem. Beide Zählungen beziehen sich auf Namen und nicht auf Ergebnisse, daher kann jedetotalüberschreiten. -
Wenn eine Suche nichts Installierenswertes zurückbringt, sag es.
npx hyperframes feedback --search-miss "<die von dir ausgeführte Abfrage>" --wanted "<der benötigte Move>" --tier <die antwortende Stufe>. Du musst diese Zeile nicht zusammenbauen:catalog --querygibt sie vorausgefüllt aus, und jeder Suchumschlag mit--jsonträgt sie alsreport_gapmit bereits korrekter Abfrage und Stufe – fülle--wantedaus und sende sie ab. Dies ist der einzige Pfad, der eine Abfrage irgendwohin sendet, und es ist ein separater bewusster Befehl, genau damit einfachescatalog --querysein Versprechen hält, nichts zu senden. Melde bei jeder Stufe, wenn die Ergebnisse die Sache nicht tun; warte nicht auf die On-Device-Stufe, die einen zugestimmten 33 MB Download benötigt und daher in den meisten Agentenläufen deaktiviert ist – darauf zu warten bedeutet, niemals zu melden. Die Stufe wird im Bericht mitgeführt, sodass ein Vokabularfehler von einem Bedeutungsfehler unterscheidbar bleibt, ohne dass du beurteilen musst, welchen du getroffen hast. Zurückkommt eine Liste von Moves, die der Katalog noch nicht hat, direkt gelesen und nicht aus Installationszahlen abgeleitet, daher ist die Formulierung, die zählt, der gewünschte Effekt, nicht der von dir imaginierte Item-Name. Es trägt keine Bewertung und landet nie in der Bewertungsmetrik. -
Biete die Offline-Stufe an; aktiviere sie niemals stillschweigend. Ein einmaliger ~33 MB Download (ein quantisierter ONNX-Build von
bge-small-en-v1.5plus sein Tokenizer, fest auf eine feste Revision gepinnt) und die Katalogvektoren aus der Registry, beide zwischengespeichert unter~/.hyperframes/, weder zum Projekt noch zu einem Paket hinzugefügt. Nach dem Zwischenspeichern sortiert er nach Bedeutung, ohne etwas zu senden. Sage die Größe laut und lass die Person entscheiden, übergib dann--on-device(mit-y, um die Eingabeaufforderung zu überspringen), sobald sie zustimmt. Das interaktive Angebot feuert nur auf einem TTY. Unter--jsongibt es keine Eingabeaufforderung, aber eine Suche, die nichts gefunden hat, stellt dieselbe Anfrage inwarnings, also lies dieses Array und lege die Entscheidung selbst dem Benutzer vor. Wenn die Person fragt, was der Download ist, warum dieses Modell oder was die Maschine verlässt, verweise sie auf https://hyperframes.heygen.com/developers/catalog-search. -
Bevorzuge
--jsonfür Agenten- und CI-Aufrufe.render,previewundplayim Server-Modus liefern keine normale JSON-Ausgabe;preview --selection --jsonundpreview --context --jsonsind Ausnahmen im Abfragemodus. -
doctor --jsonbeendet sich immer mit Null. Prüfe auf seine Nutzlast:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
Der Nicht-TTY-Modus ist automatisch und erstellt das zentriert leere Gerüst. Übergib
--examplenur, um von einem benannten Beispiel zu starten. Verwende--non-interactive, um den Flag-only-Modus 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. -
Wenn ein gehostetes Cloud-Projekt sich der 200 MB Upload-Limit nähert oder es überschreitet, verwende
cloud render --dry-run --jsonund folge der.hyperframesignore-Untersuchung inreferences/cloud.md. Ignoriere niemals ein Asset, nur weil es groß ist. -
Rendere niemals nur, weil die Checks bestanden sind. Halte bei der finalen Vorschau an und warte auf die Genehmigung.
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 dessen Selektor und Quelldatei. Wenn das Ergebnis no-selection meldet, bitte den Benutzer, auf das Element zu klicken, und führe den Befehl erneut aus. Fordere nur die benötigten Kontextausschnitte an; verwende --context-detail full nur für berechnete Stile oder bearbeitbare Textmetadaten. Vollständiges Verhalten und Fehlercodes finden sich in references/preview-render.md.
Render-Auswahl
| Bedarf | Befehl |
|---|---|
| Schnelle lokale Iteration | npx hyperframes render --quality draft |
| Erste echte Kodierung | npx hyperframes render --quality looks --output out.mp4 |
| Endgültige lokale Auslieferung | npx hyperframes render --quality delivery --output out.mp4 |
| Reproduzierbarer Container-Render | npx hyperframes render --docker --strict --output out.mp4 |
| Lokaler, variablengesteuerter Batch-Render | npx hyperframes render --batch rows.json --output "renders/{name}.mp4" |
| HeyGen-gehostetes Zero-Infrastructure-Render | npx hyperframes cloud render |
| Selbstverwaltetes verteiltes AWS-Render | npx hyperframes lambda render <projekt> --width 1920 --height 1080 --wait |
| Selbstverwaltetes verteiltes GCP-Render | npx hyperframes cloudrun render <projekt> --width 1920 --height 1080 --wait |
Die Skill-Zuordnung ist automatisch – die obigen Beispiele benötigen kein --skill. Ein von einem Workflow erstelltes Projekt (hyperframes init --skill=<workflow>) zeichnet seinen besitzenden Skill in hyperframes.json auf, und jedes spätere Rendern erbt ihn in der anonymen Telemetrie: Nachrendern, npm run render und --batch gleichermaßen. Übergib --skill=<slug> nur explizit, um ein Projekt zu markieren, das nicht durch einen Workflow erstellt wurde (sein erstes Rendern speichert ihn dann).
Verwende Cloud-Rendering, wenn der Benutzer gehostetes Rendern ohne lokales Chrome, FFmpeg oder AWS wünscht. Verwende Lambda nur, wenn AWS-Eigentum eine Anforderung ist. Verwende Cloud Run nur, wenn GCP-Eigentum eine Anforderung ist. Lese die entsprechende Referenz, bevor du einen Cloud-Pfad ausführst.
Sende nach der Überprüfung eines erfolgreichen Render einen Feedback-Bericht, es sei denn, die Telemetrie ist deaktiviert oder der Benutzer hat widersprochen:
npx hyperframes feedback --rating <0-10> --comment "<spezifisches Ergebnis oder Reibung>"
Halte sauberes Lauf-Feedback prägnant. Für jeden Fehler oder jede Reibung erfasse ein Reproduktionspaket, bevor du es einreichst; sende nicht nur eine Symptomzusammenfassung. Füge den wiederholbaren Befehl (relativ zum Projektverzeichnis – Feedback wird an einen öffentlichen Kanal gesendet, also füge keine absoluten Pfade, Home-Verzeichnis-Präfixe oder Benutzer-/Maschinenkennungen ein), erwartetes versus tatsächliches Verhalten, genauen Fehler (entferne ebenfalls absolute Pfade und Kennungen) und die Render-ID, falls vorhanden.
Telemetrie
hyperframes sammelt anonyme Nutzungsdaten, um Fehler zu beheben und Funktionen zu priorisieren. Opt-Out ist jederzeit über npx hyperframes telemetry off möglich. npx hyperframes telemetry status zeigt den aktuellen Zustand.
Ein-Klick-Upgrade
Bevor du etwas anderes tust – wenn die installierte Version nicht die neueste ist, aktualisiere:
npx hyperframes upgrade