diff --git a/.agents/skills/captions-overlay/SKILL.md b/.agents/skills/captions-overlay/SKILL.md index d669d55bf1b..81ac373e90c 100644 --- a/.agents/skills/captions-overlay/SKILL.md +++ b/.agents/skills/captions-overlay/SKILL.md @@ -1,13 +1,13 @@ --- name: captions-overlay -description: Overlay doctrine for the embedded-captions workflow — the caption MODEL (drop / rail / embed) and the rule that captions are an OVERLAY composited on top of the film, never a reserved bottom band you shift content up to avoid. Load when adding captions/subtitles to a talking-head or launch video, when deciding whether a phrase should be dropped, ride the verbatim rail, or be promoted to a scarce embedded climax, when laying out a composition that will carry captions (do NOT reserve a keep-out band), or when centering a composition on the true frame center under captions. Quotes the rail+embed model from embedded-captions and constraint #13 (captions overlay, keep-out band retired) from the product-launch-video scene agent. Applies ON TOP of embedded-captions. +description: Overlay doctrine for captions in HyperFrames videos — the caption MODEL (drop / rail / embed) and the rule that captions are an OVERLAY composited on top of the film, never a reserved bottom band you shift content up to avoid. Load when adding captions/subtitles to a talking-head or launch video, when deciding whether a phrase should be dropped, ride the verbatim rail, or be promoted to a scarce embedded climax, when laying out a composition that will carry captions (do NOT reserve a keep-out band), or when centering a composition on the true frame center under captions. Applies ON TOP of the `/hyperframes` skill's references/captions.md. metadata: internal: true --- # Captions Overlay Doctrine -> **Overlay doctrine — supplements the upstream `embedded-captions` skill. Applies ON TOP of it; do not expect it folded into the upstream skill.** +> **Overlay doctrine — supplements the upstream `/hyperframes` skill's `references/captions.md`. Applies ON TOP of it; do not expect it folded into the upstream skill.** Two ideas combine here. First, the **caption model** — every spoken phrase is `drop`, `rail`, or `embed`, and embed is the scarce earned peak, not the default. Second, the @@ -19,7 +19,7 @@ frame and centers on the true vertical center. ## The caption model — drop / rail / embed -Every spoken phrase is one of three things (verbatim from `embedded-captions`): +Every spoken phrase is one of three things: | | What | How it's shown | | --------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -31,15 +31,13 @@ Every spoken phrase is one of three things (verbatim from `embedded-captions`): never two adjacent/co-visible, spaced ≥ a beat apart. A short clip → usually one embed; a long explainer → ~one per section. Embedding every word is the common mistake. -This is the **Standard** mode shape (rail = the verbatim lower-third; embed = the climax -composited behind the subject). **Cinematic** mode drops the rail and makes everything -embed-style — use it only for pure-cinematic asks, never for explainer / voiceover where -the words must read. +This is the default shape (rail = the verbatim lower-third; embed = the climax +composited behind the subject). A pure-cinematic treatment drops the rail and makes +everything embed-style — use it only for pure-cinematic asks, never for explainer / +voiceover where the words must read. ### Rail-first, embed-scarce (the load-bearing rules) -Quoted from the `embedded-captions` non-negotiables: - - **Rail-first for talking-head / explainer.** Don't embed the whole transcript — most text is the rail; embed only peaks. Embedding everything is the default mistake. - **Embed is scarce + spaced.** ≤1 embed per sentence/beat, never two adjacent or @@ -48,11 +46,10 @@ Quoted from the `embedded-captions` non-negotiables: ## The overlay law — captions are NOT a reserved band -In a generated launch composition, when captions are enabled, finalize composites a -**small, minimal word-by-word caption line** as an overlay layer ON TOP of the whole -film (a single text line, bottom-centered, roughly the bottom ~5-8% of canvas height). -It is an overlay, not a reserved zone (verbatim from constraint #13 of the -product-launch-video scene agent): +In a composed video with captions enabled, the caption line is a **small, minimal +word-by-word line** composited as an overlay layer ON TOP of the whole film (a single +text line, bottom-centered, roughly the bottom ~5-8% of canvas height). It is an +overlay, not a reserved zone: - **Center the composition on the TRUE vertical center — y = H / 2** (landscape 540, portrait 960). Do not shift content up to "make room" for captions; a composition @@ -64,7 +61,7 @@ product-launch-video scene agent): line sits — the overlay would fight it. Large imagery / cards / ambient content under the captions is fine; the caption skin is designed to read over content. - There is no machine keep-out gate (the old `captions.mjs keepout` check is retired). - Finalize snapshot QA judges caption-over-content legibility visually. + Snapshot review judges caption-over-content legibility visually. **When captions are disabled:** identical positioning freedom — the overlay simply doesn't exist. @@ -74,8 +71,8 @@ doesn't exist. The model says the rail rides **in front** and an embed is a rare word composited **behind the subject** — both are layers added to footage that ships untouched. The overlay law says the caption line is a layer composited **on top** of the whole film, -not a band carved out of the layout. So in both the captioning pipeline and the -launch-video pipeline, captions are an overlay you add, not a zone you reserve: +not a band carved out of the layout. So whether captions go over footage or over a +composed film, they are an overlay you add, not a zone you reserve: - Keep the full frame; center on true center; let content run to the edges. - Make the rail (or the small overlay caption line) carry the verbatim words. diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index be444b838e0..ae305684fef 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -9,26 +9,20 @@ { "name": "hyperframes", "source": "./", - "description": "Recommended: all published HyperFrames skills in one versioned bundle. Create and render videos from HTML; load workflows on demand without installing newer standalone skills.", + "description": "Recommended: all published HyperFrames skills in one versioned bundle. Create and render videos from HTML: the contract, film, captions, overlays, motion and look references, the CLI, the registry, media, Figma, slideshows and Remotion ports.", "homepage": "https://hyperframes.heygen.com", "license": "Apache-2.0" }, { "name": "core-skills", "source": "./", - "description": "Legacy core-only installation. For release-managed bundled workflows, install hyperframes@hyperframes and then uninstall core-skills@hyperframes.", + "description": "Legacy core-only installation. For the release-managed bundle of every skill, install hyperframes@hyperframes and then uninstall core-skills@hyperframes.", "homepage": "https://hyperframes.heygen.com", "license": "Apache-2.0", "skills": [ "./skills/hyperframes", - "./skills/hyperframes-animation", - "./skills/hyperframes-audio", "./skills/hyperframes-cli", - "./skills/hyperframes-core", - "./skills/hyperframes-creative", - "./skills/hyperframes-keyframes", "./skills/hyperframes-registry", - "./skills/hyperframes-studio", "./skills/media-use" ] } diff --git a/.claude/skills/captions-overlay/SKILL.md b/.claude/skills/captions-overlay/SKILL.md index d669d55bf1b..81ac373e90c 100644 --- a/.claude/skills/captions-overlay/SKILL.md +++ b/.claude/skills/captions-overlay/SKILL.md @@ -1,13 +1,13 @@ --- name: captions-overlay -description: Overlay doctrine for the embedded-captions workflow — the caption MODEL (drop / rail / embed) and the rule that captions are an OVERLAY composited on top of the film, never a reserved bottom band you shift content up to avoid. Load when adding captions/subtitles to a talking-head or launch video, when deciding whether a phrase should be dropped, ride the verbatim rail, or be promoted to a scarce embedded climax, when laying out a composition that will carry captions (do NOT reserve a keep-out band), or when centering a composition on the true frame center under captions. Quotes the rail+embed model from embedded-captions and constraint #13 (captions overlay, keep-out band retired) from the product-launch-video scene agent. Applies ON TOP of embedded-captions. +description: Overlay doctrine for captions in HyperFrames videos — the caption MODEL (drop / rail / embed) and the rule that captions are an OVERLAY composited on top of the film, never a reserved bottom band you shift content up to avoid. Load when adding captions/subtitles to a talking-head or launch video, when deciding whether a phrase should be dropped, ride the verbatim rail, or be promoted to a scarce embedded climax, when laying out a composition that will carry captions (do NOT reserve a keep-out band), or when centering a composition on the true frame center under captions. Applies ON TOP of the `/hyperframes` skill's references/captions.md. metadata: internal: true --- # Captions Overlay Doctrine -> **Overlay doctrine — supplements the upstream `embedded-captions` skill. Applies ON TOP of it; do not expect it folded into the upstream skill.** +> **Overlay doctrine — supplements the upstream `/hyperframes` skill's `references/captions.md`. Applies ON TOP of it; do not expect it folded into the upstream skill.** Two ideas combine here. First, the **caption model** — every spoken phrase is `drop`, `rail`, or `embed`, and embed is the scarce earned peak, not the default. Second, the @@ -19,7 +19,7 @@ frame and centers on the true vertical center. ## The caption model — drop / rail / embed -Every spoken phrase is one of three things (verbatim from `embedded-captions`): +Every spoken phrase is one of three things: | | What | How it's shown | | --------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -31,15 +31,13 @@ Every spoken phrase is one of three things (verbatim from `embedded-captions`): never two adjacent/co-visible, spaced ≥ a beat apart. A short clip → usually one embed; a long explainer → ~one per section. Embedding every word is the common mistake. -This is the **Standard** mode shape (rail = the verbatim lower-third; embed = the climax -composited behind the subject). **Cinematic** mode drops the rail and makes everything -embed-style — use it only for pure-cinematic asks, never for explainer / voiceover where -the words must read. +This is the default shape (rail = the verbatim lower-third; embed = the climax +composited behind the subject). A pure-cinematic treatment drops the rail and makes +everything embed-style — use it only for pure-cinematic asks, never for explainer / +voiceover where the words must read. ### Rail-first, embed-scarce (the load-bearing rules) -Quoted from the `embedded-captions` non-negotiables: - - **Rail-first for talking-head / explainer.** Don't embed the whole transcript — most text is the rail; embed only peaks. Embedding everything is the default mistake. - **Embed is scarce + spaced.** ≤1 embed per sentence/beat, never two adjacent or @@ -48,11 +46,10 @@ Quoted from the `embedded-captions` non-negotiables: ## The overlay law — captions are NOT a reserved band -In a generated launch composition, when captions are enabled, finalize composites a -**small, minimal word-by-word caption line** as an overlay layer ON TOP of the whole -film (a single text line, bottom-centered, roughly the bottom ~5-8% of canvas height). -It is an overlay, not a reserved zone (verbatim from constraint #13 of the -product-launch-video scene agent): +In a composed video with captions enabled, the caption line is a **small, minimal +word-by-word line** composited as an overlay layer ON TOP of the whole film (a single +text line, bottom-centered, roughly the bottom ~5-8% of canvas height). It is an +overlay, not a reserved zone: - **Center the composition on the TRUE vertical center — y = H / 2** (landscape 540, portrait 960). Do not shift content up to "make room" for captions; a composition @@ -64,7 +61,7 @@ product-launch-video scene agent): line sits — the overlay would fight it. Large imagery / cards / ambient content under the captions is fine; the caption skin is designed to read over content. - There is no machine keep-out gate (the old `captions.mjs keepout` check is retired). - Finalize snapshot QA judges caption-over-content legibility visually. + Snapshot review judges caption-over-content legibility visually. **When captions are disabled:** identical positioning freedom — the overlay simply doesn't exist. @@ -74,8 +71,8 @@ doesn't exist. The model says the rail rides **in front** and an embed is a rare word composited **behind the subject** — both are layers added to footage that ships untouched. The overlay law says the caption line is a layer composited **on top** of the whole film, -not a band carved out of the layout. So in both the captioning pipeline and the -launch-video pipeline, captions are an overlay you add, not a zone you reserve: +not a band carved out of the layout. So whether captions go over footage or over a +composed film, they are an overlay you add, not a zone you reserve: - Keep the full frame; center on true center; let content run to the edges. - Make the rail (or the small overlay caption line) carry the verbatim words. diff --git a/.fallowrc.jsonc b/.fallowrc.jsonc index 05953890e90..0e3a4cc3805 100644 --- a/.fallowrc.jsonc +++ b/.fallowrc.jsonc @@ -94,14 +94,6 @@ // The relocated media-use .mjs files are agent-invoked scripts outside the // import graph; keep the exemption scoped to that shipped script type. "packages/cli/src/media-use/**/*.mjs", - // Agent-invoked motion-graphics tools co-located with their docs (run via - // `node ` per grounding/PROTOCOL.md / categories/maps/module.md - // prose), not import-graph reachable. - "skills/motion-graphics/grounding/**", - "skills/motion-graphics/categories/**", - // Agent-invoked reference materials (template + motion-primitive HTML, catalogs), - // forked by path by the frame-worker per SKILL.md prose, not import-graph reachable. - "skills/music-to-video/references/**", // Bundled @font-face data (read at runtime via fs.readFileSync, invisible // to the import graph) + its manual rebuild tool. "skills/**/fonts/**", diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3cdd3f8ae5b..f4f795d32d4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -170,7 +170,6 @@ jobs: - "skills/gsap/**" - "skills/media-use/**" skills: - - "scripts/generate-captured-font-copies.mjs" - "packages/cli/src/media-use/**" - "scripts/check-media-use-copy-parity.test.mjs" - "scripts/check-skill-import-boundaries.test.mjs" @@ -192,7 +191,6 @@ jobs: - ".claude-plugin/**" - ".cursor-plugin/**" - "scripts/package-agent-plugin*" - - "scripts/agent-plugin-captions.test.mjs" - "scripts/set-version*" - "LICENSE" - ".codex-plugin/**" @@ -716,8 +714,6 @@ jobs: - name: Exercise npm-cli bootstrap command run: >- node --test - skills/hyperframes-animation/scripts/package-loader.test.mjs - skills/hyperframes-creative/scripts/package-loader.test.mjs skills/hyperframes/scripts/plugin-cli.test.mjs # Guards that skills-manifest.json (the published freshness fingerprint read @@ -787,8 +783,6 @@ jobs: run: node --test scripts/package-agent-plugin.test.mjs - name: Build portable agent plugin run: node scripts/package-agent-plugin.mjs - - name: Exercise captions from the extracted portable bundle - run: node --test scripts/agent-plugin-captions.test.mjs - name: Build upload-ready Codex plugin run: node scripts/package-codex-plugin.mjs diff --git a/.gitignore b/.gitignore index d5c46c352ed..a73c7d3c135 100644 --- a/.gitignore +++ b/.gitignore @@ -197,3 +197,7 @@ chrome/ # Hosted catalog item files are generated output the docs host serves; the rules above match their folder names !docs/public/catalog/items/**/compositions/ !docs/public/catalog/items/*-ad/ + +# Python bytecode from running skill scripts +__pycache__/ +*.pyc diff --git a/.prettierignore b/.prettierignore index 9c5a9bc97fb..ef105989a14 100644 --- a/.prettierignore +++ b/.prettierignore @@ -37,8 +37,6 @@ registry/blocks/orbit-card/assets/three.module.min.js registry/blocks/orbit-card/assets/gsap-3.14.2.min.js # generated Lottie data: pretty-printing multiplies its size registry/blocks/lottie-character-walk/assets/mascot.json -# reference snippets with intentional pseudo-markup (literal "..." attributes) -skills/talking-head-recut/references/frames/polaroid.html # repo-native skill examples with intentional pseudo-markup placeholders # (e.g. , tokens the agent replaces at build time — not real HTML) .claude/skills/**/examples/**/*.html @@ -49,3 +47,12 @@ skills/talking-head-recut/references/frames/polaroid.html # explicitly (not registry/examples/**/*.html) so hand-authored example HTML still # gets formatted. registry/examples/warm-grain/compositions/captions.html + +# Skill entries: agents read each one whole when it opens, so table padding costs tokens every time. +skills/hyperframes/SKILL.md +skills/hyperframes-cli/SKILL.md +skills/hyperframes-registry/SKILL.md +skills/media-use/SKILL.md +skills/figma/SKILL.md +skills/slideshow/SKILL.md +skills/remotion-to-hyperframes/SKILL.md diff --git a/AGENTS.md b/AGENTS.md index 74a602b8c41..3603e2a7666 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,27 +4,23 @@ Open-source video rendering framework: write HTML, render video. ## Skills -This repo ships AI agent skills via [vercel-labs/skills](https://github.com/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 `/hyperframes` router installs each creation workflow on demand; install everything only when the user explicitly asks for the full set. +This repo ships AI agent skills via [vercel-labs/skills](https://github.com/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. ```bash -npx hyperframes skills update # default: installs/refreshes the core set — workflows install on demand -npx hyperframes skills # all 21 published skills at once +npx hyperframes skills update # default: installs/refreshes the core set plus anything already installed +npx hyperframes skills # all 7 published skills at once npx skills add heygen-com/hyperframes # interactive picker (terminal only; repo-internal skills are excluded by default) ``` -**Creation workflows** route through one entry skill — read `/hyperframes` 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-hyperframes`) — to a concrete workflow. Consult it before invoking a specific workflow: +Make any video by asking for it; the `/hyperframes` skill carries the contract and the references (film, captions, overlays, motion, look). Read it first. -- `/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, video to pull audio from, or one generated from a mood brief) → 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 HyperFrames toolbox; the original hyperframes flow — design → plan → layout → build → validate, any length. - -**Porting an existing composition?** `/remotion-to-hyperframes` translates a Remotion (React) video composition into HyperFrames HTML — a source migration, separate from the creation workflows above. +- `/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 for `hyperframes add` and `catalog`. +- `/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. ## Issue and PR triage diff --git a/CLAUDE.md b/CLAUDE.md index e0d9b9f7a19..8f66e6d3042 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,11 +4,11 @@ Open-source video rendering framework: write HTML, render video. ## Skills -This repo ships 21 AI agent skills via [vercel-labs/skills](https://github.com/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 `/hyperframes` router installs each creation workflow on demand; install all 21 only when the user explicitly asks for the full set. +This repo ships 7 AI agent skills via [vercel-labs/skills](https://github.com/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`); `/slideshow`, `/remotion-to-hyperframes` and `/figma` install on demand. Install all 7 only when the user explicitly asks for the full set. ```bash -npx hyperframes skills update # default: installs/refreshes the core set — workflows install on demand -npx hyperframes skills # all 21 published skills at once — only on explicit request +npx hyperframes skills update # default: installs/refreshes the core set plus anything already installed +npx hyperframes skills # all 7 published skills at once — only on explicit request npx skills add heygen-com/hyperframes # interactive picker; internal skills require INSTALL_INTERNAL_SKILLS=1 for discovery npx skills add heygen-com/hyperframes --all # excludes internal skills unless INSTALL_INTERNAL_SKILLS=1 npx skills add heygen-com/hyperframes --skill # a named match installs regardless of metadata.internal (bare name, no leading slash) @@ -18,44 +18,25 @@ npx skills add heygen-com/hyperframes --skill # a named match installs r `skills add` resolves the skills.sh registry blob, which can lag `main` by hours, so a freshly added skill may be a little behind. `npx hyperframes skills update` installs from the current `main`; prefer it when freshness matters. -**`/hyperframes` is the entry skill — read it first.** It's the capability map for the domain skills below, the intent layer that confirms every creation brief up front, AND the intent router for the creation workflows. The full README skills section mirrors this list; keep them in sync (see "Skill catalog maintenance" below). +Make any video by asking for it; the `/hyperframes` skill carries the render contract and the references (format, runtimes, motion, look, captions, film, overlays, storyboards). The skills carry knowledge, not process. The README skills section mirrors this list; keep them in sync (see "Skill catalog maintenance" below). -### Creation workflows - -- `/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). -- `/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. -- `/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`. -- `/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, video to pull audio from, or one generated from a mood brief) → 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 HyperFrames toolbox; the original hyperframes flow — design → plan → layout → build → validate, any length. -- `/remotion-to-hyperframes` — port an existing Remotion (React) composition to HyperFrames HTML. One-way migration, not creation. - -### Domain skills (loaded on demand) - -Atomic capabilities the creation workflows compose against — pull one when you need that specific layer: - -- `/hyperframes-core` — the composition contract: `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, determinism rules. Read before writing composition HTML. -- `/hyperframes-animation` — all animation knowledge: atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP default, plus Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU). -- `/hyperframes-keyframes` — seek-safe keyframe authoring across runtimes: GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth; plus `hyperframes keyframes` diagnostics for surfacing and verifying rendered motion. -- `/hyperframes-creative` — non-animation creative direction: `frame.md` / `design.md` handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns. -- `/media-use` — the media OS (a host app's own music and sound-effect tools come first for those): resolve any media need (BGM, SFX, image, icon, logo, voice, color grade, LUT) into a frozen local file or paste-ready block + ledger record; generate via TTS / music / image models when the catalog misses; transcribe, caption, remove backgrounds, and reuse assets across projects. One shared `scripts/audio.mjs` engine + manifest tracking; keeps search noise on disk. -- `/hyperframes-audio` — mix the audio already placed in a composition: voiceover carve (dip a music bed only in the bands the voice occupies, static or dynamic, level match included), the effect chain (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), automation envelopes on volume or any effect parameter, and submix buses (``) that carry one chain, fader and automation clock for several tracks at once. Sourcing the audio is `/media-use`; this is what happens to it afterwards. -- `/hyperframes-cli` — CLI dev loop: `init`, `add`, `lint`, `check`, `snapshot`, `preview`, `render`, `publish`, `doctor`, `lambda` (AWS Lambda cloud rendering). -- `/hyperframes-registry` — search, install and wire registry blocks and components into compositions via `hyperframes catalog` / `hyperframes add`. Load it before hand-building any named look, effect, treatment or transition: the search ranks the whole hosted registry with nothing installed. Covers authoring a new block or component to contribute upstream. -- `/figma` — import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition. +- `/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: transitions, overlays, titles, kinetic type, captions, charts, maps, 3D, camera moves. Use before hand-building any named visual; also for `hyperframes add` and `catalog`. +- `/media-use` — get or make any media for a video (music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks) with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull, or should be stylized or hidden. +- `/figma` — bring Figma into a video: rendered assets, brand tokens, components, storyboard frames as reconstructed motion, shaders and connector-assisted motion. Use when the person pastes a figma.com link or asks to use a Figma design, frame, logo or brand. +- `/slideshow` — a presentation, pitch deck or interactive deck with discrete slides, fragment reveals, branching, hotspot navigation and presenter mode with speaker notes; also converts an existing page into a 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. ## Skill catalog maintenance When adding a new skill, or substantially renaming / repurposing an existing one, update all agent-facing discoverability surfaces in lockstep: -1. The skill list above (CLAUDE.md) AND the workflow list in the root `AGENTS.md` (it carries workflows only, no domain-skill section) AND the `## Skills` section in `README.md` AND `docs/guides/skills.mdx` (rendered at [hyperframes.heygen.com/guides/skills](https://hyperframes.heygen.com/guides/skills)) AND the two setup tables that compress the same descriptions — `docs/prompting/overview.mdx` ("One-time setup") and `docs/quickstart.mdx`. Out-of-date entries silently kill discovery. This list is also the sync set for a **changed contract**, not just an added or renamed skill: a reworded `description:` has to be pushed to every surface or the compressed copies start asserting the opposite of the skill. +1. The skill list above (CLAUDE.md) AND the skill list in the root `AGENTS.md` AND the `## Skills` section in `README.md` AND `docs/guides/skills.mdx` (rendered at [hyperframes.heygen.com/guides/skills](https://hyperframes.heygen.com/guides/skills)) AND the two setup pages that compress the same descriptions — `docs/prompting/overview.mdx` ("One-time setup") and `docs/quickstart.mdx`. Out-of-date entries silently kill discovery. This list is also the sync set for a **changed contract**, not just an added or renamed skill: a reworded `description:` has to be pushed to every surface or the compressed copies start asserting the opposite of the skill. 2. The scaffolded project template `packages/cli/src/templates/_shared/CLAUDE.md` + `AGENTS.md` — written into every `hyperframes init` project, so a stale entry there ships to users. The two template files must stay byte-identical. -3. If the skill changes the routing surface for "make a video" requests, also update the routing table + intent layer in `skills/hyperframes/SKILL.md` AND that workflow's own route file, `skills/hyperframes/references/routes/.md`. One file carries both halves: the input/output/trigger contract the router reads before the workflow is installed, and its interview entry (must-haves, conditionals, deferred asks, run-shape). The older `references/workflow-catalog.md` and `references/route-briefs.md` are now "moved" stubs pointing at `routes/` — don't edit them. -4. Mirror the Router / Creation workflows / Domain skills grouping across all surfaces so a skill always lives in the same column. -5. Skill count appears in the README and CLAUDE.md intro lines ("20 AI agent skills…") — update on add/remove. The `docs/guides/skills.mdx` page and the CLI templates deliberately omit a count to avoid drift; keep them count-free. +3. The routing surface for "make a video" requests is the References table and closing line of `skills/hyperframes/SKILL.md`. A new reference or skill that a request should reach gets a row or a mention there. +4. Keep the same grouping on every surface: the core set (`/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry`, `/media-use`) first, then the on-demand skills (`/figma`, `/slideshow`, `/remotion-to-hyperframes`). +5. Skill count appears in the README and CLAUDE.md intro lines ("7 AI agent skills…") — update on add/remove. The `docs/guides/skills.mdx` page and the CLI templates deliberately omit a count to avoid drift; keep them count-free. The skill's own `SKILL.md` frontmatter `description:` is the source of truth for the one-line "use when" blurb; copy from there into the catalog rather than paraphrasing. diff --git a/README.md b/README.md index 4529ffdda70..8cfc65cc137 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ For standalone skills (including OpenCode), use: npx skills add heygen-com/hyperframes ``` -> The picker opens with nothing pre-selected — the **Core Skills** group is all you need: the `/hyperframes` router installs each creation workflow on demand. Agents and non-interactive runs should use `npx hyperframes skills update` instead — it installs exactly the core set, whereas `skills add --all` installs all 21 published skills. The six repo-internal skills under `.claude/skills` / `.agents/skills` are excluded by default. For the full published set use `npx hyperframes skills`. +> The picker opens with nothing pre-selected — the **Core Skills** group is all you need; `/slideshow`, `/remotion-to-hyperframes` and `/figma` install on demand. Agents and non-interactive runs should use `npx hyperframes skills update` instead — it installs exactly the core set, whereas `skills add --all` installs all 7 published skills. The six repo-internal skills under `.claude/skills` / `.agents/skills` are excluded by default. For the full published set use `npx hyperframes skills`. > > `skills add` resolves the skills.sh registry blob, which can lag `main` by hours. `npx hyperframes skills update` installs from the current `main`, so reach for it when you need the newest copy of a skill. @@ -65,11 +65,11 @@ The skills teach agents the HyperFrames production loop: plan the video, write v ## Skills -HyperFrames ships 21 skills agents load on demand. Read `/hyperframes` first — it's the router and capability map; it picks a workflow for any "make me a…" request — video, deck, or composition port — and points to the domain skills below. +HyperFrames ships 7 skills. Make any video by asking for it; the `/hyperframes` skill carries the contract and the references (film, captions, overlays, motion, look). Read it first. -For standalone installation, default to the **core set** — the router installs each creation workflow on demand. `npx hyperframes skills update` installs exactly that from anywhere; the interactive picker (`npx skills add heygen-com/hyperframes`) lists it as the "Core Skills" group, nothing pre-selected. The picker is interactive-only — a non-interactive or agent run without `--skill` installs all 21. Use `npx skills add heygen-com/hyperframes --all` to install the complete published set deliberately (skips the picker), or `npx skills add heygen-com/hyperframes --skill ` for just one (bare name, no leading `/`). +For standalone installation, default to the **core set** (`/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry`, `/media-use`). `npx hyperframes skills update` installs exactly that from anywhere; the interactive picker (`npx skills add heygen-com/hyperframes`) lists it as the "Core Skills" group, nothing pre-selected. The picker is interactive-only — a non-interactive or agent run without `--skill` installs all 7. Use `npx skills add heygen-com/hyperframes --all` to install the complete published set deliberately (skips the picker), or `npx skills add heygen-com/hyperframes --skill ` for just one (bare name, no leading `/`). -Standalone installs stay lean after that: `npx hyperframes init` keeps the **core set** fresh (the router, the `hyperframes-*` domain skills, and `media-use` — plus whatever is already installed; `/figma` stays on demand) and never expands a partial install; the creation workflows install **on demand** — the router runs `npx hyperframes skills update ` before entering one. Nothing re-pulls the full set behind your back. +Standalone installs stay lean after that: `npx hyperframes init` keeps the **core set** fresh (plus whatever is already installed) and never expands a partial install; `/figma`, `/slideshow` and `/remotion-to-hyperframes` install **on demand** with `npx hyperframes skills update `. Nothing re-pulls the full set behind your back. ### Plugin packages @@ -87,42 +87,22 @@ bun run package:codex-plugin This writes `dist/hyperframes-plugin.zip` with a `hyperframes/` root folder and fails if the archive exceeds Codex's 100 MB upload limit. -### Router - -| Skill | Use when | -| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `/hyperframes` | **Read first** for any request to make / create / edit / animate / render a video, animation, or motion graphic. Capability map for the domain skills, the intent layer that confirms every creation brief up front, and intent router for the creation workflows below. | - -### Creation workflows - -| Skill | Use when | -| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/product-launch-video` | Any **website** — marketing / launching / promoting a product (from its URL, a brief, or a script), or a site tour / showcase / social clip featuring the site's own visuals. Up to ~3 min (sweet spot 30-90s). | -| `/faceless-explainer` | **Explaining a topic / concept** from arbitrary text — no product, no URL, no website capture; every visual is LLM-invented (typography / abstract / diagram / data-viz). | -| `/pr-to-video` | A **GitHub pull request** (PR URL, `owner/repo#N` ref, or "this PR") → changelog / feature-reveal / fix / refactor explainer, read via the `gh` CLI. | -| `/embedded-captions` | Adding **captions / subtitles** to an existing talking-head video (footage untouched) — verbatim rail, embedded climax behind the subject, or pure-cinematic embed. | -| `/talking-head-recut` | Packaging an existing talking-head / interview / podcast video with **designed graphic overlays** — lower-thirds, data callouts, kinetic titles, pull-quotes, side panels, PiP. | -| `/motion-graphics` | A short, **unnarrated, design-led motion graphic** (~under 10s) — kinetic type, stat / chart hit, logo sting, lower-third, animated tweet / headline. MP4 or transparent overlay. | -| `/music-to-video` | A **music track** (audio file, video to pull audio from, or one generated from a mood brief) → a **beat-synced** video — lyric, slideshow, or kinetic promo; music drives pacing. | -| `/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` | **Anything else** — longer or multi-scene pieces, brand / sizzle reel, title card, static loop, freeform composition. Input- and length-agnostic fallback, and the home of companion mode (co-create with the full toolbox). | -| `/remotion-to-hyperframes` | **Porting an existing Remotion** (React) composition's source to HyperFrames HTML. One-way migration, not creation. | - -### Domain skills (loaded on demand) - -Atomic capabilities the creation workflows compose against — pull one when you need that specific layer. - -| Skill | Covers | -| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `/hyperframes-core` | The composition contract — `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, determinism rules. | -| `/hyperframes-animation` | All animation knowledge — atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU). | -| `/hyperframes-keyframes` | Seek-safe keyframe authoring across runtimes — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth — plus `hyperframes keyframes` diagnostics for rendered motion. | -| `/hyperframes-creative` | Non-animation creative direction — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns. | -| `/media-use` | The media OS (a host app's own music and sound-effect tools come first for those) — resolve any media need (BGM, SFX, image, icon, logo, voice, color grade, LUT) into a frozen local file or paste-ready block + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking. | -| `/hyperframes-cli` | CLI dev loop — `init`, `lint`, `check`, `snapshot`, `preview`, `render`, `publish`, `doctor`, plus HeyGen-hosted cloud rendering (`cloud render`) and AWS Lambda rendering (`lambda deploy / render / progress`). | -| `/hyperframes-audio` | Mix the audio already placed in a composition — voiceover carve (dip a music bed only in the bands the voice occupies, static or dynamic, level match included), the effect chain (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), automation envelopes on volume or any effect parameter, and submix buses (``) carrying one chain, fader and automation clock for several tracks at once. Sourcing the audio is `/media-use`. | -| `/hyperframes-registry` | Search, install and wire registry blocks and components into compositions via `hyperframes catalog` / `hyperframes add`. Load before hand-building any named look, effect, treatment or transition. Authoring a new block or component to contribute upstream. | -| `/figma` | Import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition. | +### Core set + +| Skill | Use when | +| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/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 — transitions, overlays, titles, kinetic type, captions, charts, maps, 3D, camera moves. Use before hand-building any named visual; also for `hyperframes add` and `catalog`. | +| `/media-use` | Get or make any media for a video — music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks — with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull. | + +### On demand + +| Skill | Use when | +| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/figma` | Bring Figma into a video — rendered assets, brand tokens, components, storyboard frames as reconstructed motion, shaders and connector-assisted motion. Use when you paste a figma.com link. | +| `/slideshow` | A presentation, pitch deck or interactive deck — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode with speaker notes. Output is a navigable deck, not a rendered MP4. | +| `/remotion-to-hyperframes` | Bringing existing video code or footage into HyperFrames (Remotion first; also Motion Canvas, Lottie, Three.js, canvas, other tools' renders), verified frame by frame. | For visual design handoff workflows, see the [Claude Design guide](https://hyperframes.heygen.com/guides/claude-design) and [Open Design guide](https://hyperframes.heygen.com/guides/open-design). diff --git a/docs/deploy/migrating-to-hyperframes-lambda.mdx b/docs/deploy/migrating-to-hyperframes-lambda.mdx index cba939ee592..950a026283a 100644 --- a/docs/deploy/migrating-to-hyperframes-lambda.mdx +++ b/docs/deploy/migrating-to-hyperframes-lambda.mdx @@ -107,7 +107,7 @@ The default policy doc emitted by `hyperframes lambda policies user/role` uses ` ## Migration checklist 1. **Inventory** the compositions you want to migrate. Filter out anything that needs HDR — that stays on your current framework for now. webm renders distributed via closed-GOP VP9 + concat-copy (see the webm section above). -2. **Translate** each composition to plain HTML. The `[Concepts](/concepts)` page covers the data-attribute conventions; installing the skills (`npx hyperframes skills update`) makes Claude / Cursor / Codex aware of them too — start at `/hyperframes`, which routes to `/hyperframes-core` for the composition contract. +2. **Translate** each composition to plain HTML. The `[Concepts](/concepts)` page covers the data-attribute conventions; installing the skills (`npx hyperframes skills update`) makes Claude / Cursor / Codex aware of them too — start at `/hyperframes`, which carries the composition contract and points to `references/format.md` for the details. 3. **Wire** the new composition into your build pipeline alongside the old one. HyperFrames doesn't need an external bundler — you can `npx hyperframes preview` against the HTML directly. 4. **Deploy** in a separate AWS account or with a `--stack-name=hyperframes-staging` first. Run a real render with `--wait`; verify the output bytes. 5. **Add the policy** to your CI. `hyperframes lambda policies user > infra/iam/hyperframes.json` then `hyperframes lambda policies validate infra/iam/hyperframes.json` on every PR. diff --git a/docs/examples.mdx b/docs/examples.mdx index 55c45068f51..06add95787b 100644 --- a/docs/examples.mdx +++ b/docs/examples.mdx @@ -206,5 +206,5 @@ The init templates remain available for scaffolding complete projects. ## Related topics - [Make your first video](/quickstart) -- [Choose a creation workflow](/workflows) +- [Choose what to make](/workflows) - [Take more control of an existing project](/go-further) diff --git a/docs/guides/captions-and-recuts.mdx b/docs/guides/captions-and-recuts.mdx index f646583e552..8e5e3fa51a9 100644 --- a/docs/guides/captions-and-recuts.mdx +++ b/docs/guides/captions-and-recuts.mdx @@ -31,15 +31,14 @@ quotes, statistics, lower thirds, or picture-in-picture. ## What should change? -This page covers two workflows. `/hyperframes` picks between them from what you -ask for, and you can name one directly if you already know which you want. - -- **Words on screen** — `/embedded-captions`. Readable, timed words over the clip. - Plain subtitles, or cinematic captions set behind the subject. -- **Designed cards on screen** — `/talking-head-recut`. Titles, pull-quotes, data - callouts, lower thirds, picture-in-picture, synced to the transcript. -- **Change the footage itself** — neither of these. Use - [General Video](/guides/general-video) when pauses, selected moments, or the +Say which of these you want; `/hyperframes` handles both. + +- **Words on screen** — readable, timed words over the clip. Plain subtitles, or + cinematic captions set behind the subject. +- **Designed cards on screen** — titles, pull-quotes, data callouts, lower + thirds, picture-in-picture, synced to the transcript. +- **Change the footage itself** — neither of these. Make a + [custom video](/guides/general-video) when pauses, selected moments, or the spoken order must change. Both leave the clip and its audio untouched: the first adds words, the second adds @@ -47,7 +46,7 @@ graphics, and the footage plays the same underneath either way. Captions and designed overlays work best on a clear, single-subject clip with audible speech. Both keep the original footage and audio intact. -If you need to remove pauses, choose different moments, or reorder the speech, use [General Video](/guides/general-video). +If you need to remove pauses, choose different moments, or reorder the speech, make a [custom video](/guides/general-video). ## Before it builds @@ -78,4 +77,4 @@ style changes. - [Edit captions in Studio](/studio/captions) - [Work with voice, music, sound, and captions](/guides/voice-and-audio) -- [Change the spoken edit with a custom video workflow](/guides/general-video) +- [Change the spoken edit with a custom video](/guides/general-video) diff --git a/docs/guides/claude-design-hyperframes.md b/docs/guides/claude-design-hyperframes.md index d385055488f..abc13e1f467 100644 --- a/docs/guides/claude-design-hyperframes.md +++ b/docs/guides/claude-design-hyperframes.md @@ -1232,8 +1232,7 @@ tl.to("#s5-headline", { backgroundSize: "100% 30%", duration: 0.6, ease: "power2 Everything critical is inlined above. These are for edge cases: - Core composition contract (data attributes, sub-comp wiring): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/SKILL.md -- Motion theory (easing as emotion, direction rules): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes-creative/references/motion-principles.md -- Typography (full banned list, weight contrast, OpenType): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes-creative/references/typography.md -- Transitions (shader catalog, CSS transition patterns): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes-animation/transitions/overview.md -- Captions synced to audio: https://github.com/heygen-com/hyperframes/blob/main/skills/embedded-captions/SKILL.md +- Motion and transitions (timings, eases, cuts, title entrances): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/motion.md +- Look (colours, type, presets, frame.md): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/look.md +- Captions synced to audio: https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/captions.md - Full docs: https://hyperframes.heygen.com/ diff --git a/docs/guides/export-and-share.mdx b/docs/guides/export-and-share.mdx index 410eeae2854..c6426e42705 100644 --- a/docs/guides/export-and-share.mdx +++ b/docs/guides/export-and-share.mdx @@ -45,8 +45,8 @@ When I approve it, render an MP4 to renders/final.mp4. ``` Use the agent when a failed check may require a source change or when you want -one person to manage the complete finish. HyperFrames creation workflows wait -for render approval after the final preview. +one person to manage the complete finish. The `/hyperframes` skill waits for +render approval after the final preview. ### Use Studio diff --git a/docs/guides/general-video.mdx b/docs/guides/general-video.mdx index cd76459e507..cd621df1783 100644 --- a/docs/guides/general-video.mdx +++ b/docs/guides/general-video.mdx @@ -1,12 +1,12 @@ --- title: "Create a custom video" sidebarTitle: "Custom video" -description: "Combine sources, change existing footage, or co-direct a video when no focused workflow fits." +description: "Combine sources, change existing footage, or co-direct a video when no single source decides the job." --- import { DocsVideo } from "/snippets/docs-video.jsx"; -Use General Video when the work is genuinely custom: several source types, editable footage, a longer multi-scene story, an unusual format, or close creative collaboration. +Use this path when the work is genuinely custom: several source types, editable footage, a longer multi-scene story, an unusual format, or close creative collaboration. -Short beats back to back, because that is what this workflow makes — units of +Short beats back to back, because that is what a motion graphic is — units of motion small enough to drop into something else. ## Make the request @@ -40,9 +40,9 @@ optional unless a specific moment must land precisely. - **Overlay** — create a lower third or callout that enters, holds, and clears completely over footage. - **Page, post, or map** — capture the real source and animate one detail into the visual payoff. -The same workflow can animate kinetic type, a statistic, chart, logo, lower third, map, real webpage, news headline, or post. +The same request shape can animate kinetic type, a statistic, chart, logo, lower third, map, real webpage, news headline, or post. -If the result needs narration, several scenes, or a longer story, use [General Video](/guides/general-video). +If the result needs narration, several scenes, or a longer story, make a [custom video](/guides/general-video). ## Choose the output diff --git a/docs/guides/plugins.mdx b/docs/guides/plugins.mdx index a4344a39f88..436f776d74e 100644 --- a/docs/guides/plugins.mdx +++ b/docs/guides/plugins.mdx @@ -4,9 +4,9 @@ sidebarTitle: "Agent plugins" description: "Install video creation skills as one versioned plugin and let your agent manage updates." --- -The HyperFrames plugin gives your coding agent the complete set of video workflows: -product promos, explainers, captions, motion graphics, and more. Skills load when -needed; you do not have to install each workflow separately. +The HyperFrames plugin gives your coding agent every HyperFrames skill: the video +contract and references for product promos, explainers, captions, motion graphics, +and more, plus the CLI, registry, and media skills. Skills load when needed. Choose one installation method per agent. Plugins receive updates through the agent's plugin manager. [Standalone skills](/guides/skills) remain available for @@ -35,7 +35,7 @@ claude plugin install hyperframes@hyperframes claude plugin details hyperframes ``` -The inventory should include `hyperframes`, `general-video`, and `media-use`. +The inventory should include `hyperframes`, `hyperframes-cli`, and `media-use`. Start a new session or run `/reload-plugins`, then try: ```text @@ -126,10 +126,8 @@ To stay on a specific release, install with `--ref ` instead of `--auto-update`. Choose a release containing `gemini-extension.json`. See [Gemini's extension guide](https://geminicli.com/docs/extensions/reference/). -The embedded-captions workflow additionally needs project-local Sharp, Puppeteer -with Chromium, and GSAP. Its skill includes the versioned installation command; -keep those dependencies and their lockfile in the caption project. The plugin -itself remains read-only and does not include browsers or model weights. +The plugin itself remains read-only and does not include browsers or model +weights. ## Versions and updates diff --git a/docs/guides/product-launch-video.mdx b/docs/guides/product-launch-video.mdx index dab22bd9665..e188030b212 100644 --- a/docs/guides/product-launch-video.mdx +++ b/docs/guides/product-launch-video.mdx @@ -9,12 +9,12 @@ import { DocsVideo } from "/snippets/docs-video.jsx"; Give HyperFrames the real URL when the product, website, or brand should appear in the result. -Built by running this workflow on a real site. The screens are captured from +Built from a real site. The screens are captured from huly.io, not mocked — which is the point: you give it a URL and it works from what is actually there. diff --git a/docs/guides/skills.mdx b/docs/guides/skills.mdx index 98227b95cd9..3ed2e39590b 100644 --- a/docs/guides/skills.mdx +++ b/docs/guides/skills.mdx @@ -1,22 +1,21 @@ --- title: "Install and update agent skills" sidebarTitle: "Agent skills" -description: "Teach a coding agent how to create valid HyperFrames projects and load specialized workflows when needed." +description: "Teach a coding agent how to create valid HyperFrames projects." --- import { DocsVideo } from "/snippets/docs-video.jsx"; -HyperFrames skills teach coding agents the project format, animation rules, media workflow, validation loop, and creation workflows that generic web knowledge does not cover. +HyperFrames skills teach coding agents the project format, animation rules, media workflow, and validation loop that generic web knowledge does not cover. -The terminal output is a real run of the command. Afterwards the router reads a -request and chooses the workflow for it, instead of the agent guessing at the -framework's rules. +The terminal output is a real run of the command. Afterwards the agent reads +`/hyperframes` before it builds, instead of guessing at the framework's rules. Prefer a [versioned plugin](/guides/plugins) when your agent supports one. This page covers standalone installs, including OpenCode. Plugin users should update @@ -30,7 +29,7 @@ Run the interactive installer: npx skills add heygen-com/hyperframes ``` -Select **Core Skills**. The `/hyperframes` router installs a specialized creation workflow when the request needs one, so you do not need the full catalog up front. +Select **Core Skills**. That covers every kind of video; the other skills install when a request needs them, so you do not need the full catalog up front. Start a fresh agent chat after installation, then ask it to use `/hyperframes`. @@ -42,7 +41,7 @@ For a non-interactive agent or CI environment, use: npx hyperframes skills update ``` -This installs or refreshes the core set and any HyperFrames skills already present in the global install, then links those bundles into compatible installed agents. It does not add every optional workflow. +This installs or refreshes the core set and any HyperFrames skills already present in the global install, then links those bundles into compatible installed agents. It does not add every optional skill. Check freshness without changing anything: @@ -50,10 +49,10 @@ Check freshness without changing anything: npx hyperframes skills check ``` -Install or refresh one workflow explicitly: +Install or refresh one skill explicitly: ```bash -npx hyperframes skills update pr-to-video +npx hyperframes skills update slideshow ``` ## Use the skills in GitHub Copilot CLI @@ -106,23 +105,21 @@ bob Ask Bob to use `/hyperframes` for the first request. Running the update again refreshes the same global skill bundles without changing the project format. -## Let the router choose +## What the skills cover -The normal entry point is `/hyperframes`. It confirms the important intent, then selects a workflow from the input: +Make any video by asking for it; the `/hyperframes` skill carries the contract and the references (each kind of film, story, motion, look, sound, review, captions, overlays). -| You provide | Workflow | +| Skill | What it covers | | --- | --- | -| A product website or product brief | Product launch video | -| A topic or script with no website capture | Faceless explainer | -| A GitHub pull request | PR-to-video | -| Existing talking-head footage | Captions or a designed recut | -| A music track | Music-driven video | -| A short design-led animation | Motion graphic | -| A presentation | Slideshow | -| A Figma file or frame | Figma import with assets, brand tokens, components, and reconstructed motion | -| Anything outside those shapes | General video | - -You can invoke a workflow directly when you already know it is the right one, but you do not need to memorize the names to start. +| `/hyperframes` | Read first for any request to make, edit, animate or render a video, motion graphic, captions or overlays. 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 CLI by job: scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history. | +| `/hyperframes-registry` | About 450 ready-made blocks and components installed as editable source: transitions, overlays, titles, kinetic type, captions, charts, maps, 3D, camera moves. | +| `/media-use` | Music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks, with HeyGen or free local tools; mixes placed audio. | +| `/figma` | A Figma file or frame: rendered assets, brand tokens, components, and 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` | Bringing existing video code or footage into HyperFrames (Remotion first; also Motion Canvas, Lottie, Three.js, canvas, other tools' renders), verified frame by frame. | + +You can name a skill directly, but you do not need to memorize the names to start. ## Install more only when you need it @@ -137,7 +134,7 @@ npx hyperframes skills Or install one named skill: ```bash -npx skills add heygen-com/hyperframes --skill hyperframes-animation +npx skills add heygen-com/hyperframes --skill slideshow ``` Use the full set for an environment that must work across many HyperFrames tasks without fetching later. For a normal project, the core set is smaller and easier to keep current. @@ -155,5 +152,5 @@ available in the [HyperFrames repository](https://github.com/heygen-com/hyperfra ## Related topics - [Make your first video](/quickstart) -- [Choose a specific creation workflow](/workflows) +- [Choose what to make](/workflows) - [Use authentication and hosted services](/guides/authentication) diff --git a/docs/guides/slideshow.mdx b/docs/guides/slideshow.mdx index f57ee2f6787..b8655bb6e5e 100644 --- a/docs/guides/slideshow.mdx +++ b/docs/guides/slideshow.mdx @@ -33,7 +33,7 @@ The agent confirms the audience, main outcome, and whether the deck needs reveals, optional branches, or presenter notes. You do not need to prescribe every slide before seeing the proposed structure. -If the result should play from beginning to end without a presenter, use a normal [video workflow](/workflows). A slideshow cannot be exported as one linear MP4 yet. +If the result should play from beginning to end without a presenter, make a normal [video](/workflows). A slideshow cannot be exported as one linear MP4 yet. Do not run `hyperframes render` on a deck. It does not fail — a deck has no diff --git a/docs/guides/voice-and-audio.mdx b/docs/guides/voice-and-audio.mdx index 848aec3b66c..4687b19db4b 100644 --- a/docs/guides/voice-and-audio.mdx +++ b/docs/guides/voice-and-audio.mdx @@ -110,8 +110,8 @@ graphic overlays, and an actual change to the spoken edit. - Listen on ordinary headphones and laptop speakers. When narration drives the project, time visual changes to its real transcript -rather than estimated scene lengths. When music drives the project, use the -[music-video workflow](/guides/music-to-video) and its analyzed structure. +rather than estimated scene lengths. When music drives the project, cut to its analyzed structure (see +[music to video](/guides/music-to-video)). ## Review the complete sound pass diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index 6377777684b..4f7d5d551d3 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -121,8 +121,9 @@ that off. `--tailwind` injects the pinned Tailwind v4 browser runtime and exposes a `window.__tailwindReady` promise that renders wait on before capturing frame 0. -Use the `/hyperframes-core` skill when editing these projects, so agents follow -v4 CSS-first patterns instead of v3 `tailwind.config.js` patterns. The browser +The `/hyperframes-cli` skill's `references/init-and-scaffold.md` (Tailwind) +covers editing these projects, so agents follow v4 CSS-first patterns instead +of v3 `tailwind.config.js` patterns. The browser runtime is meant for scaffolded projects and quick iteration — for offline or locked-down production renders, compile Tailwind to CSS and link the stylesheet. @@ -271,8 +272,7 @@ You get `AGENTS.md`, `CLAUDE.md`, `meta.json`, scroll screenshots, extracted HTML and CSS, visible text, design tokens, font files, images, SVGs, animation metadata, and contact sheets — plus whatever Lottie, video, and WebGL context the page exposed. It is raw material for an agent, not a finished composition; -the `/product-launch-video` workflow uses it when a real product has to appear -on screen. Dynamic sites, protected pages, and unusual media loaders produce +the `/hyperframes` skill uses it when a real product has to appear on screen. Dynamic sites, protected pages, and unusual media loaders produce partial results, so read `dropped`, the warnings, and the contact sheets before you build. @@ -838,7 +838,7 @@ did, in one command and one browser session. ```bash npx hyperframes check [dir] -npx hyperframes check [dir] --json # {ok, browserSkipped, scope, lint, runtime, layout, motion, contrast, hdr, snapshots} +npx hyperframes check [dir] --json # {ok, browserSkipped, scope, lint, runtime, layout, motion, contrast, craft, hdr, snapshots} npx hyperframes check [dir] --snapshots npx hyperframes check [dir] --at 1.5,4,7.25 npx hyperframes check [dir] --strict # warnings fail too @@ -848,7 +848,8 @@ npx hyperframes check [dir] --strict # warnings fail too Then it loads the bundled composition once and sweeps a single seek grid, running every audit at every sample: runtime console errors and failed requests, layout defects (overflow, clipping, held overlaps, occlusion, coordinate-frame -drift), `*.motion.json` assertions, and WCAG AA contrast. +drift), `*.motion.json` assertions, WCAG AA contrast, and craft warnings +(see [Craft warnings](#craft-warnings)). When the browser never ran (lint errors, a linter crash, or a browser launch failure), `browserSkipped` is `true` and the `layout`, `motion` and `contrast` @@ -867,7 +868,7 @@ cover every finding from the full check. | `--at` | Explicit timestamps in seconds, comma-separated | | `--at-transitions` | Also sample every tween start and end, to catch transient overlaps at transition seams | | `--max-transition-samples` | Cap the transition-derived samples. When it truncates, the omitted count is reported. Default: unlimited. | -| `--range ` | Sample only this interval, in global seconds. Lint stays project-wide; whole-timeline motion and `sweep_static` are skipped. | +| `--range ` | Sample only this interval, in global seconds. Lint stays project-wide; whole-timeline motion, `sweep_static` and craft warnings are skipped. | | `--components ` | Report only findings that involve these elements or their descendants. Counts, `ok` and the exit code still cover all. | | `--max-issues` | Findings to print or return after static collapse (default 80) | | `--collapse-static` / `--no-collapse-static` | Fold a repeated static finding into one row (default: on) | @@ -916,6 +917,28 @@ meant to be still can declare `data-no-timeline` to skip the guard. {/* VISUAL: a `check --snapshots` overview frame beside one finding crop, with the labelled finding box visible on both */} +#### Craft warnings + +The `craft` section reports what a viewer would notice over time and a single +frame cannot show. Every craft finding is a warning, even under `--strict`: a +film may break one on purpose. Its message names the fix and the skill reference to read. +They are measured on an 8 fps sweep of the whole film, with each short line's +edges re-measured to about 0.01 s, and skipped for a `--range` check. + +| Code | Warns when | +| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `line_unread` | A reading-size line (30 px or taller at 1080) is on screen for less than its floor: 0.4 s for one or two words, otherwise three quarters of 0.5 s + 0.3 s a word. The film's last line needs 2 s. | +| `dead_stretch` | Nothing on screen changes for more than 3 s, by the same classifier `keepsMoving` uses. | +| `text_below_floor` | Text under 2.6% of the frame's short side (28 px on 1080) stays on screen 0.5 s or more. One finding per file lists every such element. | +| `first_frame_empty` | Frame 0 paints nothing but the background: no text, image, video, canvas or SVG. The first frame is the thumbnail on social players. | +| `film_silent` | A film longer than 15 s has no unmuted `