Skip to main content
skill CX Codex

hyperframes-cli · boraoztunc — Claude Code skill: what it does, how to install

hyperframes-cli controls the HyperFrames video pipeline through npx hyperframes, covering scaffolding, layout verification, studio preview, and final rendering.

Apache-2.0 216 installs ★ 484 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add boraoztunc/skills --skill hyperframes-cli -a claude-code
Open on GitHub

What hyperframes-cli does

The skill drives video development using npx hyperframes. It expects Node.js 22 or newer and a local FFmpeg installation. Without FFmpeg in your environment, rendering fails immediately.

The workflow moves through strict validation stages. Scaffolding runs via init with templates like warm-grain or kinetic-type, setting up project assets and browser-based Tailwind v4. Before previewing, lint checks composition attributes and timeline conflicts. Next, inspect launches headless Chrome to flag text spilling out of containers or past canvas borders.

The preview command hosts a local studio server on port 3002 with hot reloading. Final production happens through render, producing MP4 or transparent WebM files with optional Docker isolation for byte-identical output.

What it helps with

  • scaffold an HTML video composition from templates like warm-grain
  • audit typography overflow across timestamps using headless Chrome
  • run a local studio preview server with hot reload
  • render animations to MP4 or transparent WebM

Example prompts for the agent

  • Initialize a new video project called promo using the kinetic-type template
  • Run inspect on my-project to check for text overflow errors
  • Render the final composition to final.mp4 at 60 fps with high quality

How to install hyperframes-cli

1Skills CLI (Vercel)

npx skills add boraoztunc/skills --skill hyperframes-cli -a claude-code

2Manually: put the files in place

~/.claude/skills/hyperframes-cli/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/hyperframes-cli/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about hyperframes-cli

How to install hyperframes-cli in Claude Code?

Run npx skills add boraoztunc/skills --skill hyperframes-cli -a claude-code in your terminal. The skill file installs to ~/.claude/skills/hyperframes-cli/SKILL.md.

What system requirements does hyperframes-cli have?

You need Node.js version 22 or higher and FFmpeg installed in your system PATH. Layout inspection also spins up headless Chrome.

What is the difference between lint and inspect?

The lint command checks HTML files for timeline overlaps and missing composition attributes. The inspect command renders the layout across timestamps in headless Chrome to catch clipped text and boundary overflows.

Source text

SKILL.md · Apache-2.0
---
name: hyperframes-cli
description: HyperFrames CLI dev loop — `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the HyperFrames build/render environment. For asset preprocessing commands (`tts`, `transcribe`, `remove-background`), invoke the `hyperframes-media` skill instead.
---

# 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. **Visual inspect** — `npx hyperframes inspect`
5. **Preview** — `npx hyperframes preview`
6. **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

```bash
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

```bash
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

```bash
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

```bash
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:

```text
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

```bash
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

```bash
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

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

© boraoztunc · Apache-2.0 · boraoztunc/skills

Similar skills

All skills for Frontend and UI →

hyperframes-cli by other authors comes first.

hyperframes-cli heygen-com hyperframes-cli is a Claude Code skill for managing HyperFrames video projects, from scaffolding and frame checks to timeline edits and rendering. The agent invokes it to inspect or build a video. CX Codex +1 1,700,000installs hyperframes-cli calesthio hyperframes-cli guides the HyperFrames video build loop, from composition validation and timeline inspection to AWS Lambda rendering. CX Codex +1 ★ 78,316repo stars hyperframes-cli coco-research The hyperframes-cli skill guides HyperFrames projects from composition checks to preview and rendering. It also helps diagnose build and render failures. CX Codex +1 ★ 328repo stars hyperframes heygen-com hyperframes — a Claude Code skill that renders video from HTML by seeking a paused timeline frame by frame. CX Codex +1 1,600,000installs hyperframes-registry heygen-com hyperframes-registry is a skill that finds and adds editable HyperFrames blocks for transitions, titles, captions, charts, maps, and 3D scenes. It searches the catalog before manual effect building. CX Codex +1 1,400,000installs hyperframes-video-composition calesthio hyperframes-video-composition is a Claude Code skill that orchestrates HTML, CSS, and JS video assembly with HyperFrames. It guides composition briefs, frame specifications, scene timing, and QA. CX Codex +1 161installs hyperframes-sales-demo-builder OneWave-AI hyperframes-sales-demo-builder — a skill for Claude Code, Codex, Cursor and other platforms that builds a prospect-specific demo video in HyperFrames. CX Codex +1 157installs hyperframes-ad-director OneWave-AI hyperframes-ad-director turns a marketing brief into a finished short-form video ad built in HyperFrames: hook, script, storyboard, HTML composition, captions, and voiceover. CX Codex +1 185installs website-to-hyperframes official HeyGen The website-to-hyperframes skill turns a website URL into a HyperFrames video project, covering capture, scripting, storyboarding, voice timing, and validation. CX Codex GP ChatGPT +1 2installs

From the same set22

The whole set →

Project sponsors

Companies that keep this analytics open