hyperframes/docs/guides/prompting.mdx

---
title: Prompt Guide
description: "How to prompt Claude Code, Cursor, Codex, 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
```

In Claude Code, restart the session after installing. Skills register as **slash commands**:

| Slash command       | What it loads                                                                |
| ------------------- | ---------------------------------------------------------------------------- |
| `/hyperframes`      | Composition authoring — HTML structure, timing, captions, TTS, transitions   |
| `/hyperframes-cli`  | CLI commands — `init`, `lint`, `preview`, `render`, `transcribe`, `tts`      |
| `/gsap`             | GSAP animation API — timelines, easing, ScrollTrigger, plugins               |

<Tip>
  Always prefix Hyperframes prompts with `/hyperframes` (or invoke the skill another way for non-Claude agents). This loads the skill context explicitly so the agent gets composition rules right the first time, instead of relying on whatever it remembers about web video.
</Tip>

## 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      | `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.

### 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"
```

## 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>