> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reframe-video.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Directing guide

# reframe directing guide — high-end, reference-heavy pieces

Read this (after the syntax guide, `reframe guide`) when the ask is a CINEMATIC or
REFERENCE-FAITHFUL piece — a product teaser, a UI/session reproduction, a title
sequence, a data story — not a simple lower-third or KPI card (those you just write).
Simple jobs render first-try; the ceiling needs a process. This is that process.

## What to get from the user (before writing anything)

Ask for / confirm these — vague prompts are why these pieces take many rounds:

* **Concept** in one line ("a faithful Claude Code session that builds a logo", "an app
  that goes viral, everywhere").
* **References** — screenshots / a reference video / pasted real content (terminal output,
  copy, data). For fidelity work, the reference IS the spec. Save them to disk so you can
  `diff` against them.
* **Brand** — exact colors (hex), the wordmark, the font feel.
* **Format** — length (\~10–20s is a good ceiling clip), aspect (16:9 / 9:16), with or
  without sound.
* **Tone** — "Apple teaser" (slow, premium, lots of negative space) vs "faithful UI sim"
  (exact, dense) vs "kinetic/energetic". This sets pacing and camera.

## The loop

### 1. Storyboard the beats FIRST (structure, not a flat timeline)

Name the acts with `beat("...", {}, [ ... ])` before animating. A beat is a labeled,
retimable narrative unit; its label anchors audio and lets you restructure whole sections.
A reliable arc: **setup → inciting beat → rising → climax → resolution.** Decide what each
beat shows and how long, THEN fill in motion. (See `device-hero.ts`: `beat("ki"/"seung"/"jeon"/"gyeol", …)` — entrance → it-takes-off → everywhere → resolve.)

### 2. Match references with `diff` (stop eyeballing)

Reproducing a screenshot pixel-faithfully is the hardest part. Use the tool:

```
reframe diff ref.png --mode grid            # labelled 100px grid over the screenshot → read coords, place nodes
reframe diff ref.png scene.ts --mode side   # reference | your render, side by side
reframe diff ref.png scene.ts --mode diff   # absolute difference — bright where you're off
reframe diff ref.png scene.ts --mode blend  # 50% overlay — spot drift
```

Loop: `--mode grid` to measure → write the node tree → `--mode side`/`diff` to compare →
fix coordinates/sizes/colors → repeat until faithful. Pick the frame with `--t <sec>`.
The grid is rendered at the reference's **full resolution** — the printed numbers are
exact scene pixels, so place nodes at the labelled coordinates directly (no scaling).
`diff`/`blend` are sharpest on hard edges (type, icons, frames); over large **soft
gradients/glows** they always light up "different" even when close, so tune those by
eye with `--mode side` rather than chasing the diff to black.

### 3. Apply the cinematic-craft checklist

These are what make a piece read as premium, not a slideshow. Patterns proven in the
flagship scenes — reuse the technique, vary the content:

* **Camera moves with the story.** Push in on each beat: a `cameraTo(...)` running in `par`
  with the beat's content. Frame the detail that matters, pull back to resolve. (See
  `terminal-claude.ts` helpers `cam()`/`scroll()`/`show()` — focus + scroll + reveal as
  parameterized eased moves.)
* **Curved entrances, not straight slides.** A hero enters on a `motionPath` arc with
  `easeOutBack` (overshoot, then settle). (`device-hero.ts` `motionPath("phone-cam", [[…]], { ease: "easeOutBack" })`.)
* **Fake depth.** Layer a backdrop of many faint concentric ellipses (a smooth glow, no hard
  edge) + a spotlight + a cast shadow that tracks the hero + an impact ring on landing.
  (`device-hero.ts` backdrop/spot/shadow/ring rig.) Or use real depth: `camera.perspective`
  * per-node `z` (see the syntax guide's "Depth & perspective").
* **Layered idle motion.** Nothing should sit perfectly still. `oscillate` a few nodes at
  DIFFERENT frequencies (slow float, slower tilt, a fast accent) for life during holds.
* **Sound on the beats.** `scene.audio` cues anchor to your beat/timeline labels, so they
  survive retiming: `{ at: "land", file: "bong_001.ogg" }`, `{ at: "viral", offset: 0.4, sfx: "pop" }`.
  An `ambient-pad` bgm with `duck` under the hits. Quote `reframe labels` to see exact seconds.

### 4. Verify objectively (don't argue about "more dynamic")

Mind the tiers so you're not full-rendering to check small things: `compile`
(validate eDSL → IR, \~1s) and `labels` are cheap, no render; `frame --t <sec>`
is the cheap visual look (one PNG, \~1s); `motion`/`trace` below need a finished
render or reference video, so they're end-stage measurement, not the per-edit loop.

* `reframe manifest scene.ts` — every editable address (nodes, states, labels, beats). Read
  it before patching an overlay so you target real, stable addresses.
* `reframe lint scene.ts --strict` — flags un-addressable motion and verifies the scene is a
  pure function of time (no `Math.random()` / `Date`). A clean lint is the studio-readiness gate.
* `reframe labels scene.ts` — every label → exact seconds. The timing source for audio + a
  sanity check that beats land when you think.
* `reframe motion out.mp4` — speeds, static fraction, oscillation rhythm, spikes. A vague
  note like "make it punchier" becomes measurable: compare `meanSpeed`/`peakSpeed` before
  and after; `staticFraction` too high = it drags.
* `reframe trace ref.mp4 --apply scene.ts` — when you have a reference VIDEO (not image),
  extract its timing/easing and re-apply it onto YOUR node ids. Borrow the motion, keep your
  assets.

### 5. Hand-tune via preview → overlay

`reframe preview` to scrub, drag motionPath waypoints, and retime steps; export the overlay
JSON and render with `--overlay`. Those nudges survive a later regeneration (stable
addresses), so the human's polish isn't lost when you redo the base.

## Pitfalls

* Don't animate before the structure is right — fixing pacing after everything is keyframed
  is painful. Beats first.
* Reference fidelity is coordinates + color + type, mostly STATIC layout; get the held frame
  matching with `diff` before adding motion.
* Keep `id`s/labels stable across rewrites (see `reframe guide --regen`) so the user's
  overlay edits survive.
* It's still iterative. The tools cut the rounds; they don't remove the loop. `compile` to
  validate (\~1s), `frame --t <sec>` to look at a held moment (\~1s), adjust — the agent should
  read frames, not guess. Full `render` is the last step, not the per-edit check.