sq-cm/claude-template

HyperFrames CLI

Everything runs through npx hyperframes. Requires Node.js >= 22 and FFmpeg.

Workflow

1. Scaffold — npx hyperframes init my-video
2. Write — author HTML composition (see the hyperframes skill)
3. Lint — npx hyperframes lint
4. Runtime validate — npx hyperframes validate
5. Visual inspect — npx hyperframes inspect
6. Preview — npx hyperframes preview
7. Render — npx hyperframes render

Lint and inspect before preview. 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.

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, note the scaffold uses Tailwind v4.2 via the browser runtime, not Studio's Tailwind v3 setup — check class and theme-token syntax against v4 docs before editing.

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).

Runtime Validation

npx hyperframes validate                  # current directory
npx hyperframes validate ./my-project     # specific project
npx hyperframes validate --json           # machine-readable
npx hyperframes validate --timeout 5000   # slow scripts/media (default 3000 ms)

Loads the composition in headless Chrome and reports JS console errors, missing assets, and WCAG contrast issues (--no-contrast to skip the contrast pass). Run it after lint, before inspect.

validate is deprecated upstream in favour of npx hyperframes check, which runs lint, runtime, layout, motion, and contrast verification in one browser session — either satisfies a "lint and validate" checklist item.

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.)

Asset Preprocessing

npx hyperframes tts, transcribe, and remove-background produce assets (narration audio, word-level transcripts, transparent video) that get dropped into a composition. Each downloads its own model on first run. For voice selection, whisper model rules (the .en-translates-non-English gotcha), output format choice (VP9 alpha WebM vs ProRes), and the TTS → transcribe → captions chain, invoke the hyperframes-media skill.

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.

Other

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