# OverlayMotion
> Remotion overlay templates and an edit-spec system built for AI agents:
> one JSON spec in, a branded rendered video out.

Generated from the overlay-motion package docs. Human version: the /docs pages.

---

# Quick start

From clone to rendered video in under five minutes. One repo, no extra
services. (The `overlay-motion` npm package is coming; today the repo is the
distribution.)

## 1. Install and explore

```bash
git clone <this-repo> && cd overlay-motion
npm install
npm run studio     # Remotion Studio: every template as a composition
```

Studio is the local gallery: every template is a composition you can scrub,
and the `custom` composition previews any spec you paste into its props.

The browsable version, with a live player and the exact JSON spec beside each
template, is at [overlaymotion.com/templates](https://overlaymotion.com/templates).
Every template page has a copy-spec button.

## 2. Write a spec

An edit is one JSON document. Start from any template's "copy spec" button,
or from scratch:

```json
{
  "version": 1,
  "format": "vertical",
  "fps": 30,
  "durationSec": 8,
  "source": { "type": "none" },
  "overlays": [
    {
      "template": "hero-title",
      "region": "center",
      "time": { "start": "0.5s", "appear": 1, "hold": 6 },
      "props": { "title": "Ship it", "subtitle": "The overlay system for agents" }
    }
  ]
}
```

For an agent editing real footage, start with the [Editing agent
playbook](agent-playbook.md): analyze the source, preserve protected subjects,
record assumptions and validate inexpensive checkpoints. The full rendering
grammar is [Edit Spec v1](edit-spec.md).

Run the agent on the strongest model you have access to, at its highest
reasoning setting. Weaker or low-effort models miss protected subjects and
mis-time overlays. Model names are left out on purpose: they turn over faster
than this document does.

## 3. Preview it

Open Remotion Studio (`npm run studio`): every template is a composition,
and the `custom` composition previews any spec you paste into its
`defaultProps`.

## 4. Render it

Every template is a composition in `remotion/index.ts`; the `custom`
composition renders whatever spec you pass:

```bash
npx remotion render remotion/index.ts hero-title out/hero.mp4
npx remotion render remotion/index.ts custom out/edit.mp4 \
  --props='{"spec": <your-spec>, "theme": <your-theme>}'
```

`--props` accepts a file path too: `--props=./my-edit.json`.

Rendering uses Remotion, which is free for individuals and companies of up
to 3 people; larger companies need a [Remotion Company
License](https://www.remotion.pro/license). See the current [Remotion
license](https://www.remotion.dev/license) for details.

## 5. Brand it

Pass any `BrandTheme` as `theme`: colors, fonts, radius, and glass/solid
surface. Same spec, another theme, rebranded video. Presets live in
`src/theme/themes.tsx`; the site's theme picker shows them all.

## Help shape OverlayMotion

OverlayMotion launched in August 2026, so this is still an early stage
project. Help us develop it: join the
[Discord](https://discord.gg/DgRTAQ3Ne) and tell us what you need. We can
work on your project with you and turn it into more real world templates
everyone gets to use.

---

# Editing agent playbook

The canonical behavior for an agent editing with OverlayMotion, written for the
common case: the user hands over footage and a weak prompt such as "make this
good," and for footage that carries spoken editing instructions.

You produce two artifacts. An **edit decision plan** records evidence,
assumptions, protected subjects, assets and QA checkpoints. An **Edit Spec v1**
describes the render. The plan explains judgment; the spec stays a deterministic
rendering input. Machine-readable defaults and the plan schema live in
`src/agent/`; tool contracts are in [agent-toolkit.md](agent-toolkit.md).

This page is what applies to every edit. Anything that applies to one kind of
request lives in its own file, and you open that file when the request names it.

## Open only what the job asks for

| The request involves | Read this first |
| --- | --- |
| captions, subtitles, word-timed text | [features/captions.md](features/captions.md) |
| removing, replacing or blurring a background | [features/background-removal.md](features/background-removal.md) |
| face or head tracking, a corner bubble, a follow crop | [features/tracking.md](features/tracking.md) |
| noise, hum, room tone, "clean up the audio" | [features/voice-cleanup.md](features/voice-cleanup.md) |
| a music bed | [features/music.md](features/music.md) |
| sound cues on overlays | [features/sound.md](features/sound.md) |
| a camera move | [camera-motion-spec.md](camera-motion-spec.md) |
| color, HDR, or an unexplained shift in the delivered file | [features/delivery-color.md](features/delivery-color.md) |
| authoring any spec at all | [edit-spec.md](edit-spec.md) |

Nothing else is required reading. A caption job never opens the matting page.
Each feature page carries the rules, the tools and the QA for that one job, so
opening it late is worse than opening it first: several of those rules decide
things before a render, and re-rendering is how they get paid for twice.

## Prime directive

Improve comprehension without contradicting the speaker, hiding the important
subject or fabricating facts. In priority order:

1. explicit user request;
2. observable transcript and visual evidence;
3. subject, message, rights and platform safety;
4. established brand and platform defaults;
5. decorative style.

When an explicit request conflicts with subject safety, satisfy both through
layout: split the screen and reframe the speaker into the open panel instead of
placing secondary media over their face.

## What you decide, and what you ask

Decide without interrupting the job: caption style, conservative motion, exact
safe placement, crop focus, phrase grouping, and the shortest faithful copy.
Record each one as an assumption.

Verify or ask before asserting identity, changing meaning, making a factual
claim, selecting unlicensed media, publishing a quote whose wording or
attribution is uncertain, or making an ambiguous destructive cut. A low-risk
draft may keep an unresolved item as a clearly labeled placeholder.

When templates are the choice, show at most three options, each with title,
slug, a one-sentence tradeoff and a preview path such as `/templates/speaker-card`,
so a UI can render linked choice cards without being coupled to one interface.

## The intake gate

Run this before writing the plan, once:

```bash
python3 scripts/check-intake.py --source talk.mp4 \
    --request "add subtitles and cut it for reels" \
    --asset logo=brand.svg
```

It probes the file and reads the request against the assets actually supplied.
Exit status is 2 when something blocks. The contract behind it is `INTAKE` in
`src/agent/policy.ts`; the script exists so the checks stop depending on an agent
remembering them at the end of a long session.

| verdict | what it means | what you do |
| --- | --- | --- |
| `blocking` | the edit cannot be finished as asked | stop and say what is missing |
| `ask` | two or three legitimate answers, materially different | one question, options, default already chosen |
| `checkpoint` | a preview answers it faster than a question | show the cheap thing, keep going |
| `default` | reversible or decorative | choose from source evidence, record it |

Only three things block, each because the missing piece cannot be invented:
captions asked of a source with no speech, brand treatment with no brand asset,
and named b-roll with no media or license.

Questions come from facts about the file, never from a fixed questionnaire. A
horizontal source going vertical raises "whose framing wins in the crop"; the
same request over a source that already fits raises nothing. A round that asks
what the file already answers teaches the user to skip the round.

Budget: one round, at most three questions, each with the default already
selected so silence means proceed. Record every one in the plan's
`clarifications` with `resolution` set to `answered`, `defaulted` or `deferred`.
`validateEditDecisionPlan` rejects a plan carrying an unanswered blocking
question, an answered question with no option named, or more than three open
questions, so the budget is enforced rather than requested.

## Environment bootstrap

```bash
bash scripts/agent-bootstrap.sh                  # detect and reuse only, downloads nothing
bash scripts/agent-bootstrap.sh --need captions  # transcriber AND forced aligner
bash scripts/agent-bootstrap.sh --need matting --need denoise
bash scripts/agent-bootstrap.sh --all
```

It is idempotent and reuse-first: it detects ffmpeg/ffprobe/whisper-cli (and
avconvert on macOS) and symlinks anything already present under
`dev-assets/projects/*` into canonical paths, so a warmed machine finishes in
seconds with zero network. Downloads happen only for groups named with `--need`;
fetch for the edits the footage actually asks for, not up front. Missing items
print a `todo:` line with the flag that fetches them, and anything listed `ok` is
safe to use while other items are missing.

The summary ends in `CAPTIONS BLOCKED` while the forced aligner is missing even
when the transcriber is ready, because a transcriber alone is not a caption
pipeline. Reading spoken instructions off a draft transcript is fine at any time;
timing captions from one is not.

Never `pip install` into an existing pinned venv without checking the imports
first. A bare `pip install torchvision` into a venv that already has torch
silently upgrades torch to the newest release (observed: 2.8.0 dragged to 2.13.0)
and breaks the denoise stack sharing that venv. The bootstrap installs matched
pairs only when the imports fail.

## Source analysis before effects

Create one normalized source record before authoring the spec:

- probe container, codec, dimensions, rotation, frame rate, duration, color
  range and audio streams;
- transcribe speech with word start/end timestamps and language. Recognizer word
  times are a draft and can overrun the real media duration near the tail, so
  clamp them to the probed duration and confirm any time used as an edit beat
  against extracted frames;
- inspect a contact sheet across the full timeline;
- inspect frames around each named person, object, gesture, scene change and
  requested edit beat;
- note face, mouth, active-hand, demonstrated-object and platform-UI regions;
- preserve the original; use a rotation-correct proxy only when the renderer
  needs one.

Treat spoken edit commands as commands only when the context supports it. Keep
the original words in the transcript either way.

## Source fidelity

Preserve the source's perceived color and audio unless the user explicitly
requests a creative change. Color grading, LUTs, exposure, contrast, saturation,
white balance, filters and HDR/SDR conversion are not reversible aesthetic
defaults.

- Preserve color primaries, transfer function, range, bit depth and HDR metadata
  through proxies and delivery when the output permits it.
- Never reinterpret or merely retag HDR footage as SDR. A required HDR-to-SDR
  conversion aims for a perceptual match, not a new look, and uses a
  color-managed path.
- Record every unavoidable conversion in the plan and the completion report. Ask
  before proceeding when the output needs a materially different look.
- Compare representative source and delivered frames through the same reference
  display transform, checking skin tones, neutral surfaces, shadows and
  highlights. Metadata alone does not prove color was preserved, and a delivery
  with an unexplained shift is not approved because its tags are compliant.

The renderer's master tags do not describe its pixels reliably, so the final
encode has a verification step of its own:
[features/delivery-color.md](features/delivery-color.md).

## The default edit for a weak prompt

For a spoken social video the useful default is deliberately modest:

- trim only obvious dead head and tail space; do not rewrite the speaker;
- add word-timed captions;
- apply brand tokens and real supplied brand assets;
- use restrained emphasis overlays only where the speech supplies a clear
  semantic beat;
- preserve faces, hands and demonstrated objects;
- keep source audio primary and avoid decorative sound under important speech;
- deliver a preview or checkpoints before paying for a full render.

Do not fill silence with effects. Do not turn every sentence into a card.

## Captions, in one paragraph

Spoken video gets word-timed captions by default unless the user opts out, and
captions have exactly one route: `scripts/align-words.py` force-aligns,
`scripts/build-caption-props.py` phrases, `scripts/check-caption-sync.py`
verifies. **Timing comes from forced alignment, never from a transcriber.**
Whisper drafts the words; a phoneme/CTC aligner decides when each one is said,
and both downstream scripts refuse input that does not name a forced aligner. A
cue carries at most 4 words, the letters carry a black outline, and captions
start in the `caption-zone` region. Everything else, phrasing, presets, props and
caption QA, is in [features/captions.md](features/captions.md).

## Protected subjects and the composed frame

Faces, mouths, eyes, active hands, a demonstrated object and the current gesture
target are protected. Add padding; do not merely avoid their bounding boxes.

When showing an image or secondary video: decide which subject is primary at that
beat, choose the secondary media region, reframe the base source into the
complementary region with `source.reframes` (see
[edit-spec.md](edit-spec.md#source-and-the-source-contract)), inspect the subject
at entrance, midpoint and exit, and place captions in the remaining safe region.
Prefer a stable crop with modest easing; unnecessary tracking looks nervous and
costs more to verify.

A spec has exactly one base `source` and it is the speaker, the one whose audio
survives to delivery. A screen recording, a demo capture, b-roll or a flat color
behind them all travel in props. Inverting that is the arrangement that loses the
speaker's audio, which is why the base source is defined by audio rather than by
whichever image is larger.

## Gesture-aware placement

Words such as "here," "there," "this" and "right here" are spatial only when
resolved with nearby frames.

1. Find the transcript time of the deictic word.
2. Inspect roughly 0.35s before through 0.65s after it.
3. Identify the active hand, fingertip and direction of the pointing ray.
4. Place the overlay just beyond the fingertip, usually about 3% of the frame
   past it, keeping hand, face and intended target visible.
5. Inspect the entire overlay window. Track only if the anchor moves enough to
   break the meaning.

Use a custom percentage region for the resolved location. A named corner is only
a fallback.

## Camera moves

Only the preset grammar is implemented (`preset`, `amount`, `inSec`, `outSec`,
`rest`, `focus`, `frequency`, `seed`, `time`, `easing`). Keyframes, rotation and
`crop` are not; do not author them.

- Outside its window a camera sits at its resting zoom, which is identity unless
  `rest` says otherwise. So "zoom in and stay zoomed" is either a window ending
  on the composition's final frame or a `rest` on a zoom preset. Do not leave a
  gap and expect the framing to persist.
- `inSec` and `outSec` pin the approach and the return to exact seconds on the
  window, which is how a spoken "zoom in right now" becomes a camera rather than
  an approximation.
- Choose the scope by semantics and text safety together. "Zoom in with the
  camera" is the recording camera, so footage-only `source.camera` fits, and it
  keeps text out of an animated scale (animated scale over text shimmers glyphs
  in Chromium renders; see [recipe-scaled-text.md](recipe-scaled-text.md)).
- A footage push-in magnifies the subject toward locked overlay regions. Check
  overlay clearance against the zoomed subject at the overlay's exit time, using
  the camera's zoom value at that moment. Sequencing the beats usually resolves
  the collision without tracking.
- Camera windows in one scope never overlap, each move has one editorial intent,
  and repeating or alternating zooms are never generated unless asked.

## Quotes, assets and logos

A quote is content, not decoration. Select wording that supports the nearby
speech and fits the safe region at a readable size, verify it against an
authoritative source, and preserve exact wording, author, work and
translation/edition. Never pass an attractive paraphrase as a quotation: label it
a paraphrase or drop the quote marks. Prefer a shorter verified excerpt over
shrinking a long quote until it is unreadable. Record the source in the plan even
when the design shows only a concise attribution.

Use assets in this order: user-supplied, brand library, licensed source, then a
generated asset when generation is appropriate and disclosed. Record source URL,
license and required credit; keep visible credit concise and full provenance in
the plan. Never reconstruct a real company logo when the asset is unavailable.
`logo-sting` accepts a real transparent `logo`; its monogram is an intentional
fallback, not an imitation.

## Efficient QA

Quality comes from targeted checks, not repeated full renders.

1. Validate the decision plan and the spec. If validation rejects a template slug
   as unknown, check `src/templates/<slug>/` before redesigning around it: a
   finished template may exist but be unwired, and registration is a three-line
   change.
2. Render low-cost stills just before the edit, at entrance, midpoint, exit and
   just after.
3. Add a checkpoint for every spatial decision (face, split, gesture) and every
   semantic one (quote, number, name, attribution). When a fullscreen-first
   template sits in a custom region, verify its complete visual bounds;
   container clipping is not intentional scaling.
4. Run the scripted checks before the visual ones. `check-caption-sync.py`
   settles onset, silences, cue windows and delivered audio offset without a
   frame being looked at, so your eyes are spent on what it cannot judge.
5. Compare the decoded delivery audio zero-point with the final cut-only audio
   and correct codec or container delay before approval. Re-measure after every
   remux, even a stream copy: edit lists and AAC priming shift on a container
   change. With no cuts, stream-copy the original track and verify the delivery
   is sample-identical at zero offset.
6. Compare representative source and delivered frames through the same display
   transform. Fail unexplained changes in skin tone, neutrals, shadows or
   highlights.
7. Watch one complete preview at normal speed. Full-render once after these pass.

Three frames may be enough for a stable static placement. A moving hand, crop,
face or tracked anchor needs more. Spend QA where the uncertainty is.

## Completion report

Report what was inferred, what was verified, asset provenance and credit, what
the template system could not express, and which QA checks ran. Never claim
"perfect sync," "face safe" or "verified quote" without the corresponding
evidence.

---

# Edit Spec v1

An edit spec is a JSON document that describes a finished edit: one base
source, a stack of overlay templates, cameras, and sound. It is the only
input an agent needs to produce a video. Zod schemas live in
`src/spec/types.ts`; full validation (shape + template cross-checks) is
`validateSpec` / `parseSpec` from `src/spec/validate.ts`.

```json
{
  "version": 1,
  "format": "landscape",
  "fps": 60,
  "durationSec": 20,
  "source": { "type": "video", "src": "your-footage.mp4" },
  "overlays": [
    {
      "template": "speaker-card",
      "region": "lower-third",
      "time": { "start": "2s", "duration": "9s", "appear": 0.7 },
      "props": { "name": "Ana", "role": "Founder", "photo": "ana.png" }
    }
  ]
}
```

This page is the grammar every spec uses. Three parts of it are big enough to
have their own page, and you only need them when the edit does:
[captions](features/captions.md), [sound cues](features/sound.md) and
[music](features/music.md).

## The two axes: region and time

Natural language like "on the bottom, at 2/3 of the video, for 3s" compiles
to `region: "lower-third"`, `time: { start: "66%", duration: "3s" }`.

- **`region`** (space): a named region (`fullscreen`, `top-banner`, `lower-third`,
  `upper-third`, `caption-zone`, `left-panel`, `right-panel`, `center`,
  `corner-tl/tr/bl/br`) or a custom rect in percentages
  (`{ "x": 31, "y": 70, "w": 38, "h": 18 }`). Unset uses the template's
  preferred region.
- **`time`** (timeline): values are seconds (`3` or `"3s"`), percentages of
  the owner timeline (`"66%"`), or negative seconds from the end (`"-2s"`).
  A window is `{ start, duration, appear, hold }`: `appear` is how long the
  entrance choreography takes, `hold` is how long the finished overlay stays
  after that. `duration` absent + `hold` present makes the window
  `appear + hold`.

Sequence overlays with about 1s between windows so handoffs read cleanly.

## Source and the source contract

`source` is the base layer: `{ type: "video", src }` (options: `muted`,
`fit`, `position`, `flipHorizontal`, footage-only `camera`, time-windowed
`reframes`), `{ type: "audio", src }`, or
`{ type: "none" }`.

### Subject-safe source reframes

`source.reframes` moves the base footage into a percentage rectangle during a
time window while overlays stay locked to the composition. This is editorial
layout, not camera motion. It is intended for split screens where simply
covering half of the fullscreen source would hide a face or demonstrated
object. Reframe windows may not overlap.

```json
{
  "type": "video",
  "src": "speaker.mp4",
  "fit": "cover",
  "position": "center 30%",
  "reframes": [
    {
      "time": { "start": "9s", "duration": "8s" },
      "region": { "x": 4, "y": 8, "w": 44, "h": 84 },
      "position": "60% center",
      "transitionSec": 0.3
    }
  ]
}
```

`fit` defaults to `cover`, `position` to `center`, and `transitionSec` to 0.3.
Resolve the position by inspecting the subject across the full window.

Every template declares one relationship with that base source, and
validation enforces it:

| Contract | Meaning | Requires |
| --- | --- | --- |
| `overlay` | Self-contained; draws over whatever the source is. Most templates. | nothing |
| `annotates-video` | Only makes sense over footage (captions, ticker, recording chrome). | `source.type: "video"` |
| `wraps-video` | Renders the base video inside its own layout (video-card). One per spec. | `source.type: "video"` |
| `visualizes-audio` | Driven by a standalone audio file (audiogram); receives it as `sourceSrc`. | `source.type: "audio"` |

A template that ships its own footage via props is still `overlay`: the
contract describes the BASE source only.

## Camera motion vs object motion

A **camera** moves the frame around finished content; **object motion** is
the content moving, and it belongs to the template. A camera never
choreographs entrances or exits.

Cameras live at three scopes, location = scope:

- `spec.camera`: the scene; source and every overlay move as one shot.
- `source.camera`: footage only; overlays stay locked to their regions.
- `overlay.camera`: one overlay's region viewport, on the overlay's own
  timeline.

Presets: `push-in`, `push-in-out`, `push-in-fast-out`, `pull-out`,
`pan-left/right/up/down`, `handheld` (fields `frequency`, `seed`), with
`amount`, `focus {x,y}`, `time`, `easing`. Scene scope accepts an array of
windows. Full grammar: [camera-motion-spec.md](camera-motion-spec.md).

## The motion language

Small on purpose, so mixed templates read as one design system. All three
knobs are optional; unset keeps the template's native motion.

- **`reveal`** (text entrance hint): `"fade-up"`, `"blur-in"`,
  `"typewriter"`. Text templates map it to their nearest native mode and may
  expose richer extensions via props (quote-card `animateIn` adds
  `"lines"`/`"words"`; tweet-card adds `"paragraphs"`/`"none"`).
- **`enter`** (card entrance, renderer-provided, identical on every
  template): `"slide-left"`, `"slide-right"`, `"spring"`, `"mask"`.
- **`exit`**: `"blur-out"` (blur + lift, the signature departure),
  `"fade-down"`, `"shrink"`, `"vanish"` (anticipation, then a 0.45s implosion
  with blur and a `pop` cue: the literal "make it disappear"; the other three
  run 0.9s). Templates with their own `exit` prop (speaker-card) treat the
  spec value as default, not override.
- **`motion`** (object motion, works on EVERY template). Two families, and the
  family decides which knobs mean anything.

  **Periodic**, oscillating for as long as their window lasts: `"shake"` (held
  in a hand: a slow drift, a mid correction and a fine tremor), `"wobble"` (a
  rock), `"float"` (a bob), `"sway-3d"` (a slow turn through depth, left and
  right). Shaped by `frequency`, phase-shifted by `seed`, faded by `rampSec` and
  `rampOutSec`.

  **One-shot**, traversing their window exactly once and easing to a stop at
  both ends: `"skew-right"`, `"skew-left"`, `"skew-up"`, `"skew-down"`. Each
  starts at the opposite extreme, passes through flat, and lands in a strong
  perspective keystone facing the named direction. The window IS the tempo, so
  `frequency`, `seed` and the ramps are inert for these; use `time` to say when
  and how long. The pair on one axis chains seamlessly, because the first ends
  in exactly the pose the second starts from:

  ```json
  "motion": [
    { "style": "skew-right", "time": { "duration": "4s" } },
    { "style": "skew-left", "time": { "start": "4s", "duration": "4s" } }
  ]
  ```

  Shared knobs: `style`, `amount` (0..1, unset uses the style's own default:
  0.2 for the flat styles, 0.7 for `sway-3d`, 0.175 for the `skew-*` sweeps,
  which land near 10deg because a sweep HOLDS its end pose and the card has to
  stay readable there) and `time`. Amplitudes are
  percentages of the overlay's region box, so one `amount` reads the same
  everywhere. It is its own transform layer, so it **stacks** with `camera`,
  `enter`, `exit` and `scale`, and an array of motions stacks with itself:

  ```json
  { "template": "quote-card", "enter": "spring",
    "camera": { "preset": "pull-out", "amount": 0.25 },
    "motion": { "style": "shake", "amount": 0.3 } }
  ```

  Use it instead of a `handheld` camera whenever you want the thing to move
  rather than the view of it: the camera preset zooms the region viewport by 5x
  `amount` to hide frame edges, which changes how big a card reads and is
  meaningless for a transparent cutout. Templates may ship a `defaultMotion`
  (the sticker drifts for free); `motion: { "style": "none" }` turns it off.
  `src/player/shake.ts`, `src/player/OverlayMotion.tsx`.

## Sticker border

`sticker` takes an optional die-cut outline. It is off unless you ask for it,
and it follows the artwork's own alpha edge, not its bounding box, because a
rectangle around a cutout is exactly the frame this template exists to avoid:

```json
{ "template": "sticker", "props": { "src": "pickle", "border": { "width": 10, "color": "white" } } }
```

`width` is design pixels at a 1080px short edge and means what it says: the
outline is grown one width out from the silhouette in every direction. `color`
takes a brand token, `white` / `black`, or a `#rrggbb` literal, the same escape
captions open. The border is painted before the contact `shadow`, so the shadow
is cast by the outlined silhouette instead of crossing it.

Two scaling behaviours worth knowing, because they differ. A camera transforms
the whole overlay after the outline is drawn, so a push-in thickens the edge
along with the art, which is what something belonging to the sticker should do.
`sizePct` does not: the width resolves against the composition, not the element,
so it is a fixed thickness on the finished frame and a small sticker reads with a
proportionally heavier edge. Drop the width when you shrink the art.

## Bundled sticker art

`sticker`'s `src` takes a bundled library NAME as well as a path or URL, so an
agent with no artwork of its own still has cutouts it can reach:

```json
{ "template": "sticker", "props": { "src": "pickle" } }
{ "template": "sticker", "props": { "src": "/my-brand/mascot.png" } }
```

Names carry no slash and no extension, so they can never collide with a path.
The set is `STICKER_LIBRARY` in `src/templates/sticker/library.ts` and the files
live in `public/stickers/`; provenance is in `public/stickers/SOURCES.md`. Today
it is one entry, `pickle`. Everything else about the template is unchanged: the
name only resolves the file.

## Sound and music

Cues default on. `sound` at the spec root sets defaults and each overlay may
override it; a template's own cue is a prop (`"sfx": "ding"`, `"sfx": false`),
while `sound.sounds` remaps by cue name for everything in scope. The core palette
is `click`, `pop`, `whoosh`, `ding`, `typewriter`. Full rules, including the two
scopes and the bundled library cues: [features/sound.md](features/sound.md).

`music` at the spec root is the bed under the whole composition, outside every
camera. `volume` is linear gain, defaults to `0.08`, and is the whole job: a bed
under speech belongs 15 to 20 LU below it, so measure both with `ffmpeg -af
ebur128` and compute the gain instead of judging it in a preview. `validateSpec`
rejects a bed above `0.3` while the source audio is unmuted. `fadeInSec` (1),
`fadeOutSec` (1.5), `trimStartSec` and `loop` (off) are the rest. The arithmetic,
a worked example and the fade/loop reasoning: [features/music.md](features/music.md).

## Captions

`caption-classic` is the caption renderer, and captions have a route that starts
before the spec does: forced alignment produces the word times, and a transcriber
never does. Read [features/captions.md](features/captions.md) before authoring
one.

The shape, in brief: pass one composition-relative `track` of cues and words (the
legacy overlay-relative `lines` remains valid), position with `region`, prefer the
named `"caption-zone"`, and configure `preset` (`classic`, `minimal`, `editorial`,
`punch`, `extruded`), `grouping`, `layout`, `highlight`, `appearance`, `styles`
and word `marks`.

```json
{
  "template": "caption-classic",
  "region": "caption-zone",
  "time": {},
  "props": {
    "preset": "classic",
    "track": {
      "timebase": "composition",
      "cues": [
        {
          "start": 1.1,
          "end": 2.4,
          "words": [
            { "text": "Build", "start": 1.18, "end": 1.45 },
            { "text": "OverlayMotion", "start": 1.46, "end": 2.05, "marks": ["buzzword"] }
          ]
        }
      ]
    }
  }
}
```

## Brand theme

Templates never hardcode style; they read tokens from the active
`BrandTheme`: `colors` (primary, onPrimary, surface, onSurface, muted,
background, optional secondary/accent), `fonts` (heading, body, optional serif), `radius`,
`logoText`, and optional `style` (surface `"solid" | "glass"`, `blur` up to
100, `opacity`, gradients, `borderColor`). Same spec + another theme =
rebranded video. Brand comes from the theme, never from props: no hex colors in
props, and caption style overrides reference these roles.

## Formats

`vertical` 1080×1920, `horizontal` 1920×1080, `landscape` 1620×1080,
`square` 1080×1080. Templates scale through the shared `rem()` helper, so
one spec renders correctly in all four.

## Validation

`parseSpec(raw)` (throws) or `validateSpec(raw)` (safe result) from
`src/spec/validate.ts`. Beyond shape, they validate every template's nested
props, enforce known template slugs, source-contract requirements, at most one
`wraps-video` overlay, and non-overlapping source-reframe windows. Overlay and
source-reframe windows may not extend past the composition duration.
`editSpec.parse` alone checks shape only; prefer the checked variants.

---

# Captions

Read this before authoring any request for subtitles, captions or word-timed
text. Spoken video gets captions by default unless the user opts out.

## One route, three commands

```bash
python3 scripts/align-words.py --audio <final cut audio> --transcript copy.txt
python3 scripts/build-caption-props.py --dir <project dir> --source <video>
python3 scripts/check-caption-sync.py --audio <final cut audio> \
    --props render-props.json --delivery <rendered file>
```

**Timing comes from forced alignment, never from a transcriber.** Whisper drafts
the words; a phoneme/CTC aligner decides when each one is said. Whisper segment
or token times, patched with silence heuristics, have shipped visibly wrong
caption timing and were rejected on review, so this is not a preference between
two working options. `align-words.py` runs torchaudio `MMS_FA` + `forced_align`
by default and WhisperX wav2vec2 with `--backend whisperx`; the aligner class is
the requirement, the package is not. `build-caption-props.py` and
`check-caption-sync.py` both refuse input that does not name a forced aligner, so
a transcriber's timestamps cannot reach a render even by accident.

If the aligner will not run, the fix is
`bash scripts/agent-bootstrap.sh --need captions`, not a fallback. Subtitles that
drift are the most visible way this product fails. The reasoning and the failure
modes are in [recipe-whisper-sync.md](../recipe-whisper-sync.md).

**Lock every source cut before final caption timing.** Alignment times belong to
the timeline of the file you align against, so align against the cut-only proxy.
Mapping pre-cut timestamps through edit ranges is only a draft.

**Verify the drafted copy before the words are final.** Running `align-words.py`
without `--transcript` drafts one and marks it `transcriptVerified: false`;
`build-caption-props.py` stops there, because a perfectly timed wrong word is
still a wrong word.

Reject an alignment when its first token begins before measured speech, when a
phrase stretches across silence, or when spot checks disagree with the waveform
or mouth timing. Never infer cadence by evenly dividing a phrase.
`check-caption-sync.py` tests the mechanical half of that list and exits 1.

## Phrasing

- **A cue carries at most 4 words**, normally no more than two lines and about 32
  characters per line. Four is a ceiling, not a target: you still phrase each
  cue, and you break where the speech breaks (clause end, comma, pause), not by
  filling every cue to the cap. On continuous speech most cues land at the cap
  anyway; that is the cap doing its job, not a phrasing decision. Raise it
  deliberately with `grouping.maxWords` when the copy needs it. `caption-classic`
  enforces the same ceiling itself, so a caller that groups loosely gets split
  rather than a wall of text: `explicit` mode means your phrasing is respected,
  not that the cap is waived.
- Show a phrase about 80ms before its first word. Highlight using aligned word
  boundaries. Hold the completed phrase for up to 180ms when the next phrase or
  silence permits; do not overlap adjacent phrase windows.
- Preserve pauses as empty time. A caption disappears during a meaningful silence
  rather than stretching across it.
- Keep casing and punctuation readable. Correct obvious transcription mistakes
  only when the audio makes the intended word clear.
- Start captions in the named `caption-zone` region (`{x: 6, y: 65, w: 88,
  h: 20}`), slightly above the lower platform-control area. Move it only after
  visual checks, keeping captions away from the face, mouth, active hands and any
  media carrying the current meaning.

**Captions carry a black outline on the letters.** This is the `classic` preset
default, not decoration. Subtitles do not get to choose what is behind them, and
a drop shadow alone disappears on light footage. Legibility has to come from the
type.

`text.case` (`as-spoken` | `upper` | `lower`) and `text.punctuation` (`keep` |
`strip`) rewrite the drawn copy only. Both stay off unless the user asks. They
never touch the transcript or the timing, and they are applied after grouping, so
punctuation still decides where a phrase breaks even when it is not drawn.
`strip` drops commas and periods only: question and exclamation marks carry
meaning a reader cannot recover from the words.

## The template

`caption-classic` is the caption renderer. New specs pass one
composition-relative `track`; legacy overlay-relative `lines` remains valid.
`region` controls the outer position.

```json
{
  "template": "caption-classic",
  "region": "caption-zone",
  "time": {},
  "props": {
    "preset": "classic",
    "grouping": {
      "mode": "auto",
      "targetWords": 3,
      "maxWords": 4,
      "maxLines": 2,
      "maxCharactersPerLine": 32
    },
    "layout": { "textAlign": "center", "verticalAlign": "bottom" },
    "highlight": { "mode": "word", "duringGaps": "none", "badgeMarginX": 6 },
    "appearance": {
      "mode": "fade-up",
      "durationSec": 0.18,
      "distance": 18,
      "staggerSec": 0.07
    },
    "styles": { "buzzword": { "fontRole": "serif", "fontWeight": 800 } },
    "track": {
      "timebase": "composition",
      "cues": [
        {
          "start": 1.1,
          "end": 2.4,
          "words": [
            { "text": "Build", "start": 1.18, "end": 1.45 },
            { "text": "OverlayMotion", "start": 1.46, "end": 2.05, "marks": ["buzzword"] }
          ]
        }
      ]
    }
  }
}
```

Highlight mode is `word` or `none`. `duringGaps: "none"` restricts active
treatment to actual aligned word windows; `hold` retains the last started word.
`badgeMarginX` reserves badge clearance on every word whenever the highlighted
style has a badge or pill background; it is never applied per active word,
because a margin that comes and goes with the highlight reflows the centered line
at word cadence and reads as the whole video micro-zooming. Appearance modes are
`instant`, `fade`, `fade-up`, `pop` and `word-by-word`.

## Presets, and which knob answers which request

Presets: `classic`, `minimal`, `editorial`, `punch`, `extruded`. `punch` is the
social hard-outline look: one word at a time, heavy weight, thick black stroke
painted behind the fill and a hard drop shadow, so it stays legible over any
footage without a plate. `extruded` keeps that cadence but replaces the shadow
with a solid extrusion down and to the right, the sticker look. `punch` wants a
heavy grotesk in the brand theme and `extruded` a rounded face (Arial Rounded MT
Bold is the reference); a light system stack will not read as intended.

A preset is a starting point, not a fork: every field it sets stays overridable
through `styles`.

- `strokeWidth` and `strokeColorRole` are the legibility layer, the only one that
  survives arbitrary footage.
- `extrude: { x, y, color }` is depth: a solid repeat of the glyph stepped out to
  `x, y`, which is what reads as a sticker. A single offset copy reads as a
  second word once the offset grows next to the type size, so prefer `extrude`
  over a hard `textShadow`.
- `textShadow` and `dropShadow` are not interchangeable. `textShadow` (`true` for
  the legacy soft shadow, or `{ x, y, blur, color, opacity }`) repeats the glyph
  alone, so under a thick stroke or an extrusion it is swallowed by them.
  `dropShadow` is cast by the whole painted silhouette, outline and extrusion
  included. Any tight offset, a 2px lift under `extruded` for instance, has to be
  `dropShadow` or it will not be visible at all.
- `fontRole` picks a theme role. `fontFamily` overrides it with a literal CSS
  stack (`"'Arial Rounded MT Bold', system-ui, sans-serif"`) when you are matching
  a reference face, which is cheaper than mutating a theme every other overlay
  shares. The family has to be installed already, because Chromium substitutes in
  silence and a wrong name renders as the wrong face instead of failing.
- Any color field accepts a brand token or a `#rrggbb` literal. Presets stay on
  roles, so a theme can still rebrand its own captions.

## Word marks

Word marks are style references, never raw CSS. A word's `marks` names one or
more styles, up to four, applied in order, so a later mark wins only the fields it
sets. `buzzword` and `emphasis` are built in; anything else resolves against
`styles.words`, a map of your own names to the same text style shape:

```json
"styles": {
  "words": {
    "pop": { "colorRole": "accent", "fontWeight": 900, "scale": 1.12 },
    "quote": { "fontRole": "serif", "fontStyle": "italic" }
  }
}
```

Naming the style instead of describing it inline keeps presentation out of the
copy and lets one treatment repeat across a track. A request for serif buzzwords
compiles to `styles.buzzword.fontRole: "serif"`; do not put prose or raw CSS in
word cues. A mark that resolves to nothing is a validation error naming the word,
not an unstyled word: the two are indistinguishable on screen, so the typo has to
fail at the gate or it never fails at all. Presets never ship `words`, because
which words in THIS track deserve a treatment belongs to the edit, not the look.

Text-only cues remain a compatibility fallback.

## Caption QA

Run `check-caption-sync.py` first: it settles onset, silences, cue windows and
delivered audio offset without a frame being looked at. Then check caption onset,
a middle word, phrase disappearance and a pause; for subtitles also inspect a
fast phrase and every cut boundary.

Hard-outline captions need sharp-glyph checkpoints (`w`, `m`, `v`, `W`) and
counter-rich glyphs (`e`, `a`, `o`): reject miter spikes, detached shadow copies
and any background gap between the painted word and its intended connected
shadow.

After render, decode the delivered file and compare its speech zero-point with
the aligned cut-only proxy. Containers and codecs add audio delay; correct that
offset before approval, then re-check the opening phrase, a fast phrase, every cut
boundary and the final phrase. Target no more than 20ms difference between
aligned audio and decoded delivery.

Re-check captions against the closest crop when the edit also tracks or reframes.
A screen-locked caption can collide with a newly centered or enlarged face even
when it was safe before.

---

# Person background removal and replacement

Read this before matting anything: removing, replacing or blurring back the
background behind a person.

Treat background removal as preparation of a reversible video proxy. Edit Spec v1
does not express person segmentation, so the original remains immutable and the
composited proxy becomes the spec's video source. Record the segmentation
backend, model/checkpoint, mask treatment, background and color path in the edit
decision plan.

## Two decisions the caller owns

"Remove the background" names what leaves and never what arrives. A second choice
hides in the same sentence: whether the cutout gets an outline, the sticker ring
that reads as a cut-out sticker rather than a floating subject.

Both are the caller's, not the agent's, and both are expensive to guess because
each wrong answer costs a full re-render. Ask them as **one** question before
matting starts:

- **Backdrop**: `transparent` (a real alpha channel, for compositing later), a
  flat color, the source blurred back, or supplied media. Transparency has a cost
  worth stating: `.mov` means ProRes 4444, which is large, and QuickTime shows
  black behind it because it does not composite alpha.
- **Outline**: off, or a width and color.

**The outline defaults to off.** It is an effect the user asks for, never a
byproduct of matting. Record its presence with the same `basis` an overlay choice
carries, in the plan's `cutout.outline`.

An outline also changes what the backdrop question means. With one, the matte's
soft edge blends into the ring instead of into the backdrop, so a busy plate
stops leaking through hair. Without one, edge quality is the whole illusion and a
high-contrast backdrop will expose every matte flaw.

## Default tool

[`scripts/person-cutout.py`](../../scripts/person-cutout.py) implements both
decisions as flags and is the path new edits should take. Run it with the
bootstrap venv:

```bash
dev-assets/matting-venv/bin/python scripts/person-cutout.py IN OUT \
    --repo dev-assets/rvm \
    --checkpoint dev-assets/models/rvm_mobilenetv3.pth \
    --background transparent|#RRGGBB|blur|<file> \
    --stroke 0 --stroke-color '#FFFFFF' \
    --overlay captions.mov
```

`--stroke 0` is the default and draws nothing. `--overlay` folds an RGBA layer (a
caption render, say) into the same pass, so the protected foreground is encoded
exactly once instead of decoded and re-encoded to composite. Do that compositing
in float with a straight-alpha "over"; ffmpeg's `overlay` filter carries the main
input's alpha through unchanged, which clips the overlay to whatever silhouette
it crosses.

Outline width is a ratio, not a constant: measure it against the subject, not the
frame. The reference look that set the current default is ~3.4% of the head's
width, which is 20px for a head filling 600px of a 1080-wide portrait.

The per-project `dev-assets/projects/*/composite_rvm*.py` copies predate this
script and are kept only as evidence for their field tests.

Use a soft alpha matte, not a binary cutout:

```text
output = source_foreground * alpha + replacement_background * (1 - alpha)
```

Run inference on a resized RGB copy when needed, but composite the
full-resolution color-managed source frame. Do not send foreground pixels through
a generative model or use a model-produced foreground when source color must be
preserved, unless a source-to-result comparison verifies that it is neutral.
Process frames in presentation-timestamp order, preserve their timestamps, and
reset temporal model state at hard cuts or discontinuities.

## Proven macOS path

A reviewed and approved edit used
[`scripts/person-gradient.swift`](../../scripts/person-gradient.swift):

1. Apple `avconvert` baked display rotation and converted the iPhone Dolby Vision
   profile 8.4 / HLG source through a color-managed path to an SDR BT.709 editing
   proxy. The original MOV remained unchanged.
2. `VNGeneratePersonSegmentationRequest` ran at `.accurate` quality through one
   `VNSequenceRequestHandler`, returning an 8-bit person matte for each frame.
3. Core Image scaled the matte to the source frame, expanded it with
   `CIMorphologyMaximum` radius `1.5`, then feathered it with `CIGaussianBlur`
   radius `1.15`. These were starting values for this 1080x1920 source, not
   universal constants.
4. `CIBlendWithMask` composited unchanged proxy foreground pixels over the
   requested procedural gradient. The script wrote a silent, rotation-correct
   H.264 BT.709 proxy with original presentation timestamps.
5. OverlayMotion rendered captions from that proxy. Final mux copied the original
   AAC packet stream instead of encoding audio again.

The approving QA for that edit measured color fidelity, matte edges, full decodes
and byte-identical copied audio; hold any reimplementation to the same checks.

## Linux and Windows backends

Keep the same ingest, alpha-composite and QA contract; replace Apple Vision with
one of these local matting backends:

- **Robust Video Matting (preferred for moving people):** RVM carries recurrent
  state between frames, which usually gives more stable video edges than an
  image-only model. Use its MobileNetV3 checkpoint through PyTorch or ONNX and
  retain recurrent state in timestamp order. The official implementation and
  weights are GPL-3.0, so review distribution requirements before using them in a
  proprietary product. See the [official RVM repository](https://github.com/PeterL1n/RobustVideoMatting).
- **MODNet (lighter fallback):** use the portrait-matting ONNX model for CPU,
  integrated-GPU or simpler deployments. Because MODNet treats frames
  independently, add motion-aware temporal smoothing and inspect fast hands, hair
  and motion blur for flicker. Avoid a blind exponential average that leaves a
  trailing silhouette. See the [official MODNet repository](https://github.com/ZHKKKe/MODNet)
  and [OpenVINO model entry](https://github.com/openvinotoolkit/open_model_zoo/blob/master/models/public/modnet-webcam-portrait-matting/README.md).

Select an ONNX Runtime execution provider from detected hardware, with CPU as a
required fallback:

- **Windows:** prefer WinML on supported current Windows systems for automatic
  provider selection; use CUDA/TensorRT for compatible NVIDIA installations,
  OpenVINO for supported Intel hardware, or DirectML for older/broad DirectX 12
  deployments. DirectML remains supported but is in sustained engineering.
- **Linux:** use CUDA/TensorRT for compatible NVIDIA installations, OpenVINO for
  supported Intel CPU/GPU/NPU hardware, or the default CPU provider.

Provider availability and version compatibility must be detected, not assumed.
Consult the current [ONNX Runtime provider matrix](https://onnxruntime.ai/docs/execution-providers/)
and [Windows guidance](https://onnxruntime.ai/docs/get-started/with-windows.html).
Pin runtime, model and checkpoint versions in the decision plan. Verify the
license of both code and the exact downloaded weights before shipping.

## Matte refinement and compositing rules

- Apply orientation before inference. A mask inferred from coded orientation must
  receive the identical transform as the displayed frame.
- Follow the selected checkpoint's exact channel order, normalization, aspect
  handling and recurrent-state contract. Never stretch a frame merely to match
  model input dimensions; pad or crop as documented, then map the matte back.
- Infer at reduced resolution when hardware requires it, but upscale only the
  matte and composite at delivery resolution. Prefer edge-aware upsampling.
- Start with roughly 1 to 2 full-resolution pixels of protective expansion and
  about 1 pixel of feather for a 1080x1920 portrait. Tune from full-resolution
  samples. Too little clips hair, glasses, ears and shoulders; too much retains a
  room-colored halo.
- For RVM, keep recurrent states across contiguous frames and reset them at cuts.
  For image-only models, use motion-compensated temporal refinement or a short
  edge-aware temporal window; never trade flicker for visible motion lag.
- Keep all matte math in float or at least 16-bit precision when the backend
  permits it. Quantize only at the required encode boundary.
- Dilate the matte for an outline with an octagonal structuring element
  (alternating square and cross 3x3 max filters). One square max-pool of the same
  radius overshoots convex corners by 41% and bevels heads and shoulders. Paint
  the ring color where the matte is partial, `source * a + ring * (1 - a)`, and
  let the dilated matte become the output coverage; the soft edge then blends
  into the ring instead of into whatever sits behind.
- Create the replacement background at the exact frame extent. Composite in a
  known working color space, then encode with correct range, primaries, transfer
  and matrix tags. Never treat an HDR tag change as conversion.

Background-removal preprocessing should normally produce video only. Preserve
audio separately. When timeline duration and cuts are unchanged, mux the original
compatible audio stream with stream copy:

```bash
ffmpeg -i rendered-video.mp4 -i source.mov \
  -map 0:v:0 -map 1:a:0 -c:v copy -c:a copy final.mp4
```

If cuts or speed change, apply the same edit map to audio; do not claim
byte-identical preservation. Validate decoded sync after the final container is
written.

## Required QA

1. Inspect a full-timeline contact sheet, then full-resolution frames at scene
   changes, lighting changes, maximum motion blur and near the beginning and end.
2. Check hair, glasses, ears, fingers, shoulders, clothing gaps and frame edges
   for clipping, holes, room-colored halos and background leaks.
3. Watch the complete composite at normal speed for matte chatter, pulsing,
   temporal trails and state leakage across cuts. Still frames alone cannot
   approve video matting.
4. Compare protected foreground crops from the color-managed source and proxy
   through the same display transform. Fail unexplained changes to skin, hair,
   clothing, neutrals, shadows or highlights. Restrict the comparison to the
   opaque region **eroded** past the outline and the feathered edge. An outline is
   opaque and is supposed to differ from the source, so including it measures the
   effect working and reads as a failing score: one such run scored 26dB where the
   eroded mask scored 57dB on the same file.
5. Decode the complete final video and audio streams. When audio was copied,
   compare source/final packet hashes and decoded samples; measure final audio
   offset as described in [captions.md](captions.md#caption-qa).

---

# Tracked overlays, head-follow and the face bubble

Read this before any request for face or head tracking, a corner bubble, or a
crop that follows the subject.

Use per-frame tracking when the user explicitly asks for it or when sampled
inspection proves that a static anchor cannot follow the subject. Unnecessary
tracking looks nervous and costs more to verify.

## Two ways to spend a track

Edit Spec v1 expresses no time-series landmarks, so tracking is always
preprocessing. There are two ways to spend the result, and picking the wrong one
is the usual mistake:

- **Bake it into a proxy**, which then becomes the spec source. Correct when the
  tracking *is* the framing of the whole delivery, such as a head-follow square
  crop. The renderer never learns the subject moved.
- **Pass it as props to a template.** Correct when the tracked subject is one
  element inside a composed frame, such as a corner bubble over a plate. The
  track is data; what it means is a rendering decision, so it belongs in the spec
  where it can be changed without re-tracking.

Prefer a tracker that emits data and a template that consumes it. A tracker that
writes pixels has welded one rendering decision shut:
`scripts/face-track.swift` exports the track,
`scripts/head-follow-square.swift` bakes a crop, and they run the same detection
over the same frames.

Captions and ordinary OverlayMotion overlays render afterward and stay
screen-locked in both paths.

## Tracking contract

1. Normalize orientation and color first. Detection coordinates, crop geometry
   and rendered pixels must share one upright display space; never mix coded
   dimensions with display dimensions.
2. Detect every presentation-timestamp-ordered frame. For a single-presenter
   shot, select the largest face. Record confidence or detection failures.
3. Convert the detector box into pixel coordinates with its documented origin.
   Apple Vision and Core Image both use a lower-left origin after orientation is
   baked; browser and CSS coordinates do not.
4. Stabilize center and size. At 24 to 30 fps, an exponential smoothing alpha
   near `0.18` to `0.28` is a useful starting range; increase it on large
   movement so the frame catches up instead of visibly lagging. Do not smooth
   across hard cuts.
5. When detection drops briefly, hold the last good anchor. Do not jump to frame
   center for one missed frame. After a real cut or sustained failure, reacquire
   or fall back to a verified static safe crop.
6. Keep tracked graphics hollow or offset unless occlusion is explicitly wanted.
   Eyes, mouth, hairline and expression remain protected.

## Head-follow square crop

Use a real crop rather than placing the portrait over a square canvas. Start
around `0.84 * source short edge` when modest zoom is acceptable; this creates
horizontal and vertical travel while retaining enough context. Center the crop on
the detected face with a small upward bias (about `0.08 * face height`) because
face boxes omit some hair. Smooth first, then clamp the crop center to
`[halfCrop, dimension - halfCrop]` on each axis. This guarantees full-frame pixels
and no black or transparent background. At source edges the subject must remain
off-center; report those clamped frames instead of fabricating pixels or
letterboxing.

On macOS, [`scripts/head-follow-square.swift`](../../scripts/head-follow-square.swift)
implements the proven local path with `VNDetectFaceRectanglesRequest`, adaptive
smoothing, edge clamping, BT.709 video-only output and tracking diagnostics:

```bash
swift scripts/head-follow-square.swift upright-bt709-input.m4v head-follow.mov 900
```

The optional crop side is in source pixels and may not exceed the short edge.
Choose it from full-resolution checkpoints, not from a contact-sheet thumbnail.
Preserve audio separately and mux it only after the OverlayMotion render.

## Face bubble: the recorder look, and what goes behind it

The style: the footage opens full frame, then collapses into a small tracked
bubble in a corner while something else takes the frame. Screen-recorder software
made it familiar, and it is the right shape whenever the speaker stops being the
thing worth looking at but is still the thing worth hearing.

It is a template, `face-bubble`, contract `wraps-video`. Two inputs:

```bash
swift scripts/face-track.swift upright-bt709-proxy.mov face-track.json
```

then the track goes into the overlay's props. Start the overlay where the
collapse should begin, not at 0: the template's own frame 0 is the untouched full
frame, so the base source layer hands over to it with nothing to see.

**What sits behind is a prop, never a second source.** This is the rule, not a
convenience:

> A spec has exactly one base `source`, and it is the speaker: the one whose
> audio survives to delivery. A screen recording, a demo capture, b-roll or a
> flat color behind them all travel in props.

Inverting that (screen recording as source, speaker as a prop) is the arrangement
that loses the speaker's audio, and it is the reason the base source is defined by
audio rather than by whichever image is larger.

| Prop | Notes |
| --- | --- |
| `track` | `[x, y, size]` per frame. `size` is the face box height, and it is what holds the head at a constant share of the bubble while the speaker leans in and out. `timebase: "composition"` indexes from the video's first frame, so a track file needs no slicing to match a late overlay start. |
| `shape` | `"circle"`, `"square"`, or `{ radiusPct }` for anything between. The aperture is square, so rounding is the only shape control; a 16:9 picture-in-picture window is not expressible yet. |
| `backdrop` | A hex string, or `{ color, media }`. `media` takes `src`, `fit`, `position`, `dim` and `loopSec`. Supply `loopSec` for any plate shorter than the talk: the renderer cannot probe media while rendering a frame, so without it the plate freezes on its last frame. |
| `corner`, `sizePct`, `marginPct` | Placement and size, both as a share of frame width so they read the same in any format. |
| `headroom` | Crop side as a multiple of the face box. Below ~1.5 the aperture clips chin and forehead on a head turn; above ~2.5 the face stops being the subject of its own bubble. |
| `enterSec` | `0` by default, a hard cut into the bubble. Raise it only when the collapse is doing work, handing over from a full-frame shot mid-take; around 0.8s reads as a move without stalling the talk. An animated entrance the edit did not ask for is a stall. |
| `shadow` | Give it a plate to sit on, or leave it off. Flat black has nothing to receive a shadow. |

Dim a busy plate (`backdrop.media.dim` around 0.3) rather than shrinking the
bubble to compete with it.

The template caps the crop to the frame and clamps its center inside, so the
bubble is never part backdrop. Do not undo that by widening `headroom` past what
the frame can supply: on a portrait clip with a close subject the cap engages,
which is correct, and the face simply sits off-center near the edges. Perfect
centering inside a circle is not observable; a crescent of backdrop is.

## Required QA

- Inspect a full-timeline contact sheet and dense frames at maximum speed,
  largest displacement, closest and farthest face, blur, frame-edge clamps and any
  detection miss.
- Check temporal behavior at normal speed. Fail nervous micro-jitter, delayed
  catch-up, snap-back, identity swaps, black edges and crop-size pulsing.
- For tracked graphics, verify eyes and mouth remain visible. For head-follow
  crops, verify the head is centered when geometry permits and quantify
  edge-clamped frames when it does not.
- Re-check captions against the closest crop. A screen-locked caption can collide
  with a newly centered or enlarged face even when it was safe before tracking.
- Record detector/backend, coordinate mapping, smoothing values, crop size,
  misses, clamp counts and visual checkpoints in the decision plan.
- For a bubble, verify the aperture is full at the frame where the subject is
  furthest off-center, not just at a comfortable one. Compute the worst frame from
  the track rather than hunting for it by eye. Verify the handover frame against
  the source too: a wrapping template that starts late must show that moment of
  the video, not the video's first frame.

---

# Voice cleanup and background-noise removal

Read this when the request names noise, hum, room tone, echo, or asks to "clean
up the audio."

Treat noise removal as restoration, not mastering. The goal is to reduce
non-speech sound while preserving the speaker's tone, timing, breaths, consonants
and perceived volume. A cleaner signal must not become louder merely because its
noise floor fell.

## The local, open-source workflow

1. Preserve the original audio unchanged. Lock the source cuts, then export the
   exact cut-only audio as uncompressed PCM. Avoid unnecessary resampling;
   DeepFilterNet3 expects 48kHz.

   ```bash
   ffmpeg -i final-cut.mp4 -vn -ac 2 -ar 48000 -c:a pcm_s24le voice-source.wav
   ```

2. Select and record representative noise-only and speech windows before
   processing. Measure their mean or RMS level and peak level so the result can be
   compared against the same windows later.

3. Run a local open-source speech enhancer. DeepFilterNet3 is the proven default:

   ```bash
   deepFilter --pf --atten-lim 30 --output-dir enhanced voice-source.wav
   ```

   Record the package version, model or checkpoint, license, attenuation limit and
   post-filter setting. Treat 30dB as a tested upper bound, not a universal value;
   reduce it if speech becomes metallic, watery, phasey or over-processed.

4. Listen to the complete enhanced track before EQ or mastering. Reject clipped
   consonants, missing word tails, pumping, metallic or watery tone, exaggerated
   sibilance, damaged plosives, or speech removed during pauses. Do not use a hard
   noise gate by default.

5. Apply only conservative corrective filtering when needed. These frequencies are
   starting points, not mandatory values:

   ```bash
   ffmpeg -i enhanced/voice-source_DeepFilterNet3_pf.wav \
     -af 'highpass=f=70:p=2,lowpass=f=15500:p=2' \
     -ar 48000 -c:a pcm_s24le voice-clean.wav
   ```

6. Master loudness as a separate step. Measure first:

   ```bash
   ffmpeg -i voice-clean.wav -af 'ebur128=peak=true' -f null -
   ```

   Never apply a large fixed gain merely because denoising made the waveform
   quieter. A modest lift is allowed when it materially improves intelligibility;
   normally start between +1 and +3 LU relative to the source and confirm it by
   A/B listening. Unless the user or delivery platform specifies a target, use
   about -18 LUFS integrated as a conservative starting point for close-mic speech
   and prefer clear over loud or fatiguing. Keep final true peak at or below
   -1.5dBTP. Compression is optional; if needed, use a low ratio and level-match
   the before/after comparison so louder does not masquerade as cleaner.

7. Mux the exact processed voice master into the delivery. Do not add music,
   ambience or decorative sound unless requested.

8. Verify synchronization after processing and final encoding. Enhancement, delay
   compensation, AAC priming and container timing can introduce offsets. Correlate
   the decoded delivery audio against the voice master and target an absolute
   offset of 20ms or less. If timing changed, realign captions to the delivered
   audio.

## Required QA

- Keep the original audio immutable.
- Use only locally runnable open-source components when the user prohibits paid or
  closed tools.
- Record component, model, checkpoint and license provenance.
- Compare the same noise-only and speech windows before and after cleanup.
- A/B at matched perceived volume; judge cleanup independently from loudness.
- Report integrated loudness, loudness range, true peak and the gain change from
  the cleaned signal.
- Listen for artifacts across the full track, including pauses and word
  boundaries.
- Confirm that silence remains natural and no gate clips consonants or breaths.
- Decode the complete final stream and verify audio/video duration and sync.
- Disclose any unavoidable residual noise or processing artifact.

Field note: one edit reached approximately -16.1 LUFS integrated and -1.3dBFS
encoded peak. It was technically clean but the speaker judged the voice too loud.
Therefore -16 LUFS is not a safe universal default; use only a modest lift when it
improves clarity, and evaluate denoising success separately from delivery
loudness.

---

# Music beds

Read this when the request asks for music. Music is never added to fill silence
and is not part of any default edit.

When it is requested it goes in `spec.music`, and the whole job is the gain.

```json
{ "music": { "src": "/music/bed.wav", "volume": 0.03, "fadeInSec": 1, "fadeOutSec": 1.5 } }
```

`music` is the bed under the whole composition, and it is neither a `source` nor a
cue: the source is whatever audio carries meaning, cues belong to the moments that
fire them, and this is the layer under both. It sits outside every camera, so
nothing that reframes the picture reframes the music.

## The bed is much quieter than the voice, and "much" is a number

Target the bed 15 to 20 LU below the speech, which is where a listener hears it
without having to work past it to follow the words. Nothing about that is a taste
call.

The reason this is a rule and not a preference is that the intuitive default is
wrong. A commercial music master sits near -14 LUFS. Recorded speech from a normal
setup usually sits well below that. So `volume: 1` does not mean "balanced", it
means the track is louder than the person talking, often by more than 10 LU.
`MUSIC_BED_DEFAULT_VOLUME` is 0.08 for that reason, and `validateSpec` rejects
anything above `MUSIC_BED_MAX_VOLUME_UNDER_SPEECH` (0.3) while the source audio is
unmuted, naming the field.

Measure, then compute. Never set the gain by ear in a preview, because the only
thing a preview proves is where your system volume happens to be:

```bash
ffmpeg -hide_banner -nostats -i cut-audio.wav -af ebur128 -f null - 2>&1 | grep -A 2 "Integrated"
ffmpeg -hide_banner -nostats -i bed.wav        -af ebur128 -f null - 2>&1 | grep -A 2 "Integrated"
```

Then `gainDb = (speechLufs - targetSeparationLu) - musicLufs`, and
`volume = 10 ** (gainDb / 20)`. Worked example: speech -27.3 LUFS, bed -14.3 LUFS,
target 18 LU of separation. `gainDb = (-27.3 - 18) - (-14.3) = -31`, so
`volume: 0.03`. At unity that same bed would have been 13 LU LOUDER than the
speaker.

Record both measurements and the arithmetic in the decision plan. A gain with no
measurement behind it is a guess, and it is the guess that ships as the version
nobody can listen to.

**15 to 20 LU is where you start, not where you stop.** Measure to get into that
range, then let the person whose video it is hear it, and set the delivered number
from their answer. Field note: an edit whose bed landed at -46.2 LUFS against
-27.3 LUFS speech, 18.9 LU of separation and textbook by every rule above, came
back as "the volume is too low." It shipped at 11.6 LU. Report the measured
separation in the completion report so the judgement has a number attached to it,
and never argue a reviewer out of their own ears with this table.

## The other fields

- **Fade, never cut.** `fadeInSec` (1) and `fadeOutSec` (1.5) are
  composition-relative, because a bed is usually longer than the edit and its own
  tail is nowhere near the last frame. A bed that starts on frame 0 at full gain
  reads as a mistake even when the level is right.
- **Loop deliberately.** `loop` is off by default. A bed shorter than the edit goes
  silent partway through unless you ask for the loop, and a loop point in the
  middle of a phrase is audible; prefer a bed longer than the composition.
- `trimStartSec` skips the head of the track.

Ducking is not expressed in Edit Spec v1. If the copy genuinely needs the bed to
step back under each sentence, that is a preprocessing job on the bed itself,
recorded in the plan like any other proxy.

---

# Sound cues

Read this when an overlay should make a sound, or when a request asks to change,
swap or silence one. For the bed under the whole edit, see [music.md](music.md).

`sound` at the spec root sets defaults; each overlay may override with its own
`sound` block. Cues resolve to built-in names, arbitrary audio paths, or `false`
to silence one cue. Cues default on. The curated core palette, which is what to
reach for first: `click`, `pop`, `whoosh`, `ding`, `typewriter` (`CORE_SFX` in
`src/sound/config.ts`).

## Two scopes, and picking the wrong one is the usual mistake

- **A template's own cue is a prop**, and every template that makes a sound has
  one. It is never a boolean: `false` is silence, a premade name swaps the cue
  (`"sfx": "ding"`), and any path or URL plays your own file
  (`"sfx": "/sfx/library/my-stamp.wav"`). Omit it and the template's default cue
  plays. `true` is rejected on purpose, because a boolean can only mean "whatever
  the template picked", which is the one choice that belongs to the caller.

  Naming is uniform: one sound is `sfx`, and a template with several names each
  one (`tickSfx` and `endSfx` on countdown, `typingSfx` on tweet-card and
  chat-bubbles, `exitSfx` on speaker-card, `checkSfx` and `stepSfx` on the step
  lists). Each template's page and its props schema list the ones it has.

- **`sound.sounds` remaps BY CUE NAME**, for everything in scope: `{ "pop":
  "ding" }` on an overlay changes every `pop` that overlay fires, including the one
  `exit: "vanish"` plays. Reach for it when you are restyling a whole edit, and for
  the template's own sound reach for the prop.

```json
{ "template": "sticker", "props": { "src": "logo.png", "sfx": "ding" } }
{ "template": "sticker", "props": { "src": "logo.png", "sfx": false } }
{ "template": "countdown", "props": { "from": 3, "tickSfx": "click", "endSfx": false } }
{ "template": "sticker", "sound": { "sounds": { "pop": "/sfx/custom.wav" } },
  "props": { "src": "logo.png" } }
```

## Library cues

Some defaults are **library cues**: a name whose sound is a bundled CC0 file
rather than a pack entry (`quote-word` and `word-settle`, the word-reveal clicks;
`chat-typing`, the typing-dots blip; `list-step`, the non-check list marker). They
behave like any other cue: swap them with a prop, or remap them by name in
`sound.sounds`. `LIBRARY_CUES` is in `src/sound/config.ts`, provenance in
[sfx-library.md](../sfx-library.md).

Avoid decorative sound under important speech.

---

# Delivery encode and color verification

Read this before the final standards-safe encode, and whenever a delivered file
looks different from the source.

The color rules themselves are in the playbook: preserve the source's perceived
color and audio unless a creative change was requested, never retag HDR as SDR,
and never approve an unexplained shift. This page is the mechanical part, the
encode out of the renderer's master.

## The master's tags are a hypothesis, not a fact

The Chromium-based renderer emits a master whose pixel format and color tags do
not describe the pixels reliably (observed: `yuvj420p` tagged `bt470bg` full range
for BT.709 input). Before the final encode:

1. Treat the master's tags as a hypothesis. Decode one overlay-free frame under
   each plausible interpretation and PSNR it against the same frame of the editing
   proxy; the interpretation that matches the proxy wins.
2. Convert with an explicit decode-to-RGB step using the verified interpretation,
   then encode RGB to BT.709 limited with explicit H.264 color metadata. A single
   YUV-to-YUV filter chain that trusts the tags can silently double-apply a range
   conversion and crush levels; this exact failure has produced a crushed 17.9 dB
   delivery in practice.
3. Re-measure delivered frames against the proxy (overlay-free frame, around 40 dB
   expected) before approval. A "correctly tagged" delivery is not evidence; the
   measurement is.

## Normalizing an awkward source

Normalize only when the source cannot be decoded predictably. Bake rotation and
make an editor-friendly proxy while preserving the original reference. Preserve
the source color primaries, transfer function, range, bit depth and HDR metadata
when supported. When HDR-to-SDR is unavoidable, use a color-managed transform,
record its parameters, and verify representative source, proxy and delivery frames
through the same display transform. Do not silently alter speed, perceived color
or audio sample timing.

---

# Camera motion

Everything on this page is implemented. Keyframes, rotation and `crop` are not
part of Edit Spec v1: do not author them.

A camera block may live at three locations, and its location is its scope:

- `spec.camera`: the scene; source and every overlay move as one shot
  (`src/player/SceneCamera.tsx`).
- `source.camera`: footage only; overlays stay locked to their regions.
- `overlay.camera`: one overlay's region viewport, on the overlay's own timeline
  (`src/player/OverlayCamera.tsx`).

Location-based scope avoids selectors and overlay IDs. Any scope accepts one
camera or an array of up to 8, each becoming its own nested transform, so a
zoom-out is a reusable effect rather than something an overlay can only have
once. Scopes combine; their transforms nest.

## Camera motion vs object motion

The one distinction every author and agent must hold: a **camera** moves the
frame around finished content; **object motion** is the content moving. They
never share knobs.

| | Camera motion | Object motion |
| --- | --- | --- |
| What moves | The viewport (scene, footage, or one overlay's region) | The template's own elements (card, text, items) |
| Who owns it | The spec's `camera` blocks | The template |
| Steered by | `spec.camera`, `source.camera`, `overlay.camera` | `time.appear`, `reveal`, `exit`, `overlay.motion`, template props |
| Examples | Push in on a face, handheld sway, settle after entrance | Card springs up, text types on, list items stagger |

The `handheld` preset is the one place authors reliably pick the wrong side. It
is a CAMERA: it moves a region's viewport and therefore zooms in (5x `amount`) so
drift never exposes a frame edge. For a transparent cutout there is no edge to
protect and the zoom silently changes how big the art reads, so overlays carry
`overlay.motion` for that: object motion applied to the element itself
(`src/player/shake.ts`, rendered by `src/player/OverlayMotion.tsx`), available on
every template. Shaking framed footage or a whole scene is still the camera's job.
The two motion families are documented in
[edit-spec.md](edit-spec.md#the-motion-language).

`motion` and `camera` are separate transform layers, so they stack: a card can
pull out and drift at the same time. Order, outermost first, is
`OverlayTransform` (scale/enter/exit) → `OverlayCamera` (region viewport) →
`OverlayMotion` (the element) → the template.

Rule of thumb: if the move belongs to a thing ("the card slides in"), it is
object motion and lives in the template. If the move belongs to the viewer's eye
("we lean toward the speaker"), it is a camera. A camera never choreographs
entrances or exits, and templates never implement camera motion internally.

## The fields

```ts
{
  preset: "push-in" | "push-in-out" | "push-in-fast-out" | "pull-out"
        | "pan-left" | "pan-right" | "pan-up" | "pan-down" | "handheld",
  amount?: number,                       // default 0.06, max 1
  inSec?: number,                        // zoom presets only
  outSec?: number,                       // zoom presets only
  rest?: number,                         // default 0, zoom presets only
  focus?: { x: number, y: number },      // composition percentages, default center
  frequency?: number,                    // handheld only, default 2.4
  seed?: number,                         // handheld only, default 0
  time?: TimeWindow,
  easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out",  // default ease-in-out
}
```

- **`amount`** is motion strength: zoom fraction for push and pull, own-size
  fraction for pans, wobble amplitude for handheld (0.018 reads as natural
  micro-shake).
- **`inSec` / `outSec`** are second-exact phase durations on the raw window
  timeline, and they bypass the easing curve so seconds stay seconds. `inSec` is
  how long the approach takes from the window start ("zoom in right NOW");
  `outSec` is how long the return takes, ending at the window close. Whatever
  remains between them is the hold. `push-in` takes `inSec` and holds the arrived
  framing to the window end; `pull-out` takes `outSec`; `push-in-out` and
  `push-in-fast-out` take both. This is the tool for spoken beats: two commands
  in the audio become one window whose edges sit on them.
- **`rest`** is the zoom this camera HOLDS when it is not moving: after its move
  settles, and everywhere outside its window. Without it a camera returns to
  identity, so "open tight on the face, then sit at a slight push for the rest of
  the video" would be two windows meeting at a step. `rest: 0.1` with
  `preset: "pull-out"` and `amount: 0.375` opens at 1.375, settles to 1.10 and
  stays there. `rest: 0` is the plain behaviour.
- **`focus`** is the transform origin in percentages of the camera owner's
  untransformed box: `{x: 0, y: 0}` top-left, `{x: 100, y: 100}` bottom-right,
  default center. The focus point lands at viewport center.

Scope viewport: root is the composition, source is the footage slot (including a
slot inside a `wraps-video` template), overlay is the resolved region box. Render
nesting:

```text
composition clip
  root camera
    source camera
      source
    overlay region placement
      overlay camera
        template internal motion
```

## Time semantics

- Root and source camera time uses the composition timeline. Overlay camera time
  uses that overlay's own timeline: `0s` is the overlay's first frame.
- `camera.time` selects a window inside the owner timeline. Without it, the window
  is the full owner timeline.
- Outside the window the camera sits at its resting zoom, which is identity
  unless `rest` says otherwise. A completed window never leaks its final pan into
  the following edit. A delayed overlay `pull-out` is the exception before its
  window: it holds the opening zoom so motion can begin without a snap.
- All resolution uses frames, `fps` and pure interpolation. No CSS animation,
  wall clock, randomness or runtime measurement affects rendered frames, which is
  why the Player and a CLI render agree frame for frame.

## Safe authoring defaults

Camera motion needs one editorial intent. It is not background decoration.

- Camera windows in the same scope must not overlap, and validation rejects it.
  Stacked transforms read as rapid zoom reversals or playback glitches.
- `push-in-fast-out` needs at least a 3-second window: arrive, hold the new
  framing long enough to read, then return once. Validation rejects shorter.
- Leave about 1 second between separate moves in the same scope unless a cut
  creates a new shot.
- Do not alternate push-in and pull-out repeatedly to manufacture energy.
  Repeating camera motion requires an explicit editorial reason, which means the
  user asked for it.
- To end zoomed, either close the window on the composition's final frame or set
  `rest`. Do not leave a gap and expect the framing to persist on its own.
- Choose the scope by semantics and text safety together. "Zoom in with the
  camera" is the recording camera, so footage-only `source.camera` fits, and it
  keeps text out of an animated scale: animated scale over text shimmers glyphs
  in Chromium renders, see [recipe-scaled-text.md](recipe-scaled-text.md).
- A footage push-in magnifies the subject toward locked overlay regions. Check
  overlay clearance against the zoomed subject at the overlay's exit time, using
  the camera's zoom at that moment, not the pre-zoom frame.
- Inspect a continuous preview at normal speed. Entrance, middle and exit stills
  cannot reveal oscillation.

## Presets

Presets are authoring sugar, never separate rendering behavior.

- `push-in`: zoom from `1` to `1 + amount`.
- `pull-out`: zoom from `1 + amount` to `1`.
- `push-in-out`: approach, hold, then restore framing before the window ends.
- `push-in-fast-out`: spends most of the window approaching, then returns quickly.
- `pan-left/right/up/down`: move focus by `amount * 100` percentage points.
  Direction describes camera attention, so `pan-right` raises focus `x` and
  pixels move left.
- `handheld`: deterministic wobble shaped by `frequency` and phase-shifted by
  `seed`; `easing` is ignored.

## Example

```json
{
  "version": 1,
  "format": "vertical",
  "fps": 30,
  "durationSec": 12,
  "camera": {
    "preset": "push-in",
    "amount": 0.06,
    "time": { "start": "0s", "duration": "12s" },
    "easing": "ease-in-out"
  },
  "source": {
    "type": "video",
    "src": "intro.mp4",
    "camera": {
      "preset": "pull-out",
      "amount": 0.375,
      "rest": 0.1,
      "outSec": 1.2,
      "focus": { "x": 72, "y": 42 },
      "time": { "start": "2s", "duration": "4s" }
    }
  },
  "overlays": [
    {
      "template": "stat-counter",
      "region": "corner-tl",
      "time": { "start": "3s", "duration": "4s" },
      "camera": { "preset": "push-in", "amount": 0.08, "inSec": 0.6 },
      "props": { "value": 150, "suffix": "K", "label": "subscribers" }
    }
  ]
}
```

## Validation

`validateSpec` rejects, by name and path:

- a camera window extending past the composition duration;
- overlapping windows within one scope;
- `push-in-fast-out` under 3 seconds;
- `rest` on a preset that does not zoom, or `rest` greater than `amount`;
- `inSec` or `outSec` on a pan or handheld, `outSec` on `push-in`, `inSec` on
  `pull-out`, or `inSec + outSec` longer than the window;
- a camera on an `audio` or `none` source.

---

# Agent capability toolkit

OverlayMotion specifies capabilities, not vendors. An agent may use local CLI
tools, hosted services or a human-assisted step, provided the returned evidence
meets these contracts. The canonical machine-readable list is
`AGENT_CAPABILITIES` in `src/agent/policy.ts`.

## Required capabilities

### Media probe

Input: source media. Output: duration, display dimensions, rotation, frame
rate, codec, color/HDR information and audio streams. `ffprobe` is one suitable
implementation. Never assume file extension describes the decoded video.

### Word transcription and forced alignment

Input: the final cut-only speech audio plus verified transcript copy. Output:
language, segments, each word's forced-aligned start/end time and confidence
where available.

These are two capabilities, not one, and only the second one sets timing.
Transcription drafts the words. Forced phoneme/CTC alignment against the edited
audio supplies every timestamp. Segment-only or raw Whisper token timestamps
are not a degraded fallback for this contract, they are a rejected input:
evenly divided or ASR-inferred words are not exact sync, and captions built
that way have already been rejected on review. `scripts/align-words.py` is the
local implementation (torchaudio MMS_FA, or WhisperX wav2vec2), and it writes
an envelope naming the aligner so downstream steps can refuse anything else.

The delivery QA step must also return decoded audio offset relative to the
aligned proxy; `scripts/check-caption-sync.py` measures it.

### Frame sampling

Input: media and timestamps. Output: a timeline contact sheet plus
full-resolution frames at edit checkpoints. Sample the whole clip once, then
densely around gestures, overlays, cuts, crops and semantic inserts.

### Visual inspection

Input: frames plus transcript intent. Output: padded protected regions, crop
focus, gesture anchor and confidence. Multimodal inspection is enough for
stable placements. It must examine time, not one convenient still.

### Validation and preview QA

Validate both the Edit Decision Plan and Edit Spec with `validateEditDecisionPlan`
(`src/agent/edit-plan.ts`) and `parseSpec` (`src/spec/validate.ts`). Inspect
low-cost checkpoints before full render; verify source audio, captions, spatial
safety and semantic content.

## Conditional capabilities

### Face/hand landmarks or tracking

Use a detector such as MediaPipe only when the face, hand or fingertip moves
enough that sampled inspection cannot keep an anchor safe. Return time-series
landmarks in upright display coordinates, presentation timestamps, confidence,
detection misses, smoothing parameters and any crop-edge clamps. Smooth noisy
coordinates, keep padding, hold the last good anchor over brief misses, reset at
hard cuts, and fall back to a verified static safe region after sustained
failure. A tracked crop must remain inside the source on every frame; never
letterbox, expose black/transparent pixels or invent scene content merely to
keep a face mathematically centered. Installing a large model for a stable
three-second gesture is wasteful and creates extra failure modes.

### Asset acquisition

Use when the requested image/video is absent. Search sources that expose usage
rights, download an editor-friendly file, and return source URL, license and
required credit. Reject a visually good asset when its rights cannot be
established. Cache it locally so preview and render do not depend on a remote
URL.

### Citation verification

Use when displaying a quote, statistic, identity, date or other factual claim.
Return verified copy, an authoritative source and any edition/translation that
changes wording. Search snippets are discovery, not verification.

### Media normalization

Use only when the source cannot be decoded predictably. Bake rotation and make
an editor-friendly proxy while preserving the original reference. Preserve the
source color primaries, transfer function, range, bit depth and HDR metadata
when supported. Never reinterpret or merely retag HDR as SDR. When HDR-to-SDR
is unavoidable, use a color-managed transform, return its parameters, and
verify representative source/proxy/delivery frames through the same display
transform. Do not silently alter speed, perceived color or audio sample timing.

## Escalation ladder

1. metadata + transcript + sparse contact sheet;
2. targeted full-resolution frames;
3. denser sampling around uncertain motion;
4. landmarks/tracking when spatial meaning still cannot be preserved;
5. ask the user only when evidence cannot resolve a consequential choice.

This ladder keeps tokens, model downloads and renders proportional to actual
uncertainty.

---

# AI instructions

You are an agent producing a video with OverlayMotion. This page is the compiler
model: how a request becomes a spec. Editorial behavior is normative in the
[Editing agent playbook](agent-playbook.md), and the playbook's routing table
says which feature page a given request needs.

## What you produce

One JSON edit spec. You never write React and never touch template internals. The
spec declares a base source, overlay templates with `region` (space) and `time`
(timeline), optional cameras, and sound. `parseSpec` in `src/spec/validate.ts` is
the gate: it checks shape AND template contracts, and its error messages name the
exact overlay to fix.

## Rules that keep output correct

1. **Pick templates by source contract.** `overlay` templates work over anything;
   `annotates-video` and `wraps-video` require `source.type: "video"`;
   `visualizes-audio` requires `source.type: "audio"`. Only one `wraps-video`
   overlay per spec. The contract is in each template's registry entry.
2. **Camera moves the frame, templates move the content.** Want the eye to
   travel? Use `spec.camera` (scene), `source.camera` (footage) or
   `overlay.camera` (one card). Want a card to slide, spring or type? Use `enter`,
   `reveal`, `exit` and template props. Never both for the same idea.
3. **Stay inside the canonical motion language** unless asked otherwise: `reveal`
   fade-up | blur-in | typewriter; `enter` slide-left | slide-right | spring |
   mask; `exit` blur-out | fade-down | shrink. Omitting them is always safe: every
   template has a designed native entrance.
4. **Time grammar:** `"3s"` seconds, `"66%"` of the owner timeline, `"-2s"` from
   the end. `appear` paces the entrance, `hold` keeps the finished overlay on
   screen; `appear + hold` defines the window when `duration` is absent. Sequence
   overlays with about 1s gaps so handoffs read cleanly.
5. **Brand comes from the theme, never from props.** No hex colors in props; the
   `BrandTheme` carries colors, heading/body/optional serif fonts, radius, and
   glass or solid surface. Style overrides reference these roles.

## Workflow

1. Analyze the media and write an Edit Decision Plan from the playbook.
2. Open the feature page for anything the request names (captions, background
   removal, tracking, voice cleanup, music, sound). Several of their rules decide
   things before a render.
3. Read the template list (`src/templates/registry.ts` or the gallery) and pick
   by contract and purpose.
4. Draft the spec.
5. Validate with `parseSpec`. Fix what the error names.
6. Check targeted frames and a full preview, then render once:

   ```bash
   npx remotion render remotion/index.ts custom out.mp4 --props=./edit.json
   ```

   Props JSON is `{"spec": ..., "theme": ...}`.

Technical reference: [Edit Spec v1](edit-spec.md). Camera grammar:
[Camera motion](camera-motion-spec.md).

---

# Recipe: forced-aligned subtitles and speech triggers

Goal: checklist ticks (or captions, or any timed prop) land exactly when the
speaker says each thing. Everything runs on the agent's machine; nothing on ours.

## The route

```bash
bash scripts/agent-bootstrap.sh --need captions          # transcriber + aligner
python3 scripts/align-words.py --audio cut-audio.wav --transcript copy.txt
python3 scripts/build-caption-props.py --dir <project> --source cut-proxy.mp4
python3 scripts/check-caption-sync.py --audio cut-audio.wav \
    --props render-props.json --delivery delivery.mp4
```

Transcription drafts the words. **Forced alignment decides every timestamp.**
That split is the whole recipe; the rest of this page is why each step exists
and how to read what it prints.

Whisper is a transcriber. Asked what was said, it is excellent. Asked when each
word was said, it answers from segment and token boundaries that drift a tenth
of a second or more, and drift differently on either side of a cut. A CTC
aligner is asked a narrower question, given these exact words and this exact
audio, where does each word start, and it answers to the frame. Captions timed
from the first question have shipped visibly wrong and were rejected on review.

## 1. Lock cuts and extract final edit audio

Do not finalize captions from the original media when the edit contains cuts.
Render a cut-only proxy first; `align-words.py` extracts mono 16kHz PCM from
whatever you hand it, so pass that proxy:

```bash
python3 scripts/align-words.py --audio cut-proxy.mp4 --transcript copy.txt
```

Alignment times belong to the timeline of the file you pass. Passing the
original media instead of the cut proxy produces times that are correct for a
video nobody will watch.

## 2. Verify the words, then align them

With a verified transcript, one command does everything:

```bash
python3 scripts/align-words.py --audio cut-audio.wav --transcript copy.txt
```

Without one, the same command drafts a transcript with `whisper-cli` first,
aligns that draft, and marks the result `transcriptVerified: false`. The timing
is real; the wording is a guess. Read it back against the audio, fix names,
brands, contractions and punctuation, and re-run with `--transcript`.
`build-caption-props.py` stops on an unverified draft, because a perfectly
timed wrong word is still a wrong word.

Numbers and letters spoken as words carry no alignable letters. Write them the
way they are said and keep the drawn form after a pipe:

```
Do it for about twelve|12 seconds
```

Backends:

- `mms_fa` (default) is `torchaudio.pipelines.MMS_FA` +
  `torchaudio.functional.forced_align`, running in the venv that
  `agent-bootstrap.sh` provisions. It times every word you give it.
- `whisperx` (`--backend whisperx`) transcribes and aligns in one pass through
  `uvx whisperx`, no install left behind. It leaves words it cannot align
  untimed, and the script fails rather than inventing their cadence.

Two traps behind the default backend, both already handled by the script and
both worth knowing when it breaks: torch and torchaudio must be a matched pair,
and a mismatch fails only at import; and torchaudio >= 2.11 routes
`torchaudio.load` through torchcodec, so the WAV is read with stdlib `wave` +
numpy instead. `align-words.py` re-execs itself under a python that has both,
so calling it with the system python3 is fine.

## 3. Read the alignment

`aligned-words.json` is an envelope, not a bare list:

```json
{
  "alignment": "forced-phoneme-or-ctc",
  "aligner": "mms_fa",
  "transcriptVerified": true,
  "words": [[5.26, 5.52, "marketing,", 0.91]]
}
```

The envelope is what `build-caption-props.py` and `check-caption-sync.py`
check. Numbers alone cannot show which question they answered, so a file that
does not name its aligner is refused rather than rendered.

Reject an alignment yourself when a low score clusters where the audio is
clear, when the mouth disagrees at a checkpoint, or when a phrase covers a
pause you can hear. Never infer cadence by evenly dividing a phrase.

## 4. Build readable caption phrases

`build-caption-props.py` groups words into cues and writes `render-props.json`.
It breaks where the speech breaks, at a sentence end, a comma or a pause over
0.6s, and caps a cue at 4 words. Phrase start is `firstWord.start - 0.08`,
phrase end is at most `lastWord.end + 0.18` and never overlaps the next cue.
Meaningful pauses stay empty.

Placement defaults to a band a little above the lower platform controls
(`--y`, `--x`, `--region-h`, `--region-w`). Override only after checking
subject and overlay collisions at representative frames.

The shape it writes:

```json
{
  "template": "caption-classic",
  "region": "caption-zone",
  "time": {},
  "props": {
    "preset": "classic",
    "grouping": { "mode": "explicit", "maxWords": 4 },
    "highlight": { "mode": "word", "duringGaps": "none", "badgeMarginX": 6 },
    "appearance": { "mode": "fade-up", "durationSec": 0.18, "distance": 18 },
    "track": {
      "timebase": "composition",
      "cues": [
        {
          "start": 1.17,
          "end": 2.44,
          "words": [
            { "text": "Hi,", "start": 1.25, "end": 1.49 },
            { "text": "my", "start": 1.51, "end": 1.61 },
            { "text": "name", "start": 1.63, "end": 1.75 },
            { "text": "is", "start": 1.77, "end": 1.83 },
            { "text": "Ricardo.", "start": 1.87, "end": 2.41, "marks": ["buzzword"] }
          ]
        }
      ]
    },
    "styles": {
      "buzzword": { "fontRole": "serif", "fontStyle": "italic" }
    }
  }
}
```

## 5. Map aligned words to other timed props

Pick the trigger word for each step and use its `start`. Make the overlay span
the whole video (`"time": {}`) so step times equal the transcript's absolute
times: no arithmetic. (If the overlay has its own `start`, subtract it.)

```json
{
  "template": "checklist-steps",
  "region": "lower-third",
  "time": {},
  "props": {
    "title": "What you can make",
    "steps": [
      { "text": "Social media clips", "at": "4.34s" },
      { "text": "Marketing videos", "at": "5.26s" },
      { "text": "Product demos", "at": "5.96s" }
    ]
  }
}
```

With timed steps the card slides in 0.6s before the first tick and leaves 1.5s
after the last one, so the overlay window can stay `{}`.

## 6. Check timing, including delivered audio

```bash
python3 scripts/check-caption-sync.py --audio cut-audio.wav \
    --props render-props.json --delivery delivery.mp4
```

It fails when the first word starts before the audio speaks, when a word spends
most of its length inside a detected silence, when words run backwards or leave
the clip, when a cue does not contain its own words or overlaps the next one,
and when delivered audio has moved more than 20ms from the audio the alignment
used. Exit status is 1 on any of those, so it can gate a render.

A word's release decays under the noise floor, so the last word of a phrase
legitimately reaches into the silence after it; the check looks at how much of
the word the silence holds rather than at raw overlap.

When the delivery offset check fails, shift delivery audio by the measured
amount and re-run. Positive delta means delivery audio is late and its leading
`delta` must be trimmed; negative means it needs matching delay. Never hardcode
one clip's offset.

Approval still needs your eyes at the opening phrase, one fast phrase, every
cut boundary, one meaningful pause and the final phrase. The script proves the
numbers agree with the waveform; it cannot tell you the words are right.

---

# Recipe: zooming text without glyph shimmer

Any template that animates `transform: scale` over live DOM text (zoom-in,
zoom-out, Ken Burns drift) makes letters wiggle slightly while the scale
changes. This is not a template bug and not spring jitter: Chromium
re-rasterizes glyphs with fresh hinting at every new effective scale, so stems
snap to different subpixels frame by frame. Proven on tweet-card: with the zoom
disabled, settled frames are pixel-identical; the shimmer only exists while
scale changes.

## The fix, in the template

Put this on the element that carries the animated `scale` (the card/root, not
each text node; `text-rendering` and `font-smoothing` inherit):

```tsx
transform: `scale(${scale}) translateZ(0)`,
willChange: "transform",
backfaceVisibility: "hidden",
WebkitFontSmoothing: "antialiased",
textRendering: "geometricPrecision",
```

- `translateZ(0)` + `will-change` promote the element to its own compositor
  layer: the browser scales the cached texture instead of re-hinting glyphs.
- `geometricPrecision` positions glyphs geometrically, no hinting snap.
- `antialiased` swaps subpixel AA for grayscale, killing RGB fringing shimmer.

This fully fixes the site player preview (real compositor). See
`src/templates/tweet-card/index.tsx` for the reference implementation.

## The fix, in final renders

The headless renderer screenshots every frame, so it re-rasterizes anyway and
the CSS only helps partially. For final files of any zooming template,
supersample and downscale:

```bash
npx remotion render remotion/index.ts <slug> out.mp4 --props=props.json --scale=2
npx remotion ffmpeg -y -i out.mp4 -vf "scale=1080:1920:flags=lanczos" \
  -c:v libx264 -crf 18 -pix_fmt yuv420p out-1080.mp4
```

Halves the shimmer amplitude and melts the rest into antialiasing.

## Measuring (to verify a new zoom effect)

1. Sanity: render two stills AFTER the motion settles with the zoom disabled.
   They must be pixel-identical (`PIL ImageChops.difference` bbox = None).
   If not, some spring/interpolation never settles; clamp it.
2. Shimmer metric: render two stills 0.2s apart mid-zoom, measure the card
   width on both to get the scale ratio, LANCZOS-resample still A by that ratio
   around the scale origin, diff against still B over the text area. Pure
   resample noise floor is ~1.0 mean abs diff; DOM text re-hinting shows ~2.5+.

## Other rules for scale animations

- Never animate `fontSize` or layout for a zoom: text re-wraps and genuinely
  jumps. Always `transform: scale`.
- End the settle at exactly scale 1 so the resting card is sharp.
- `Easing.inOut` spreads a long drift across the whole window; `Easing.out`
  front-loads it and the tail looks static.
- Derive every frame constant from `fps` (`fps * seconds`, never bare frame
  counts) so 30/60 fps specs keep the same wall-clock timing.

---

# SFX Library

A curated library of sound effects for edit specs, on top of the core 20-cue
palette in `public/sfx/` (which is synthesized in-house and license-free).
Every sound here was checked for free commercial use. Credits below name the
author and source of each file; keep this page updated when adding sounds.

## How to use

Sound cues in an edit spec resolve to built-in names, arbitrary audio paths,
or URLs (see [Edit Spec v1](edit-spec.md), section Sound). Use library files
by path:

```json
{
  "sound": {
    "sounds": {
      "click": "/sfx/library/kenney-click-001.ogg",
      "impact": "/sfx/library/freesound-deep-cinematic-impact.mp3"
    }
  }
}
```

### Library cues

Four library files are wired as NAMED cues, because a template ships them as
the default of a sound prop and a default has to be a name, not a path
(`LIBRARY_CUES` in `src/sound/config.ts`):

| Cue | File | Used by |
|---|---|---|
| `quote-word` | `kenney-tick-001.ogg` | quote-card, once per revealed word |
| `word-settle` | `kenney-tick-001.ogg` | blur-focus-text, as each word focuses |
| `chat-typing` | `kenney-uiaudio-rollover2.ogg` | chat-bubbles, under the typing dots |
| `list-step` | `kenney-tick-001.ogg` | numbered and bullet step lists |

They behave like any other cue: swap one on a single overlay with the
template's prop (`"wordSfx": "ding"`), or remap it everywhere in scope with
`sounds: { "quote-word": "..." }`.

## Licenses at a glance

| License | Commercial use | Attribution | Bundled in this repo |
|---|---|---|---|
| CC0 1.0 Universal | Yes | Not required (we credit anyway) | Yes, in `public/sfx/library/` |
| Mixkit Sound Effects Free License | Yes | Not required | No. Forbids redistribution as part of a tool or template, so download from the linked page into your own project |
| Pixabay Content License | Yes | Not required | No, same reason: no standalone redistribution. Download from the linked page |

Rows marked CC0 ship in `public/sfx/library/` (see
[SOURCES.md](../public/sfx/library/SOURCES.md) for the per-file credit list).
Mixkit rows link straight to the official Mixkit CDN file: agents may fetch
those URLs programmatically at build time (do not mirror them). Pixabay rows
only link to the source page; Pixabay blocks non-browser clients, so a human
must download the file there before an agent can use it.

## Transitions and whooshes

| Sound | File | Duration | Source | Author | License |
|---|---|---|---|---|---|
| Air woosh | [`1489.wav`](https://assets.mixkit.co/active_storage/sfx/1489/1489.wav) | 2.3s | [Mixkit](https://mixkit.co/free-sound-effects/whoosh/) | Mixkit | Mixkit Free License |
| Simple Whoosh | [download](https://pixabay.com/sound-effects/film-special-effects-simple-whoosh-382724/) | 1s | [Pixabay](https://pixabay.com/sound-effects/film-special-effects-simple-whoosh-382724/) | DRAGON-STUDIO | Pixabay Content License |
| Whoosh Cinematic | [download](https://pixabay.com/sound-effects/film-special-effects-whoosh-cinematic-376875/) | 2s | [Pixabay](https://pixabay.com/sound-effects/film-special-effects-whoosh-cinematic-376875/) | DRAGON-STUDIO | Pixabay Content License |

## Risers and build-ups

| Sound | File | Duration | Source | Author | License |
|---|---|---|---|---|---|
| Cinematic trailer riser | [`790.wav`](https://assets.mixkit.co/active_storage/sfx/790/790.wav) | 2.6s | [Mixkit](https://mixkit.co/free-sound-effects/riser/) | Mixkit | Mixkit Free License |
| Cinematic Riser 03 | [download](https://pixabay.com/sound-effects/film-special-effects-cinematic-riser-03-414575/) | 4s | [Pixabay](https://pixabay.com/sound-effects/film-special-effects-cinematic-riser-03-414575/) | DRAGON-STUDIO | Pixabay Content License |
| Reverse Cymbal Swell 3 | [download](https://pixabay.com/sound-effects/film-special-effects-reverse-cymbal-swell-3-185073/) | 6s | [Pixabay](https://pixabay.com/sound-effects/film-special-effects-reverse-cymbal-swell-3-185073/) | floraphonic | Pixabay Content License |

## UI: clicks, switches, hover

| Sound | File | Duration | Source | Author | License |
|---|---|---|---|---|---|
| Click 001 | [`kenney-click-001.ogg`](../public/sfx/library/kenney-click-001.ogg) | 0.1s | [Kenney Interface Sounds](https://kenney.nl/assets/interface-sounds) | Kenney | CC0 1.0 |
| Click 002 | [`kenney-click-002.ogg`](../public/sfx/library/kenney-click-002.ogg) | <0.1s | [Kenney Interface Sounds](https://kenney.nl/assets/interface-sounds) | Kenney | CC0 1.0 |
| Switch 004 | [`kenney-switch-004.ogg`](../public/sfx/library/kenney-switch-004.ogg) | 0.5s | [Kenney Interface Sounds](https://kenney.nl/assets/interface-sounds) | Kenney | CC0 1.0 |
| Tick 001 | [`kenney-tick-001.ogg`](../public/sfx/library/kenney-tick-001.ogg) | <0.1s | [Kenney Interface Sounds](https://kenney.nl/assets/interface-sounds) | Kenney | CC0 1.0 |
| Drop 002 | [`kenney-drop-002.ogg`](../public/sfx/library/kenney-drop-002.ogg) | 0.2s | [Kenney Interface Sounds](https://kenney.nl/assets/interface-sounds) | Kenney | CC0 1.0 |
| Pluck 001 | [`kenney-pluck-001.ogg`](../public/sfx/library/kenney-pluck-001.ogg) | 0.1s | [Kenney Interface Sounds](https://kenney.nl/assets/interface-sounds) | Kenney | CC0 1.0 |
| Bong 001 | [`kenney-bong-001.ogg`](../public/sfx/library/kenney-bong-001.ogg) | 0.1s | [Kenney Interface Sounds](https://kenney.nl/assets/interface-sounds) | Kenney | CC0 1.0 |
| Click 1 (UI Audio) | [`kenney-uiaudio-click1.ogg`](../public/sfx/library/kenney-uiaudio-click1.ogg) | 0.1s | [Kenney UI Audio](https://kenney.nl/assets/ui-audio) | Kenney | CC0 1.0 |
| Rollover 2 (hover) | [`kenney-uiaudio-rollover2.ogg`](../public/sfx/library/kenney-uiaudio-rollover2.ogg) | 0.1s | [Kenney UI Audio](https://kenney.nl/assets/ui-audio) | Kenney | CC0 1.0 |
| Switch 2 | [`kenney-uiaudio-switch2.ogg`](../public/sfx/library/kenney-uiaudio-switch2.ogg) | 0.3s | [Kenney UI Audio](https://kenney.nl/assets/ui-audio) | Kenney | CC0 1.0 |
| UI click | [`freesound-ui-click.mp3`](../public/sfx/library/freesound-ui-click.mp3) | 0.6s | [Freesound](https://freesound.org/people/Ranner/sounds/488534/) | Ranner | CC0 1.0 |
| Select click | [`1109.wav`](https://assets.mixkit.co/active_storage/sfx/1109/1109.wav) | 1.1s | [Mixkit](https://mixkit.co/free-sound-effects/click/) | Mixkit | Mixkit Free License |
| Interface Click | [download](https://pixabay.com/sound-effects/film-special-effects-interface-click-124476/) | 2s | [Pixabay](https://pixabay.com/sound-effects/film-special-effects-interface-click-124476/) | Universfield | Pixabay Content License |

## Pops

| Sound | File | Duration | Source | Author | License |
|---|---|---|---|---|---|
| Long pop | [`2358.wav`](https://assets.mixkit.co/active_storage/sfx/2358/2358.wav) | 0.5s | [Mixkit](https://mixkit.co/free-sound-effects/pop/) | Mixkit | Mixkit Free License |
| Bubble Pop 06 | [download](https://pixabay.com/sound-effects/film-special-effects-bubble-pop-06-351337/) | 1s | [Pixabay](https://pixabay.com/sound-effects/film-special-effects-bubble-pop-06-351337/) | Universfield | Pixabay Content License |

## Notifications, success, error

| Sound | File | Duration | Source | Author | License |
|---|---|---|---|---|---|
| Confirmation 001 (success) | [`kenney-confirmation-001.ogg`](../public/sfx/library/kenney-confirmation-001.ogg) | 0.3s | [Kenney Interface Sounds](https://kenney.nl/assets/interface-sounds) | Kenney | CC0 1.0 |
| Confirmation 002 (success) | [`kenney-confirmation-002.ogg`](../public/sfx/library/kenney-confirmation-002.ogg) | 0.5s | [Kenney Interface Sounds](https://kenney.nl/assets/interface-sounds) | Kenney | CC0 1.0 |
| Error 001 | [`kenney-error-001.ogg`](../public/sfx/library/kenney-error-001.ogg) | 0.2s | [Kenney Interface Sounds](https://kenney.nl/assets/interface-sounds) | Kenney | CC0 1.0 |
| Error 004 | [`kenney-error-004.ogg`](../public/sfx/library/kenney-error-004.ogg) | 0.1s | [Kenney Interface Sounds](https://kenney.nl/assets/interface-sounds) | Kenney | CC0 1.0 |
| Question 001 | [`kenney-question-001.ogg`](../public/sfx/library/kenney-question-001.ogg) | 0.5s | [Kenney Interface Sounds](https://kenney.nl/assets/interface-sounds) | Kenney | CC0 1.0 |
| Message pop alert | [`2354.mp3`](https://assets.mixkit.co/active_storage/sfx/2354/2354.mp3) | 1.1s | [Mixkit](https://mixkit.co/free-sound-effects/message/) | Mixkit | Mixkit Free License |
| Fairy message notification | [`861.wav`](https://assets.mixkit.co/active_storage/sfx/861/861.wav) | 2.3s | [Mixkit](https://mixkit.co/free-sound-effects/message/) | Mixkit | Mixkit Free License |
| Achievement bell | [`600.wav`](https://assets.mixkit.co/active_storage/sfx/600/600.wav) | 2.4s | [Mixkit](https://mixkit.co/free-sound-effects/achievement/) | Mixkit | Mixkit Free License |
| Game level completed | [`2059.wav`](https://assets.mixkit.co/active_storage/sfx/2059/2059.wav) | 3.5s | [Mixkit](https://mixkit.co/free-sound-effects/game/) | Mixkit | Mixkit Free License |
| Wrong answer bass buzzer | [`948.wav`](https://assets.mixkit.co/active_storage/sfx/948/948.wav) | 2.5s | [Mixkit](https://mixkit.co/free-sound-effects/error/) | Mixkit | Mixkit Free License |
| Chime notification | [`freesound-chime-notification.mp3`](../public/sfx/library/freesound-chime-notification.mp3) | 0.3s | [Freesound](https://freesound.org/people/Jofae/sounds/380482/) | Jofae | CC0 1.0 |
| New Notification 07 | [download](https://pixabay.com/sound-effects/film-special-effects-new-notification-07-210334/) | 2s | [Pixabay](https://pixabay.com/sound-effects/film-special-effects-new-notification-07-210334/) | Universfield | Pixabay Content License |
| Success Notification | [download](https://pixabay.com/sound-effects/film-special-effects-success-notification-132473/) | 2s | [Pixabay](https://pixabay.com/sound-effects/film-special-effects-success-notification-132473/) | Universfield | Pixabay Content License |
| Error Notification | [download](https://pixabay.com/sound-effects/film-special-effects-error-notification-352286/) | 1s | [Pixabay](https://pixabay.com/sound-effects/film-special-effects-error-notification-352286/) | Universfield | Pixabay Content License |

## Impacts, booms, braams

| Sound | File | Duration | Source | Author | License |
|---|---|---|---|---|---|
| Impact metal medium | [`kenney-impact-metal.ogg`](../public/sfx/library/kenney-impact-metal.ogg) | 0.3s | [Kenney Impact Sounds](https://kenney.nl/assets/impact-sounds) | Kenney | CC0 1.0 |
| Impact wood medium | [`kenney-impact-wood.ogg`](../public/sfx/library/kenney-impact-wood.ogg) | 0.3s | [Kenney Impact Sounds](https://kenney.nl/assets/impact-sounds) | Kenney | CC0 1.0 |
| Impact glass medium | [`kenney-impact-glass.ogg`](../public/sfx/library/kenney-impact-glass.ogg) | 0.5s | [Kenney Impact Sounds](https://kenney.nl/assets/impact-sounds) | Kenney | CC0 1.0 |
| Impact punch heavy | [`kenney-impact-punch.ogg`](../public/sfx/library/kenney-impact-punch.ogg) | 0.6s | [Kenney Impact Sounds](https://kenney.nl/assets/impact-sounds) | Kenney | CC0 1.0 |
| Impact bell heavy | [`kenney-impact-bell.ogg`](../public/sfx/library/kenney-impact-bell.ogg) | 1.5s | [Kenney Impact Sounds](https://kenney.nl/assets/impact-sounds) | Kenney | CC0 1.0 |
| Impact soft heavy (thud) | [`kenney-impact-soft.ogg`](../public/sfx/library/kenney-impact-soft.ogg) | 0.5s | [Kenney Impact Sounds](https://kenney.nl/assets/impact-sounds) | Kenney | CC0 1.0 |
| Impact plate medium | [`kenney-impact-plate.ogg`](../public/sfx/library/kenney-impact-plate.ogg) | 0.6s | [Kenney Impact Sounds](https://kenney.nl/assets/impact-sounds) | Kenney | CC0 1.0 |
| Big cinematic impact | [`788.mp3`](https://assets.mixkit.co/active_storage/sfx/788/788.mp3) | 7.9s | [Mixkit](https://mixkit.co/free-sound-effects/impact/) | Mixkit | Mixkit Free License |
| Movie trailer epic impact | [`2908.wav`](https://assets.mixkit.co/active_storage/sfx/2908/2908.wav) | 4.9s | [Mixkit](https://mixkit.co/free-sound-effects/impact/) | Mixkit | Mixkit Free License |
| Futuristic bass hit (drop) | [`2303.wav`](https://assets.mixkit.co/active_storage/sfx/2303/2303.wav) | 2.8s | [Mixkit](https://mixkit.co/free-sound-effects/bass/) | Mixkit | Mixkit Free License |
| Deep cinematic impact | [`freesound-deep-cinematic-impact.mp3`](../public/sfx/library/freesound-deep-cinematic-impact.mp3) | 6.8s | [Freesound](https://freesound.org/people/zazz.sound.design/sounds/754424/) | zazz.sound.design | CC0 1.0 |
| Braam | [`freesound-braam.mp3`](../public/sfx/library/freesound-braam.mp3) | 10s | [Freesound](https://freesound.org/people/unfa/sounds/647712/) | unfa | CC0 1.0 |
| Cinematic Impact Boom 05 | [download](https://pixabay.com/sound-effects/film-special-effects-cinematic-impact-boom-05-352465/) | 2s | [Pixabay](https://pixabay.com/sound-effects/film-special-effects-cinematic-impact-boom-05-352465/) | Universfield | Pixabay Content License |
| Bass Drop | [download](https://pixabay.com/sound-effects/musical-bass-drop-390291/) | 1s | [Pixabay](https://pixabay.com/sound-effects/musical-bass-drop-390291/) | DRAGON-STUDIO | Pixabay Content License |

## Tech: beeps, glitch, power

| Sound | File | Duration | Source | Author | License |
|---|---|---|---|---|---|
| Glitch 001 | [`kenney-glitch-001.ogg`](../public/sfx/library/kenney-glitch-001.ogg) | <0.1s | [Kenney Interface Sounds](https://kenney.nl/assets/interface-sounds) | Kenney | CC0 1.0 |
| Phaser up 1 | [`kenney-phaserup1.ogg`](../public/sfx/library/kenney-phaserup1.ogg) | 0.5s | [Kenney Digital Audio](https://kenney.nl/assets/digital-audio) | Kenney | CC0 1.0 |
| Low down (power off) | [`kenney-lowdown.ogg`](../public/sfx/library/kenney-lowdown.ogg) | 0.8s | [Kenney Digital Audio](https://kenney.nl/assets/digital-audio) | Kenney | CC0 1.0 |
| Glitch static | [`1457.wav`](https://assets.mixkit.co/active_storage/sfx/1457/1457.wav) | 1.4s | [Mixkit](https://mixkit.co/free-sound-effects/glitch/) | Mixkit | Mixkit Free License |
| Positive interface beep | [`221.wav`](https://assets.mixkit.co/active_storage/sfx/221/221.wav) | 0.6s | [Mixkit](https://mixkit.co/free-sound-effects/beep/) | Mixkit | Mixkit Free License |
| Glitch sfx | [download](https://pixabay.com/sound-effects/film-special-effects-glitch-sfx-312910/) | 2s | [Pixabay](https://pixabay.com/sound-effects/film-special-effects-glitch-sfx-312910/) | Kave_msri | Pixabay Content License |

## Money and games

| Sound | File | Duration | Source | Author | License |
|---|---|---|---|---|---|
| Chips collide 1 | [`kenney-chips-collide.ogg`](../public/sfx/library/kenney-chips-collide.ogg) | 0.3s | [Kenney Casino Audio](https://kenney.nl/assets/casino-audio) | Kenney | CC0 1.0 |
| Chips stack 1 | [`kenney-chips-stack.ogg`](../public/sfx/library/kenney-chips-stack.ogg) | 0.3s | [Kenney Casino Audio](https://kenney.nl/assets/casino-audio) | Kenney | CC0 1.0 |
| Chip lay 1 | [`kenney-chip-lay.ogg`](../public/sfx/library/kenney-chip-lay.ogg) | 0.2s | [Kenney Casino Audio](https://kenney.nl/assets/casino-audio) | Kenney | CC0 1.0 |
| Card slide 1 | [`kenney-card-slide.ogg`](../public/sfx/library/kenney-card-slide.ogg) | 0.6s | [Kenney Casino Audio](https://kenney.nl/assets/casino-audio) | Kenney | CC0 1.0 |
| Dice throw 1 | [`kenney-dice-throw.ogg`](../public/sfx/library/kenney-dice-throw.ogg) | 0.6s | [Kenney Casino Audio](https://kenney.nl/assets/casino-audio) | Kenney | CC0 1.0 |
| Clinking coins | [`1993.wav`](https://assets.mixkit.co/active_storage/sfx/1993/1993.wav) | 1s | [Mixkit](https://mixkit.co/free-sound-effects/coin/) | Mixkit | Mixkit Free License |
| Cash Register (Kaching) | [download](https://pixabay.com/sound-effects/film-special-effects-cash-register-kaching-sound-effect-125042/) | 3s | [Pixabay](https://pixabay.com/sound-effects/film-special-effects-cash-register-kaching-sound-effect-125042/) | Modestas123123 | Pixabay Content License |

## People: applause, snaps

| Sound | File | Duration | Source | Author | License |
|---|---|---|---|---|---|
| Applause (large hall) | [`oga-applause-church.wav`](../public/sfx/library/oga-applause-church.wav) | 39.1s | [OpenGameArt](https://opengameart.org/content/applause-in-a-large-hall-or-church) | eXpl0it3r | CC0 1.0 |
| Small group cheer and applause | [`518.wav`](https://assets.mixkit.co/active_storage/sfx/518/518.wav) | 10.6s | [Mixkit](https://mixkit.co/free-sound-effects/applause/) | Mixkit | Mixkit Free License |
| Concert applause | [`freesound-applause-concert.mp3`](../public/sfx/library/freesound-applause-concert.mp3) | 32.1s | [Freesound](https://freesound.org/people/thaighaudio/sounds/478415/) | thaighaudio | CC0 1.0 |
| Applause | [download](https://pixabay.com/sound-effects/people-applause-236785/) | 8s | [Pixabay](https://pixabay.com/sound-effects/people-applause-236785/) | Driken5482 | Pixabay Content License |
| Finger Snap | [download](https://pixabay.com/sound-effects/film-special-effects-finger-snap-sound-423220/) | 1s | [Pixabay](https://pixabay.com/sound-effects/film-special-effects-finger-snap-sound-423220/) | SoundReality | Pixabay Content License |

## Ambience loops

| Sound | File | Duration | Source | Author | License |
|---|---|---|---|---|---|
| Rain on window (loop) | [`oga-rain-window.wav`](../public/sfx/library/oga-rain-window.wav) | 10.9s | [OpenGameArt](https://opengameart.org/content/rain-on-window-loop) | alxl | CC0 1.0 |
| Forest ambience (loop) | [`oga-forest.mp3`](../public/sfx/library/oga-forest.mp3) | 44.7s | [OpenGameArt](https://opengameart.org/content/forest-ambience) | TinyWorlds | CC0 1.0 |
| Sci-fi city (loop) | [`oga-scifi-city.mp3`](../public/sfx/library/oga-scifi-city.mp3) | 29.4s | [OpenGameArt](https://opengameart.org/content/scifi-city-ambient-loop) | TinyWorlds | CC0 1.0 |
| Ambient loop 01 (rubberduck) | [`oga-loop-ambient1.ogg`](../public/sfx/library/oga-loop-ambient1.ogg) | 8.2s | [OpenGameArt](https://opengameart.org/content/30-cc0-sfx-loops) | rubberduck | CC0 1.0 |
| Office ambience | [`447.wav`](https://assets.mixkit.co/active_storage/sfx/447/447.wav) | 42.1s | [Mixkit](https://mixkit.co/free-sound-effects/office/) | Mixkit | Mixkit Free License |
| City traffic ambience | [`2930.wav`](https://assets.mixkit.co/active_storage/sfx/2930/2930.wav) | 1m 7s | [Mixkit](https://mixkit.co/free-sound-effects/city/) | Mixkit | Mixkit Free License |
| Light rain loop | [`2393.wav`](https://assets.mixkit.co/active_storage/sfx/2393/2393.wav) | 15s | [Mixkit](https://mixkit.co/free-sound-effects/rain/) | Mixkit | Mixkit Free License |
| Morning birds | [`2472.wav`](https://assets.mixkit.co/active_storage/sfx/2472/2472.wav) | 3m 30s | [Mixkit](https://mixkit.co/free-sound-effects/nature/) | Mixkit | Mixkit Free License |
| Cafe ambience | [`freesound-ambience-cafe.mp3`](../public/sfx/library/freesound-ambience-cafe.mp3) | 6m 20s | [Freesound](https://freesound.org/people/samyi/sounds/382314/) | samyi | CC0 1.0 |
| Forest bird | [`freesound-forest-bird.mp3`](../public/sfx/library/freesound-forest-bird.mp3) | 34.6s | [Freesound](https://freesound.org/people/sama66/sounds/462137/) | sama66 | CC0 1.0 |
| Birds Forest Nature | [download](https://pixabay.com/sound-effects/nature-birds-forest-nature-445379/) | 1m 49s | [Pixabay](https://pixabay.com/sound-effects/nature-birds-forest-nature-445379/) | SoundReality | Pixabay Content License |

## Cartoon and magic

| Sound | File | Duration | Source | Author | License |
|---|---|---|---|---|---|
| Fairy magic sparkle | [`871.wav`](https://assets.mixkit.co/active_storage/sfx/871/871.wav) | 1.3s | [Mixkit](https://mixkit.co/free-sound-effects/magic/) | Mixkit | Mixkit Free License |

## Paper and pages

| Sound | File | Duration | Source | Author | License |
|---|---|---|---|---|---|
| Book page flip 2 | [`oga-book-flip.ogg`](../public/sfx/library/oga-book-flip.ogg) | 1.1s | [OpenGameArt](https://opengameart.org/content/10-book-page-flips) | StarNinjas | CC0 1.0 |
| Book page flip 5 | [`oga-book-flip5.ogg`](../public/sfx/library/oga-book-flip5.ogg) | 0.9s | [OpenGameArt](https://opengameart.org/content/10-book-page-flips) | StarNinjas | CC0 1.0 |
| Page turn single | [`1104.wav`](https://assets.mixkit.co/active_storage/sfx/1104/1104.wav) | 0.5s | [Mixkit](https://mixkit.co/free-sound-effects/page-turn/) | Mixkit | Mixkit Free License |

## Camera

| Sound | File | Duration | Source | Author | License |
|---|---|---|---|---|---|
| Camera shutter click | [`1133.wav`](https://assets.mixkit.co/active_storage/sfx/1133/1133.wav) | 0.4s | [Mixkit](https://mixkit.co/free-sound-effects/camera/) | Mixkit | Mixkit Free License |

## Keyboard

| Sound | File | Duration | Source | Author | License |
|---|---|---|---|---|---|
| Keyboard typing | [`1386.wav`](https://assets.mixkit.co/active_storage/sfx/1386/1386.wav) | 26.3s | [Mixkit](https://mixkit.co/free-sound-effects/keyboard/) | Mixkit | Mixkit Free License |

## Stings and jingles

| Sound | File | Duration | Source | Author | License |
|---|---|---|---|---|---|
| Jingle Pizzicato 00 | [`kenney-jingle-pizzi00.ogg`](../public/sfx/library/kenney-jingle-pizzi00.ogg) | 0.5s | [Kenney Music Jingles](https://kenney.nl/assets/music-jingles) | Kenney | CC0 1.0 |
| Jingle Pizzicato 07 | [`kenney-jingle-pizzi07.ogg`](../public/sfx/library/kenney-jingle-pizzi07.ogg) | 1.3s | [Kenney Music Jingles](https://kenney.nl/assets/music-jingles) | Kenney | CC0 1.0 |
| Jingle Steel 00 | [`kenney-jingle-steel00.ogg`](../public/sfx/library/kenney-jingle-steel00.ogg) | 0.9s | [Kenney Music Jingles](https://kenney.nl/assets/music-jingles) | Kenney | CC0 1.0 |
| Jingle Steel 07 | [`kenney-jingle-steel07.ogg`](../public/sfx/library/kenney-jingle-steel07.ogg) | 1.6s | [Kenney Music Jingles](https://kenney.nl/assets/music-jingles) | Kenney | CC0 1.0 |
| Jingle Sax 00 | [`kenney-jingle-sax00.ogg`](../public/sfx/library/kenney-jingle-sax00.ogg) | 0.4s | [Kenney Music Jingles](https://kenney.nl/assets/music-jingles) | Kenney | CC0 1.0 |
| Movie logo intro impact | [`2900.wav`](https://assets.mixkit.co/active_storage/sfx/2900/2900.wav) | 9s | [Mixkit](https://mixkit.co/free-sound-effects/logo/) | Mixkit | Mixkit Free License |
| Transition (hit + whoosh) | [`freesound-transition-hit.mp3`](../public/sfx/library/freesound-transition-hit.mp3) | 4s | [Freesound](https://freesound.org/people/xkeril/sounds/736852/) | xkeril | CC0 1.0 |
| Logo Reveal | [download](https://pixabay.com/sound-effects/film-special-effects-logo-reveal-199582/) | 3s | [Pixabay](https://pixabay.com/sound-effects/film-special-effects-logo-reveal-199582/) | Universfield | Pixabay Content License |