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
npx skills add boraoztunc/skills --skill hyperframes-cli -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/hyperframes-cli/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/hyperframes-cli/
1Skills CLI (Vercel)
npx skills add boraoztunc/skills --skill hyperframes-cli -a codex2Manually: put the files in place
.agents/skills/hyperframes-cli/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add boraoztunc/skills --skill hyperframes-cli -a cursor2Manually: put the files in place
.cursor/skills/hyperframes-cli/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install boraoztunc/skills hyperframes-cli2Manually: put the files in place
.github/skills/hyperframes-cli/SKILL.md1Skills CLI (Vercel)
npx skills add boraoztunc/skills --skill hyperframes-cli -a gemini-cli2Platform CLI
gemini skills install https://github.com/boraoztunc/skills --path hyperframes-cliManually: put the files in place
.devin/skills/hyperframes-cli/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add boraoztunc/skills --skill hyperframes-cli -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.