ext/hyperframes
2
0
Fork 0
mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-01 03:06:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(prompting): expand prompt guide into top-level multi-page section

Browse Source 
Splits guides/prompting into a Prompt Guide nav group (overview + Fundamentals
+ Making it look good, 11 pages) with a redirect from the old URL. Applies
research-validated upgrades: beat content formula, before/after prompt rewrites
with engine rationale, single-variable iteration moves, absolute-target
calibration, camera/depth/pacing vocabulary, prerequisites gate.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Vance Ingalls
2026-07-09 22:21:10 -07:00
co-authored by Claude Fable 5
parent e7a6cb0da6
commit 383dd35685
14 changed files with 933 additions and 301 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/docs.json
+34 -3
View File
@@ -71,6 +71,32 @@
"concepts/determinism"
]
},
{
"group": "Prompt Guide",
"pages": [
"prompting/overview",
{
"group": "Fundamentals",
"pages": [
"prompting/anatomy",
"prompting/examples",
"prompting/specification-dial",
"prompting/vocabulary",
"prompting/iterating",
"prompting/rules-and-anti-patterns"
]
},
{
"group": "Making it look good",
"pages": [
"prompting/visual-specs",
"prompting/motion",
"prompting/generated-artwork",
"prompting/recreating-references"
]
}
]
},
{
"group": "Guides",
"pages": [
@@ -86,7 +112,6 @@
"guides/copilot-cli",
"guides/claude-design",
"guides/open-design",
"guides/prompting",
"guides/hyperframes-vs-remotion",
"guides/gsap-animation",
"guides/keyframes",
@@ -410,5 +435,11 @@
"socials": {
"github": "https://github.com/heygen-com/hyperframes"
}
}
}
},
"redirects": [
{
"source": "/guides/prompting",
"destination": "/prompting/overview"
}
]
}
docs/guides/prompting.mdx
-298
View File
@@ -1,298 +0,0 @@
---
title: Prompt Guide
description: "How to prompt Claude Code, Cursor, Codex, Google Antigravity, GitHub Copilot CLI, and other AI agents to author Hyperframes compositions — with copy-pasteable examples and vocabulary tables."
---
Hyperframes is built for AI agents — compositions are plain HTML, the CLI is non-interactive, and the framework ships [skills](https://github.com/vercel-labs/skills) that teach agents the patterns docs alone don't cover. This guide shows how to prompt agents effectively once skills are installed — the vocabulary that changes output, the iteration patterns that save time, and the rules that prevent breakage.
## One-time setup
Install the skills in your project (or globally for your agent):
```bash
npx skills add heygen-com/hyperframes
```
The installer shows a picker. Select the **core skills** below — every project needs them. In Claude Code, restart the session after installing; the skills register as **slash commands**. Start at `/hyperframes`: it orients you to the whole surface and routes "make me a video" requests to the right workflow.
**Core skills — install all of these**
| Slash command | What it loads |
| ----------------------- | -------------------------------------------------------------------------- |
| `/hyperframes` | **Read first.** The entry skill — capability map + video router; sends "make me a video" intent to the right workflow |
| `/hyperframes-core` | Composition contract — HTML structure, `data-*` attributes, clips, tracks |
| `/hyperframes-animation`| All animation — motion rules, scene blueprints, transitions, and the runtime adapters (GSAP, Lottie, Three.js, Anime.js, CSS, WAAPI, TypeGPU) |
| `/hyperframes-creative` | Creative direction — design spec, palettes, typography, narration, beats |
| `/hyperframes-cli` | Dev-loop CLI — `init`, `lint`, `validate`, `inspect`, `preview`, `render`, `doctor` |
| `/media-use` | Asset preprocessing — `tts`, `transcribe`, `remove-background` |
| `/hyperframes-registry` | Block and component installation via `hyperframes add` |
| `/general-video` | The general authoring workflow — fallback for any video that doesn't match a specific workflow below |
**Optional workflows — add the ones that match your inputs** (`/hyperframes` routes to whichever you've installed)
| Slash command | Input → output |
| ------------------------ | --------------------------------------------------------------------------- |
| `/product-launch-video` | A product URL / brief / script → launch or promo video |
| `/website-to-video` | A general website / URL → a video of the site (tour / showcase / social clip) |
| `/faceless-explainer` | Arbitrary text (no URL) → faceless explainer with its own TTS narration |
| `/pr-to-video` | A GitHub PR → code-change explainer |
| `/embedded-captions` | An existing talking-head video → the same footage with captions / subtitles |
| `/talking-head-recut` | An existing talking-head video → footage packaged with designed graphic cards |
| `/motion-graphics` | A short, unnarrated, design-led motion graphic (logo sting, kinetic type, stat / chart) |
| `/music-to-video` | A music track (audio file or video) → a beat-synced video (lyric, slideshow, or kinetic promo) |
| `/slideshow` | A presentation / pitch deck / interactive deck — discrete slides, fragment reveals, branching |
| `/remotion-to-hyperframes` | Port an existing Remotion (React) composition to HyperFrames HTML |
<Tip>
To skip the picker and install everything (core + every workflow) in one shot, run `npx skills add heygen-com/hyperframes --all`. And start Hyperframes prompts with `/hyperframes` (or invoke the skill another way for non-Claude agents) — it loads the routing + composition context explicitly so the agent picks the right workflow and gets the rules right the first time.
</Tip>
## Claude Design
Claude Design uses a different setup. Download [`claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) from GitHub (click the ↓ button), then **attach it to your chat** (don't paste the URL — file attachments produce better output):
```text
Use the attached skill. 25-second LinkedIn video for my startup.
Problem: Sales teams waste 3 hours/day on manual CRM updates.
Solution: AutoCRM — AI that logs every call, email, and meeting.
Traction: 200+ teams, $1.2M ARR, 18% MoM growth.
CTA: autocrmhq.com
```
Claude Design produces a valid first draft (brand identity, scene content, animations, transitions). Download the ZIP and refine in any AI coding agent with `npx hyperframes preview` running. See the [Claude Design guide](/guides/claude-design) for the full workflow.
## The two prompt shapes
Most successful Hyperframes prompts fall into one of two shapes.
### Cold start — describe the video
You tell the agent what you want from scratch. Best for greenfield work where you have the creative direction in your head.
> Using `/hyperframes`, create a 10-second product intro with a fade-in title over a dark background and subtle background music.
> Make a 9:16 TikTok-style hook video about [topic] using `/hyperframes`, with bouncy captions synced to a TTS narration.
Cold-start prompts work best when you specify:
- **Duration** (e.g. "10 seconds", "30s", "5 scenes of 3s each")
- **Aspect ratio** ("16:9", "9:16 vertical", "1:1 square") — defaults to 1920x1080 otherwise
- **Mood / style** ("minimal Swiss grid", "warm grain analog", "high-energy social")
- **Key elements** (title, lower third, captions, background video, music)
### Warm start — turn context into a video
You give the agent something to work with — a URL, a doc, a CSV, a transcript — and ask it to synthesize that into a video. This is where Hyperframes shines because the agent does the research/summarization step *and* the production step in one flow.
> Take a look at this GitHub repo https://github.com/heygen-com/hyperframes and explain its uses and architecture to me using `/hyperframes`.
> Summarize the attached PDF into a 45-second pitch video using `/hyperframes`.
> Read this changelog and turn the top three changes into a 30-second release announcement video using `/hyperframes`.
> Turn this CSV into an animated bar chart race using `/hyperframes`.
Warm-start prompts produce richer, more grounded videos because the agent is writing about *something specific* instead of inventing copy.
## Iterating
Hyperframes is a conversation. After the first render, talk to the agent the way you'd talk to a video editor — don't re-prompt from scratch:
> Make the title 2x bigger.
> Swap to dark mode.
> Add a fade-out at the end and a lower third at 0:03 with my name and title.
> The captions are too small and they overlap the lower third. Move them up and shrink them.
> Replace the background music with `assets/track.mp3`.
The agent already has the composition open and the skills loaded — small targeted edits produce better results than long re-specifications.
## Vocabulary that changes output
The skills map natural-language adjectives to specific framework settings. Using the right word gets you the right result without specifying technical details.
### Motion & easing
Describe how motion should *feel* and the agent picks the matching GSAP ease:
| Say this | Agent uses | Feels like |
| ----------- | ---------------- | ------------------------------ |
| smooth | `sine` / `power1`| Natural deceleration |
| snappy | `power4.out` | Quick and decisive |
| bouncy | `back.out` | Overshoots then settles |
| springy | `elastic.out` | Oscillates into place |
| dramatic | `expo.out` | Fast start, long glide |
| dreamy | `sine.inOut` | Slow, symmetrical |
**Timing shorthand:** fast (0.2s) = energy, medium (0.4s) = professional, slow (0.6s) = luxury, very slow (1–2s) = cinematic.
### Caption tones
Describe the *energy* of your captions and the agent picks matching typography, size, and animation:
| Tone | Typography | Animation | Size range |
| ------------ | ---------------------- | ------------ | ---------- |
| Hype | Heavy weight fonts | Scale-pop | 72–96px |
| Corporate | Clean sans-serif | Fade + slide | 56–72px |
| Tutorial | Monospace | Typewriter | 48–64px |
| Storytelling | Serif | Slow fade | 44–56px |
| Social | Rounded, playful | Bounce | 56–80px |
```
"Hype-style captions with scale-pop"
"Calm, elegant subtitles with slow fades"
"Karaoke-style word highlighting"
```
Per-word styling also works:
```
"Make brand names larger with accent color"
"Add bounce to emotional keywords"
"Highlight numbers differently"
```
### Transitions
Every multi-scene composition benefits from transitions. Describe the energy level:
| Energy | CSS option | Shader option |
| ------- | ---------------- | ------------------- |
| Calm | Blur crossfade | Cross-warp morph |
| Medium | Push slide | Whip pan |
| High | Zoom through | Glitch, ridged burn |
Or describe by mood:
```
"Warm transitions for this wellness brand"
"Cold, clinical transitions for tech"
"Playful bouncy transitions"
"Dramatic zoom for the reveal"
```
### Audio-reactive animation
Map audio frequency bands to visual properties. The agent uses these defaults:
| Audio band | Maps to | Visual effect |
| ---------- | --------- | ------------------- |
| Bass | `scale` | Pulse on the beat |
| Treble | `glow` | Shimmer intensity |
| Amplitude | `opacity` | Breathing |
| Mids | `borderRadius` | Shape morphing |
```
"Make the text pulse with the beat"
"Add bass-driven scale to the logo"
"Create glow that responds to treble"
```
<Tip>
Keep audio-reactive effects subtle for text (3–6% intensity). Go bigger for backgrounds (10–30%).
</Tip>
### Marker highlights
Hand-drawn emphasis effects for text:
| Mode | Effect | Best for |
| ----------- | ------------------ | ------------- |
| `highlight` | Marker sweep | Key phrases |
| `circle` | Hand-drawn ellipse | Single words |
| `burst` | Radiating lines | Hype moments |
| `scribble` | Chaotic scratch | Rough emphasis|
| `sketchout` | Cross-hatch lines | Crossing out |
```
"Add a marker highlight sweep on 'revolutionary'"
"Circle this keyword with hand-drawn effect"
"Add burst lines around 'AMAZING'"
```
### Text-to-speech voices
HyperFrames supports three TTS providers: **HeyGen** (Starfish voices, requires sign-in via `npx hyperframes auth`), **ElevenLabs** (requires API key), and **Kokoro** (free, runs locally, no API key needed). The agent asks which provider to use — or picks automatically in autonomous mode. Describe the content and the agent picks a voice, or request one directly:
| Content type | Kokoro voices |
| ------------- | -------------------------- |
| Product demo | `af_heart`, `af_nova` |
| Tutorial | `am_adam`, `bf_emma` |
| Marketing | `af_sky`, `am_michael` |
```
"Generate narration for this script"
"Create voiceover with a professional female voice"
"Add TTS with British male voice at 1.1x speed"
"Use HeyGen TTS for this narration"
```
### Rendering quality
| Quality | Use for |
| ---------- | ------------------------ |
| `draft` | Fast iteration |
| `standard` | Review and feedback |
| `high` | Final delivery |
```
"Quick draft render"
"Render at high quality"
"Export as transparent WebM"
```
## Rules to know
The skills enforce these automatically, but if you hand-edit compositions or debug issues, these are the rules that matter:
1. **Register all timelines** on `window.__timelines` — the renderer can't seek animations it doesn't know about.
2. **Video elements must be `muted`** — audio goes in separate `<audio>` elements so the renderer can mix it.
3. **No `Math.random()`** — random values produce different frames on each render, breaking determinism. Use a seeded PRNG (e.g. mulberry32) if you need pseudo-random values.
4. **Synchronous timeline construction** — no `async`/`await` or `fetch()` during GSAP timeline setup.
5. **Timed elements need `class="clip"`** — plus `data-start`, `data-duration`, and `data-track-index`.
6. **Add entrance animations to every scene** — elements appearing without animation feel broken on video.
7. **Add transitions between scenes** — jump cuts between scenes are almost always unintentional in composed video.
<Warning>
Rules 1–5 are technical requirements — breaking them produces incorrect renders. Rules 6–7 are best practices that the skills apply by default. You can override them when you have a reason to.
</Warning>
## Anti-patterns
Things that cause friction (or wrong output):
- **Don't ask for React / Vue components.** Hyperframes compositions are plain HTML with `data-*` attributes and a GSAP timeline. Asking for "a React component for the intro" forces the agent to translate later.
- **Don't ask for 4K or 60fps unless you need it.** Defaults (1920×1080, 30fps) render fast and look great. Higher specs slow rendering meaningfully.
- **Don't skip the slash command.** Without `/hyperframes`, the agent may guess at HTML video conventions instead of using the framework's actual rules (`class="clip"` on timed elements, `window.__timelines` registration, etc.).
- **Don't paste long error logs into the prompt without context.** Run `npx hyperframes lint` and `npx hyperframes validate` first — lint catches structural issues, validate catches runtime errors (JS exceptions, missing assets, contrast problems).
- **Don't assume the agent knows your assets.** Mention file paths explicitly (`assets/intro.mp4`, `assets/logo.png`) — the agent will check what's there but a hint speeds it up.
## Recommended workflow
1. `npx hyperframes init my-video` — scaffold a project (skills install automatically)
2. Open the project in Claude Code (or Cursor / Codex)
3. Prompt with `/hyperframes` and one of the shapes above
4. `npx hyperframes preview` — watch in the browser as the agent edits
5. Iterate with small targeted prompts
6. `npx hyperframes render --output final.mp4` when you're happy
## Next steps
<CardGroup cols={2}>
<Card title="Quickstart" icon="rocket" href="/quickstart">
Build and render your first video
</Card>
<Card title="Common Mistakes" icon="circle-exclamation" href="/guides/common-mistakes">
Pitfalls the linter can't catch
</Card>
<Card title="GSAP Animation" icon="wand-magic-sparkles" href="/guides/gsap-animation">
Add fade, slide, scale, and custom animations
</Card>
<Card title="Catalog" icon="grid-2" href="/catalog/blocks/data-chart">
50+ ready-to-use blocks and components
</Card>
</CardGroup>
docs/prompting/anatomy.mdx
+70
View File
@@ -0,0 +1,70 @@
---
title: Anatomy of a one-shot prompt
description: "The six-part skeleton - route, spec, beats, copy, technique, negatives - that removes the decisions agents most often get wrong."
---
## Anatomy of a one-shot prompt
The [copy-paste examples](/prompting/examples) share one skeleton. Each part removes a decision agents most often get wrong on a first try:
```text
[route] /motion-graphics
[spec] 8-second 1920x1080 video.
[beats] Beat 1 (0-4s): ... Beat 2 (4-5s): ... Beat 3 (5-8s): ...
[copy] the exact on-screen text, quoted
[technique] Use the `code-typing` and `vfx-shatter` registry blocks.
[negatives] No narration, no image or media files.
```
- **Route** with a slash command — it loads the right workflow and the framework rules.
- **Spec** duration and resolution up front. Defaults are 1920x1080 at 30fps.
- **Beats** get timestamps. Include pacing instructions ("then hold on the blinking cursor") — agents skip breathing room unless told.
- **Copy** is quoted exactly, with `/` for line breaks. Unquoted copy gets paraphrased.
- **Technique**: name registry blocks exactly as they appear in the [catalog](/catalog/blocks/data-chart), and pin a technique wherever the default choice can fail (see [the specification dial](/prompting/specification-dial)).
- **Negatives** close the gaps: "no narration" is not "silent" — if you want no sound at all, say "no audio". Avoid ambiguous phrases like "no external assets" (CDN-loaded runtimes are normal; say "no image or media files" if that's what you mean).
Assembled:
> /motion-graphics Make an 8-second 1920x1080 video. Beat 1 (0-4s): dark macOS terminal types "npx skills add heygen-com/hyperframes" character by character, then hold on the blinking cursor. Beat 2 (4-5s): the terminal shatters into fragments. Beat 3 (5-8s): bold white kinetic text on black slams in word by word, snappy: "YOU JUST MADE THIS / WITH HYPERFRAMES." Use the `code-typing` and `vfx-shatter` registry blocks. No narration, no image or media files.
## The beat formula
The skeleton above structures the *ask*. Inside each beat, describe the *content* with the same five slots every time:
```text
[element] what's on screen a giant number · the tweet card · "SHOWREEL"
[motion] what it does counts up with an odometer roll · slides up · fades in per letter
[layout] where it sits top-center · filling the lower half · bottom-right
[style] how it looks dark navy, green accent · 8-bit pixel · thin geometric sans
[timing] when, inside the beat at 1s · over 3s, easing out as it lands · staggered 0.1s apart
```
One sentence per element, slots in any order: *"a giant number **(element)** counts up to $4.2M with an odometer roll **(motion)**, easing out as it lands **(timing)**, centered **(layout)** in green on dark navy **(style)**."* Elements you don't describe, the agent designs — which is fine when you trust its taste and a drift risk when you don't (see [the specification dial](/prompting/specification-dial)).
<Tip>
Beat-timestamped prompting — `Beat 2 (4-5s): ...` — is HyperFrames' native language. Diffusion video models bolt time segmentation on top of a single clip; here every beat maps directly to a timed clip in the composition, so per-beat descriptions translate losslessly. Use timestamps liberally.
</Tip>
## Common rewrites
The fixes that come up most, as before/after pairs — each exists because of how the engine actually behaves:
**Freezing the hold.** Compositions hold their final state, so a literal "hold" renders a frozen frame — the single biggest cheap-motion tell.
- ❌ `then everything holds motionless to the end`
- ✅ `then everything settles into a gentle ambient idle (breathing scale, slow drift)`
**Simultaneity collisions.** Two things "at 4s" overlap for a few frames; the renderer does exactly what you wrote.
- ❌ `at 4s the counter fades out and READY stamps in`
- ✅ `the counter fades out fully by 4.2s; at 4.2s READY stamps in`
**Vague negatives.** "No external assets" is ambiguous — CDN-loaded runtimes are normal infrastructure.
- ❌ `no external assets`
- ✅ `no image or media files`
**Prose where copy belongs.** Unquoted text gets paraphrased; quoted text renders verbatim.
- ❌ `show a tagline about shipping faster`
- ✅ `tagline: "Ship faster."`
**Format-blind numbers.** An odometer needs fixed digit columns — "counts $0 → $4.2M" forces an awkward "$0.0M" start.
- ❌ `counts from $0 to $4.2M`
- ✅ `counts up to $4.2M`
docs/prompting/examples.mdx
+74
View File
@@ -0,0 +1,74 @@
---
title: Verified example prompts
description: "18 copy-paste prompts, every one run end-to-end to a finished video that passes lint and validate."
---
## Copy-paste examples
Every prompt below has been run end-to-end and one-shots a finished video that passes `lint` and `validate`. Swap the copy, colors, and inputs for your own.
### With registry blocks and workflows
<AccordionGroup>
<Accordion title="Stat count-up">
> /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 everything settles into a gentle ambient idle (subtle breathing scale, slow particle drift). Use the `apple-money-count` registry block as base. No narration.
</Accordion>
<Accordion title="Animated social post">
> /motion-graphics 7-second 1080x1350 vertical video. A real tweet card (handle @hyperframes, text "we render video from HTML now. no timeline UI. just code.") slides up over a soft animated gradient, likes counter ticks 0→1.2K, then the card tilts in 3D and a highlight sweeps the second sentence. Hold on the card at the end. Use the `x-post` and `vfx-liquid-background` registry blocks. No narration, no image or media files.
</Accordion>
<Accordion title="Map route">
> /motion-graphics 8-second 1920x1080 video. Dark world map, a glowing arc animates from San Francisco to Tokyo over 3s, destination pin drops with a pulse, then camera zooms into Tokyo and the label "LATENCY: 89ms" types on. Use the `nyc-paris-flight` registry block as the base pattern, restyle to teal on charcoal. No narration.
</Accordion>
<Accordion title="Logo sting with shader transition">
> /motion-graphics 5-second 1920x1080 logo sting. Beat 1 (0-2s): the word "ACME" assembles from scattered particles. Beat 2 (2-3s): full-frame `swirl-vortex` shader transition. Beat 3 (3-5s): logo lockup + tagline "Ship faster." settles on white, holds. Use `code-particle-assemble` for the assembly.
</Accordion>
<Accordion title="Product launch from a URL">
> /product-launch-video Make a 45-second 1920x1080 launch video for https://linear.app. Energetic but minimal, use the site's own palette and screenshots. Structure: hook stating the problem, 3 feature beats with UI captures and one-line captions, end card with logo + "Try it free". Female TTS voice, confident tone, subtle electronic BGM under -18dB.
</Accordion>
<Accordion title="Explainer from pasted text">
> /faceless-explainer Turn this into a ~60-second 1080x1920 vertical explainer: [paste your text]. One idea per scene, big typography, diagrams over stock footage, brand color #FF5533 on off-black. Male TTS voice, calm. Embedded captions, keywords highlighted in the brand color.
With a verbatim script, final duration follows the narration — ask for "~60 seconds", not exactly 60.
</Accordion>
<Accordion title="GitHub PR 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.
</Accordion>
<Accordion title="Beat-synced slideshow">
> /music-to-video 20-second 1080x1080 video from ./track.mp3 (pick the best 20 seconds of the track) and the 8 photos in ./shots/. Cut on the beat grid, one photo per bar, punch-in on downbeats, `whip-pan` transitions on phrase changes. End on the last photo with "SUMMER '26" in condensed caps. No TTS.
</Accordion>
</AccordionGroup>
### Freeform — no blocks, hand-built HTML/CSS/SVG/GSAP
<AccordionGroup>
<Accordion title="Kinetic quote">
> 12-second 1920x1080 video, off-white background. The quote "Simplicity is the ultimate sophistication" builds word by word in massive black serif type, each word snapping in with a slight overshoot; "sophistication" lands last in italic with a hand-drawn underline drawing on. Attribution "— Leonardo da Vinci" fades in small, bottom-right, at 9s. Settle into a barely-visible ambient idle to the end. No audio.
</Accordion>
<Accordion title="Countdown title card">
> 6-second 1920x1080 video. Numbers 3, 2, 1 each fill the frame for one second — each number wipes in with a diagonal mask and its background alternates black/white with inverted text. At 3s the frame slams to "LAUNCH DAY" in condensed caps with a screen-shake, holds with a subtle grain flicker. No audio.
</Accordion>
<Accordion title="Bar chart race">
> 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.
</Accordion>
<Accordion title="Before / after split">
> 8-second 1920x1080 video. Vertical split: left half labeled "BEFORE" shows a cluttered mock UI (grey, 12 overlapping windows drawn in CSS), right half "AFTER" shows one clean card. Both halves settle within the first second. A vertical divider line sweeps left to right at 4s, wiping the clutter into the clean state across the full frame. End on "One tool." centered. No audio.
</Accordion>
<Accordion title="Loader → reveal">
> 7-second 1920x1080 video, black background. A thin white progress ring draws from 0° to 360° over 4s while a percentage counter (0→100) ticks in the center in mono type, matching the arc exactly. Ring and counter fade out fully by 4.2s; at 4.2s the ring bursts outward into short radial dashes and "READY." stamps into the center, then holds. No audio.
</Accordion>
<Accordion title="3D cards (Three.js)">
> 9-second 1920x1080 video, light warm cream background. Build the scene in Three.js via the adapter: three rounded card meshes labeled "Design", "Build", "Ship" lie flat on the ground plane, camera at a fixed 3/4 isometric angle, soft directional light + ambient so the cards cast soft shadows. One at a time each card lifts and straightens upright to face the viewer center-frame while the other two slide apart and dim; then it returns. Finish with all three standing upright in a row by 8.5s, hold. All easing power3.inOut. No audio.
</Accordion>
<Accordion title="SVG line-draw logo reveal">
> 6-second 1920x1080 video, deep green background. A minimal mountain-range logo draws on as an SVG stroke over 2.5s, then the stroke fills with cream, the wordmark "NORTHTRAIL" letterspaces in beneath it, and a thin rule expands from center. Hold the last 1.5s. No audio.
</Accordion>
<Accordion title="Word-swap headline">
> 8-second 1920x1080 video, white background. Static sentence "Make it ___." in huge black type stays centered while the blank cycles through "faster", "simpler", "yours" — each swap flips vertically like a split-flap board, 1.5s apart, with a slight blur on motion. Final word "yours." lands in orange and the period pops. No audio.
</Accordion>
<Accordion title="Stat tile dashboard">
> 10-second 1920x1080 video, near-black background. Four stat tiles slide up in a 2x2 grid, staggered: "99.99% uptime", "42ms p50", "18M req/day", "0 incidents". Each tile's number counts or decrements to its value with its own easing; sparklines draw underneath in teal. At 8s the grid scales back and "Built to hold." fades in above. No audio.
</Accordion>
<Accordion title="Vertical social hook">
> 9-second 1080x1920 vertical video, charcoal background. Social-style hook: "nobody talks about this" types on center in bold white, then each following phrase replaces it on a hard cut every 1.5s — "it's not your code", "it's your prompts", "here's the fix" — with yellow highlight bars behind key words, alternating tilt. Last phrase holds with an arrow-down bounce. No audio.
</Accordion>
</AccordionGroup>
docs/prompting/generated-artwork.mdx
+16
View File
@@ -0,0 +1,16 @@
---
title: When to generate artwork
description: "Code-drawn wins for UI, type, geometry, and 3D; illustration-led hero art comes from an image model, animated as layers."
---
## When to generate artwork instead of drawing it
Code-drawn HTML/CSS/SVG excels where the medium is native: UI mockups, typography, geometric shapes, charts, pixel art, and 3D via Three.js. For **illustration-led** hero art — characters, painterly scenes, sculptural objects — hand-drawn SVG tops out at clipart quality no matter how well you prompt. The fix is a hybrid:
> Generate the hero artwork as an image (via the media skill's image generation), then animate it with code. Anything that must move independently — eyelids, light beams, drawing lines — stays a code layer on top of the static art.
Three rules that make this work:
1. **Generate on a solid contrasting background** (magenta works) so the subject keys out cleanly. A light subject on a light background gets silently eaten.
2. **Key flat vector-style art with a chroma key** (`ffmpeg colorkey`), not AI background removal — saliency matting can invert on flat art and keep the background instead. Save `remove-background` for photographic subjects.
3. **Put a restraint clause in the generation prompt** ("minimal, lots of negative space") — image models fill the frame by default, and a busy generated texture reads as cheap as bad vector art.
docs/prompting/iterating.mdx
+40
View File
@@ -0,0 +1,40 @@
---
title: Iterating
description: "Talk to the agent like a video editor - small targeted edits beat re-specification."
---
## Iterating
Hyperframes is a conversation. After the first render, talk to the agent the way you'd talk to a video editor — don't re-prompt from scratch:
> Make the title 2x bigger.
> Swap to dark mode.
> Add a fade-out at the end and a lower third at 0:03 with my name and title.
> The captions are too small and they overlap the lower third. Move them up and shrink them.
> Replace the background music with `assets/track.mp3`.
The agent already has the composition open and the skills loaded — small targeted edits produce better results than long re-specifications.
## Editing is for nudging, not gambling
Three moves keep iteration convergent instead of circular:
1. **One variable per edit.** Change one thing, render, judge, repeat. A request that moves three things at once ("bigger title, warmer colors, faster cuts") makes it impossible to attribute what helped and what hurt.
2. **Layer one element type at a time.** Building up a complex scene? Start with the minimal version (subject + its motion only), confirm it reads, then add exactly one layer per pass — camera move, then background motion, then style treatment. Every addition stays attributable.
3. **Strip, then re-layer.** When a scene keeps misfiring, don't pile on corrections — strip it back to the simplest version that works (freeze the camera, simplify the motion, clear the background), confirm, then reintroduce complexity one layer at a time until you find the ingredient that breaks it.
## Calibrate with absolute targets
When you're dialing in a look, relative corrections oscillate — "make the dots finer" overshoots, "a bit bigger" overshoots back. State targets as absolute values and the agent lands them in one pass:
- ❌ `make the dots 2x finer`
- ✅ `dot radius = 25% of row spacing, with clear gaps between dots`
- ❌ `the glow is too strong`
- ✅ `glow at ~35% peak opacity, always subtler than the orb itself`
And freeze what already works: "the framing and motion are right — don't touch them; only change the dot size." Without the freeze clause, a rebuild can drift on axes you'd already settled.
docs/prompting/motion.mdx
+15
View File
@@ -0,0 +1,15 @@
---
title: Motion that reads premium
description: "Six motion-grammar rules from frame-by-frame study of professional work - nothing stops, the camera acts, action overlaps."
---
## Motion that reads premium
Static frames can be perfect and the video still feels cheap if the motion is dead. Professional motion design follows a grammar you can put directly in prompts:
1. **Nothing ever fully stops.** Every "hold" carries ambient idle motion — a 1-2% breathing scale, slow drift, a shimmer. Never write "holds motionless"; write "settles into a gentle ambient idle." A frozen final second is the single biggest cheap-motion tell.
2. **The camera is an actor.** Give each scene one continuous camera move — a 4-8% push-in, a slow orbit, parallax between layered planes — easing gently but never settling on screen (compute the ease over a window slightly longer than the render).
3. **Overlapping action.** No two elements share a start or end time. Entrances stagger at irregular offsets; the next element begins while the last is still settling.
4. **Overshoot and follow-through.** Every pop scales past its target and settles back; letters can tumble in individually with rotation.
5. **Depth planes.** One or two large, heavily-blurred foreground elements drifting near the lens sell depth instantly.
6. **Match pacing to genre.** Showreel-style cuts run 1.5-4 seconds per idea; a stretched 8-second version of a 2-second idea feels slow no matter how it's animated.
docs/prompting/overview.mdx
+126
View File
@@ -0,0 +1,126 @@
---
title: Prompt Guide
description: "How to prompt AI agents to author HyperFrames videos - setup, the two prompt shapes, and the map of this guide."
---
Hyperframes is built for AI agents — compositions are plain HTML, the CLI is non-interactive, and the framework ships [skills](https://github.com/vercel-labs/skills) that teach agents the patterns docs alone don't cover. This guide shows how to prompt agents effectively once skills are installed — the vocabulary that changes output, the iteration patterns that save time, and the rules that prevent breakage.
<Note>
**Before you prompt**, have three things in place: the skills installed (below), a scaffolded project (`npx hyperframes init my-video`), and the live preview running (`npx hyperframes preview`) so you can judge each render the moment it lands. Prompting without the preview open turns every iteration into a blind guess.
</Note>
## One-time setup
Install the skills in your project (or globally for your agent):
```bash
npx skills add heygen-com/hyperframes
```
The installer shows a picker. Select the **core skills** below — every project needs them. In Claude Code, restart the session after installing; the skills register as **slash commands**. Start at `/hyperframes`: it orients you to the whole surface and routes "make me a video" requests to the right workflow.
**Core skills — install all of these**
| Slash command | What it loads |
| ----------------------- | -------------------------------------------------------------------------- |
| `/hyperframes` | **Read first.** The entry skill — capability map + video router; sends "make me a video" intent to the right workflow |
| `/hyperframes-core` | Composition contract — HTML structure, `data-*` attributes, clips, tracks |
| `/hyperframes-animation`| All animation — motion rules, scene blueprints, transitions, and the runtime adapters (GSAP, Lottie, Three.js, Anime.js, CSS, WAAPI, TypeGPU) |
| `/hyperframes-creative` | Creative direction — design spec, palettes, typography, narration, beats |
| `/hyperframes-cli` | Dev-loop CLI — `init`, `lint`, `inspect`, `preview`, `render`, `doctor` |
| `/hyperframes-media` | Asset preprocessing — `tts`, `transcribe`, `remove-background` |
| `/hyperframes-registry` | Block and component installation via `hyperframes add` |
| `/general-video` | The general authoring workflow — fallback for any video that doesn't match a specific workflow below |
**Optional workflows — add the ones that match your inputs** (`/hyperframes` routes to whichever you've installed)
| Slash command | Input → output |
| ------------------------ | --------------------------------------------------------------------------- |
| `/product-launch-video` | A product URL / brief / script → launch or promo video |
| `/website-to-video` | A general website / URL → a video of the site (tour / showcase / social clip) |
| `/faceless-explainer` | Arbitrary text (no URL) → faceless explainer with its own TTS narration |
| `/pr-to-video` | A GitHub PR → code-change explainer |
| `/embedded-captions` | An existing talking-head video → the same footage with captions / subtitles |
| `/talking-head-recut` | An existing talking-head video → footage packaged with designed graphic cards |
| `/motion-graphics` | A short, unnarrated, design-led motion graphic (logo sting, kinetic type, stat / chart) |
| `/remotion-to-hyperframes` | Port an existing Remotion (React) composition to HyperFrames HTML |
<Tip>
To skip the picker and install everything (core + every workflow) in one shot, run `npx skills add heygen-com/hyperframes --all`. And start Hyperframes prompts with `/hyperframes` (or invoke the skill another way for non-Claude agents) — it loads the routing + composition context explicitly so the agent picks the right workflow and gets the rules right the first time.
</Tip>
## Claude Design
Claude Design uses a different setup. Download [`claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) from GitHub (click the ↓ button), then **attach it to your chat** (don't paste the URL — file attachments produce better output):
```text
Use the attached skill. 25-second LinkedIn video for my startup.
Problem: Sales teams waste 3 hours/day on manual CRM updates.
Solution: AutoCRM — AI that logs every call, email, and meeting.
Traction: 200+ teams, $1.2M ARR, 18% MoM growth.
CTA: autocrmhq.com
```
Claude Design produces a valid first draft (brand identity, scene content, animations, transitions). Download the ZIP and refine in any AI coding agent with `npx hyperframes preview` running. See the [Claude Design guide](/guides/claude-design) for the full workflow.
## The two prompt shapes
Most successful Hyperframes prompts fall into one of two shapes.
### Cold start — describe the video
You tell the agent what you want from scratch. Best for greenfield work where you have the creative direction in your head.
> Using `/hyperframes`, create a 10-second product intro with a fade-in title over a dark background and subtle background music.
> Make a 9:16 TikTok-style hook video about [topic] using `/hyperframes`, with bouncy captions synced to a TTS narration.
Cold-start prompts work best when you specify:
- **Duration** (e.g. "10 seconds", "30s", "5 scenes of 3s each")
- **Aspect ratio** ("16:9", "9:16 vertical", "1:1 square") — defaults to 1920x1080 otherwise
- **Mood / style** ("minimal Swiss grid", "warm grain analog", "high-energy social")
- **Key elements** (title, lower third, captions, background video, music)
### Warm start — turn context into a video
You give the agent something to work with — a URL, a doc, a CSV, a transcript — and ask it to synthesize that into a video. This is where Hyperframes shines because the agent does the research/summarization step *and* the production step in one flow.
> Take a look at this GitHub repo https://github.com/heygen-com/hyperframes and explain its uses and architecture to me using `/hyperframes`.
> Summarize the attached PDF into a 45-second pitch video using `/hyperframes`.
> Read this changelog and turn the top three changes into a 30-second release announcement video using `/hyperframes`.
> Turn this CSV into an animated bar chart race using `/hyperframes`.
Warm-start prompts produce richer, more grounded videos because the agent is writing about *something specific* instead of inventing copy.
## Recommended workflow
1. `npx hyperframes init my-video` — scaffold a project (skills install automatically)
2. Open the project in Claude Code (or Cursor / Codex)
3. Prompt with `/hyperframes` and one of the shapes above
4. `npx hyperframes preview` — watch in the browser as the agent edits
5. Iterate with small targeted prompts
6. `npx hyperframes render --output final.mp4` when you're happy
## Explore the guide
<CardGroup cols={2}>
<Card title="Prompt anatomy" href="/prompting/anatomy">The six-part skeleton every one-shot prompt shares</Card>
<Card title="Verified examples" href="/prompting/examples">18 copy-paste prompts, each one-shots a finished video</Card>
<Card title="The specification dial" href="/prompting/specification-dial">How much to specify, and what density buys</Card>
<Card title="Vocabulary" href="/prompting/vocabulary">Words that map to specific framework settings</Card>
<Card title="Premium motion" href="/prompting/motion">The six-rule grammar that keeps video from feeling cheap</Card>
<Card title="Recreating references" href="/prompting/recreating-references">Match something you saw, from text alone</Card>
</CardGroup>
docs/prompting/recreating-references.mdx
+34
View File
@@ -0,0 +1,34 @@
---
title: Recreating something you saw
description: "Transcribe motion, iterate with absolute targets, distill the constants - and know where the text-only ceiling is."
---
## Recreating something you saw
Matching a specific reference from text alone is possible to roughly 90% — but only with a specific workflow, and knowing where the ceiling is.
**Transcribe motion, not just composition.** Watch the reference frame by frame and write down: the exact duration, the camera's path, what each element does with timestamps, how entrances overlap, which layers are blurred, sampled colors. A prompt built this way one-shots ~75% of the target — structure and motion arc land, rendering calibration doesn't.
**Iterate with absolute targets.** Compare your render against the reference frame by frame, then correct one axis at a time while freezing everything that already matches. State corrections as absolute values, not relative nudges — "dot radius = 25% of row spacing", not "make dots 2x finer". Relative corrections pendulum: too big, then too small, then too big. Expect a handful of rounds to converge.
**Distill the converged values back into the prompt.** Iteration is a search; the found constants are reusable. A prompt carrying them one-shots ~80-90% of the converged quality on a fresh build — the discrete facts (timings, counts, hexes, ratios, camera arcs) transfer losslessly, while continuous qualities (glow prominence, framing feel) still vary by a calibration note or two. And the converged composition file itself is the pixel-exact artifact: renders are deterministic, so re-rendering it reproduces the result bit-for-bit.
A distilled spec that one-shots a broadcast-style animated globe:
<Accordion title="Worked example: the hologram globe (full distilled spec)">
> 1.8-second 1920x1080 video, Three.js via the adapter (seek-driven, no rAF). One continuous shot; every element is still moving on the final frame.
>
> FIELD: blue-violet background, linear #2a24a8 → #12105e top-to-bottom with a soft radial lift at center; faint blurred vertical cyan light-streaks (#5ee0e8 at ~10% opacity, ~340px spacing) drifting 70px left across the piece; deep corner vignette; soft-light film grain at ~6% (seeded noise).
>
> GLOBE: royal-blue sphere (#4348f2), lit from upper-left with a 0.58 ambient floor; a broad subtle satin band (#6470ff, very wide falloff, ~30% mix) sweeping the upper curve; a strong cyan rim-light line (#5ee8f0) tracing only the top edge. Continents in TWO layers: (a) a heavily-blurred darker-blue silhouette (#3439c2, 80% opacity) just under the surface, reading as a soft shadow shape; (b) a dot-matrix just above the surface on an equal-area grid (0.9° latitude rows, longitude step widening with latitude): dot radius = 24–28% of row spacing — clear blue gaps between dots — growing slightly toward the equator, 85% dot opacity; two color populations — cyan-aqua #5ee0e8 north, spring-green #7ce97a from latitude ~32° southward — with seeded ±30% per-dot brightness variance; dots dimmed to 40% in the view-space lower-right shadow zone. Continents read as distinct dotted landmasses with royal-blue ocean dominating (~30–35% coverage of the visible hemisphere).
>
> CAMERA: open EXTREMELY close — the sphere's curve fills the entire frame, horizon exiting the upper corners — then one continuous pull-back + crane (fov 52°→40°) ending with the dome filling the lower half edge-to-edge, its silhouette touching both frame edges, horizon at ~45%. Ease power1.inOut computed over a 2.0s window while rendering 1.8s so the move never settles on-screen. The globe rotates 28° about its vertical axis, linear, continents drifting right-to-left, never stopping.
>
> ORBS — 12 across three depth planes, world-anchored on the upper hemisphere so stems stay vertical, popping at staggered starts 0.45s→1.15s (0.06–0.13s apart), each rising 0.44–0.56s with back.out overshoot (vary 1.7–2.6 per orb), then bobbing ±8px on phase-offset sines forever. 5 midground (~90–110px at end framing): soft mint body #a7ecc4 with a darker-green under-shade #3f9b5e at lower-left and a pale rim #d6ffe8 top-right, no white core; each wrapped in a soft additive bloom sprite ~3.5x its diameter whose texture is HOLLOW-centered peaking ~35% just outside the orb edge (a bright-cored additive glow over the opaque orb blows the mint to lime); plus a thin soft halo ring ~4.2x radius at 60% opacity, always subtler than the orb itself, with a slow 5% scale pulse. 4 background (~30px, sharp, tighter bloom). 3 foreground near-lens bokeh (~160–190px, dense mint radial-gradient sprites riding the camera at center-left / lower-center / upper-right, ~70% opacity, drifting ±30px laterally, no stems). Stems: 2–3px additive cyan cylinders fading to transparent at the surface. Tag canvas-generated sprite textures sRGB or the mints wash out pale.
>
> CAPTION: "Across 82 Countries" — Inter 300, 34px, 0.06em tracking, white at 90%, top-center 12% from the top; left-to-right per-letter fade starting t=1.0s completing ~1.45s, then a slow 6px upward drift still easing at the final frame.
>
> No audio.
</Accordion>
The honest ceiling: words carry discrete, countable things losslessly and underdetermine continuous perceptual qualities — bloom falloff, material feel, optical color mixing. That last 10% doesn't close from text; it oscillates. If pixel-exact matters, keep the composition file.
docs/prompting/rules-and-anti-patterns.mdx
+54
View File
@@ -0,0 +1,54 @@
---
title: Rules and anti-patterns
description: "The technical rules that keep renders correct, and the prompt patterns that cause friction."
---
## Rules to know
The skills enforce these automatically, but if you hand-edit compositions or debug issues, these are the rules that matter:
1. **Register all timelines** on `window.__timelines` — the renderer can't seek animations it doesn't know about.
2. **Video elements must be `muted`** — audio goes in separate `<audio>` elements so the renderer can mix it.
3. **No `Math.random()`** — random values produce different frames on each render, breaking determinism. Use a seeded PRNG (e.g. mulberry32) if you need pseudo-random values.
4. **Synchronous timeline construction** — no `async`/`await` or `fetch()` during GSAP timeline setup.
5. **Timed elements need `class="clip"`** — plus `data-start`, `data-duration`, and `data-track-index`.
6. **Add entrance animations to every scene** — elements appearing without animation feel broken on video.
7. **Add transitions between scenes** — jump cuts between scenes are almost always unintentional in composed video.
<Warning>
Rules 1–5 are technical requirements — breaking them produces incorrect renders. Rules 6–7 are best practices that the skills apply by default. You can override them when you have a reason to.
</Warning>
## Anti-patterns
Each one causes friction or wrong output for a specific engine reason — with the fix.
**Don't ask for React / Vue components.** Compositions are plain HTML with `data-*` attributes and a GSAP timeline; framework components force a translation step.
- ❌ `build a React component for the intro`
- ✅ `build the intro scene` (the agent writes composition HTML directly)
**Don't over-spec resolution or framerate.** Defaults (1920×1080, 30fps) render fast and look great; higher specs slow rendering meaningfully.
- ❌ `render in 4K 60fps` (for a social clip)
- ✅ say nothing — or `4K` only when the delivery target actually needs it
**Don't skip the slash command.** Without `/hyperframes`, the agent guesses at HTML video conventions instead of loading the framework's actual rules.
- ❌ `make me a video of...`
- ✅ `/hyperframes make me a video of...`
**Don't paste raw error logs.** Lint and validate localize the problem first; a bare log makes the agent re-derive what the tools already know.
- ❌ pasting 200 lines of console output
- ✅ `lint passes but validate reports a missing asset in scene 2 — fix it`
**Don't assume the agent knows your assets.** It will look, but a path skips the search.
- ❌ `use my logo`
- ✅ `use assets/logo.svg`
**Don't override a workflow's designed style.** Each workflow skill carries an art-directed preset; fighting it produces a compromise, not your theme.
- ❌ `/pr-to-video ... dark theme`
- ✅ let the preset carry the look, or use a freeform build when you need full style control
**Don't hard-time a verbatim script.** With supplied narration text, duration follows the spoken words.
- ❌ `a 60-second explainer from this script: ...`
- ✅ `a ~60-second explainer from this script: ...`
docs/prompting/specification-dial.mdx
+19
View File
@@ -0,0 +1,19 @@
---
title: The specification dial
description: "Spec density controls how far the result drifts from what you imagined - not whether it works."
---
## The specification dial
How much you specify sets how much you delegate — it controls how far the result can drift from what you imagined, not whether it works. Mood-level prompts ("snappy", "cinematic") get a designer's interpretation: coherent, but the agent picks the colors, staging, and details. Dense specs — hexes, timestamps, easings, pinned techniques — get *your* frame.
Three settings:
1. **Mood words** — "a warm, minimal logo sting". Fastest to write; the agent owns the look.
2. **Style tokens** — exact hexes, named textures ("halftone-dot", "paper-cut matte", "8-bit pixel"), type direction ("condensed caps", "thin geometric sans, wide tracking"). Cheap precision, no downside.
3. **Full visual spec** — every element gets shape + color + position + timing (next section). Use when you're recreating a specific look.
Density never hurts — a stronger model just uses less of its own taste. It matters most for technique choices a smaller model won't default well. Two worth pinning every time:
- **3D**: any real depth, lighting, or camera motion → say **"Three.js via the adapter"**. CSS perspective transforms read flat on lighting-critical scenes, and Three.js is a supported seek-safe runtime.
- **Sequencing**: resolve simultaneity in the text. "The counter fades out and READY stamps in at 4s" produces an overlap; "fades out fully by 4.2s; at 4.2s READY stamps in" doesn't.
docs/prompting/visual-specs.mdx
+15
View File
@@ -0,0 +1,15 @@
---
title: High-fidelity looks
description: "Write a visual spec - every element named, positioned, colored, and timed - to carry a specific look in words."
---
## High-fidelity looks: write a visual spec
Recreating a specific look from words alone works when the prompt reads like a designer's spec — every element named, positioned, colored, and timed. Compare a description ("dark night scene, mountain, glowing ring, title fades in") with a spec:
> 8-second 1920x1080 title card. Scene, back to front: #0a0e2a night sky with faint grain; a huge concentric ring system (5 rings, 1px strokes at 8% white opacity, innermost ring glowing #4a5fd9) centered 40% from the top; behind the rings an orange radial glow (#ff6a2b core → transparent, ~300px) igniting at the peak's right shoulder from 2s; a low-poly mountain (6-8 dark navy facets, #141a3d–#1e2650) filling the lower third, a white road S-curving up its face with a soft glow; thin horizontal cloud streaks (white, 6% opacity) drifting right at two heights; a man's silhouette, pure black, ~90px tall, bottom-right, fading in at 2.5s. At 3.5s "SHOWREEL" — thin geometric sans, ~140px, 0.35em tracking, white at 90% — fades in per letter across the ring center, the orange glow bleeding through the O. Slow 4% push-in across the full 8s. No audio.
Every element is a primitive the agent can build directly. Two honest limits:
- **Organic illustration** (drawn characters, painterly texture) can't be fully carried by text — words underdetermine a drawing. Steer to geometric shape language ("flat rounded-geometric figure, circle head, no facial features"), or generate the artwork (next section).
- **Photographic and live-action content** must be supplied as files — mention the paths explicitly.
docs/prompting/vocabulary.mdx
+170
View File
@@ -0,0 +1,170 @@
---
title: Vocabulary that changes output
description: "Natural-language adjectives the skills map to specific framework settings - easing, captions, transitions, audio, voices."
---
## Vocabulary that changes output
The skills map natural-language adjectives to specific framework settings. Using the right word gets you the right result without specifying technical details.
### Motion & easing
Describe how motion should *feel* and the agent picks the matching GSAP ease:
| Say this | Agent uses | Feels like |
| ----------- | ---------------- | ------------------------------ |
| smooth | `power2.out` | Natural deceleration |
| snappy | `power4.out` | Quick and decisive |
| bouncy | `back.out` | Overshoots then settles |
| springy | `elastic.out` | Oscillates into place |
| dramatic | `expo.out` | Fast start, long glide |
| dreamy | `sine.inOut` | Slow, symmetrical |
**Timing shorthand:** fast (0.2s) = energy, medium (0.4s) = professional, slow (0.6s) = luxury, very slow (1–2s) = cinematic.
### Camera language
Compositions have no physical camera, but camera words translate directly into scene transforms (or real camera moves in Three.js scenes):
| Say this | Agent builds |
| ------------------- | --------------------------------------------------------- |
| slow push-in | 4–8% scale increase across the scene, gentle ease |
| pull back / widen | scale decrease, often paired with elements entering |
| pan across | horizontal translate of the scene layer |
| drone orbit | continuous camera orbit (Three.js scenes) |
| crane down/up | vertical camera drift combined with a look-at shift |
| whip to | fast blurred slide into the next framing |
| parallax | layers translating at different rates for depth |
### Depth language
| Say this | Agent builds |
| ---------------------- | -------------------------------------------------------- |
| near-lens / foreground bokeh | large, heavily-blurred elements drifting close to camera |
| depth planes | 2–3 layers moving at different speeds |
| out-of-focus background | blurred, slower-moving back layer |
| shallow depth of field | sharp subject, blurred everything-else |
### Pacing language
| Say this | Agent builds |
| ----------------- | --------------------------------------------------- |
| punchy cuts | 1.5–4s per idea, hard cuts, overlapping entrances |
| cinematic holds | longer beats with ambient idle motion |
| beat-synced | cuts and accents on the music's beat grid |
| breathing room | a held moment before the next beat starts |
| ambient idle | 1–2% breathing scale + slow drift during holds |
### Caption tones
Describe the *energy* of your captions and the agent picks matching typography, size, and animation:
| Tone | Typography | Animation | Size range |
| ------------ | ---------------------- | ------------ | ---------- |
| Hype | Heavy weight fonts | Scale-pop | 72–96px |
| Corporate | Clean sans-serif | Fade + slide | 56–72px |
| Tutorial | Monospace | Typewriter | 48–64px |
| Storytelling | Serif | Slow fade | 44–56px |
| Social | Rounded, playful | Bounce | 56–80px |
```
"Hype-style captions with scale-pop"
"Calm, elegant subtitles with slow fades"
"Karaoke-style word highlighting"
```
Per-word styling also works:
```
"Make brand names larger with accent color"
"Add bounce to emotional keywords"
"Highlight numbers differently"
```
### Transitions
Every multi-scene composition benefits from transitions. Describe the energy level:
| Energy | CSS option | Shader option |
| ------- | ---------------- | ------------------- |
| Calm | Blur crossfade | Cross-warp morph |
| Medium | Push slide | Whip pan |
| High | Zoom through | Glitch, ridged burn |
Or describe by mood:
```
"Warm transitions for this wellness brand"
"Cold, clinical transitions for tech"
"Playful bouncy transitions"
"Dramatic zoom for the reveal"
```
### Audio-reactive animation
Map audio frequency bands to visual properties. The agent uses these defaults:
| Audio band | Maps to | Visual effect |
| ---------- | --------- | ------------------- |
| Bass | `scale` | Pulse on the beat |
| Treble | `glow` | Shimmer intensity |
| Amplitude | `opacity` | Breathing |
| Mids | `shape` | Morphing |
```
"Make the text pulse with the beat"
"Add bass-driven scale to the logo"
"Create glow that responds to treble"
```
<Tip>
Keep audio-reactive effects subtle for text (3–6% intensity). Go bigger for backgrounds (10–30%).
</Tip>
### Marker highlights
Hand-drawn emphasis effects for text:
| Mode | Effect | Best for |
| ----------- | ------------------ | ------------- |
| `highlight` | Marker sweep | Key phrases |
| `circle` | Hand-drawn ellipse | Single words |
| `burst` | Radiating lines | Hype moments |
| `scribble` | Chaotic scratch | Crossing out |
| `sketchout` | Rectangle outline | Callouts |
```
"Add a marker highlight sweep on 'revolutionary'"
"Circle this keyword with hand-drawn effect"
"Add burst lines around 'AMAZING'"
```
### Text-to-speech voices
TTS runs locally via Kokoro (no API key needed). Describe the content and the agent picks a voice, or request one directly:
| Content type | Recommended voices |
| ------------- | -------------------------- |
| Product demo | `af_heart`, `af_nova` |
| Tutorial | `am_adam`, `bf_emma` |
| Marketing | `af_sky`, `am_michael` |
```
"Generate narration for this script"
"Create voiceover with a professional female voice"
"Add TTS with British male voice at 1.1x speed"
```
### Rendering quality
| Quality | Use for |
| ---------- | ------------------------ |
| `draft` | Fast iteration |
| `standard` | Review and feedback |
| `high` | Final delivery |
```
"Quick draft render"
"Render at high quality"
"Export as transparent WebM"
```
plans/prompt-guide-expansion.md
+266
View File
@@ -0,0 +1,266 @@
# Prompt Guide expansion plan
Status: draft 2026-07-08. Owner: Vance. Source of validated content: the 2026-07-07/08
prompting-guide work (18 verified example prompts, showreel recreation, motion grammar,
asset-gen hybrid, recreation protocol; renders in ~/src/hyperframes-prompt-examples,
preview page https://www.heygenverse.com/a/5db0a33b-97e3-4fdb-8747-823a73ad9bbe).
## Goal
Promote `guides/prompting` from a single page to a top-level **Prompt Guide** nav group:
the current page splits into focused sub-pages, each expanded, and every documented
feature that _implies_ a promptable action gets actual prompting guidance. Standing
rule carried over from the original guide: **no prompt ships unverified** — every
example is built, rendered, and (where feasible) embedded next to its prompt.
## Navigation (docs.json)
New top-level group between **Concepts** and **Guides**:
```
[Prompt Guide]
prompting/overview
[Fundamentals]
prompting/anatomy
prompting/specification-dial
prompting/vocabulary
prompting/iterating
prompting/rules-and-anti-patterns
[Making it look good]
prompting/visual-specs
prompting/motion
prompting/generated-artwork
prompting/recreating-references
[By video type]
prompting/product-launch
prompting/explainers
prompting/code-and-prs
prompting/music-and-slideshows
prompting/captions-and-talking-heads
prompting/motion-graphics
[By feature]
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
```
`guides/prompting` becomes a redirect to `prompting/overview`. Keep the page count out
of prose (drift rule, same as skills.mdx).
## Page-by-page
### prompting/overview
Landing: what prompting a video means, one-time skill setup (moved from current page),
the two prompt shapes (cold/warm), the recommended workflow loop, and a map of the
section. Ends with 3 "best of" example prompts w/ embedded renders.
### Fundamentals (split + expand current content — all already validated)
- **anatomy** — the 6-part skeleton, per-part rationale, assembled terminal example,
plus 3 dissections: take a weak prompt, show the fixed version, diff annotated.
- **specification-dial** — mood → style tokens → full spec; cross-model validation
result; the two always-pins (Three.js, sequencing). Expand: when looseness is a
feature (creative exploration) vs when density is mandatory.
- **vocabulary** — existing mapping tables (easing, caption tones, transition energy,
audio-reactive, marker highlights, TTS voices, render quality) + new validated ones:
camera language ("push in 6%", "drone orbit"), depth language ("near-lens bokeh"),
pacing language ("punchy 2s cuts" vs "cinematic holds").
- **iterating** — talk-like-an-editor edits (existing) + the calibration rules from the
recreation work: absolute targets not relative nudges, one axis at a time, freeze
what works.
- **rules-and-anti-patterns** — the 7 technical rules, anti-patterns, plus the newly
validated ones: never "holds motionless", don't create simultaneity conflicts,
don't override skill-mandated styles, "~60s" with verbatim scripts.
### Making it look good (current sections promoted to pages, each gains examples)
- **visual-specs** — density ladder + mountain-title worked example + 2 more specs
(one UI piece, one typographic piece) with renders.
- **motion** — the six-rule premium-motion grammar; before/after render pair
(frozen-hold build vs motion-pass build of the same piece — we have both).
- **generated-artwork** — hybrid pattern, 3 keying/restraint rules, before/after
(hand-drawn SVG team vs asset-gen team — we have both renders).
- **recreating-references** — the transcribe → iterate → distill protocol, fidelity
table, globe worked example + its one-shot render; honest-ceiling callout.
### By video type (one page per workflow; the 8 current examples seed them)
Each page: what the workflow does, 3-5 verified prompts (the existing one + variants:
different durations, aspect ratios, tones), the knobs that matter for that workflow
(e.g. explainer: verbatim vs summarized script, caption style, scene density), and
common failure modes. NEW VALIDATION NEEDED: ~2-4 variant builds per page.
Pages: product-launch (also covers website-to-video), explainers, code-and-prs
(pr-to-video + code blocks context), music-and-slideshows, captions-and-talking-heads
(embedded-captions + talking-head-recut), motion-graphics (also logo stings, stats).
### By feature — the "implied but unguided" gap pages
Sourced from existing docs that document a capability without prompting guidance:
- **transitions** (sources: 14 shader + 13 CSS catalog groups, transitions skill) —
energy/mood → named block mapping, when shader vs CSS, per-seam prompting
("whip-pan on phrase changes"), full block name table. Validation: montage build
exercising ~6 transitions.
- **captions-catalog** (sources: 15 caption components + embedded-captions skill) —
tone → component mapping ("karaoke pill", "kinetic slam", "matrix decode"), per-word
styling asks, safe-area/vertical notes. Validation: one clip rendered with 4 styles.
- **overlays-and-lower-thirds** (sources: social overlays, lower-thirds, news-ticker
catalog groups) — "add a lower third at 0:03 with name/title" class of prompts,
picking styles by brand tone, transparent-overlay output for NLEs.
- **code-blocks** (sources: code animations + 24 code-snippet themes) — prompting
code walkthroughs: typing, diff, highlight, scroll; theme selection language.
- **data-and-maps** (sources: data-chart, 5 US-map variants, world/spain maps) — chart
prompts from CSV/inline data, map highlight/flow/bubble asks, the animated-map
motion-graphics pattern.
- **vfx-and-liquid-glass** (sources: HTML-in-Canvas group, html-in-canvas guide) —
device mockups, liquid glass, shatter/portal/magnetic effects; when these need the
canvas pipeline and what to say.
- **rendering-and-output** (sources: rendering, 4k-rendering, hdr, deploy/lambda) —
quality/format/framerate asks, transparent WebM (and when it's incoherent — full-frame
designs), 4K/HDR guidance incl. cost warnings, "render this on Lambda" cloud prompts.
- **editing-existing-videos** (sources: timeline-editing, keyframes,
video-editor-cheatsheet, studio docs) — NLE-verb prompts: trim/split/move/retime
scenes, keyframe nudges, "make scene 2 snappier", swap assets; maps the cheatsheet's
editor verbs to prompt phrasings. Likely the highest-traffic page of the group.
- **media-and-audio** (sources: video-components, remove-background, media-use skill)
— TTS voice/tone/speed asks, BGM mood + loudness targets ("under -18dB"), SFX cues,
transcription/captions from audio, background removal, video-in-video/PiP, and the
supplied-assets rule (explicit paths).
- **variables-and-templating** (sources: concepts/variables, sdk) — parameterized
compositions ("make name/logo/color variables"), batch/personalization prompts,
template-then-instantiate pattern.
- **runtimes-and-3d** (sources: concepts/frame-adapters, gsap-animation) — the
Three.js-via-adapter pin with worked language, when Lottie/CSS/WAAPI make sense to
request, shader transition requests, canvas/WebGL determinism caveats in prompt form.
- **design-systems** (sources: claude-design, open-design, figma skill) — design.md /
brand-token driven prompting, "use the site's own palette", Figma import asks.
## Validation & build plan
Reuse the proven pipeline: Opus builder subagents, one-shot from the page's prompts,
lint+validate+render gates, frame verification; embed finished MP4s next to prompts
(Mintlify supports video embeds; assets go wherever docs media lives today — confirm
hosting path, else link the HeyGenVerse gallery).
Phasing (each phase shippable):
1. **Restructure** — split current page into overview + Fundamentals + Making-it-look-good
(no new validation needed; content exists). Add nav group + redirect. ~1 PR.
2. **High-traffic gaps** — editing-existing-videos, rendering-and-output,
media-and-audio, transitions, captions-catalog. Each needs a validation build day.
3. **By video type** — 6 pages, variant builds per workflow.
4. **Long tail** — remaining feature pages (data-and-maps, vfx, variables, runtimes,
design-systems, overlays, code-blocks).
## Competitive research findings (2026-07-08, adversarially verified)
Deep-research survey of first-party prompt guides — Sora 2 (OpenAI Cookbook), Runway
Gen-3/Gen-4, Veo (DeepMind + Cloud Veo 3.1), Luma, Anthropic prompt-engineering docs.
(Pika/Kling/Midjourney/Gemini/Copilot claims failed verification — resurvey later.)
What the best guides converge on, and what we adopt:
1. **Named content-slot anatomy.** Every major guide teaches a slot formula
(camera + subject + action + context + style [+ audio]); Veo 3.1 and Runway Gen-3
make it a literal bracket template. We already have a _process_ skeleton
(route/spec/beats/copy/technique/negatives) — ADD a named _content_ formula whose
slots map to HyperFrames concepts (beat + element + motion + layout + style/brand
- audio), demonstrated in one worked example. Lives on the anatomy page.
2. **Keyword→Output tables.** Runway Gen-3's gold standard: six categorized keyword
tables where every row pairs the keyword with the actual generated output. Our
vocabulary tables get the same treatment: motion verbs → GSAP behavior, camera
terms → transform/Three.js choreography, style terms → CSS treatment — each row
with a small rendered clip. (Borrow the format, not their legacy keywords.)
3. **Output pairing is the differentiator.** Even the best guides skip outputs on
their most complex examples (Sora's longest templates ship without any; both Veo
guides mostly unpaired — refuted 0-3). Our article standard (every prompt +
unedited render) beats the field; keep it absolute.
4. **❌/✅ paired rewrites under named rules with engine rationale** — Runway's
dominant device (e.g. ❌ "no clouds in the sky" → ✅ "a clear blue sky", because
negative prompts backfire). Adopt across anatomy + rules pages using our own
validated pairs: ❌ "holds motionless" → ✅ "settles into ambient idle";
❌ "both at 4s" → ✅ "fades out by 4.2s; at 4.2s..."; ❌ "make dots 2x finer" →
✅ "dot radius = 25% of row spacing".
5. **Iteration as single-variable science.** Sora: "editing is for nudging, not
gambling" — one change per edit; Runway Gen-4: minimal motion-only prompt first,
then add ONE element type at a time; strip-then-relayer when a shot misfires.
Expand the iterating page with these three moves + our absolute-targets rule.
6. **Timestamped/beat-segmented prompting as a signature device.** Veo 3.1's
[00:00-00:02] per-segment prompting is the survey's most distinctive device — and
it maps one-to-one onto HyperFrames' native data-* timing. Our "Beat N (x-ys)"
convention is this; promote it explicitly ("more native here than in any
diffusion model") on anatomy + by-video-type pages.
7. **Anthropic's IA moves**: thin-router overview, one consolidated living
best-practices reference (legacy URLs 301 into anchors), prerequisite gate
("before prompting, have X"). Adopt: keep overview thin; add a short
prerequisites block (skills installed, preview running, project scaffolded);
plan redirects when pages consolidate later.
8. **Efficacy evidence as differentiation** (research open question): no surveyed
guide shows its advice measurably works. Ours can — renders are deterministic and
cheap; we already hold before/after pairs (frozen vs motion-passed, hand-drawn vs
generated, loose vs dense builds). Add "before/after" render pairs as a standard
device on making-it-look-good pages.
Full cited report: deep-research run wf_c81199b6-b15 (22 confirmed claims, 3 refuted;
sources incl. cookbook.openai.com, help.runwayml.com, deepmind.google, cloud.google.com,
lumalabs.ai, platform.claude.com).
## Incorporate the article's drafted guidance
The HeyGenVerse article (https://www.heygenverse.com/a/5db0a33b-97e3-4fdb-8747-823a73ad9bbe)
drafted guidance and presentation patterns beyond the current mdx — these become the
template for every expanded page:
- **Proof pairing**: every example prompt is immediately followed by its unedited
render with the label "Rendered from the prompt above, unedited." This is the
guide's core credibility device — pages without renders don't ship.
- **Provenance line**: each page states how its claims were validated (built,
rendered, frame-verified) and when. The article's footer wording is the model.
- **Example tags**: prompts carry a visible registry-block / workflow / freeform tag
so readers learn which layer of the system they're exercising.
- **Drafted section prose to carry over into the split pages** (the article's phrasing
is tighter than the mdx in places — reconcile toward the article):
- Specification dial: "controls how far the result drifts from what you imagined,
not whether it works" + the two-pins callout as a distinct highlighted element.
- Generated artwork: the wins/loses two-column comparison (code-drawn wins /
code-drawn loses) rather than prose paragraphs.
- Motion: six numbered rules with the "frozen final second is the biggest
cheap-motion tell" line.
- Recreation: the 3-row fidelity table (transcribe ~75% / iterate ~90% /
distill ~80-90%) + honest-ceiling callout, with the one-shot render embedded
under the distilled spec (not the hand-tuned version — the honest artifact).
- **Article lifecycle**: the HV page stays the shareable preview/marketing surface;
it gets regenerated from the docs content at the end of each phase so the two never
fork. Renders already uploaded as HV assets (19 MP4s) are reusable by URL in the
docs if we choose the link-out hosting option (open question 2).
## Consistency obligations
- CLAUDE.md "skill catalog maintenance" applies: skills' SKILL.md descriptions stay the
source of truth for one-line blurbs; the by-video-type pages must link the matching
skill and not fork its routing language.
- llms.txt regenerates from docs — verify the new group lands there.
- Vocabulary tables must match what skills actually implement (easing map, caption
tones) — audit against skills/hyperframes-animation + embedded-captions at write time.
- Catalog pages already demo each block; feature pages link to them rather than
duplicating block docs. Prompting pages own only the "what to say" layer.
## Open questions
1. Group vs tab in docs.json (Mintlify): group keeps single-sidebar; tab gives the
guide its own sidebar. Current nav is single-tab groups — start as group, promote to
tab if it crowds.
2. Where do example MP4s live for docs embeds — repo (heavy), CDN bucket, or link out
to the HeyGenVerse gallery page? Decide before Phase 1 ships renders.
3. Do by-video-type pages absorb the existing standalone guides (website-to-video) or
link them? Proposal: link, don't absorb — those guides cover mechanics, prompting
pages cover phrasing.