Skill

---
name: remotion-ad-video
description: >
  Build product/SaaS ad videos and motion-graphics promos AS CODE (Remotion + React),
  with frame-precise music beat-sync, synthesized SFX, per-scene segment exports, and
  a visual-QC loop on rendered frames. Use this skill whenever the user wants to create
  a promo video, product ad, launch video, motion-design commercial, "סרטון פרסומת",
  "פרסומת SaaS", "סרטון תדמית", animated explainer built from UI screenshots, or asks
  to sync a video to music / "להתאים את הסרטון לביט". Also use when iterating on an
  existing Remotion ad (feedback rounds with timestamps), when adding a soundtrack
  to any Remotion composition, or when **translating / localizing an existing ad to
  another language** — "תרגם את הסרטון לאנגלית", swapping copy, currency and idiom,
  and flipping RTL↔LTR layout. Works for any brand — brand tokens are inputs, not part
  of the method.
---

# Remotion Ad Video — הפרסומת כקוד

A method for producing premium ad videos entirely in code. The video is a React
composition: every frame is deterministic, every client note is a one-line edit plus a
re-render, and music sync is exact because timing lives in numbers, not on a timeline.

Built and battle-tested across ~19 feedback iterations on a real 77s SaaS ad.

## Why code and not an editor

- **Iteration speed**: "change the title at 0:54" = edit one string, render, done.
- **Determinism**: `useCurrentFrame()` + `interpolate`/`spring` only. Never CSS
  animations, never `Date.now()`/`Math.random()` (use Remotion's seeded `random()`).
- **Beat-sync**: when scene durations are integers derived from the track's BPM, the
  cut lands on the beat every single render.
- **Versioning**: v1…vN are just renders of git-diffable code.

## The workflow

### Phase 0 — Intake (one round of questions, then build)
Collect: brand tokens (colors, fonts, logo), real UI screenshots/recordings, mascots
if any, target length, aspect, where it will run. Create TWO folders: one the user
uploads materials into, one for deliverables. Number outputs `v1, v2…` — never
overwrite a version the user has seen.

### Phase 1 — Ideas before pixels
Deliver a written list of **50 frame ideas** grouped by category (hook / product-demo
/ data / social-proof / closer). Let the user pick; you keep creative freedom inside
their picks. This costs minutes and prevents building the wrong film.

### Phase 2 — Scene skeleton
One file per scene, a master `SCENES = [{comp, dur}]` array, cumulative bounds,
transitions drawn at boundaries, and a `makeSceneSegment(i)` factory so every scene
also exports standalone (no transitions) for social cutdowns. Register master +
segments in Root. See [references/remotion-patterns.md](references/remotion-patterns.md)
for the exact component patterns (typed titles, split titles, chat bubbles, KPI
counters, screen stacks, cursor+click, camera flyovers, SFX arrays).

### Phase 3 — The feedback loop (this is most of the project)
The user reviews a render and sends timestamped notes ("ב-0:45 המעבר מהר מדי").
For each note: locate the scene via the bounds table → edit → re-render master +
ONLY the changed segments → **QC on rendered frames** → open the file for the user
→ record the round in memory. Never claim a fix without frame evidence (below).

### Phase 4 — Music (after picture is roughly locked)
Two-stage: the user generates groove candidates (Suno or any source) — do NOT fight
the generator for a structured intro; **build the intro yourself from the track's own
audio** (sample a hit from the drop). Then quantize all scene durations to the beat
grid and re-render. Full recipe + runnable scripts:
[references/beat-sync.md](references/beat-sync.md), `scripts/beat_sync.py`,
`scripts/build_soundtrack.py`.

### Phase 5 — Lock
Final pass: brand font on headings, fade-out aligned to a musical phrase, refresh ALL
segments, update memory with the version ledger.

### Phase 6 — Localization (optional — translate to another language)
Route every string and every direction-sensitive choice through a one-line `LANG`
switch instead of forking the project — then flipping one constant re-renders the whole
film in the new language, layout direction and all. Translate meaning + idiom (not word
for word), localize currency/dates/numbers, keep brand names in their canonical script,
flip RTL↔LTR via logical CSS + mirrored chat bubbles + flipped chevrons (but charts
still rise left→right), and **translate the embedded UI screenshots too** (rebuild HTML
mockups in the target language and re-shoot at identical dimensions — parallelize with
one subagent per screen). Keep scene durations identical so the beat-sync survives
untouched. Full recipe: [references/localization.md](references/localization.md).

## Non-negotiables (learned the hard way)

1. **RTL growth charts still rise left→right.** A right-to-left line reads as decline.
2. **Copy is sacred.** Apply the client's exact wording character-for-character; if you
   suspect a typo, apply your best guess and FLAG it in the summary — never silently
   rewrite.
3. **Brand names stay in their canonical script** (e.g. English product names inside
   Hebrew sentences) — ask once, then persist the rule.
4. **No invented data** in KPI/demo scenes for a real brand — plausible neutral demo
   numbers only, approved style.
5. **Soft SFX only, synthesized, few.** Loud stock "risers/booms" get rejected. A
   typing tick, a low sine thump, a filtered-noise swipe, a quiet click cover 95% of
   needs. Recipes in [references/beat-sync.md](references/beat-sync.md#sfx).
6. **Everything lands on the beat grid** once music exists — element pop-ins, clicks,
   transitions. A 3-frame miss (~100ms) is audible; compute, don't eyeball.
7. **One visual language**: pick 1-2 motifs (e.g. typewriter titles + marker
   underline) and repeat them everywhere; model them as shared components so a style
   note updates the whole film.

## Visual QC — prove it, don't assume it

After every render, verify the actual output file:

```bash
# extract frames at the timestamps you changed
$FFMPEG -y -ss 44.5 -i out.mp4 -frames:v 1 f1.png
# build a contact sheet with PIL and LOOK at it (Read tool)
```

- Text change → frame at that moment shows the new text.
- Motion complaint → pixel-diff two frames (`ImageChops.difference(...).mean()`):
  equal diffs before/after = uniform pace; ~0 = frozen background.
- Audio events → decode to wav, check RMS in 100ms windows at expected hit times and
  silence in the gaps; check the fade actually reaches ~0 at the last frame.

Playwright's bundled ffmpeg has no H.264 — use the `imageio_ffmpeg` binary for all
conversions and frame extraction.

## Iteration etiquette

- Render master + only changed segments; full segment refresh only at style-wide
  changes (font swap) or at lock.
- Long renders run in the background; report what changed while it runs.
- Open the deliverable automatically when done; lead the summary with what the user
  asked for, in their terms, with the QC evidence.
- Keep a version ledger (what changed in each v) in persistent memory/notes — clients
  refer back ("תחזיר את מה שהיה ב-v12").