mirror of https://github.com/hanzoai/frames.git synced 2026-09-24 00:08:03 +00:00

Files

T

zooqueen bb68594c65 chore: cut the vendor out of the registry, CI, skill mirrors, and root docs

The 217 catalog preview URLs pointed at static.heygen.ai, which now answers
403 Access Denied. The manifests carry no preview rather than a URL that
cannot resolve; scripts/generate-catalog-previews.ts regenerates the files
whenever we have somewhere of our own to serve them from.

Social-card blocks introduce Hanzo, not HeyGen, and the avatar they ship is
the Frames mark instead of the vendor logo. ui-3d-reveal drops the embedded
vendor logo, its hg- class prefix, and the app.heygen.com framing.

.github/workflows ran on GitHub-hosted runners, published to npm with a
repo-held token, and synced skills to clawhub.ai/heygen-com. CI runs from
.hanzo/workflows on the git.hanzo.ai fleet, so the tree goes; the issue and
patch templates stay, pointed at our forge.

The changelog-video mirrors synthesize with `frames tts` and time words with
`frames transcribe` — local models, no key, no account — in place of the
HeyGen CLI and its pinned voice, and ship Inter and JetBrains Mono in place
of two licensed brand faces we have no right to redistribute.

Dockerfile.test filtered on the @hyperframes scope and a runtime script name
that no longer exist, so it built nothing.

2026-08-13 17:14:11 -07:00

6.1 KiB

Raw Blame History

Frames

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 — the /frames router installs each creation workflow on demand; install everything only when the user explicitly asks for the full set.

npx @hanzo/frame skills update                        # default: installs/refreshes the core set — workflows install on demand
npx skills add hanzoai/frames --full-depth   # interactive picker (terminal only — non-interactive without --skill installs everything)

Creation workflows route through one entry skill — read /frames first: it orients you to the whole surface, confirms the brief up front (the intent layer), and maps "make me a…" intent — usually a video, but also a navigable deck (/slideshow) or a composition port (/remotion-to-frames) — to a concrete workflow. Consult it before invoking a specific workflow:

/product-launch-video — any website URL (or a pre-written script / text brief in no-capture mode) → a product launch / promo video, or a site tour / showcase featuring the site's own captured screens; up to ~3 min (sweet spot ~30-90s).
/faceless-explainer — arbitrary text, no URL and no website capture → faceless explainer, up to ~3 min (sweet spot ~30-90s); every visual is LLM-invented (typography / abstract graphics / diagram / data-viz).
/embedded-captions — an existing talking-head video (MP4) → the same footage with captions / subtitles added (verbatim rail + embedded climax, or pure-cinematic embed); the footage itself is untouched (no NLE-style editing).
/talking-head-recut — an existing talking-head / interview / podcast video (MP4) → the same footage packaged with designed graphic overlays (kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, pip) synced to the transcript; the clip plays unchanged underneath, footage untouched. For plain captions/subtitles → /embedded-captions.
/pr-to-video — a GitHub PR (URL / owner/repo#N / "this PR") → code-change explainer, up to ~3 min (changelog / feature reveal / fix / refactor). A PR link, not a product website.
/motion-graphics — a short (typically under 10s) design-led motion graphic, motion-is-the-message, no narration: kinetic type, a stat / number count-up, a chart, a logo sting, a lower-third / overlay, or an animated tweet / headline / captured-page highlight; rendered to MP4 or a transparent overlay. Longer / narrated / custom → /general-video.
/music-to-video — a music track (audio file, or video to pull audio from) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid.
/slideshow — a presentation / pitch deck / interactive deck — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video.
/general-video — fallback for any other video creation (title card, longer brand / sizzle reel, multi-scene montage, static loop, custom composition) and the home of companion mode — co-create with the full Frames toolbox; the original frames flow — design → plan → layout → build → validate, any length.

Porting an existing composition? /remotion-to-frames translates a Remotion (React) video composition into Frames HTML — a source migration, separate from the creation workflows above.

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

Linting & Formatting

Uses oxlint and oxfmt (not eslint, not prettier, not biome).

bunx oxlint <files>        # Lint
bunx oxfmt <files>         # Format
bunx 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 @hanzo/frame lint       # Static HTML structure check
npx @hanzo/frame check      # Browser gate (headless Chrome — runtime errors, layout, motion, WCAG contrast)

Both must pass before previewing or considering work complete.

Project Structure

packages/
  cli/                  → frames CLI (create, preview, lint, render)
  core/                 → Types, parsers, generators, linter, runtime, frame adapters
  engine/               → Seekable page-to-video capture engine (Puppeteer + FFmpeg)
  player/               → Embeddable <frames-player> web component
  producer/             → Full rendering pipeline (capture + encode + audio mix)
  shader-transitions/   → WebGL shader transitions for compositions
  studio/               → Browser-based composition editor UI
registry/
  blocks/               → Installable sub-composition scenes (50+)
  components/           → Installable effects and snippets
  examples/             → Starter project templates
docs/                   → Mintlify documentation site (frames.hanzo.ai)
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 any and as T assertions. Prefer type guards and narrowing.
Compositions: HTML files with data-* attributes. Clips need class="clip". GSAP timelines must be paused and registered on window.__timelines.
Frame Adapters: Animation runtimes plug in via the seek-by-frame adapter pattern. GSAP is the primary adapter.
Deterministic rendering: No Date.now(), no unseeded Math.random(), no render-time network fetches.

Documentation

Docs: https://frames.hanzo.ai/introduction
Catalog (50+ blocks): https://frames.hanzo.ai/catalog/blocks/data-chart

6.1 KiB Raw Blame History