diff --git a/docs/docs.json b/docs/docs.json index 4876a4d93..52e32f5f9 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -94,6 +94,34 @@ "prompting/generated-artwork", "prompting/recreating-references" ] + }, + { + "group": "By video type", + "pages": [ + "prompting/product-launch", + "prompting/explainers", + "prompting/code-and-prs", + "prompting/music-and-slideshows", + "prompting/captions-and-talking-heads", + "prompting/motion-graphics" + ] + }, + { + "group": "By feature", + "pages": [ + "prompting/transitions", + "prompting/captions-catalog", + "prompting/overlays-and-lower-thirds", + "prompting/code-blocks", + "prompting/data-and-maps", + "prompting/vfx-and-liquid-glass", + "prompting/rendering-and-output", + "prompting/editing-existing-videos", + "prompting/media-and-audio", + "prompting/variables-and-templating", + "prompting/runtimes-and-3d", + "prompting/design-systems" + ] } ] }, diff --git a/docs/prompting/captions-and-talking-heads.mdx b/docs/prompting/captions-and-talking-heads.mdx new file mode 100644 index 000000000..1fe866a8d --- /dev/null +++ b/docs/prompting/captions-and-talking-heads.mdx @@ -0,0 +1,84 @@ +--- +title: Captions and talking-head footage +description: "Two ways to dress an existing talking-head clip - readable captions or designed graphic overlays - both leaving the footage itself untouched." +--- + +## Two things you can add to a talking head + +Both workflows take an existing talking-head / interview / podcast clip and add a layer on top. Neither edits the footage — no trims, no recolor, no reframe, no reorder. The clip plays untouched underneath; you're choosing what rides on top of it. + +| You want | Route | What it adds | +| --- | --- | --- | +| The spoken words as readable text | `/embedded-captions` | Captions / subtitles — a rail, with earned climax embeds | +| Designed on-screen graphics synced to the talk | `/talking-head-recut` | Overlay cards — titles, lower-thirds, data callouts, quotes, PiP | + +If the words themselves need to read, you want captions. If you want a produced look — kinetic titles, a stat callout, a pull-quote card, the speaker shrunk into a corner while a chart fills the frame — you want overlay cards. When it's genuinely both, caption first, then package; they're siblings, not substitutes. + +`/embedded-captions` runs locally end to end — it transcribes and mattes the subject itself, no API key — and needs a **single-subject clip**. Multi-speaker clips or hard cuts get split per shot or refused, because the matte is one person. + +## Base prompt — captions + +Captions route by **identity**, not by mode. You pick one look from the catalog; the engine behind it is a lookup detail you never have to name. The default is a clean verbatim rail — `anchor` — with the occasional peak word composited behind the subject. + +> /embedded-captions Add captions to ./interview.mp4. Use the `anchor` identity — clean verbatim rail carrying the spoken words, readable lower-third. Promote just the two hardest-hitting lines to an embed behind the speaker; highlight the key word in each rail line. 9:16. Footage stays untouched. + +The rail carries most of the text; an **embed** is the scarce, earned peak — one big word matted behind the subject at the climax, never every line. Embedding the whole transcript is the most common mistake this skill guards against. + +## Base prompt — overlay cards + +> /talking-head-recut Package ./founder-clip.mp4 with designed graphic overlay cards synced to the transcript. 9:16 portrait, warm-paper style. Open with a fullscreen kicker + title hook, drop a lower-third when she names the company, a data callout card counting up the "200+ teams / $1.2M ARR" stat, and a pull-quote card for the strongest line. Speaker stays full-bleed under the cards; shrink her into a corner PiP while the data card holds. The clip plays untouched underneath. + +You describe the *cards* — their content, timing, and how the speaker shares the canvas with them (full-bleed, split, PiP, or glass overlay). The skill designs and writes each card; there's no fixed archetype list, so the overlays follow what the transcript actually says. + +## Variants + + + + > /embedded-captions Cinematic captions on ./poem.mp4 — no rail, hero typography composited behind the speaker, words accumulating as a column. Use the `editorial` identity (lowercase-italic hero). One apex word per thought, air between them. 4:5. Never grade the footage. + + Column-flow identities drop the rail and make everything embed-style — reach for them on poetic / social / "cinematic" asks where mood beats strict readability, never on an explainer where the words must read. + + + > /embedded-captions Add verbatim captions to ./outdoor-vlog.mp4. It's a bright daylight scene, so use the `ink` identity — near-black type printed onto the surface — not a light-on-bright look that washes out. Keep it a readable rail. 16:9. + + Screen-blend cream looks wash out over bright backdrops (luminance > ~180); `ink` is built for bright surfaces. Match the identity to the scene rather than asking the engine to recolor a look. + + + > /embedded-captions Bring the energy on ./hype-clip.mp4 — I want the captions to hit hard. Use the `stomp` identity: heavy themed constitution, punch reactions on the climax. Rail carries the verbatim; the payoff line is the setpiece. 9:16. + + Themed identities (`ordnance`, `terminal`, `stomp`, `neonsign`, `stardust`, …) are the answer to "make it explode / 特效 / like AE did it". Theme mode is the one place a register-gated reaction beat may touch the frame — applied after the matte composite so subject, text, and plate move as one — but the a-roll is still never graded. + + + > /talking-head-recut Recut ./analyst-interview.mp4 as a 16:9 explainer with a clinical style. Split layout: speaker on the right, data cards on the left. Cards for each claim — a count-up for the headline number, a swiss-grid comparison for the two options, a terminal-style callout for the technical bit. Auto-pace the card count for a 5-minute clip. Footage untouched. + + Layout (split / stack / pip / overlay) sets how speaker and cards share the canvas; card count auto-infers from duration and information density, with a floor of five so even a short clip has rhythm. + + + +## The knobs that matter + +**Identity and tone (captions).** One identity picks the entire look — surface, palette, motion, climax behavior. Route by content: explainer / interview / must-read words → a rail-carrying identity like `anchor`, `keynote`, or `documentary`; poetic / social / cinematic → a column-flow identity by register (`editorial`, `cream`, `loud`, `neon`); "炸 / 特效 / VFX" → a themed identity (`ordnance`, `terminal`, `stomp`). Unsure → `anchor`: the words read and the scene stays safe. Don't ask for "Standard vs Cinematic vs Theme" — those are engine names; name the identity. + +**Verbatim rail vs climax embed.** The rail is the default and carries most of the text. An embed is a promotion — one peak word matted behind the subject, scarce and spaced (roughly one per beat, never two co-visible, at most one apex). Tell the skill *which* lines earn the embed; leave the rest on the rail. + +**Style, layout, and canvas (recut).** Pick a style group (warm-paper / clinical / experimental), a layout (split / stack / pip / overlay), and a canvas ratio; the video frame follows from layout × style. The recommended ratio matches the source, but you choose — 16:9 for desktop / YouTube, 9:16 for Reels / Shorts, 4:5 for feed. + +**Keyword highlighting.** On the caption rail, a punch word can carry an inline `emphasis` — an accent-color or active-word pop — without leaving the rail. Ask for "highlight the key word in each line" and it stays readable. + +## Failure modes + +**Asking for footage edits.** Both skills add a layer and leave the a-roll exactly as shot. Trimming, speeding up, recoloring, reframing, or reordering is NLE editing and out of scope — captions and cards are the only additions. +- ❌ `add captions and trim the dead air at the start, and warm up the color to match my brand` +- ✅ `add captions; leave the footage untouched` — do the trim / grade in an editor first, then bring the finished clip here. + +**Embedding every word.** On a talking head the rail is the verbatim default; matting every caption behind the subject buries the words and spends the climax on nothing. +- ❌ `composite every caption behind the speaker for a cinematic look` (on an explainer) +- ✅ `verbatim rail; promote only the two payoff lines to an embed` + +**Multi-subject clips.** The caption matte is one person; two speakers or hard cuts flicker or get refused. +- ❌ `caption this two-person podcast in one pass` +- ✅ `split the clip per shot / per speaker first, then caption each` — or use a single-subject cut. + + + For the beat-timestamped skeleton these prompts share, see [Prompt anatomy](/prompting/anatomy); for adjectives that map to motion and emphasis settings, [Vocabulary](/prompting/vocabulary). To build a video from scratch instead of dressing existing footage, start at the router in `/hyperframes`. + diff --git a/docs/prompting/captions-catalog.mdx b/docs/prompting/captions-catalog.mdx new file mode 100644 index 000000000..c85c7a23d --- /dev/null +++ b/docs/prompting/captions-catalog.mdx @@ -0,0 +1,75 @@ +--- +title: Caption styles +description: "Map caption tone to named caption components, and prompt per-word emphasis for composed videos." +--- + +## What caption styles do and when they trigger + +Caption components are drop-in snippets that render animated on-screen text — one visual identity per component, animating per word or per line. Prompts trigger this layer when you ask for captions, subtitles, kinetic text, lyric-style words, or word-by-word titles inside a composition you're building. Describe the *energy* of the captions and the agent picks matching typography, size, and animation; name a component to lock the look. + + + These components are for **composed videos** — captions you author into a HyperFrames composition. To add captions to an existing **talking-head MP4**, use the [`/embedded-captions`](/prompting/captions-and-talking-heads) workflow instead: it carries its own catalog of caption identities built around subject matting and occlusion (the caption sits *behind* the speaker), which the composition snippets below don't do. + + +## Tone → caption component + +| Tone | Components | +| ---- | ---------- | +| **Hype / high-energy social** | [`caption-kinetic-slam`](/catalog/components/caption-kinetic-slam), [`caption-highlight`](/catalog/components/caption-highlight), [`caption-particle-burst`](/catalog/components/caption-particle-burst), [`caption-emoji-pop`](/catalog/components/caption-emoji-pop) | +| **Clean / corporate** | [`caption-clip-wipe`](/catalog/components/caption-clip-wipe), [`caption-weight-shift`](/catalog/components/caption-weight-shift) | +| **Elegant / editorial** | [`caption-editorial-emphasis`](/catalog/components/caption-editorial-emphasis), [`caption-gradient-fill`](/catalog/components/caption-gradient-fill), [`caption-weight-shift`](/catalog/components/caption-weight-shift) | +| **Neon / nightlife / music** | [`caption-neon-glow`](/catalog/components/caption-neon-glow), [`caption-neon-accent`](/catalog/components/caption-neon-accent) | +| **Tech / cyber / glitch** | [`caption-glitch-rgb`](/catalog/components/caption-glitch-rgb), [`caption-matrix-decode`](/catalog/components/caption-matrix-decode) | +| **Karaoke / lyric / follow-along** | [`caption-pill-karaoke`](/catalog/components/caption-pill-karaoke), [`caption-highlight`](/catalog/components/caption-highlight) | +| **Textured / cinematic display type** | [`caption-texture`](/catalog/components/caption-texture), [`texture-mask-text`](/catalog/components/texture-mask-text) | +| **Depth / 3D layering** | [`caption-parallax-layers`](/catalog/components/caption-parallax-layers) | + +## Text-effect components + +Three [Text Effects](/catalog/components/morph-text) components do one focused job rather than caption a whole track: + +| Component | Use when | +| --------- | -------- | +| [`caption-blend-difference`](/catalog/components/caption-blend-difference) | Text sits over busy or shifting footage and must stay legible — it auto-inverts per pixel against whatever is behind it. | +| [`morph-text`](/catalog/components/morph-text) | You want one spot to cycle through a short word list with a gooey morph ("fast / simple / yours"). | +| [`texture-mask-text`](/catalog/components/texture-mask-text) | A large display word filled with a physical texture (brick, rock, wood, metal, lava). | + +## Example prompts + +> /faceless-explainer 30-second vertical explainer. Add [`caption-highlight`](/catalog/components/caption-highlight) captions, TikTok-style — one word active at a time. + +> Hype captions with [`caption-kinetic-slam`](/catalog/components/caption-kinetic-slam): one full-screen word per beat, alternating slam-in direction. + +> Neon music-video captions using [`caption-neon-glow`](/catalog/components/caption-neon-glow). Make brand names larger with an accent color and highlight the numbers differently. + +> Fill the hero word "STONE" with [`texture-mask-text`](/catalog/components/texture-mask-text) using the rock texture. + +## Knobs + +- **Tone** picks typography, size, and animation — Hype (heavy, 72–96px, scale-pop) through Storytelling (serif, 44–56px, slow fade). See the caption-tone table in [vocabulary](/prompting/vocabulary). +- **Per-word emphasis.** "Make brand names larger with accent color," "highlight numbers differently," "add bounce to emotional keywords" all work — several components key off this: [`caption-editorial-emphasis`](/catalog/components/caption-editorial-emphasis) drives a dramatic size contrast on emphasis words, [`caption-particle-burst`](/catalog/components/caption-particle-burst) fires on keywords, and the neon components carry keyword accent colors. +- **Texture variable.** [`caption-texture`](/catalog/components/caption-texture) ships lava, marble, metal, wood, concrete, and rock — name the one you want. +- **Word list.** [`morph-text`](/catalog/components/morph-text) cycles an editable list; quote the words in order. +- **Format.** Full-screen single-word styles ([`caption-kinetic-slam`](/catalog/components/caption-kinetic-slam)) and TikTok-style highlights ([`caption-highlight`](/catalog/components/caption-highlight)) are built for vertical / social framing — say "vertical" or "9:16" so sizing and safe areas match. + +## Failure modes + +**Don't stack a heavy effect on every word.** Caption components already animate per word; layering another emphasis on top of that competes and turns illegible. Emphasize only the keywords. +- ❌ `make every word explode with particles` +- ✅ `caption-particle-burst, firing only on the keywords` + +**Don't mix caption styles in one section.** One identity per composition (or per section) reads as designed; two competing styles read as a mistake. +- ❌ `use caption-neon-glow and caption-matrix-decode together` +- ✅ pick one; switch styles only across a clear section break + +**Don't reach for these on talking-head footage.** These are composition snippets, not the matting/occlusion pipeline — captions won't sit behind the speaker. +- ❌ `/hyperframes add caption-highlight to my interview.mp4` +- ✅ `/embedded-captions` (see [captions and talking heads](/prompting/captions-and-talking-heads)) + +**Don't match a hype style to calm content.** A high-energy caption on a corporate explainer fights the tone; let the tone table pick the identity. +- ❌ `glitchy RGB captions` (on a wellness brand piece) +- ✅ `clean captions with caption-clip-wipe` + +**Don't invent caption names.** Only the components in the [Captions](/catalog/components/caption-highlight) and [Text Effects](/catalog/components/morph-text) groups exist. +- ❌ `add typewriter-bounce captions` +- ✅ describe the tone ("tutorial, monospace, typewriter") or name a real component diff --git a/docs/prompting/code-and-prs.mdx b/docs/prompting/code-and-prs.mdx new file mode 100644 index 000000000..494823d6e --- /dev/null +++ b/docs/prompting/code-and-prs.mdx @@ -0,0 +1,71 @@ +--- +title: Code changes and PRs +description: "What to say to turn a GitHub pull request into a code-change explainer - changelog, feature reveal, fix, or refactor walkthrough." +--- + +## What this makes + +A code-change explainer built from a GitHub pull request. The [`/pr-to-video`](/prompting/overview) workflow reads the PR through `gh` — the diff, commits, files, and contributors — reshapes it into a story, and builds it frame by frame, rendering code beats on a purpose-built diff surface. + +The input is a **code change**, not a website or a product page. A PR link (`https://github.com/owner/repo/pull/N`), an `owner/repo#N` ref, or "this PR" in a checked-out repo all work. A product to sell → [`/product-launch-video`](/prompting/product-launch); a topic with no PR → [`/faceless-explainer`](/prompting/explainers). Unsure → start at `/hyperframes`. + +## Base prompt + +Verified, from the [examples](/prompting/examples) page — a 30-second feature reveal: + +> /pr-to-video Make a 30-second 1920x1080 feature-reveal video from [PR URL]. Lead with what users get, not the diff; show the key code change with the `code-diff` block for one beat only; end on version number + repo URL. No narration, kinetic captions instead. + +## Variants + + + + > /pr-to-video Make a ~40-second 1920x1080 changelog video from [PR URL]. Changelog angle: open with the release line, then one beat per notable change — a short label and a one-line "what it does" each. Show at most two `code-diff` hunks across the whole video. End on version + repo URL. Calm male TTS narration. + + A changelog trades depth for breadth — many small changes, each a beat, rather than one change explored deeply. Keep code beats sparse so the pace stays fast. + + + > /pr-to-video Make a ~40-second 1920x1080 fix-explainer from [PR URL], for developers. Fix angle: state the bug's symptom first, then the root cause, then the one-line fix on the `code-diff` block. End on version + repo URL. No narration, kinetic captions. + + A fix reads as symptom → cause → fix. Lead with what users saw break, not the stack trace — the diff is the payoff, not the opening. + + + > /pr-to-video Make a ~70-second 1920x1080 refactor-walkthrough from [PR URL], for developers. Refactor angle: why the old shape hurt, then the new shape, showing the before/after with the `code-morph` block for the key file. End on version + repo URL. Calm male TTS narration. + + A refactor changes shape without changing behavior, so the story is *why* the new structure is better. `code-morph` animates one form transforming into another — the right block when the point is the transition, not a line-by-line delta. + + + +## The knobs that matter + +| Knob | What to say | Why it matters | +| --- | --- | --- | +| **Impact vs diff** | "lead with what users get, not the diff" | The video explains the *change*, it doesn't read the diff aloud; opening on impact answers "why should I care?" before the code | +| **How many hunks** | "one `code-diff` beat only" / "at most two hunks" | Code beats feature 2-4 real hunks total, each a small legible snippet — a whole file is unreadable at video scale | +| **Which code block** | `code-diff` for a delta · `code-morph` for a refactor · `code-typing` for new code | The block matches the story: a diff shows added/removed lines, a morph shows one shape becoming another | +| **Angle** | "changelog" / "feature-reveal" / "fix-explainer" / "refactor-walkthrough" | Sets the story shape; the workflow reshapes the PR into it rather than walking files in diff order | +| **Audience** | "for developers" (default) / "mixed technical" / "non-technical stakeholders" | Shifts how much the narration assumes — a non-technical cut leans harder on impact and lighter on code | +| **End card** | "end on version number + repo URL" | The conventional close for a code explainer; state what goes on it so it's a real CTA, not an afterthought | +| **Narration vs captions** | "calm male narration" or "no narration, kinetic captions instead" | Both are supported; captions-only keeps it silent-friendly for social, narration carries a longer walkthrough | +| **Length** | "~30s" for one headline, up to ~3 min for a large PR | The workflow reads the change size and recommends a tier — a huge PR is a ceiling on story, not a floor to fill | + + + The style is fixed to the workflow's warm-editorial preset with a navy code surface built for diffs — it's what makes the code beats legible. You don't choose a theme here; you choose the angle, the hunks, and the narration. + + +## Common failure modes + +**Forcing a theme over the preset.** The style is fixed for a reason — the navy code surface is tuned for diff legibility; a foreign theme fights it and produces a compromise (see [rules and anti-patterns](/prompting/rules-and-anti-patterns)). +- ❌ `/pr-to-video ... dark theme, neon accents` +- ✅ let the preset carry the look; spend your specificity on the angle and the code beats + +**Asking for the whole diff.** A PR video explains the change; it doesn't recite every file. A full diff is unreadable at video scale. +- ❌ `walk through the entire diff, file by file` +- ✅ `feature the 2-3 key hunks, each a small legible snippet` + +**Opening on the code.** The diff is the payoff, not the hook — lead with what the change means. +- ❌ `start with the diff, then explain what it does` +- ✅ `lead with what users get, then show the key hunk` + +**Hard-timing a narrated cut.** With narration the spoken length sets the runtime; state a range, not a fixed number. +- ❌ `a 40-second narrated walkthrough` +- ✅ `a ~40-second narrated walkthrough` diff --git a/docs/prompting/code-blocks.mdx b/docs/prompting/code-blocks.mdx new file mode 100644 index 000000000..2022ab086 --- /dev/null +++ b/docs/prompting/code-blocks.mdx @@ -0,0 +1,125 @@ +--- +title: Code animations +description: "Prompt code walkthroughs — typing, diffing, highlighting, scrolling — and pick a terminal or editor theme by name." +--- + +## Code animations + +Code is the one subject where the framework does the hard part for you. The [Code Animations](/catalog/blocks/code-typing) blocks handle syntax highlighting, caret tracking, diff coloring, and camera moves deterministically — you describe the *walkthrough*, name the block, and paste your snippet. This page is the vocabulary for doing that well; for turning a real pull request into a code-change video, see [Code and PRs](/prompting/code-and-prs). + +Everything here follows the [one-shot skeleton](/prompting/anatomy): route, spec, beats, copy, technique, negatives. The "technique" slot is where you name the block, and the "copy" slot is where your code goes — quoted exactly, because unquoted code gets paraphrased into something that won't compile. + +### Pick the motion by what the viewer should learn + +Each Code Animations block answers a different "what is the viewer supposed to notice." Map the intent to the block: + +| You want to show… | Name this block | Length | +| ------------------------------------------ | ------------------------------------------------------- | ------ | +| Code being written, character by character | [`code-typing`](/catalog/blocks/code-typing) | 5s | +| An edit — before → after, red/green | [`code-diff`](/catalog/blocks/code-diff) | 6s | +| One line as *the* line, everything else dim | [`code-highlight`](/catalog/blocks/code-highlight) | 5s | +| Walking a long file to a spot deep inside | [`code-scroll`](/catalog/blocks/code-scroll) | 6s | +| One snippet transforming into another | [`code-morph`](/catalog/blocks/code-morph) | 7s | +| Snippets flying in and stacking up | [`code-snippet-flight`](/catalog/blocks/code-snippet-flight) | 6s | +| Code on a rotating 3D slab (title-card feel) | [`code-3d-extrude`](/catalog/blocks/code-3d-extrude) | 8s | +| Code resolving out of a shader dissolve | [`code-shader-dissolve`](/catalog/blocks/code-shader-dissolve) | 7s | +| Code assembling from a particle swarm | [`code-particle-assemble`](/catalog/blocks/code-particle-assemble) | 8s | + +The first four are the workhorses of a code *walkthrough* — they keep the code readable and the viewer oriented. The last three are entrance spectacle: they look great as an opener or a hero moment, but they trade legibility for motion, so don't ask them to carry an explanation. + + + `code-morph` re-drives Shiki Magic Move as a paused GSAP timeline, and `code-diff` collapses removed lines and expands added lines. Both read "an edit happened" far more clearly than retyping the whole snippet with `code-typing` — reach for them when the story is *a change*, not *authoring from scratch*. + + +### Prompting a typing reveal + +`code-typing` streams tokens with a caret that tracks the frontier — no CSS animation, so it seeks cleanly. Give it the exact code and a pace. + +> /motion-graphics 6-second 1920x1080 video. A dark editor types this snippet, token by token, caret tracking the frontier, then holds on the blinking cursor for the final second: +> ``` +> export async function render(comp: Composition) { +> await comp.seek(0); +> return comp.capture(); +> } +> ``` +> Use the `code-typing` registry block. No narration, no image or media files. + +**Quote the code as a literal block.** Prose descriptions of code get paraphrased. +- ❌ `type out a function that seeks to zero and captures` +- ✅ paste the actual snippet in a fenced block — it renders verbatim + +**Give the caret somewhere to rest.** Compositions hold their final state, so if you don't ask for a hold the last frame is a frozen full snippet — the [dead-motion tell](/prompting/motion). +- ❌ `types the code and ends` +- ✅ `types the code, then holds on the blinking cursor for the final second` + +### Prompting a diff or a highlight + +For "here's what changed," hand `code-diff` the before and after and let it color the delta. For "look at *this* line," give `code-highlight` the full context and name the target line. + +> /motion-graphics 6-second 1920x1080 video. Show this edit as a colored diff — the removed line collapses in red, the added line expands in green: +> removed: `const res = await fetch(url)` +> added: `const res = await fetch(url, { signal })` +> Use the `code-diff` registry block. No audio. + +> /motion-graphics 5-second 1920x1080 video. Show a 12-line config file; a highlight band sweeps to line 7 (`timeout: 30_000`) while the surrounding lines dim. Hold with line 7 lit. Use the `code-highlight` registry block. No audio. + +**Name the target line unambiguously.** The block dims context around one line — tell it which. +- ❌ `highlight the important line` +- ✅ `highlight line 7 (`timeout: 30_000`)` + +### Prompting a scroll-through + +`code-scroll` moves the camera down a long file to bring a target line to center and spotlights it — the block for walking real modules, not toy snippets. + +> /motion-graphics 6-second 1920x1080 video. Scroll a ~60-line source file so line 44 (`return dedupeFrames(frames)`) arrives at center and gets spotlighted; ease the scroll and let it settle without snapping. Use the `code-scroll` registry block. No audio. + +**Ask the scroll to ease and settle, not snap.** A linear scroll that stops dead reads mechanical. +- ❌ `scroll straight to the line` +- ✅ `ease the scroll and let it settle` — pair with the [motion grammar](/prompting/motion) + +### Choosing a theme by name + +The [Code Snippets](/catalog/blocks/code-snippet-monokai) blocks are pre-styled shells with per-character typing already built in. There are two families, and you select one by asking for it in plain language — the exact block name is the theme name. + +**macOS Terminal.app profiles** — a real terminal window chrome. Say "apple terminal, ocean profile" → [`code-snippet-apple-terminal-ocean`](/catalog/blocks/code-snippet-apple-terminal-ocean). The full set of profiles: + +| Profile | Block | Profile | Block | +| ------------ | ----------------------------------------- | -------------- | ------------------------------------------- | +| Basic | `code-snippet-apple-terminal-basic` | Novel | `code-snippet-apple-terminal-novel` | +| Clear Dark | `code-snippet-apple-terminal-clear-dark` | Ocean | `code-snippet-apple-terminal-ocean` | +| Clear Light | `code-snippet-apple-terminal-clear-light` | Pro | `code-snippet-apple-terminal-pro` | +| Grass | `code-snippet-apple-terminal-grass` | Red Sands | `code-snippet-apple-terminal-red-sands` | +| Homebrew | `code-snippet-apple-terminal-homebrew` | Silver Aerogel | `code-snippet-apple-terminal-silver-aerogel`| +| Man Page | `code-snippet-apple-terminal-man-page` | Solid Colors | `code-snippet-apple-terminal-solid-colors` | + +**VS Code workbench themes** — full editor chrome (activity bar, sidebar, tabs, terminal, status bar). Say "monokai" or "visual studio dark": + +| Say this | Block | Say this | Block | +| ---------------------- | ------------------------------------- | ------------------- | ---------------------------------- | +| Monokai | `code-snippet-monokai` | Solarized Light | `code-snippet-solarized-light` | +| Dark Modern | `code-snippet-dark-modern` | Light Modern | `code-snippet-light-modern` | +| Dark Plus | `code-snippet-dark-plus` | Light Plus | `code-snippet-light-plus` | +| Dark 2026 | `code-snippet-dark-2026` | Light 2026 | `code-snippet-light-2026` | +| High Contrast | `code-snippet-high-contrast` | High Contrast Light | `code-snippet-high-contrast-light` | +| Visual Studio Dark | `code-snippet-visual-studio-dark` | Visual Studio Light | `code-snippet-visual-studio-light` | + +> /motion-graphics 5-second 1920x1080 video. A macOS Terminal window in the Ocean profile types `npx skills add heygen-com/hyperframes` character by character, then holds on the prompt. Use the `code-snippet-apple-terminal-ocean` registry block. No narration. + +**Match the theme to the surface you're claiming to show.** A terminal command in a VS Code editor chrome reads wrong; a source file in Terminal.app reads wrong. +- ❌ `monokai theme typing a shell command` +- ✅ `apple terminal homebrew profile typing a shell command` + + + Ambiguity resolves to the closest named block. "Dark theme" is under-specified — the agent picks one of a dozen dark variants and you may not get the one you pictured. Say the theme name. This is the [specification dial](/prompting/specification-dial) applied to code: name the block when the default choice can miss. + + +### Pairing with a pull request + +When the code you're animating comes from a real PR, don't hand-write the beats — the [`/pr-to-video`](/prompting/code-and-prs) workflow reads the diff and composes `code-diff`, `code-highlight`, and `code-scroll` around the actual changed hunks. Use the blocks on this page directly when you're illustrating a concept; route through the PR workflow when you're narrating a specific change set. + +### Where to go next + +- [Anatomy of a one-shot prompt](/prompting/anatomy) — the skeleton every prompt above uses. +- [Copy-paste examples](/prompting/examples) — full prompts you can adapt. +- [Code and PRs](/prompting/code-and-prs) — turning a GitHub PR into a code-change video. +- [Motion that reads premium](/prompting/motion) — the hold-and-settle rules the code blocks still need from you. diff --git a/docs/prompting/data-and-maps.mdx b/docs/prompting/data-and-maps.mdx new file mode 100644 index 000000000..1a4f2a476 --- /dev/null +++ b/docs/prompting/data-and-maps.mdx @@ -0,0 +1,81 @@ +--- +title: Data and maps +description: "Prompt animated charts, count-up stats, and maps — highlight regions, draw flows, size bubbles — or hand-draw a chart for full control." +--- + +## Data and maps + +Numbers and geography are the two subjects where "what data" and "how it moves" are separate decisions. The [Data](/catalog/blocks/data-chart) blocks give you a polished chart or map you feed values into; the count-up [showcase](/catalog/blocks/apple-money-count) blocks handle the odometer-and-flourish moment. Everything here plugs into the [one-shot skeleton](/prompting/anatomy) — the data goes in the "copy" slot, the block name in "technique." + +### Charts: name the block, or hand-draw + +There are two ways to get a chart, and the choice is about control: + +- **Name [`data-chart`](/catalog/blocks/data-chart)** to get the built animated bar + line chart — staggered reveal, value labels, NYT-style typography — and feed it your numbers. Fast, consistent, no design decisions. +- **Say "hand-draw everything — no chart library"** to make the agent build the chart from inline SVG and GSAP instead. You give up the polish of the block for total control over shape, motion, and layout — a bar race that overtakes mid-animation, an arc that draws to match a counter, a layout no library ships. + +Feed data inline or as a file. Small series go straight in the prompt; a CSV gets referenced and parsed at build time (keep it deterministic — no [render-time fetches](/concepts/determinism)). + +> 12-second 1920x1080 video. Turn this into an animated bar chart with a staggered reveal and value labels counting up on each bar: +> ``` +> Python 41, TypeScript 33, Rust 19, Go 14, Java 9 +> ``` +> Use the `data-chart` registry block. No audio. + +> 10-second 1920x1080 video, dark slate background. Title "Top languages 2026" top-left. Five horizontal bars (Python, TypeScript, Rust, Go, Java) grow from zero with staggered starts, overtaking each other twice mid-animation; each bar has a right-edge value label counting up to its final %. End state holds 2s with the leader pulsing once. Hand-draw everything — no chart library. No audio. + +**State the block *or* opt out of it — don't leave it implicit.** "Animate this data" without a decision drifts between a generic block and an improvised layout. +- ❌ `animate this CSV as a chart` +- ✅ `turn this CSV into an animated bar chart — use the `data-chart` registry block` **or** `…hand-draw everything, no chart library` + +**Format numbers for the animation you asked for.** An odometer count-up needs fixed digit columns; a `$0 → $4.2M` range forces an awkward `$0.0M` start. +- ❌ `counts from $0 to $4.2M` +- ✅ `counts up to $4.2M` + +### Count-up stats + +For a single hero number, [`apple-money-count`](/catalog/blocks/apple-money-count) is the Apple-style finance counter — it rolls from $0, flashes green, and bursts money icons with sound. Name it when you want that exact flourish; hand-draw when you want a bare number in your own type. + +> /motion-graphics 6-second 1920x1080 video, dark navy background. Beat 1 (0-1s): label "ARR" fades up small, top-center. Beat 2 (1-4s): a giant number counts up to $4.2M with an odometer roll, easing out as it lands. Beat 3 (4-6s): "+312% YoY" stamps in below in green, then settles into a gentle ambient idle. Use the `apple-money-count` registry block as base. No narration. + +### Maps: match the ask to the map + +Each map block answers a different geographic question. Say what the map is *for* and name the matching block: + +| You want to… | Name this block | Length | +| ----------------------------------------------- | -------------------------------------------------- | ------ | +| Shade US states by a value (choropleth) | [`us-map`](/catalog/blocks/us-map) | 12s | +| Size US cities by a value (proportional bubbles)| [`us-map-bubble`](/catalog/blocks/us-map-bubble) | 12s | +| Draw connections between US cities (origin→dest)| [`us-map-flow`](/catalog/blocks/us-map-flow) | 12s | +| Show US states as an equal-weight hex grid | [`us-map-hex`](/catalog/blocks/us-map-hex) | 10s | +| Shade Spain by autonomous community | [`spain-map`](/catalog/blocks/spain-map) | 12s | +| Shade the world country by country | [`world-map`](/catalog/blocks/world-map) | 14s | + +The US maps are composable — `us-map-bubble` and `us-map-flow` are built to layer over the base `us-map`, so "shade states *and* draw flows between two cities" is one composition, not two. + +> 12-second 1920x1080 video. A US choropleth shades states by adoption rate with staggered reveals and a gradient legend, then connection arcs draw between San Francisco, Austin, and New York. Use the `us-map` and `us-map-flow` registry blocks. No audio. + +**Pick the encoding, don't just say "map."** Choropleth (color), bubble (size), hex (equal weight), and flow (arcs) tell different stories from the same data. +- ❌ `put California's number on a US map` +- ✅ `size each city as a proportional bubble` → `us-map-bubble`, or `shade each state by value` → `us-map` + +**Name the region's block.** The choropleths are region-specific with baked-in projections (`spain-map` is D3 conic conformal, `world-map` is Natural Earth) — there's no generic "any country" map. +- ❌ `a map of Spain's regions` (leaves the projection and geography to chance) +- ✅ `use the `spain-map` registry block` + +### Routes and flights + +For a point-to-point journey — a route drawing across a map with a landing beat — [`nyc-paris-flight`](/catalog/blocks/nyc-paris-flight) is the Apple-style flight animation: a plane flies New York → Paris with a marker circle, landing pop, and sound effects. Use it as the base and re-point the endpoints in your prompt. + +> /motion-graphics 6-second 1920x1080 video. A realistic map with a plane flying between two cities, a marker circle at the origin, and a landing pop at the destination. Use the `nyc-paris-flight` registry block as base. No narration. + +**A route is a flow with a vehicle, not a static arc.** If you want the drawn arc without the plane and sound, that's `us-map-flow`; if you want the journey performance, that's `nyc-paris-flight`. +- ❌ `draw a line from NYC to Paris` (ambiguous between arc-only and full flight) +- ✅ `a plane flies the route with a landing pop` → `nyc-paris-flight` + +### Where to go next + +- [Anatomy of a one-shot prompt](/prompting/anatomy) — the skeleton, and why odometers need fixed digit columns. +- [Copy-paste examples](/prompting/examples) — bar-chart race and stat-grid prompts to adapt. +- [Generated artwork](/prompting/generated-artwork) — where hand-drawn HTML/CSS/SVG shines, and where it doesn't. +- [The specification dial](/prompting/specification-dial) — deciding when to name a block versus hand-draw. diff --git a/docs/prompting/design-systems.mdx b/docs/prompting/design-systems.mdx new file mode 100644 index 000000000..5778e0e6d --- /dev/null +++ b/docs/prompting/design-systems.mdx @@ -0,0 +1,90 @@ +--- +title: Design systems and brand +description: "Point the agent at a source of brand truth - a design spec, a site, or a Figma file - instead of asking for 'on-brand', and let it compose the frame." +--- + +## Design systems and brand + +"Make it on-brand" is the single vaguest thing you can ask. The agent has no way to know what your brand *is*, so it invents one. The fix is always the same: give it a **source of brand truth** — a design spec, a live site, or a Figma file — and name it in the prompt. Everything on this page is a way to do that. + +## Point at a spec, don't describe a vibe + +HyperFrames projects can carry a design spec — `frame.md` (video-first) or `design.md` — whose frontmatter tokens are the machine-readable brand: exact hex values, font families, weight relationships, and the brand's Do's and Don'ts. When one exists, name it: + +> Use the palette and type from `frame.md`. Build a 15-second feature announcement. + +- ❌ `make it feel on-brand and premium` +- ✅ `pull colors and fonts from design.md; premium means generous spacing and one restrained accent` + +The engine rationale: `on-brand` is a mood the agent guesses at. A spec's frontmatter is normative — the agent quotes the hex and font family verbatim instead of approximating, and reads the prose sections for intent. If your brand lives somewhere else (a PDF brand guide, a screenshot, pasted hex codes), attach it — attachments and pasted tokens are read more reliably than a described impression. + +## Brand is truth for color and type — not for layout + +A design spec tells the agent what the brand *looks like*; it does **not** dictate how to compose a video frame. Say what's sacred and let the agent stage the rest: + +> Colors and fonts are locked to the brand — keep the exact hexes and the display/body pairing. Layout, spacing, and motion are yours to compose for video. + +The engine rationale: web-scale brand values don't survive video. A `1px` border with a `0.06`-opacity shadow is invisible after H.264 compression; a web body size vanishes on a 1080p frame. The brand color, background choice (if the brand is a light canvas, keep it light), fonts, and weight relationships are strict — but type sizes, decorative opacity, and border weight get scaled up for the medium. Over-specifying layout from a web design system fights this; pin the palette and typography, delegate the frame. + +## Use the site's own palette and fonts + +When there's no spec but there is a brand out there, point at it and let the agent extract: + +> Match this site's look — pull its palette and fonts — and make a 20-second launch clip: `https://…` + +For a well-known brand, naming it is often enough for the agent to research the palette and typography. One caveat worth stating: a single-page-app homepage often returns a near-empty shell, so if the palette comes back thin, point the agent at a blog, press, or docs page instead. This is the same brand-truth move — the *site* is the source instead of a file. + +## Bringing in a Figma frame, brand, or logo + +If the brand lives in Figma, ask for it directly — the agent imports it rather than eyeballing a screenshot: + +> Bring in the brand tokens from this Figma file, then build the intro: `https://figma.com/…` + +> Import this Figma frame as the opening scene and this logo as an SVG: `` + +The [Figma import](/guides/figma) path freezes each import as a local asset with recorded provenance (so renders stay deterministic) and imports brand variables as composition brand tokens. Two things worth knowing when you phrase the ask: + +- **Import tokens before components.** Say "brand tokens first, then the components" — that's what lets imported component colors link to your brand variables instead of baking in duplicate hexes. +- **Storyboard frames are states, not slides.** If you point at a strip of scene frames, ask the agent to *reconstruct the motion between them* — a frame showing an element at four positions is one element animating, not four stills to flip through. + +## Keeping a multi-video series consistent + +For a series — a launch set, a weekly clip, a per-region cut — consistency comes from a **shared source of truth**, not from re-describing the brand each time: + +> All four videos share `frame.md` for palette and type. Only the headline and the stat change per video. + +Because the runtime exposes every declared brand token as a CSS custom property, the parts that stay constant come from the one spec (or one set of imported Figma tokens), and the parts that vary become [variables](/prompting/variables-and-templating). Change one brand value in the spec and every video re-skins on the next render — you don't touch four files. This is where design systems and templating meet: the brand is shared, the content is parameterized. + +## Supplying brand assets by path + +Logos, fonts, textures, and product shots are inputs — hand the agent the path, don't ask it to draw them: + +> Logo at `assets/logo.svg`, brand font files in `assets/fonts/`, product shot at `assets/hero.png`. Use them; don't invent placeholders. + +Prefer an SVG logo (scalable, animatable) over a raster one. State the paths explicitly so the agent wires the real assets instead of generating stand-ins — and so the render is deterministic, with every asset present locally before it starts. + +## Supply inputs a workflow accepts — don't fight its preset + +The creation workflows (`/product-launch-video`, `/website-to-video`, and the rest) each come with a designed look. The productive move is to feed that look your brand inputs, not to override its composition after the fact: + +- ❌ `run /product-launch-video, then restyle every scene to my colors afterward` +- ✅ `run /product-launch-video with my palette, fonts, and logo as inputs up front` + +The engine rationale: a workflow's preset is a coherent, tested system — colors, spacing, motion, and component treatments that hang together. Supplying brand inputs at the start lets it apply your palette and type *within* that system. Restyling scene-by-scene afterward pulls threads out of a design that was balanced as a whole, and you spend more effort fighting the preset than you'd have spent handing it a spec. + +## Related + + + + Import brand tokens, assets, components, and motion from a Figma file. + + + Turn brand tokens into variables that re-skin a whole series from one value. + + + How pinning exact hexes and type direction removes drift. + + + Attach a brand guide or screenshot to seed a first draft from your look. + + diff --git a/docs/prompting/editing-existing-videos.mdx b/docs/prompting/editing-existing-videos.mdx new file mode 100644 index 000000000..fe9685b23 --- /dev/null +++ b/docs/prompting/editing-existing-videos.mdx @@ -0,0 +1,125 @@ +--- +title: Editing existing videos +description: "Direct the agent like an editor — trim, move, retime, swap, restyle — with the NLE verb you already know mapped to the prompt that lands it in one pass." +--- + +## Editing existing videos + +Most HyperFrames time isn't the first render — it's the twenty edits after it. A composition is plain HTML with `data-*` timing attributes and a GSAP timeline, so every edit you'd make in a non-linear editor maps to a specific, inspectable change in the source. You don't re-specify the video; you name the edit the way you'd say it to a human editor, and the agent makes the smallest change that does it. + +This page maps the editor verbs to the prompts that land them. Two habits from [Iterating](/prompting/iterating) apply to every one of them, so keep them in mind: **change one thing per render**, and **state targets as absolute values** ("scene 2 = 2 seconds", not "a bit shorter") so the agent lands it in a single pass instead of oscillating. + +## The verb → edit map + +Every timeline verb resolves to a `data-*` attribute or an inline style. This is what each one touches under the hood — useful to know because it's why absolute targets work and why some edits are cheap: + +| You say | Editor verb | What the agent edits | +| --- | --- | --- | +| "start scene 2 later / earlier" | Move | `data-start` | +| "put the captions on top of the video" | Restack | `data-track-index` + inline `z-index` | +| "end the logo sooner" | Trim (right) | `data-duration` | +| "skip the first second of the clip" | Trim (front, media only) | `data-media-start` / `data-playback-start` | +| "make scene 2 two seconds long" | Retime | `data-duration` (and the GSAP timeline length) | +| "the audio bed is too loud" | Level | `data-volume` | + + + The mental model the Studio timeline uses: **move** changes when a clip *starts*, **right trim** changes when it *ends*, and **front trim** only exists for media clips — a `