Was macht HyperFrames CLI?
Alles läuft über npx hyperframes. Erfordert Node.js >= 22 und FFmpeg.
Workflow
- Gerüst bauen –
npx hyperframes init mein-video - Schreiben – HTML-Komposition verfassen (siehe die
hyperframes-Fähigkeit) - Linten –
npx hyperframes lint - Visuell inspizieren –
npx hyperframes inspect - Vorschau –
npx hyperframes preview - Rendern –
npx hyperframes render
Vor der Vorschau linten und inspizieren. lint erkennt fehlende data-composition-id, überlappende Tracks und nicht registrierte Timeline-Elemente. inspect öffnet die gerenderte Komposition in headless Chrome, durchsucht die Timeline und meldet Text, der aus Blasen/Containern oder der Leinwand ragt.
Gerüst bauen
npx hyperframes init mein-video # interaktiver Assistent
npx hyperframes init mein-video --beispiel warm-grain # Beispiel auswählen
npx hyperframes init mein-video --video clip.mp4 # mit Videodatei
npx hyperframes init mein-video --audio track.mp3 # mit Audiodatei
npx hyperframes init mein-video --beispiel blank --tailwind # mit Tailwind v4 Browser-Laufzeit
npx hyperframes init mein-video --nicht-interaktiv # keine Eingabeaufforderung (CI/Agenten)
Vorlagen: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph.
init erstellt die richtige Dateistruktur, kopiert Medien, transkribiert Audio mit Whisper und installiert KI-Entwicklungsfähigkeiten. Verwende es anstatt Dateien von Hand zu erstellen.
Bei Verwendung von --tailwind rufe die tailwind-Fähigkeit auf, bevor du Klassen oder Theme-Token bearbeitest. Das Gerüst verwendet Tailwind v4.2 über die Browser-Laufzeit, nicht Tailwind v3 von Studio.
Linting
npx hyperframes lint # aktuelles Verzeichnis
npx hyperframes lint ./mein-projekt # bestimmtes Projekt
npx hyperframes lint --ausführlich # Info-Stufen-Funde
npx hyperframes lint --json # maschinenlesbar
Lintet index.html und alle Dateien in compositions/. Meldet Fehler (müssen behoben werden), Warnungen (sollten behoben werden) und Info (mit --ausführlich).
Visuelle Inspektion
npx hyperframes inspect # gerendertes Layout über die Timeline inspizieren
npx hyperframes inspect ./mein-projekt # bestimmtes Projekt
npx hyperframes inspect --json # agentenlesbare Funde
npx hyperframes inspect --samples 15 # dichtere Timeline-Abtastung
npx hyperframes inspect --um 1.5,4,7.25 # explizite Hero-Frame-Zeitstempel
Verwende dies nach lint und validate, besonders bei Kompositionen mit Sprechblasen, Karten, Untertiteln oder enger Typografie. Es meldet:
- Text, der außerhalb des nächsten sichtbaren Containers oder der Blase liegt
- Text, der durch die eigene feste Breite/Höhe abgeschnitten wird
- Text, der außerhalb der Kompositionsleinwand liegt
- Kinder, die aus beschneidenden Containern entkommen
Fehler sollten vor dem Rendern behoben werden. Warnungen werden für die Agentenprüfung angezeigt; füge --streng hinzu, um auch bei Warnungen fehlzuschlagen. Wiederholte statische Probleme werden standardmäßig zusammengefasst, damit die JSON-Ausgabe für LLM-Kontextfenster kompakt bleibt. Wenn ein Überlauf für eine Ein-/Ausgangsanimation beabsichtigt ist, markiere das Element oder den Vorfahren mit data-layout-allow-overflow. Wenn ein dekoratives Element nie geprüft werden soll, markiere es mit data-layout-ignore.
npx hyperframes layout bleibt als Kompatibilitätsalias für denselben visuellen Inspektionsdurchlauf verfügbar.
Vorschau
npx hyperframes preview # aktuelles Verzeichnis bereitstellen
npx hyperframes preview --port 4567 # eigener Port (Standard 3002)
Hot-Reload bei Dateiänderungen. Öffnet das Studio automatisch im Browser.
Wenn du ein Projekt an den Benutzer zurückgibst, verwende die Studio-Projekt-URL, nicht den Pfad zur index.html-Quelle:
http://localhost:<port>/#projekt/<projektname>
Verwende den tatsächlichen Port aus der Vorschau-Ausgabe und den Projektverzeichnisnamen. Beispiel: Nach npx hyperframes preview --port 3017 in codex-openai-video melde http://localhost:3017/#projekt/codex-openai-video.
Behandle index.html nur als Quellcode-Kontext. Es ist in Ordnung, sie als Implementierungsdatei zu verlinken, aber bezeichne sie nicht als Projekt- oder Vorschauoberfläche.
Rendern
npx hyperframes render # Standard-MP4
npx hyperframes render --ausgabe final.mp4 # benannte Ausgabe
npx hyperframes render --qualität entwurf # schnelle Iteration
npx hyperframes render --fps 60 --qualität hoch # endgültige Auslieferung
npx hyperframes render --format webm # transparentes WebM
npx hyperframes render --docker # byte-identisch
| Flag | Optionen | Standard | Hinweise |
|---|---|---|---|
--ausgabe | Pfad | renders/name_zeitstempel.mp4 | Ausgabepfad |
--fps | 24, 30, 60 | 30 | 60fps verdoppelt die Renderzeit |
--qualität | entwurf, standard, hoch | standard | entwurf zum Iterieren |
--format | mp4, webm | mp4 | WebM unterstützt Transparenz |
--arbeiter | 1-8 oder auto | auto | Jeder startet Chrome |
--docker | Flag | aus | Reproduzierbare Ausgabe |
--gpu | Flag | aus | GPU-beschleunigte Codierung |
--streng | Flag | aus | Fehlschlag bei Lint-Fehlern |
--streng-alles | Flag | aus | Fehlschlag bei Fehlern UND Warnungen |
--variablen | JSON-Objekt | — | Überschreibt in data-composition-variables deklarierte Variablen |
--variablen-datei | Pfad | — | JSON-Datei mit Variablenwerten (Alternative zu --variablen) |
--streng-variablen | Flag | aus | Rendern bei nicht deklarierten Schlüsseln oder Typkonflikten abbrechen |
Qualitätsrichtlinie: entwurf während des Iterierens, standard für die Überprüfung, hoch für die endgültige Auslieferung.
Parametrisierte Render: Die Komposition deklariert ihre Variablen auf dem <html>-Root mit data-composition-variables – einem JSON-Array von Deklarationen ({id, typ, label, standard} pro Eintrag), das das Schema definiert. Skripte darin lesen die aufgelösten Werte über window.__hyperframes.getVariables(). Die CLI --variablen '{"titel":"Q4-Bericht"}' ist ein JSON-Objekt, das nach ID schlüsselt und die deklarierten Standardwerte für einen Render überschreibt; fehlende Schlüssel fallen durch, sodass dieselbe Komposition unverändert in der Entwicklungsvorschau und in der Produktion läuft. (Sub-Comp-Hosts können auch pro Instanz mit data-variable-values überschreiben – dieselbe Objektform, beschränkt auf eine Einbindung der Sub-Komposition. Siehe die hyperframes-Fähigkeit für das vollständige Muster.)
Asset-Vorverarbeitung
npx hyperframes tts, transcribe und remove-background erzeugen Assets (Erzähl-Audio, Wort-für-Wort-Transkripte, transparentes Video), die in eine Komposition eingefügt werden. Jedes lädt beim ersten Durchlauf ein eigenes Modell herunter. Für Sprachauswahl, Whisper-Modellregeln (die .en-übersetzt-Nicht-Englisch-Falle), Ausgabeformatwahl (VP9-Alpha-WebM vs. ProRes) und die Kette TTS → Transkribieren → Untertitel rufe die hyperframes-media-Fähigkeit auf.
Fehlerbehebung
npx hyperframes doctor # Umgebung prüfen (Chrome, FFmpeg, Node, Speicher)
npx hyperframes browser # gebündeltes Chrome verwalten
npx hyperframes info # Versions- und Umgebungsdetails
npx hyperframes upgrade # nach Updates suchen
Führe zuerst doctor aus, wenn das Rendern fehlschlägt. Häufige Probleme: fehlendes FFmpeg, fehlendes Chrome, zu wenig Arbeitsspeicher.
Sonstiges
npx hyperframes compositions # Kompositionen im Projekt auflisten
npx hyperframes docs # Dokumentation öffnen
npx hyperframes benchmark . # Render-Performance benchmarken