mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-03 04:38:33 +00:00

Files

T

James 051e985868 refactor(skills): split asset preprocessing out of hyperframes-cli

Move tts/transcribe/remove-background guidance into a new
hyperframes-media sibling skill so the CLI skill stays focused on
the dev loop (init/lint/inspect/preview/render/doctor).

Two motivations:

1. Description bloat. The CLI skill listed every subcommand as a
   trigger keyword, which made agents auto-load it for any mention
   of audio, transcription, or backgrounds — even when the task
   was just rendering a composition.
2. Body bloat. Voice tables, the .en-translates-non-English
   whisper rule, and codec selection guidance all loaded on
   every CLI invocation. With three preprocessing commands now
   in the CLI (tts, transcribe, remove-background), this is only
   going to grow.

The split keeps a single sibling (hyperframes-media), not three:
the commands share a workflow (preprocess asset → drop into
composition) and the same first-run-downloads-a-model pattern,
so they belong together. CLI skill now references hyperframes-media
from a one-paragraph "Asset Preprocessing" stub.

Doc references updated in README.md, CLAUDE.md,
docs/quickstart.mdx, and docs/guides/prompting.mdx.

2026-05-04 21:59:35 +00:00

3.9 KiB

Raw Blame History

Hyperframes

Open-source video rendering framework: write HTML, render video.

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)
  studio/    → Browser-based composition editor UI

Development

bun install     # Install dependencies
bun run build   # Build all packages
bun run test    # Run tests

This repo uses bun, not pnpm. Do NOT run pnpm install — it creates a pnpm-lock.yaml that should not exist. Workspace linking relies on bun's resolution from "workspaces" in root package.json.

Linting & Formatting

This project uses oxlint and oxfmt (not biome, not eslint, not prettier).

bunx oxlint <files>        # Lint
bunx oxfmt <files>         # Format (write)
bunx oxfmt --check <files> # Format (check only, used by pre-commit hook)

Always run both on changed files before committing. The lefthook pre-commit hook runs bunx oxlint and bunx oxfmt --check automatically.

Adding CLI Commands

When adding a new CLI command:

Define the command in packages/cli/src/commands/<name>.ts using defineCommand from citty
Export examples in the same file — export const examples: Example[] = [...] (import Example from ./_examples.js). These are displayed by --help.
Register it in packages/cli/src/cli.ts under subCommands (lazy-loaded)
Add to help groups in packages/cli/src/help.ts — add the command name and description to the appropriate GROUPS entry. Without this, the command won't appear in hyperframes --help even though it works.
Document it in docs/packages/cli.mdx — add a section with usage examples and flags.
Validate by running npx tsx packages/cli/src/cli.ts --help (command appears in the list) and npx tsx packages/cli/src/cli.ts <name> --help (examples appear).

Regression Test Golden Baselines (producer)

packages/producer/tests/<name>/output/output.mp4 baselines MUST be generated inside Dockerfile.test, not on your host. CI renders inside that Docker image with a specific Chrome + ffmpeg build; pixel-level output drifts across different host Chrome/ffmpeg versions and will fail PSNR at dozens of checkpoints even when the code is correct.

# Build the test image once:
docker build -t hyperframes-producer:test -f Dockerfile.test .

# Generate or update a baseline (runs the harness with --update inside Docker):
bun run --cwd packages/producer docker:test:update <test-name>

Never run bun run --cwd packages/producer test:update directly from the host to capture a baseline that will be committed — the resulting output.mp4 will not match CI. Use it only for local-only experimentation.

Skills

Composition authoring (not repo development) is guided by skills installed via npx skills add heygen-com/hyperframes. See skills/ for source. Invoke /hyperframes, /hyperframes-cli, /hyperframes-registry, /tailwind, or /gsap when authoring compositions. Use /tailwind for projects created with hyperframes init --tailwind so agents follow the pinned Tailwind v4 browser-runtime contract instead of Studio's Tailwind v3 setup. Use /animejs, /css-animations, /lottie, /three, or /waapi when a composition uses those first-party runtime adapters. Invoke /hyperframes-media for asset preprocessing (TTS narration, audio/video transcription, background removal for transparent overlays) — these commands have their own skill so the CLI skill stays focused on the dev loop. When a user provides a website URL and wants a video, invoke /website-to-hyperframes — it runs the full 7-step capture-to-video pipeline.

3.9 KiB Raw Blame History