WaterrrForever
8089f0049c
* feat(skills): publish reverse-any-video, render it at high quality, and stop on a stuck shot From Wanbi's Pro test of reverse-any-video (11-01, checked against 0.9.2): - A standard install never found the skill: it was internal, and /hyperframes did not route to it. It is now an on-demand skill on every catalog surface, and the routing line names it. - The cloud render in SKILL.md had no --quality high, so the final rendered at standard. - A re-shoot that stayed pending had no rule; the run waited four hours. people.md now runs the command once more after generate's 30-minute stop, then treats the shot as failed. * feat(cli): generate takes a language for --voice, so a Pro sign-in gets a HeyGen voice Wanbi's Pro run fell back to Kokoro: --voice needed an id, and the only way to list ids was the separate heygen CLI and its own login. /v3/voices answers on the HyperFrames sign-in, so: - --voice <language> picks HeyGen's first public voice in it and names it in the output. - A missing --voice lists six English voices to pick from instead of a bare error. - A voice id still goes straight through, with no extra call. * fix(cli): a voice picked by language stays with its request across re-runs Rames: `--voice Chinese` re-picked HeyGen's first voice on every run, and the voice is part of the body and the idempotency key. If the catalog reordered while a job was pending, the same command could start a second paid job instead of resuming the first. The pick is now bound to the request (every field, plus the account scope a job bills) in the project's heygen-jobs.jsonl, or the CLI config dir outside a project, and a re-run reuses it. Regression: a pending timeout, a reordered catalog, the same command, for voice and avatar; the second POST keeps the voice, body and key. * fix(cli): a voice pick waits for a known account instead of binding to none Rames: when /v3/users/me failed, senderScope() was null and the pick was bound to an empty scope; once the account came back, the same command missed that binding and could pick another voice and paid key. pickVoice now stops before picking or posting while the account is unknown, and never reads or writes a blank-account binding. Regressions, both directions: unknown then known refuses with no POST, then picks once; known then unknown refuses the re-run with no second POST, then resumes with the same body and key. Also README: a non-interactive install gets all 8 skills, not 7.
6.8 KiB
Hyperframes
Open-source video rendering framework: write HTML, render video.
Skills
This repo ships AI agent skills via vercel-labs/skills. Install them before writing compositions — they encode framework-specific patterns that generic docs don't cover. Default to the core set (/hyperframes, /hyperframes-cli, /hyperframes-registry, /media-use); install everything only when the user explicitly asks for the full set.
npx hyperframes skills update # default: installs/refreshes the core set plus anything already installed
npx hyperframes skills # all 8 published skills at once
npx skills add heygen-com/hyperframes # interactive picker (terminal only; repo-internal skills are excluded by default)
Make any video by asking for it; the /hyperframes skill carries the contract and the references (film, captions, overlays, motion, look). Read it first.
/hyperframes— read first for any request to make, edit, animate or render a video, motion graphic, captions or overlays with HyperFrames (HTML rendered to video). Holds the render contract and the work loop, and points to the references for format, motion, look, captions, whole films and storyboards./hyperframes-cli— the HyperFrames CLI by job: scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history; plus reading its JSON and recovering from build or render failures./hyperframes-registry— about 450 ready-made blocks and components installed as editable source. Use before hand-building any named visual; also forhyperframes addandcatalog./media-use— get or make any media for a video (music, sound effects, images, voiceover, avatar and generated video, transcripts, cutouts, colour grades) with HeyGen or free local tools, and mix placed audio./figma— bring Figma into a video: rendered assets, brand tokens, components, storyboard frames as reconstructed motion./slideshow— a presentation, pitch deck or interactive deck. Output is a navigable deck, not a rendered MP4./remotion-to-hyperframes— bring existing video code or footage into HyperFrames (Remotion first; also Motion Canvas, Lottie, Three.js, canvas, or renders from other tools) and verify it frame by frame against the original./reverse-any-video— rebuild any video file as an editable HyperFrames project (motion graphics, talking heads, live action or AI-generated footage) and check the render against the original frame by frame. A HyperFrames Pro feature.
Issue and PR triage
Read TRIAGE.md before classifying issues, advertising contribution work, or triaging PRs. Check current source and overlapping PRs; keep difficulty, readiness, and ownership separate. Apply changes only within the task's authorization and verify the resulting GitHub state.
Build & Test
bun install # Install dependencies (NOT pnpm — do not create pnpm-lock.yaml)
bun run build # Build all packages
bun run test # Run all tests
Packages load each other through their exports. Under Node, core, parsers,
lint and studio-server resolve to dist/, and player always loads its built
bundle. Run bun run build once in a fresh worktree, before any package's
tests or typecheck. After editing a package that another package imports, run
that package's build again before the dependent package's tests. Core's
src/generated/ is git-ignored build output: if you see
Cannot find module '../generated/runtime-inline', run
bun run build:hyperframes-runtime.
One file: bun run --cwd packages/<pkg> test <path>. Each package's test
script picks its runner (vitest in most, bun test in aws-lambda and
gcp-cloud-run). Producer is the exception: a file that imports bun:test runs
with bun test <file>, any other with bunx vitest run <file>. Root scripts/*.test.mjs run through bun run test:scripts,
which is an explicit list in package.json. CI's test-reachability check fails
any test file that no runner reaches.
Linting & Formatting
Uses oxlint and oxfmt (not eslint, not prettier, not biome).
node_modules/.bin/oxlint <files> # Lint
node_modules/.bin/oxfmt <files> # Format
node_modules/.bin/oxfmt --check <files> # Check formatting (CI / pre-commit)
Always lint and format changed files before committing. Lefthook pre-commit hooks enforce this automatically.
Composition Validation
After creating or editing any .html composition:
npx hyperframes lint # Static HTML structure check
npx hyperframes check # Browser gate (headless Chrome — runtime errors, layout, motion, WCAG contrast)
Both must pass before previewing or considering work complete.
Project Structure
packages/
cli/ → hyperframes CLI (create, preview, lint, render)
core/ → Types, parsers, generators, linter, runtime, frame adapters
engine/ → Seekable page-to-video capture engine (Puppeteer + FFmpeg)
player/ → Embeddable <hyperframes-player> web component
producer/ → Full rendering pipeline (capture + encode + audio mix)
shader-transitions/ → WebGL shader transitions for compositions
studio/ → Browser-based composition editor UI (read packages/studio/AGENTS.md first)
registry/
blocks/ → Installable sub-composition scenes (50+)
components/ → Installable effects and snippets
examples/ → Starter project templates
docs/ → Mintlify documentation site (hyperframes.heygen.com)
skills/ → AI agent skill definitions
Key Conventions
- Package manager: bun (not pnpm, not npm for workspace operations)
- Commit format: Conventional commits (
feat:,fix:,docs:,refactor:,test:) - TypeScript: Avoid
anyandas Tassertions. Prefer type guards and narrowing. - Compositions: HTML files with
data-*attributes. Clips needclass="clip". Register one paused GSAP root timeline per composition onwindow.__timelines. Scene timelines manually added to that root must not be paused, or they will not advance when the root is seeked. - Frame Adapters: Animation runtimes plug in via the seek-by-frame adapter pattern. GSAP is the primary adapter.
- Deterministic rendering: No
Date.now(), no unseededMath.random(), no render-time network fetches. - Docs ship with the change: a PR that adds or changes a CLI command, flag, or user-visible behavior updates
docs/in the same PR. A new command also goes in "Find your command" indocs/packages/cli.mdx(CI checks it).
Documentation
- Docs: https://hyperframes.heygen.com/introduction
- Catalog (50+ blocks): https://hyperframes.heygen.com/catalog/blocks/data-chart