hyperframes-cli

name

hyperframes-cli

description

HyperFrames CLI dev loop for scaffolding, validation, snapshots, preview, rendering, and environment troubleshooting. Use Prometheus's bundled wrapper inside the Prometheus source tree so FFmpeg and FFprobe are exposed correctly; use ambient `npx hyperframes` only for standalone projects outside Prometheus. Route media sourcing, TTS, transcription, captions, and background removal through `media-use`.

HyperFrames CLI

Command entrypoint

Inside the Prometheus source tree, run the committed wrapper:

node <PROMETHEUS_ROOT>/scripts/run-hyperframes.js <command> [...args]

The wrapper resolves Prometheus's bundled @ffmpeg-installer/ffmpeg and @ffprobe-installer/ffprobe, prepends their directories to the child PATH, and sets FFMPEG_PATH / FFPROBE_PATH. Do not diagnose the renderer from an ambient npx hyperframes doctor result when this wrapper is available; test through the same entrypoint the app ships.

For a standalone project outside Prometheus, use npx hyperframes. All examples below use that portable form; substitute the wrapper command when working in Prometheus.

Run doctor --json before rendering and inspect the individual FFmpeg, FFprobe, and Chrome checks. An overall ok: false can be caused by an available CLI update or missing optional Docker even when local MP4 rendering is healthy.

Workflow

1. Scaffold — npx hyperframes init my-video
2. Write — author HTML composition (see the hyperframes skill)
3. Copy assets — place real images/video/audio under the project with stable relative paths
4. Lint — npx hyperframes lint
5. Validate — npx hyperframes validate when available / required by the project
6. Visual inspect — npx hyperframes inspect, plus --at hero timestamps for important frames
7. Preview — npx hyperframes preview when interactive review is useful
8. Render — npx hyperframes render --output final.mp4
9. Verify exported MP4 — sample frames from the actual final file before presenting

Lint, validate, and inspect before preview/render. lint catches missing data-composition-id, overlapping tracks, and unregistered timelines. inspect opens the rendered composition in headless Chrome, seeks through the timeline, and reports text spilling out of bubbles/containers or off the canvas. Export verification is a no-ship gate: output-file existence is not proof that the rendered MP4 is good.

For final delivery or frozen-output recovery, read references/qa-and-export-verification.md.

Scaffolding

npx hyperframes init my-video                        # interactive wizard
npx hyperframes init my-video --example warm-grain   # pick an example
npx hyperframes init my-video --video clip.mp4        # with video file
npx hyperframes init my-video --audio track.mp3       # with audio file
npx hyperframes init my-video --example blank --tailwind # with Tailwind v4 browser runtime
npx hyperframes init my-video --non-interactive       # skip prompts (CI/agents)

Templates: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph.

init creates the right file structure, copies media, transcribes audio with Whisper, and installs AI coding skills. Use it instead of creating files by hand.

When using --tailwind, invoke the tailwind skill before editing classes or theme tokens. The scaffold uses Tailwind v4.2 via the browser runtime, not Studio's Tailwind v3 setup.

Linting

npx hyperframes lint                  # current directory
npx hyperframes lint ./my-project     # specific project
npx hyperframes lint --verbose        # info-level findings
npx hyperframes lint --json           # machine-readable

Lints index.html and all files in compositions/. Reports errors (must fix), warnings (should fix), and info (with --verbose).

Visual Inspect

npx hyperframes inspect                 # inspect rendered layout over the timeline
npx hyperframes inspect ./my-project    # specific project
npx hyperframes inspect --json          # agent-readable findings
npx hyperframes inspect --samples 15    # denser timeline sweep
npx hyperframes inspect --at 1.5,4,7.25 # explicit hero-frame timestamps

Use this after lint and validate, especially for compositions with speech bubbles, cards, captions, or tight typography. It reports:

• Text extending outside the nearest visual container or bubble
• Text clipped by its own fixed-width/fixed-height box
• Text extending outside the composition canvas
• Children escaping clipping containers

Errors should be fixed before rendering. Warnings are surfaced for agent review; add --strict to fail on warnings too. Repeated static issues are collapsed by default so JSON output stays compact for LLM context windows. If overflow is intentional for an entrance/exit animation, mark the element or ancestor with data-layout-allow-overflow. If a decorative element should never be audited, mark it with data-layout-ignore.

npx hyperframes layout remains available as a compatibility alias for the same visual inspection pass.

Previewing

npx hyperframes preview                   # serve current directory
npx hyperframes preview --port 4567       # custom port (default 3002)

Hot-reloads on file changes. Opens the studio in your browser automatically.

When handing a project back to the user, use the Studio project URL, not the source index.html path:

http://localhost:<port>/#project/<project-name>

Use the actual port from the preview output and the project directory name. For example, after npx hyperframes preview --port 3017 in codex-openai-video, report http://localhost:3017/#project/codex-openai-video.

Treat index.html as source-code context only. It is fine to link it as an implementation file, but do not label it as the project or preview surface.

Rendering

npx hyperframes render                                # standard MP4
npx hyperframes render --output final.mp4             # named output
npx hyperframes render --quality draft                # fast iteration
npx hyperframes render --fps 60 --quality high        # final delivery
npx hyperframes render --format webm                  # transparent WebM
npx hyperframes render --docker                       # byte-identical

Flag	Options	Default	Notes
--output	path	renders/name_timestamp.mp4	Output path
--fps	24, 30, 60	30	60fps doubles render time
--quality	draft, standard, high	standard	draft for iterating
--format	mp4, webm	mp4	WebM supports transparency
--workers	1-8 or auto	auto	Each spawns Chrome
--docker	flag	off	Reproducible output
--gpu	flag	off	GPU-accelerated encoding
--strict	flag	off	Fail on lint errors
--strict-all	flag	off	Fail on errors AND warnings
--variables	JSON object	—	Override variable values declared in data-composition-variables
--variables-file	path	—	JSON file with variable values (alternative to --variables)
--strict-variables	flag	off	Fail render on undeclared keys or type mismatches in --variables

Quality guidance: draft while iterating, standard for review, high for final delivery.

Parametrized renders: the composition declares its variables on the <html> root with data-composition-variables — a JSON array of declarations ({id, type, label, default} per entry) that defines the schema. Scripts inside read the resolved values via window.__hyperframes.getVariables(). The CLI --variables '{"title":"Q4 Report"}' is a JSON object keyed by id that overrides those declared defaults for one render; missing keys fall through, so the same composition runs unchanged in dev preview and in production. (Sub-comp hosts can also override per-instance with data-variable-values — same object shape, scoped to one mount of the sub-composition. See the hyperframes skill for the full pattern.)

Export Verification — No-Ship Gate

Never call a render finished just because npx hyperframes render exited or final.mp4 exists. Verify the actual exported MP4 before final response:

• sample frames from the final MP4, not the source HTML or preview page;
• confirm duration/frame count is plausible for the requested length;
• confirm sampled frames are not black, blank, or missing the main composition;
• confirm requested logos, text, and primary assets appear in sampled frames;
• if extraction fails, the file is implausibly tiny, frames are black/empty, or required visible assets are missing, treat the export as failed and keep fixing.

The final response for a rendered HyperFrames video should include: project path, source index.html, exported MP4 path, checks run, export frame-verification status, and any accepted non-fatal warnings.

Asset Preprocessing

npx hyperframes tts, transcribe, and remove-background can produce project assets, but capability selection and preflight belong to media-use. Use its provider doctor and supported fallbacks before promising local generation. It owns voice selection, transcription language rules, captions, and the TTS → transcript chain.

Troubleshooting

npx hyperframes doctor       # check environment (Chrome, FFmpeg, Node, memory)
npx hyperframes browser      # manage bundled Chrome
npx hyperframes info         # version and environment details
npx hyperframes upgrade      # check for updates

Run doctor first if rendering fails. Common issues: missing FFmpeg, missing Chrome, low memory.

Prometheus Windows runtime notes

Read references/windows-runtime.md when wrapper discovery, Node, Chrome, or encoder behavior differs from a standalone project.

• FFmpeg not found: First rerun with <PROMETHEUS_ROOT>/scripts/run-hyperframes.js. It exposes the encoders already bundled with Prometheus; no system-wide install is needed. Treat failure through that wrapper as the real blocker.
• Node version: Compare the installed version with the CLI's declared engine requirement. Treat engine warnings separately from actual render failures.
• PowerShell syntax: Do not assume && works in Prometheus Windows PowerShell runs. Use separate run_command calls or PowerShell-native $LASTEXITCODE chaining.
• Install checks: Do not treat missing node_modules/@hyperframes alone as proof HyperFrames cannot run; determine whether the workflow uses npx hyperframes, a local package, or Prometheus-bundled Creative/HyperFrames tooling.
• Duplicate media warning: duplicate_media_discovery_risk is not automatically fatal when it comes from intentional repeated static logo/image use and render plus inspect pass. Fix it when it indicates accidentally stacked or duplicated media/video nodes.
• Native Prometheus tool errors: If first-class Creative/HyperFrames QA/export errors with ReferenceError: __name is not defined or exports a black/empty MP4, preserve the authored source and continue via the real CLI project path rather than claiming success.

Other

npx hyperframes compositions   # list compositions in project
npx hyperframes docs           # open documentation
npx hyperframes benchmark .    # benchmark render performance