hyperframes-cli

Plugin-Installation: Führen Sie vor Setup- oder Freshness-Befehlen die Plugin-Ausführungsregeln aus, wenn sich dieses Skill innerhalb eines HyperFrames-Plugins befindet. Bei eigenständigen Installationen gelten die unten stehenden Aktualisierungsanweisungen.

HyperFrames CLI

Führen Sie Befehle als npx hyperframes ... aus, es sei denn, Projektanweisungen geben einen Wrapper vor. Befolgen Sie den Wrapper, falls vorhanden. Das CLI erfordert Node.js 22 oder neuer und FFmpeg.

Entwicklungsschleife

1. Scaffolding: npx hyperframes init <projekt> (zentriert leer). Oder erfassen Sie eine Website. Übergeben Sie --example=<name> nur, um von einem benannten Beispiel zu starten.
2. Die Bewegung finden: Wenn die Anfrage ein Asset, einen Ton, ein Bild, eine Stimme oder eine schnelle visuelle Bearbeitung nennt, lösen Sie dies über /media-use, bevor Sie einen Plan vorschlagen. Bevor Sie manuell eine Bewegung erstellen, suchen Sie nach einem Baustein, der dies bereits tut: npx hyperframes catalog --query "eine Überschrift Zeile für Zeile enthüllen". Fragen Sie nach dem gewünschten Effekt, nicht nach dem Mechanismus, den Sie im Kopf haben. Installieren Sie mit npx hyperframes add <name> (siehe /hyperframes-registry). Nur selbst erstellen, wenn nichts passt.
3. Erstellen: Schreiben Sie die Komposition mit /hyperframes-core. Um zu erfahren, was sich auf der Timeline eines Projekts befindet (Spuren, Clips, Start, Ende, was abgespielt wird), führen Sie npx hyperframes timeline --json aus, anstatt index.html und jede Unterkompositionsdatei zu lesen: Verschachtelte Reihen tragen absolute Haupt-Timeline absStart/absEnd und ihre zugehörige file, nicht nur ihre lokale, pro-Unterkompositions-Zeit. Bevorzugen Sie --json gegenüber der Textform; es verbraucht weniger Tokens bei gleicher oder besserer Korrektheit. Siehe references/upgrade-info-misc.md für Einzeiler, die häufige Fragen beantworten, ohne die gesamte Ausgabe lesen zu müssen.
4. Schnelles Feedback während der Bearbeitung: Führen Sie npx hyperframes lint nach dem ersten HTML-Durchlauf und nach strukturellen Änderungen aus.
5. Den finalen Gate ausführen: Führen Sie npx hyperframes check aus; es führt lint erneut aus, bevor der Browser geöffnet wird. Fügen Sie keinen redundanten eigenständigen lint-Aufruf voran. Fügen Sie --snapshots für kommentierte Übersichtsbilder und das Auffinden von Zuschneidungen hinzu.
6. Unterkompositionen inspizieren: Wenn index.html data-composition-src einbindet, erfassen Sie Mittelpunkt-Snapshots und inspizieren Sie jede eingebundene Szene.
7. Die finale Studio-Vorschau öffnen: Führen Sie npx hyperframes preview --background aus, überprüfen Sie, ob die URL HTTP 200 zurückgibt, übergeben Sie die Timeline-Projekt-URL an den Benutzer und fragen Sie, ob überarbeitet oder gerendert werden soll. Halten Sie es bis zum Ende der Überprüfung aktiv.
8. Nur nach Genehmigung rendern: Verwenden Sie --quality draft während der Iteration, --quality looks für die erste echte Kodierung (CLI-Standard) und --quality delivery für die endgültige Auslieferung.
9. Die Ausgabe überprüfen: Bestätigen Sie, dass die Datei existiert und nicht leer ist. Lesen Sie die zweite Zeile der Render-Zusammenfassung (beginframe vs screenshot, GPU, Phasen-Timings). screenshot + software gpu auf Linux ist der langsame Pfad. ffprobe -v error -show_format -show_streams und vergleichen Sie die Dauer (und fps, falls im Brief festgelegt) mit der root data-duration.

Projekthistorie in Ihrem Zug

Jeder Schreibzugriff auf das Projekt wird als Eintrag gespeichert, der rückgängig gemacht werden kann. Verwenden Sie es nur zu zwei Zeitpunkten, niemals bei jedem Schritt:

• Start eines Zuges: npx hyperframes history begin --who <ihr-name> --label "<was Sie gleich tun werden>", dann npx hyperframes history --since mine --who <ihr-name>, um zu sehen, was die Person seit Ihrem letzten Zug geändert hat. Bauen Sie auf deren Bearbeitungen auf; überschreiben Sie sie niemals.
• Ein Check ist fehlgeschlagen oder die Person sagt, es sei schlechter geworden: npx hyperframes history undo --who <ihr-name> macht Ihren neuesten Zug rückgängig und lässt die Bearbeitungen der Person in Ruhr. Bearbeiten Sie nicht von Hand zurück. Bei einem Konflikt beendet es mit Exit-Code 2 und gibt beide Optionen aus.

Beenden Sie jeden Zug mit npx hyperframes history end, damit Ihre Schreibvorgänge als Ihre eigenen gelesen werden, nicht als "Außerhalb der App geändert". Während ein Zug offen ist, zählt jeder Schreibzugriff auf das Projekt als Ihrer, bis 10 Minuten ohne einen vergangen sind; danach ist der Zug von selbst beendet.

Obligatorische Ersteller-Bearbeitungs-Querverweise

• Bevor Sie einen Zoom, Punch-In/Punch-Out, Reframe, Kamerabewegung oder eine Keyframe-Bewegung erstellen oder diagnostizieren, lesen Sie zuerst /hyperframes-keyframes.
• Vor hyperframes keyframes lesen Sie /hyperframes-keyframes; der Befehl zeigt Animationsverläufe an und diagnostiziert keine Clip-Schnitte.
• Für einen Schnitt, Trim, Splice, Neuordnung oder Quell-Timing-Bearbeitung lesen Sie /hyperframes-core und verwenden Sie dessen Clip-/Timeline-Vertrag.
• Für Einblendung/Ausblendung, Crossfade, Spurverstärkung, Lautstärkeautomatisierung, Ducking, Voiceover-Carve oder FX auf platziertem Audio lesen Sie /hyperframes-audio. Laden Sie core parallel dazu, wenn auch Clip-Platzierung oder Bild-Timing geändert wird.
• Eine Anfrage, die ein Asset, einen Ton, ein Bild, eine Stimme oder eine schnelle visuelle Bearbeitung nennt, wird über /media-use aufgelöst, bevor ein Plan vorgeschlagen wird. Kopieren Sie das Ersteller-Bearbeitungs-Markup aus /hyperframes-core → references/creator-editing-recipes.md.

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

# Erforderlicher finaler 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 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. Verwenden Sie --strict, um Warnungen zu blockieren. validate, inspect und layout bleiben aus Kompatibilitätsgründen Aliasse, dürfen aber nicht in neuen Anweisungen oder Skripten erscheinen.

Vorschau vor dem Rendern

Öffnen Sie die finale Kompositionsvorschau (#project/<name>) erst, nachdem check bestanden hat, um die zusammengestellte Timeline zu überprüfen. Der Plan im Chat und das storyboard.html-Skizzenblatt sind keine Genehmigung des finalen Videos. Rendern erfordert immer die finale Genehmigung, die in hyperframes/references/review-loop.md definiert ist.

Unterkompositions-Smoke-Test

Statische Audits können nicht jeden Einbettungsfehler erkennen. Wenn das Projekt Unterkompositionen verwendet, erfassen Sie mindestens einen sichtbaren Mittelpunkt für jeden Host-Slot:

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

Behandeln Sie winzige, ungestaltete Inhalte, leinwandgroße Symbole, fehlende Hero-Elemente oder Timeout-Fehler bei der Timeline-Registrierung als renderblockierende Einbettungsfehler. Siehe hyperframes-core/references/sub-compositions.md für die entsprechenden Korrekturen.

Agenten-Konventionen

• Durchsuchen Sie den Katalog, bevor Sie Bewegung von Hand schreiben. 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 wird nach Vokabular sortiert, das mit dem Namen, Titel, der Beschreibung und den Tags des Elements geteilt wird, was jede Formulierung übersieht, die nicht die eigene Wortwahl des Katalogs wiederverwendet. Fügen Sie --on-device hinzu, um nach Bedeutung zu sortieren (siehe die Offline-Stufe unten).

• Fragen Sie auf Englisch, auch wenn das Video es nicht ist. Beide Stufen indexieren einen englischen Katalog, daher erzeugt eine Abfrage in einer anderen Schrift keine durchsuchbaren Begriffe und gibt nichts zurück. Beschreiben Sie die Bewegung auf Englisch; der Bildschirmtext bleibt in der Sprache, die das Video benötigt. No searchable words in query bedeutet genau das und ist keine fehlende Komponente; melden Sie es daher nicht als Katalog-Lücke.

• Lesen Sie, welche Stufe geantwortet hat; schließen Sie dies nie aus den Ergebnissen. Mit --json trägt der Umschlag query, tier (on-device oder words), tier_detail, dropped, unindexed, shown, total und results, plus top_score, wenn die antwortende Stufe einen produziert, und warnings, wenn eine Stufe angefordert wurde und nicht ausgeführt werden konnte, oder wenn eine Suche nichts zurückgab und eine bessere Stufe noch auf die Zustimmung von jemandem wartet. Ein schwaches Ergebnis auf words ist zu erwarten; das gleiche Ergebnis auf on-device ist ein Fehler. top_score ist nur On-Device und hat keinen Schwellenwert dahinter: Der Ranker gibt für jede Abfrage den gesamten Katalog in einer bestimmten Reihenfolge zurück, lesen Sie es also als Hinweis, nicht als Bestehen oder Nichtbestehen.

• dropped und unindexed sind entgegengesetzte Abweichungen zwischen dem Registry und dem On-Device-Index, und eine Umformulierung der Abfrage behebt keines von beiden. dropped zählt rankierte Namen, die diese Registry nicht installieren kann, sodass die stärksten Übereinstimmungen verloren gehen. unindexed zählt Registry-Bewegungen, die der Index überhaupt nicht sehen kann, die keine Abfrage jemals zurückgeben kann. Das Aktualisieren der Registry ist für keines von beiden die Antwort: Ihr Manifest trägt 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-device ruft diesen Index erneut ab, wenn unindexed über Null liegt, das ist also das Mittel, das dem Benutzer an die Hand gegeben wird. Eine reine Überdeckungsabweichung (dropped über Null bei unindexed = Null) löst den erneuten Abruf nicht aus; das Löschen von ~/.hyperframes/catalog/ ist der einzige Ausweg. Beide Zählungen beziehen sich auf Namen, nicht auf Ergebnisse, daher kann jeder Wert total überschreiten.

• Wenn eine Suche nichts Nennenswertes zum Installieren zurückbringt, sagen Sie das. npx hyperframes feedback --search-miss "<die von Ihnen ausgeführte Abfrage>" --wanted "<die benötigte Bewegung>" --tier <die antwortende Stufe>. Sie müssen diese Zeile nicht selbst zusammenstellen: catalog --query gibt sie vorausgefüllt aus, und jeder --json-Suche-Umschlag trägt sie als report_gap mit bereits korrekter Abfrage und Stufe – füllen Sie --wanted aus und senden Sie sie ab. Dies ist der einzige Pfad, der eine Abfrage irgendwohin sendet, und es ist ein separater bewusster Befehl, damit catalog --query sein Versprechen, nichts zu senden, einhält. Melden Sie auf beiden Stufen, wann immer die Ergebnisse die Sache nicht erledigen; warten Sie nicht auf die On-Device-Stufe, die einen zugestimmten 33-MB-Download erfordert und daher in den meisten Agentenläufen deaktiviert ist – auf sie zu warten bedeutet, nie zu melden. Die Stufe wird im Bericht mitgeführt, sodass eine Vokabular-Lücke von einer Bedeutungs-Lücke unterscheidbar bleibt, ohne dass Sie beurteilen müssen, welche Sie getroffen haben. Was zurückkommt, ist eine Liste von Bewegungen, die der Katalog noch nicht hat, die direkt gelesen und nicht aus Installationszahlen geschätzt wird, daher ist die relevante Formulierung der gewünschte Effekt, nicht der vorgestellte Elementname. Es trägt keine Bewertung und landet nie in der Bewertungsmetrik.

• Bieten Sie die Offline-Stufe an; aktivieren Sie sie niemals stillschweigend. Ein einmaliger ~33-MB-Download (ein quantisiertes ONNX-Build von bge-small-en-v1.5 plus sein Tokenizer, fest an eine bestimmte Revision gebunden) und die Katalogvektoren aus der Registry, beide zwischengespeichert unter ~/.hyperframes/, weder zum Projekt noch zu einem Paket hinzugefügt. Nach dem Zwischenspeichern sortiert es nach Bedeutung, ohne etwas zu senden. Sagen Sie die Größe laut und lassen Sie die Person entscheiden, übergeben Sie dann --on-device (mit -y, um die Eingabeaufforderung zu überspringen), sobald sie zustimmt. Das interaktive Angebot wird nur bei einem TTY ausgelöst. Bei --json gibt es keine Eingabeaufforderung, aber eine Suche, die nichts gefunden hat, platziert dieselbe Anfrage in warnings. Lesen Sie dieses Array und stellen Sie die Entscheidung dem Benutzer anheim. Wenn die Person fragt, was der Download ist, warum dieses Modell oder was die Maschine verlässt, verweisen Sie sie auf https://hyperframes.heygen.com/developers/catalog-search.

• Bevorzugen Sie --json für Agenten- und CI-Aufrufe. Servermodus 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. Prüfen Sie auf dessen Daten:

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

• Der Nicht-TTY-Modus ist automatisch und erstellt das zentrierte leere Projekt. Übergeben Sie --example nur, um von einem benannten Beispiel zu starten. Verwenden Sie --non-interactive, um auf einem TTY den Flag-Only-Modus zu erzwingen.

• Verwenden Sie eine HYPERFRAMES_RUN_ID für alle Befehle im selben Überprüfungsdurchlauf.

• Wenn der Speicherplatz knapp ist, führen Sie npx hyperframes clean aus (--dry-run zur Vorschau); es entfernt, was tote Render-Versuche hinterlassen haben und Leer-Caches, die sich selbst neu aufbauen, niemals Ausgaben, Quellen oder etwas, das ein laufender Render verwendet. Schreiben Sie QC-Frames in ein temporäres Verzeichnis, nicht in das Projekt.

• Verwenden Sie --strict, --strict-all und --strict-variables, wenn die entsprechenden Warnungen, Variablen oder CI-Bedingungen den Render blockieren müssen.

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

• Wenn ein gehostetes Cloud-Projekt sich dem 200-MB-Upload-Limit nähert oder es überschreitet, verwenden Sie cloud render --dry-run --json und folgen Sie der .hyperframesignore-Untersuchung in references/cloud.md. Ignorieren Sie niemals ein Asset nur, weil es groß ist.

• Rendern Sie niemals nur, weil Prüfungen bestanden sind. Halten Sie bei der finalen Vorschau inne und warten Sie auf Genehmigung.

Studio-gesteuerte Bearbeitungen

Wenn der Benutzer sich auf "dieses Element" oder die aktuelle Auswahl bezieht, fragen Sie Studio ab, anstatt zu raten:

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

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

Render-Optionen

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-gehosteter Zero-Infrastructure-Render	npx hyperframes cloud render
Selbstverwalteter verteilter AWS-Render	`npx hyperframes l

…

[gekürzt zur Übersetzung]