persian-motion-director skill

---
name: persian-motion-director
description: Direct and build professional motion design (promo and launch films, kinetic typography, animated explainers, social clips, title sequences) with correct Persian/Farsi and right-to-left typography, in Remotion or plain web code. Use this skill whenever the user wants a video, animation, motion graphics, teaser or animated text that contains Persian, Farsi, Arabic-script or RTL text, and whenever they say a motion piece looks "default", "like a slideshow", "AI-made" or "not pro", or that the Persian looks off, broken or disconnected, even if they never say "motion design". It brings the anti-slideshow method (one camera, objects that carry across scenes, music-first beat-locked edits), eight ready techniques with live sketches, HarfBuzz tooling for per-letter and per-dot Persian animation, kashida stretching, and a Persian correctness checklist and linter.
---

# Persian Motion Director

You are directing, not just animating. Most generated motion fails in two predictable ways: it plays like a slideshow (scenes that fade into each other, one ease-in-out on everything, everything arriving at once), and its Persian is broken (letters split apart, dots clipped, Arabic letters and digits, missing half-spaces, left-to-right reveals). This skill fixes both. The method comes from how professional motion designers describe their own work on X; the Persian rules come from W3C's Arabic & Persian Layout Requirements and were checked in Chrome (the engine Remotion renders with).

## The director's loop

Work in this order. Each step exists because skipping it is how pieces end up looking default.

1. **Read the brief and fill only real gaps.** Copy (Persian and any Latin), length, aspect ratio, brand colours and fonts, where it will be posted, music. If a brand exists, use its palette and fonts instead of inventing one.
2. **Show directions before building.** Motion is subjective and expensive to redo. Pick 6–10 techniques from the library below that fit the brief, open `assets/sketches/gallery.html` (or render the clips) and let the user choose. Rework after a full build costs ten times more than a pick list.
3. **Music first.** Lock the track and its tempo before animating. Build a bar map: which section lives on which bars. If there's no track, compose one (`assets/music/compose_shur_pulse.py` is a working example that writes `beats.json`) or ask for one. At 120 BPM one beat is 0.5 s and one bar 2 s; at 60 fps a beat is 30 frames.
4. **Write the shot list on the bar grid** (template in `references/workflow.md`). Every section change lands on a downbeat; every cut on a beat or 2 frames before it.
5. **Style frames.** Render 4–6 stills (`assets/remotion/render-stills.mjs`) and get a yes before animating everything.
6. **Build** in Remotion with one camera container and shared objects (see `assets/remotion/src/intro/Intro.tsx` for a complete worked example).
7. **Check**, then render: run `scripts/lint_persian.py` on all copy, review stills at full size for clipped dots and broken joins, scrub every cut against the beat, and make loops exact (clip length = a whole number of loops).

## What separates pro motion from a slideshow

| Slideshow habit | What to do instead |
|---|---|
| Scenes chained with fade transitions | One camera travels between scenes, or one object carries into the next scene. Never `fade()` scene to scene. |
| The same ease-in-out on everything | Each move gets its own curve. Entrances: `bezier(.16,1,.3,1)` over ~20 frames. Exits: `bezier(.7,0,.84,0)` over ~8 frames, travelling only ~70% as far. |
| Everything arrives together, evenly spaced | One lead element, the rest 2–4 frames behind, spaced on a curve rather than evenly. |
| Remotion's default bouncy `spring()` (overshoots ~16%) | Under 2% overshoot on UI, none on text: stiffness 100 / damping 16 gives ~1.5%. |
| Music laid on at the end | Music first; cuts on the beat; sound attacks placed on the visual hits. |
| Centered text on a gradient, logo at the end | Show the real product doing a real task in the first 10 seconds. |
| Freezes, or motion that never pauses | Hold long enough to read; only the camera breathes (zoom 1.00 → 1.04 per scene). |
| Grain, halftone or ASCII as a finish | Texture only with a physical reason (paper, print, light). These finishes are now the AI default. |

More numbers and the sources behind them: `references/anti-slideshow.md`.

## Persian non-negotiables

Read `references/persian-typography.md` before writing any Persian into a frame. The short version:

1. **Never put Persian letters in their own boxes.** `inline-block` spans, flex children (including direct children of Remotion's `<AbsoluteFill>`, which is a flex box) and any per-letter transform draw each letter in its isolated form. Animate whole words or lines. When you truly need per-letter or per-dot motion, use shaped outlines (`scripts/shape_persian.py`) or zero-width-joiner splitting (`scripts/split_fa.js`).
2. **Fade words, not letters.** Joined letters overlap; per-letter opacity or see-through text colour leaves seams at every join.
3. **Masks need slack.** Persian reaches far above and below Latin: pad clip masks by about 0.5em top and bottom, use line-height ≥ 1.6 (≥ 2.4 for Nastaliq), or the dots and the top of گ get cut.
4. **Direction.** `dir="rtl" lang="fa"` on every Persian block; wrap Latin names and numbers in `<bdi>` (or FSI/PDI) or the line scrambles. Reveals and staggers start on the right, camera progress travels left, "next" arrows point left. Play buttons, clocks and numbers are never mirrored.
5. **Characters.** Persian ی (U+06CC) and ک (U+06A9), never Arabic ي/ك; Persian digits ۰–۹ (U+06F0–06F9), never Arabic-Indic ٠–٩; the half-space (ZWNJ, U+200C) in می‌, ‑ها, ‑تر/‑ترین; punctuation ، ؛ ؟ « ». `scripts/lint_persian.py` catches these.