mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-03 12:54:29 +00:00
James RussoandClaude Opus 4.6
0a0d5d3654
* refactor(skills): consolidate 15 skills into 3 for better trigger reliability Merge 9 GSAP skills (core, timeline, scrolltrigger, plugins, utils, react, frameworks, performance, effects) and 6 HyperFrames skills (compose, captions, tts, audio-reactive, marker-highlight, cli) into 3 consolidated skills: - `gsap` — core API + timelines + performance in SKILL.md; scrolltrigger, plugins, utils, react, frameworks, effects in references/ - `hyperframes` — composition authoring rules in SKILL.md; captions, tts, audio-reactive, marker-highlight in references/ - `hyperframes-cli` — CLI commands (init, lint, preview, render, etc.) Why: With 15 separate skills, agents must correctly trigger the right subset for any task. "Create an animated video with captions" needed 6+ skills to fire — each with ~90% trigger accuracy means ~53% chance of getting all of them. With 3 skills, that same task needs just `hyperframes` + `gsap` (~90% both fire). Progressive disclosure still works via references/ files loaded on demand. Also fixes: CLAUDE.md referenced `window.__GSAP_TIMELINE` (incorrect) — corrected to `window.__timelines`. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * feat(cli): add --skip-skills flag to init command Allow skipping the AI coding skills installation prompt during `hyperframes init` with `--skip-skills`. Useful when skills are already installed or when the user wants to scaffold without them. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(skills): address code review feedback on consolidation Restore content lost during over-compression: - captions: fix overflow to `visible` (not hidden — clips glow effects), add container pattern warning, scale headroom formula, and self-lint placement guidance - audio-reactive: restore sampling frequency pattern (per-frame tl.call loop vs single tween) and textShadow-on-container gotcha - effects/typewriter: restore word rotation, appending words, spacing with static text, and multi-line cursor handoff patterns - effects/audio-visualizer: restore spatial mapping conventions, fetch vs inline loading, WebGL/DOM rendering approaches, and canvas layering - hyperframes-cli: restore --strict-all flag in render flags table Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(cli): update build:copy and template for consolidated skill names - build:copy: reference skills/hyperframes, skills/hyperframes-cli, skills/gsap instead of the old 15 skill directory names - _shared/CLAUDE.md template: update skill table to consolidated names Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
115 lines
4.8 KiB
Markdown
115 lines
4.8 KiB
Markdown
---
|
|
name: hyperframes-cli
|
|
description: HyperFrames CLI tool — hyperframes init, lint, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark. Use when scaffolding a project, linting or validating compositions, previewing in the studio, rendering to video, transcribing audio, generating TTS, or troubleshooting the HyperFrames environment.
|
|
---
|
|
|
|
# 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. **Preview** — `npx hyperframes preview`
|
|
5. **Render** — `npx hyperframes render`
|
|
|
|
Lint before preview — catches missing `data-composition-id`, overlapping tracks, unregistered timelines.
|
|
|
|
## Scaffolding
|
|
|
|
```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.
|
|
|
|
## 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`).
|
|
|
|
## 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.
|
|
|
|
## 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 |
|
|
|
|
**Quality guidance:** `draft` while iterating, `standard` for review, `high` for final delivery.
|
|
|
|
## Transcription
|
|
|
|
```bash
|
|
npx hyperframes transcribe audio.mp3
|
|
npx hyperframes transcribe video.mp4 --model medium.en --language en
|
|
npx hyperframes transcribe subtitles.srt # import existing
|
|
npx hyperframes transcribe subtitles.vtt
|
|
npx hyperframes transcribe openai-response.json
|
|
```
|
|
|
|
## Text-to-Speech
|
|
|
|
```bash
|
|
npx hyperframes tts "Text here" --voice af_nova --output narration.wav
|
|
npx hyperframes tts script.txt --voice bf_emma
|
|
npx hyperframes tts --list # show all voices
|
|
```
|
|
|
|
## 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
|
|
```
|