mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-08 10:46:06 +00:00
Vance Ingalls
ad2d63db32
## Summary **Skill install targets (original):** - Add project-level skill install targets: Windsurf, Cline, Roo Code, Trae (opt-in via flag) - Split install logic into global vs project-level - Fix lint false positive: timed tags with `data-composition-id` no longer flagged by media rule **Skill system cleanup (folded from #189):** - Delete `install-skills.ts` (~485 lines) — remove custom installation wrapper entirely - Strip skill logic from `init` — no more project-level `.claude/skills/` copies, no `--skip-skills` flag; replaced with post-scaffold message: `npx skills add heygen-com/hyperframes` - Front-load SKILL.md trigger words — all 5 skill descriptions rewritten so activation language comes first (~150 chars) - Update CLAUDE.md — install instructions now point to [vercel-labs/skills](https://github.com/vercel-labs/skills) - Fix `.claude/settings.json` — pre-commit hook changed from `pnpm` to `bun` ## Test plan - [ ] `npx hyperframes skills` → "Unknown command skills" - [ ] `npx hyperframes init test --template blank --non-interactive --skip-transcribe` → prints `npx skills add heygen-com/hyperframes` - [ ] `grep -r "install-skills" packages/cli/src/` → no results - [ ] All 5 `skills/*/SKILL.md` have front-loaded descriptions 🤖 Generated with [Claude Code](https://claude.com/claude-code)
120 lines
5.7 KiB
Markdown
120 lines
5.7 KiB
Markdown
---
|
|
name: hyperframes-cli
|
|
description: Preview, render, lint, validate, scaffold, or troubleshoot HyperFrames compositions. Also use after finishing a composition — lint and preview are the natural next steps.
|
|
---
|
|
|
|
# HyperFrames CLI
|
|
|
|
The CLI turns HTML compositions into previews and rendered video. Everything runs through `npx hyperframes`.
|
|
|
|
```bash
|
|
npx hyperframes <command>
|
|
```
|
|
|
|
Requires Node.js >= 22 and FFmpeg. Run `npx hyperframes doctor` if anything fails.
|
|
|
|
## Workflow
|
|
|
|
The natural sequence when building a composition:
|
|
|
|
1. **Scaffold** — `npx hyperframes init my-video` (new projects only)
|
|
2. **Write** — author HTML composition (see `compose-video` skill)
|
|
3. **Lint** — `npx hyperframes lint` to catch structural errors
|
|
4. **Preview** — `npx hyperframes preview` to see it live in the studio
|
|
5. **Render** — `npx hyperframes render` to export video
|
|
|
|
**Lint before preview.** It catches missing `data-composition-id`, overlapping tracks on the same `data-track-index`, unregistered timelines, and other structural issues that silently produce broken output. A 2-second lint saves minutes debugging a blank screen. Both `preview` and `render` auto-lint, but linting explicitly after editing gives you a chance to fix issues without waiting for the server or renderer to spin up.
|
|
|
|
## Scaffolding New Projects
|
|
|
|
```bash
|
|
npx hyperframes init my-video # interactive wizard
|
|
npx hyperframes init my-video --template warm-grain # pick a template
|
|
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 --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 — the template includes boilerplate that's easy to forget.
|
|
|
|
## Linting
|
|
|
|
```bash
|
|
npx hyperframes lint # current directory
|
|
npx hyperframes lint ./my-project # specific project
|
|
npx hyperframes lint --verbose # include info-level findings
|
|
npx hyperframes lint --json # machine-readable output for scripting
|
|
```
|
|
|
|
Lints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (with `--verbose`).
|
|
|
|
**When to lint:**
|
|
|
|
- After writing or editing any composition file — always
|
|
- Before rendering — `render` blocks on errors with `--strict`, but linting first is faster
|
|
- After timing changes — overlapping clips on the same track are a common mistake
|
|
|
|
## Previewing in the Studio
|
|
|
|
```bash
|
|
npx hyperframes preview # serve current directory
|
|
npx hyperframes preview ./my-project # specific project
|
|
npx hyperframes preview --port 4567 # custom port (default 3002)
|
|
```
|
|
|
|
Opens the studio in your browser automatically. Hot-reloads on file changes. Run from the project root (directory containing `index.html`).
|
|
|
|
## Rendering to Video
|
|
|
|
```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 -o hd.mp4 # high quality
|
|
npx hyperframes render --format webm -o overlay.webm # transparent WebM
|
|
npx hyperframes render --docker -o deterministic.mp4 # reproducible
|
|
```
|
|
|
|
| Flag | Options | Default | Notes |
|
|
| -------------- | --------------------- | ---------------------------- | ------------------------------------- |
|
|
| `--output` | path | renders/name_timestamp.mp4 | Output file path |
|
|
| `--fps` | 24, 30, 60 | 30 | 60fps doubles render time |
|
|
| `--quality` | draft, standard, high | standard | Use draft while iterating |
|
|
| `--format` | mp4, webm | mp4 | WebM supports transparency |
|
|
| `--workers` | 1-8 or auto | auto (half CPU cores, max 4) | Each spawns a Chrome process |
|
|
| `--docker` | flag | off | Byte-identical output across machines |
|
|
| `--gpu` | flag | off | GPU-accelerated encoding |
|
|
| `--strict` | flag | off | Fail on lint errors |
|
|
| `--strict-all` | flag | off | Fail on errors AND warnings |
|
|
|
|
**Quality guidance:**
|
|
|
|
- `draft` while iterating on timing and layout — fast feedback
|
|
- `standard` for review and most deliverables
|
|
- `high` only for final delivery where render time doesn't matter
|
|
|
|
## Troubleshooting
|
|
|
|
```bash
|
|
npx hyperframes doctor # check environment (Chrome, FFmpeg, Node, memory, disk)
|
|
npx hyperframes browser # manage bundled Chrome installation
|
|
npx hyperframes info # version and environment details
|
|
npx hyperframes upgrade # check for updates
|
|
```
|
|
|
|
Run `doctor` first if rendering fails or produces unexpected results. Common issues:
|
|
|
|
- Missing FFmpeg → `brew install ffmpeg`
|
|
- Missing Chrome → `npx hyperframes browser ensure`
|
|
- Low memory → close other apps (each render worker uses ~256MB)
|
|
|
|
## Other Commands
|
|
|
|
```bash
|
|
npx hyperframes compositions # list compositions in current project
|
|
npx hyperframes docs # open documentation in browser
|
|
npx hyperframes benchmark . # benchmark render performance
|
|
```
|