hyperframes: add HTML/CSS/GSAP as a parallel composition runtime
Separates creative grammar (renderer_family) from technical engine (render_runtime) so HyperFrames can stand alongside Remotion as a first-class runtime instead of masquerading as a Remotion sub-case. Locks runtime choice at proposal stage and enforces it end-to-end: the schemas require it, video_compose routes by it, the reviewer fails closed on silent swaps, and a parametrized contract test walks every pipeline manifest to ensure each planning-stage skill explains the conversation to the user. Adds hyperframes_compose (scaffold/lint/ validate/render/doctor/add_block), a playbook -> CSS style bridge, and vendored HyperFrames Layer 3 skills from commit d291358, pinned via PROVENANCE.md for future re-sync. Final_review now records render_runtime_used and runtime_swap_detected so compose lies are catchable after the fact.
This commit is contained in:
calesthio
@@ -0,0 +1,136 @@
|
||||
---
|
||||
name: hyperframes-cli
|
||||
description: HyperFrames CLI tool — hyperframes init, lint, validate, 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.
|
||||
---
|
||||
|
||||
<!--
|
||||
Vendored into OpenMontage from C:\Users\ishan\Documents\hyperframes\skills\hyperframes-cli\SKILL.md
|
||||
Source commit: d291358 (2026-04-17)
|
||||
See .agents/skills/hyperframes/PROVENANCE.md for re-sync instructions.
|
||||
|
||||
OpenMontage-local edit: added `validate` to the top-line command list and a
|
||||
dedicated "Validation" section — upstream omits it even though the CLI ships it
|
||||
and `hyperframes validate` is the real browser-based contract check (contrast,
|
||||
timelines, assets) that runs before render.
|
||||
-->
|
||||
|
||||
# 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` (static checks)
|
||||
4. **Validate** — `npx hyperframes validate` (browser-based runtime checks + contrast audit)
|
||||
5. **Preview** — `npx hyperframes preview`
|
||||
6. **Render** — `npx hyperframes render`
|
||||
|
||||
Lint catches static issues (missing `data-composition-id`, overlapping tracks, unregistered timelines). Validate catches runtime/visual issues by seeking into the paused composition in a real browser (contrast, broken overlays, missing assets). Run both before render.
|
||||
|
||||
## Validation
|
||||
|
||||
```bash
|
||||
npx hyperframes validate # full validation (static + contrast + contract)
|
||||
npx hyperframes validate --no-contrast # skip WCAG contrast audit when iterating fast
|
||||
npx hyperframes validate --json # machine-readable output
|
||||
```
|
||||
|
||||
Validation seeks to several timestamps in the paused composition, screenshots the page, samples pixels behind every text element to compute WCAG contrast ratios, and verifies runtime contracts (`window.__timelines` registration, `class="clip"` presence, valid `data-*` attributes). Run it before every render — it's cheap and catches issues lint cannot see.
|
||||
|
||||
## 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 --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
|
||||
```
|
||||
Reference in New Issue
Block a user