/persian-motion-director

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. 6. **No letter-spacing.** Chrome ignores it inside Persian words (since version 137) and other tools break the joins. Stretch with kas