diff --git a/DOCS_GUIDELINES.md b/DOCS_GUIDELINES.md index 8bd6d6b413..6edc01d723 100644 --- a/DOCS_GUIDELINES.md +++ b/DOCS_GUIDELINES.md @@ -91,8 +91,7 @@ After CLI commands, show what the user should see: ```bash npx hyperframes preview -# ✓ Server running at http://localhost:3000 -# ✓ Watching for changes... +# Studio running at http://localhost:3002 ``` ### Use CodeGroup for multi-platform commands diff --git a/docs/guides/skills.mdx b/docs/guides/skills.mdx index 8c60644600..a2e08f03fb 100644 --- a/docs/guides/skills.mdx +++ b/docs/guides/skills.mdx @@ -19,7 +19,8 @@ The skills split into three groups: npx hyperframes skills update ``` - Installs exactly the core set — the `/hyperframes` router, the `hyperframes-*` domain skills, and `media-use` — and the router installs each creation workflow on demand the first time it routes there. Always installs from the repo's current `main`. Works with [Claude Code](https://claude.ai/claude-code), [Cursor](https://cursor.sh), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Codex CLI](https://github.com/openai/codex), [GitHub Copilot CLI](/guides/copilot-cli), and [Google Antigravity](/guides/antigravity). + Installs exactly the core set — the `/hyperframes` router, the `hyperframes-*` domain skills, and `media-use` — and the router installs each creation workflow on demand the first time it routes there. Always installs from the repo's current `main`. Works with [Claude Code](https://claude.ai/claude-code), [Cursor](https://cursor.com), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Codex CLI](https://github.com/openai/codex), [GitHub Copilot CLI](/guides/copilot-cli), and [Google Antigravity](/guides/antigravity). + ```bash @@ -27,6 +28,7 @@ The skills split into three groups: ``` In a terminal this opens a picker — the core set under the "Core Skills" group, the on-demand creation workflows under "Other", nothing pre-selected. Keep `--full-depth`: it installs the current `main`; without it `skills add` fetches the skills.sh registry blob, which lags `main` by hours. The picker is interactive-only: a non-interactive or agent run without `--skill` installs all 19, so agents should use `npx hyperframes skills update` above. + ```bash @@ -34,6 +36,7 @@ The skills split into three groups: ``` Writes every skill to your project in one shot. Use this only when you explicitly want the full set up front — the router installs workflows on demand otherwise. + ```bash @@ -41,6 +44,7 @@ The skills split into three groups: ``` Pass the bare skill name (no leading `/`) — e.g. `--skill hyperframes-animation`. Useful when you want a single capability without the full set. + Once installed, invoke `/hyperframes` in your agent. It's the capability map for everything below and routes "make me a…" intent — a video, a deck, or a composition port — to the right creation workflow based on your input. @@ -48,7 +52,8 @@ The skills split into three groups: - **Don't see a slash command after install?** Open a new agent session, or run `/skills` (Copilot CLI) / restart your agent's skill loader. Most agents pick up new skills on the next prompt. + **Don't see a slash command after install?** Open a new agent session, or run `/skills` (Copilot + CLI) / restart your agent's skill loader. Most agents pick up new skills on the next prompt. ## Keeping skills current @@ -73,41 +78,41 @@ npx hyperframes skills # install the full set explicitly The single entry point. Read `/hyperframes` before invoking anything else — it knows what's available and which workflow fits your request. -| Skill | Use when | -| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 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 One workflow per input shape. The router (`/hyperframes`) picks one of these for you — but you can invoke them directly when you already know which fits. -| 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. | +| 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 — 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 / list / get / delete`) and AWS Lambda rendering (`lambda deploy / render / progress / destroy / policies`). | -| `/hyperframes-registry` | Install and wire registry blocks and components into compositions via `hyperframes add`. 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. | +| 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 — 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 / list / get / delete`) and AWS Lambda rendering (`lambda deploy / render / progress / destroy / policies`). | +| `/hyperframes-registry` | Install and wire registry blocks and components into compositions via `hyperframes add`. 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. | ## Source of truth diff --git a/docs/guides/website-to-video.mdx b/docs/guides/website-to-video.mdx index b2f2215af3..80501830ed 100644 --- a/docs/guides/website-to-video.mdx +++ b/docs/guides/website-to-video.mdx @@ -20,7 +20,8 @@ Give your AI agent a URL and a creative direction. It captures the site, extract npx skills add heygen-com/hyperframes ``` - Works with [Claude Code](https://claude.ai/claude-code), [Cursor](https://cursor.sh), [Gemini CLI](https://github.com/google-gemini/gemini-cli), and [Codex CLI](https://github.com/openai/codex). + Works with [Claude Code](https://claude.ai/claude-code), [Cursor](https://cursor.com), [Gemini CLI](https://github.com/google-gemini/gemini-cli), and [Codex CLI](https://github.com/openai/codex). + Open your agent in any directory and describe the video you want: @@ -34,6 +35,7 @@ Give your AI agent a URL and a creative direction. It captures the site, extract Agents also trigger this skill automatically when they see a URL and a video request. + ```bash @@ -41,6 +43,7 @@ Give your AI agent a URL and a creative direction. It captures the site, extract ``` Opens the video in your browser. Edits reload automatically. + ```bash @@ -51,26 +54,29 @@ Give your AI agent a URL and a creative direction. It captures the site, extract ✓ Captured 750 frames in 12.4s ✓ Encoded to my-video.mp4 (25.0s, 1920×1080, 6.8MB) ``` + - You don't need to run `npx hyperframes capture` manually — the skill instructs the agent to capture as the first step. The capture command is documented [below](#capture-command) for advanced use. + You don't need to run `npx hyperframes capture` manually — the skill instructs the agent to + capture as the first step. The capture command is documented [below](#capture-command) for + advanced use. ## How the Pipeline Works The skill follows the [Hyperframes pipeline](/guides/pipeline): seven steps, each producing a named artifact that feeds the next. -| Step | Output | What happens | -|------|--------|-------------| -| **Capture** | `capture/` | Extract screenshots, design tokens, fonts, assets, animations | -| **Design** | `DESIGN.md` | Brand reference — colors, typography, component stylings, spacing, iteration guide | -| **Strategy & Messaging** | — | Align on video type, style, the ONE message, and narrative arc | -| **Storyboard + Script** | `STORYBOARD.md` + `SCRIPT.md` | Concept-first storyboard and narration script, written together | -| **VO + Timing** | `narration.wav` + `transcript.json` | TTS audio with word-level timestamps | -| **Build** | `compositions/*.html` | Animated HTML compositions, one per beat | -| **Validate** | Snapshot PNGs + lint/validate pass | Visual verification and runtime checks before delivery | +| Step | Output | What happens | +| ------------------------ | ----------------------------------- | ---------------------------------------------------------------------------------- | +| **Capture** | `capture/` | Extract screenshots, design tokens, fonts, assets, animations | +| **Design** | `DESIGN.md` | Brand reference — colors, typography, component stylings, spacing, iteration guide | +| **Strategy & Messaging** | — | Align on video type, style, the ONE message, and narrative arc | +| **Storyboard + Script** | `STORYBOARD.md` + `SCRIPT.md` | Concept-first storyboard and narration script, written together | +| **VO + Timing** | `narration.wav` + `transcript.json` | TTS audio with word-level timestamps | +| **Build** | `compositions/*.html` | Animated HTML compositions, one per beat | +| **Validate** | Snapshot PNGs + lint/validate pass | Visual verification and runtime checks before delivery | See [the pipeline guide](/guides/pipeline) for a detailed walkthrough of each step, the contents of every generated file, and how to iterate without re-running the whole pipeline. The structure is useful for any Hyperframes project, not just website captures. @@ -78,16 +84,18 @@ See [the pipeline guide](/guides/pipeline) for a detailed walkthrough of each st The prompt determines the format. Include a duration and creative direction: -| Type | Duration | Example | -|------|----------|---------| -| Social ad | 10–15s | _"15-second Instagram reel. Energetic, fast cuts."_ | -| Product demo | 30–60s | _"45-second demo showing the top 3 features."_ | -| Feature announcement | 15–30s | _"Feature announcement highlighting the new AI agents."_ | -| Brand reel | 20–45s | _"30-second brand video. Celebrate the design."_ | -| Launch teaser | 10–20s | _"12-second teaser. Super minimal. Just the hook."_ | +| Type | Duration | Example | +| -------------------- | -------- | -------------------------------------------------------- | +| Social ad | 10–15s | _"15-second Instagram reel. Energetic, fast cuts."_ | +| Product demo | 30–60s | _"45-second demo showing the top 3 features."_ | +| Feature announcement | 15–30s | _"Feature announcement highlighting the new AI agents."_ | +| Brand reel | 20–45s | _"30-second brand video. Celebrate the design."_ | +| Launch teaser | 10–20s | _"12-second teaser. Super minimal. Just the hook."_ | - Creative direction matters more than format. _"Playful, hand-crafted feel"_ or _"dark, developer-focused, show code"_ shapes the storyboard and drives every visual decision the agent makes. + Creative direction matters more than format. _"Playful, hand-crafted feel"_ or _"dark, + developer-focused, show code"_ shapes the storyboard and drives every visual decision the agent + makes. ## Enriching Captures with Gemini Vision @@ -110,24 +118,20 @@ OpenRouter is used when its key is present (it takes priority if both are set). - ``` - - hero-bg.png — 582KB, section: "Hero", above fold - ``` - The agent knows the file exists and where it was on the page, but not what it looks like. + ``` - hero-bg.png — 582KB, section: "Hero", above fold ``` The agent knows the file exists and + where it was on the page, but not what it looks like. - ``` - - hero-bg.png — 582KB, A gradient wave in purple and blue sweeps - across a dark background, creating an aurora-like effect. - ``` - The agent knows what the image actually shows, enabling better creative decisions in the storyboard. + ``` - hero-bg.png — 582KB, A gradient wave in purple and blue sweeps across a dark background, + creating an aurora-like effect. ``` The agent knows what the image actually shows, enabling + better creative decisions in the storyboard. | Tier | Rate limit | Cost per image | -|------|-----------|----------------| -| Free | 5 RPM | Free | -| Paid | 2,000 RPM | ~$0.001 | +| ---- | ---------- | -------------- | +| Free | 5 RPM | Free | +| Paid | 2,000 RPM | ~$0.001 | A typical capture with 40 images costs about **$0.04** on the paid tier. @@ -148,26 +152,26 @@ npx hyperframes capture https://stripe.com Fonts: sohne-var ``` -| Flag | Default | Description | -|------|---------|-------------| -| `-o, --output` | `./capture` | Output directory (auto-suffixes to `./capture-2/`, `./capture-3/`, … if `./capture/` is taken) | -| `--timeout` | `120000` | Page load timeout in ms | -| `--skip-assets` | `false` | Skip downloading images and fonts | -| `--max-screenshots` | `24` | Maximum screenshot count | -| `--json` | `false` | Output structured JSON for programmatic use | +| Flag | Default | Description | +| ------------------- | ----------- | ---------------------------------------------------------------------------------------------- | +| `-o, --output` | `./capture` | Output directory (auto-suffixes to `./capture-2/`, `./capture-3/`, … if `./capture/` is taken) | +| `--timeout` | `120000` | Page load timeout in ms | +| `--skip-assets` | `false` | Skip downloading images and fonts | +| `--max-screenshots` | `24` | Maximum screenshot count | +| `--json` | `false` | Output structured JSON for programmatic use | ### What Gets Captured -| Data | Description | -|------|-------------| -| **Screenshots** | Viewport captures at every scroll depth — dynamic count based on page height | -| **Colors** | Pixel-sampled dominant colors + computed styles, including oklch/lab conversion | -| **Fonts** | CSS font families + downloaded woff2 files | -| **Assets** | Images, SVGs with semantic names, Lottie animations, video previews | -| **Text** | All visible text in DOM order | -| **Animations** | Web Animations API, scroll-triggered animations, WebGL shaders | -| **Sections** | Page structure with headings, types, background colors | -| **CTAs** | Buttons and links detected by class names and text patterns | +| Data | Description | +| --------------- | ------------------------------------------------------------------------------- | +| **Screenshots** | Viewport captures at every scroll depth — dynamic count based on page height | +| **Colors** | Pixel-sampled dominant colors + computed styles, including oklch/lab conversion | +| **Fonts** | CSS font families + downloaded woff2 files | +| **Assets** | Images, SVGs with semantic names, Lottie animations, video previews | +| **Text** | All visible text in DOM order | +| **Animations** | Web Animations API, scroll-triggered animations, WebGL shaders | +| **Sections** | Page structure with headings, types, background colors | +| **CTAs** | Buttons and links detected by class names and text patterns | ## Snapshot Command @@ -177,11 +181,11 @@ Capture key frames from a built video as PNGs — verify compositions without a npx hyperframes snapshot my-project --at 2.9,10.4,18.7 ``` -| Flag | Default | Description | -|------|---------|-------------| -| `--frames` | `5` | Number of evenly-spaced frames | -| `--at` | — | Comma-separated timestamps in seconds | -| `--timeout` | `5000` | Ms to wait for runtime to initialize | +| Flag | Default | Description | +| ----------- | ------- | ------------------------------------- | +| `--frames` | `5` | Number of evenly-spaced frames | +| `--at` | — | Comma-separated timestamps in seconds | +| `--timeout` | `5000` | Ms to wait for runtime to initialize | ## Iterating @@ -202,6 +206,7 @@ See the [pipeline guide](/guides/pipeline#iterating) for more re-entry patterns. ```bash npx hyperframes capture https://example.com --timeout 180000 ``` + Sites using frameworks like Framer lazy-load images via IntersectionObserver. The capture scrolls through the page to trigger loading, but very long pages may miss images near the bottom. Adding a Gemini key improves descriptions of captured assets, but doesn't increase the count. @@ -217,6 +222,7 @@ See the [pipeline guide](/guides/pipeline#iterating) for more re-entry patterns. ``` Lead your prompt with _"Use the /product-launch-video skill"_ for the most reliable results — site tours route there too. Agents also discover it automatically when they see a URL and a video request. +