creator-editing-studio 1.3.5 → 1.3.7

package/template/CLAUDE.md

@@ -33,6 +33,14 @@ out/               finished renders.
 - `npm run ramp -- <clip> --ramp "3-5:1->0.4"` — eased speed ramps
 - `npm run sync -- <a> <b>` — line up a second angle or a separate mic
 - `npm run refstyle -- <reference clip>` — measure a reference edit's pacing and colour
+- `npm run refmotion -- <reference clip>` — study HOW a reference moves and sounds: every move's speed-up and
+  settle, the holds between moves, every cut, every frame across each transition (strips to look at),
+  standout sounds and how far they lead the picture, plus a spectrogram of the sound. Run it on any clip
+  the person shares as a reference, then LOOK at the strips and spectrogram before planning — numbers
+  alone do not show how one scene turns into the next.
+- `python scripts/track_head.py <clip> <first> <last> <out.json> --check <img>` — motion tracking: where the head
+  is, frame by frame (only when asked; see "Motion tracking" below)
+- `python scripts/setup_models.py --language <code>` — (re)install the models for a video language
 - `npm run stills -- <Comp> --every=45` — many stills at once, with contact sheets
 - `npm run check` — typecheck plus motion lint. Must pass.
 - `npm run motion-check -- <Comp> --scale=2` — frame-by-frame POP / CUT / STUTTER detection
@@ -83,6 +91,11 @@ that is when people can actually name what they like.
 Then transcribe with word-level timings. **The transcript is the truth, not the script and not
 what they remember saying.**
 
+The language comes from setup (`studio.config.json`; the transcriber and aligner read it). For Indian
+languages and Hinglish, **ask for the script or captions file first** and match it to the audio
+(`python scripts/align-script.py <media> <script.srt> --whole`) — matching known words beats recognising
+them, especially in code-mixed speech. Recognise only when there is no script.
+
 ### 2. The first cut, before the plan
 
 Cut the silence, the filler and the retakes first. This is mechanical — no design decisions in
@@ -116,6 +129,31 @@ what stops motion graphics drifting into generic.
 Then stop and ask: *here is the plan, change anything that is off, say go ahead and I will cut
 it.* Wait for a yes. "Go ahead", "yes", "approved", "ship it" is a yes. Silence is not.
 
+### 4. The live preview — after the yes, before any render
+
+Once they approve, build the edit and **open the live preview yourself** — `preview_edit({video})`. They must
+never have to ask for it, and never get a draft MP4 instead of it. It plays the edit in the chat with instant
+controls (size, position, timing, sound, icon, follow head) that cost no messages; see `preview/README.md` for
+what each video needs (`preview.tsx`, `TweaksProvider`).
+
+- A change typed in the preview arrives as a chat message: change only that beat, then call `preview_edit`
+  again so the updated preview opens below. **Undo** = `preview_undo`, then `preview_edit`.
+- **Save** and **Render** arrive as one message each, carrying their adjustments as JSON for the video's
+  `tweaks.json` — write it exactly.
+- Render only when they press **Render final video**, and give the estimated render time only then.
+- If the preview tool is missing (not switched on yet), say so in one line and fall back to rendering with
+  the time estimate. Never send them off to fix it mid-edit.
+
+### Motion tracking — only when asked
+
+Text or graphics can ride with the speaker's head. **Never a default** — use it when they ask ("make the title
+follow my head") or press **Follow head** in the preview. Track only the stretch that needs it:
+`python scripts/track_head.py <clip> <first source frame> <last source frame> src/videos/<video>/head-track.json
+--check work/<video>/track-check.jpg` (≈1 minute per 5 seconds), and **look at the check image** — the box must
+sit on the face in every tile — before using it. Then either pin a graphic with `<HeadPin>`
+(`src/components/HeadPin.tsx`) or turn on `follow` for the beat. A wide line will not fit above a head: split
+it. It takes half the head's tilt and trails two frames — attached, not glued.
+
 ### Keep it proportionate
 
 The plan is there to save them a rebuild, not to put a form in front of them.
@@ -240,260 +278,260 @@ preserves the damage rather than repairing it. It is clearly audible and it gets
 every extra render. Use `node scripts/voice.mjs` to pull the voice losslessly from the camera
 file, render the picture muted, and mux the two together at the end.
 
-## Non-negotiables
-
-1. **No magic numbers.** Durations, curves, springs, staggers, blur come from `src/design/motion.ts`.
-   Colours, fonts, sizes, spacing come from `src/design/tokens.ts`. If a needed token does not
-   exist, add it to the token file (with a comment) instead of inlining a value.
-2. **Timing derives from the spine.** Animation start frames come from word timestamps, beats,
-   or other elements' timings via helpers — never hand-typed frame numbers.
-3. **`npm run check` and `motion-check --scale=2` must pass** before any render is shown to the user.
-4. **Verify visually before claiming done** (see Verification). Never say something "looks good"
-   without having rendered and viewed the frames.
-
+## Non-negotiables
+
+1. **No magic numbers.** Durations, curves, springs, staggers, blur come from `src/design/motion.ts`.
+   Colours, fonts, sizes, spacing come from `src/design/tokens.ts`. If a needed token does not
+   exist, add it to the token file (with a comment) instead of inlining a value.
+2. **Timing derives from the spine.** Animation start frames come from word timestamps, beats,
+   or other elements' timings via helpers — never hand-typed frame numbers.
+3. **`npm run check` and `motion-check --scale=2` must pass** before any render is shown to the user.
+4. **Verify visually before claiming done** (see Verification). Never say something "looks good"
+   without having rendered and viewed the frames.
+
 ---
 
-## The 12 motion laws
-
-1. **No linear easing** — except constant-velocity loops/scrolls (mark with `// motion-ok`).
-2. **Entrances ease-out (`EASE.out`), exits ease-in (`EASE.in`), on-screen A-to-B moves ease-in-out (`EASE.inOut`).**
-3. **Exits are faster than entrances** — `EXIT_RATIO` (0.65). Use `exitFrames()`.
-4. **Max 2–3 animated properties per element.** No fade + scale + rotate + blur together.
-5. **Never opacity alone.** Pair with 8–24px travel or scale >= 0.94. Opacity completes at
-   `OPACITY_LEAD` (60%) of the transform.
-6. **Never scale from below 0.9.** Text scaling from zero is the #1 AI-edit tell.
-7. **Blur-in capped at 12px**, fully resolved before the transform ends.
-8. **Groups always stagger** (`STAGGER.tight/normal/dramatic`). Never simultaneous.
-9. **Distance couples to duration sub-linearly** (`travelFrames()`), never linearly.
-10. **Anything that moves fast is motion-blurred** (see Smoothness system). No hard edge may jump
-    across the frame unblurred.
-11. **Readable hold:** text stays fully visible >= `readFrames(text)` (min 0.9s, +55ms/word).
-12. **Continuity:** every transition inherits the outgoing motion (see below).
-
-### Continuity (what makes it feel connected, not cut together)
-
-- **Shared elements never re-enter.** If an element exists across two beats, `morph()` its
-  position/size/radius between layouts; never exit and re-animate it. (TransitionTest: the
-  eyebrow dot stays on screen and grows into the next card's icon tile.)
-- **Velocity handoff.** An exit toward a direction is answered by an entrance continuing that
-  direction — `handoff(exitTo)`.
-- **Overlap, never gap.** The next beat starts before the previous one settles —
-  `nextBeatAt(prevSettled)`.
-- **One camera over cuts.** Lay scenes out on one canvas and glide a camera between them
-  (`src/lib/camera.ts`) instead of hard-cutting between unrelated layouts. Content that should
-  stay put during a move (shared elements) lives in screen space, outside the camera.
-- **Nothing is cut off.** Compute exit start times backward from the end so the slowest,
-  most-staggered exit completes on or before the last frame.
-- **Sound glues cuts.** Whooshes start `TRANSITION.sfxLeadMs` before a visual change and tail
-  `sfxTailMs` after.
-
+## The 12 motion laws
+
+1. **No linear easing** — except constant-velocity loops/scrolls (mark with `// motion-ok`).
+2. **Entrances ease-out (`EASE.out`), exits ease-in (`EASE.in`), on-screen A-to-B moves ease-in-out (`EASE.inOut`).**
+3. **Exits are faster than entrances** — `EXIT_RATIO` (0.65). Use `exitFrames()`.
+4. **Max 2–3 animated properties per element.** No fade + scale + rotate + blur together.
+5. **Never opacity alone.** Pair with 8–24px travel or scale >= 0.94. Opacity completes at
+   `OPACITY_LEAD` (60%) of the transform.
+6. **Never scale from below 0.9.** Text scaling from zero is the #1 AI-edit tell.
+7. **Blur-in capped at 12px**, fully resolved before the transform ends.
+8. **Groups always stagger** (`STAGGER.tight/normal/dramatic`). Never simultaneous.
+9. **Distance couples to duration sub-linearly** (`travelFrames()`), never linearly.
+10. **Anything that moves fast is motion-blurred** (see Smoothness system). No hard edge may jump
+    across the frame unblurred.
+11. **Readable hold:** text stays fully visible >= `readFrames(text)` (min 0.9s, +55ms/word).
+12. **Continuity:** every transition inherits the outgoing motion (see below).
+
+### Continuity (what makes it feel connected, not cut together)
+
+- **Shared elements never re-enter.** If an element exists across two beats, `morph()` its
+  position/size/radius between layouts; never exit and re-animate it. (TransitionTest: the
+  eyebrow dot stays on screen and grows into the next card's icon tile.)
+- **Velocity handoff.** An exit toward a direction is answered by an entrance continuing that
+  direction — `handoff(exitTo)`.
+- **Overlap, never gap.** The next beat starts before the previous one settles —
+  `nextBeatAt(prevSettled)`.
+- **One camera over cuts.** Lay scenes out on one canvas and glide a camera between them
+  (`src/lib/camera.ts`) instead of hard-cutting between unrelated layouts. Content that should
+  stay put during a move (shared elements) lives in screen space, outside the camera.
+- **Nothing is cut off.** Compute exit start times backward from the end so the slowest,
+  most-staggered exit completes on or before the last frame.
+- **Sound glues cuts.** Whooshes start `TRANSITION.sfxLeadMs` before a visual change and tail
+  `sfxTailMs` after.
+
 ---
 
-## Smoothness system (every one of these was a real defect found by motion-check)
-
-- **Use the components, not raw transforms.** `<Presence>`, `<MaskReveal>`, `<HighlightMark>`,
-  `<RollingNumber>` add velocity motion blur automatically. Anything else that moves wraps its
-  moving element in `<VelocityBlur vx vy>` with `perFrame()` velocities.
-- **Velocity motion blur** (`VelocityBlur`): directional blur sized to this frame's movement with
-  a 180-degree shutter; fades to zero as the element settles. Near-free to render.
-- **Wipes** use `wipeMask(p, perFrame(...))`: the leading edge softens with speed. Never wipe with
-  a hard `clipPath` edge.
-- **Camera moves**: wrap the camera canvas in a full-frame `VelocityBlur` with `bleed={0}` and
-  `overflow: hidden`, velocity from `cameraShot` (see TransitionTest).
-- **Zooms / rotations** (not translations): use `<MotionBlur active>` (temporal sampling, centred
-  on the frame so toggling it never shifts timing). It costs 10x render time while active —
-  enable only during the move. Never use `@remotion/motion-blur`'s `CameraMotionBlur`: it samples
-  ahead of the frame, so switching it on/off causes a timing hitch.
-- **Counters roll, never tick.** Use `<RollingNumber>`. A counting number changes glyphs in single
-  frames as it slows, which motion-check flags as pops.
-- **Never `will-change`.** It makes each parallel render tab cache text at a different sub-pixel
-  position, so settled elements flicker between 4 versions. (Lint enforces this.)
-- **Screen recordings used as b-roll usually scroll in steps** (they judder). Use a still frame with a
-  smooth `ScreenView` pan instead, and blur names on the still.
-- **Presence `dur` sets entrance AND exit length.** `dur="instant"` makes exits last 3 frames (a snap) —
-  for containers that only fade in, use at least `"base"`.
-- **Final renders are supersampled at `--scale=2`**, then downscaled to 1080x1920. At 1x, Chrome
-  snaps text to whole pixels, so the slow tail of every ease-out steps ("move 1px, hold, move 1px")
-  and motion-check reports stutters. Run motion-check with the same `--scale`.
-- **Frame rate:** match the footage. If footage is 60fps, build at 60 — per-frame jumps halve.
-  All tokens are in ms, so compositions work at either rate.
-
+## Smoothness system (every one of these was a real defect found by motion-check)
+
+- **Use the components, not raw transforms.** `<Presence>`, `<MaskReveal>`, `<HighlightMark>`,
+  `<RollingNumber>` add velocity motion blur automatically. Anything else that moves wraps its
+  moving element in `<VelocityBlur vx vy>` with `perFrame()` velocities.
+- **Velocity motion blur** (`VelocityBlur`): directional blur sized to this frame's movement with
+  a 180-degree shutter; fades to zero as the element settles. Near-free to render.
+- **Wipes** use `wipeMask(p, perFrame(...))`: the leading edge softens with speed. Never wipe with
+  a hard `clipPath` edge.
+- **Camera moves**: wrap the camera canvas in a full-frame `VelocityBlur` with `bleed={0}` and
+  `overflow: hidden`, velocity from `cameraShot` (see TransitionTest).
+- **Zooms / rotations** (not translations): use `<MotionBlur active>` (temporal sampling, centred
+  on the frame so toggling it never shifts timing). It costs 10x render time while active —
+  enable only during the move. Never use `@remotion/motion-blur`'s `CameraMotionBlur`: it samples
+  ahead of the frame, so switching it on/off causes a timing hitch.
+- **Counters roll, never tick.** Use `<RollingNumber>`. A counting number changes glyphs in single
+  frames as it slows, which motion-check flags as pops.
+- **Never `will-change`.** It makes each parallel render tab cache text at a different sub-pixel
+  position, so settled elements flicker between 4 versions. (Lint enforces this.)
+- **Screen recordings used as b-roll usually scroll in steps** (they judder). Use a still frame with a
+  smooth `ScreenView` pan instead, and blur names on the still.
+- **Presence `dur` sets entrance AND exit length.** `dur="instant"` makes exits last 3 frames (a snap) —
+  for containers that only fade in, use at least `"base"`.
+- **Final renders are supersampled at `--scale=2`**, then downscaled to 1080x1920. At 1x, Chrome
+  snaps text to whole pixels, so the slow tail of every ease-out steps ("move 1px, hold, move 1px")
+  and motion-check reports stutters. Run motion-check with the same `--scale`.
+- **Frame rate:** match the footage. If footage is 60fps, build at 60 — per-frame jumps halve.
+  All tokens are in ms, so compositions work at either rate.
+
 ---
 
-## Design rules
-
-**Read `STYLE.md` before any design decision.** It is the house style (type scale, layout, motion,
-sound, approved and rejected beats) and wins over anything below or in a reference. Update it
-whenever the user approves or rejects something.
-
-- Everything visual comes from `src/design/tokens.ts`, which is yours to define.
-- **Brand essentials:** your display typeface only, at every weight (headlines/stats 800). One accent: accent
-  `your accent` on ink and cream/white. No blue, no purple, no serif. Signature emphasis is the accent
-  marker behind the key phrase — use `<HighlightMark>`; don't invent other emphasis styles.
-  Headlines are short two-part fragments with the payoff highlighted. Numbers are shown raw and
-  bold ("$1.3M", "11x") and roll in. Eyebrows are uppercase pills with a accent-ringed dot.
-  Radii are generous, shadows soft, buttons/badges pills.
-- Secondary text uses `COLOR.fgSecondary`; `COLOR.fgMuted` fails contrast on cream — decoration only.
-- **User style decisions (first project):**
-  - Captions are **crisp white** (`CAPTION` token, tight + soft dark shadow). Never ink text with a light glow.
-    Over the cream background white is invisible, so in card layouts captions go **inside the video
-    card's bottom edge** on the card's dark scrim (`StageState.scrim`).
-  - Big headline text is **accent with a glow** (`HeroBlock` / `HeroTag`, `heroGlow()`).
-  - Pointer is a **solid accent arrow** like the reference (`Cursor`), ~68px.
-  - Brand logos are **real full-colour logos** (`LogoIcon`, SVG Logos CC0 via `src/design/logos.json` —
-    extract only the icons used). Never approximate a logo that isn't in the set; use a neutral
-    icon and ask for the official file (Klaviyo is missing).
-  - A corner tag (e.g. "11 MINUTES" pill) is removed when the video returns full screen.
-- **Text behind the subject must stay readable:** the head covers only the lower ~20–30% of the
-  headline. Head height changes shot to shot (leaning forward lifts it ~80px) — check a still of
-  EVERY hero moment and raise the block (`top`; put labels above as `eyebrow`) where needed.
-- Keep accent highlights away from the accent background glow so they don't disappear into it.
-- Stats use proportional figures, not tabular (tabular makes "11" look gappy in your display typeface).
-- **Web design systems do not map 1:1 to video.** Keep colour, font families/weights, type-scale
-  ratios, radii, spacing rhythm, iconography and imagery style — but rescale sizes for a
-  1080-wide frame viewed on a phone (body roughly 40–48px, not 16px). Web UI components mostly
-  do not apply.
-- Respect safe zones: `LAYOUT.safeTop` / `LAYOUT.safeBottom` for Reels/Shorts UI.
-- Text contrast >= 4.5:1 against whatever is behind it, including over footage.
-- Draw graphics in code (SVG/CSS) so every part can animate. Use flat images only for things
-  that must be real (logos, screenshots, photos). Avoid AI-generated imagery for anything the
-  viewer is meant to look at.
-- Icons: SVG drawn in code or an installed icon library, never image files.
-
+## Design rules
+
+**Read `STYLE.md` before any design decision.** It is the house style (type scale, layout, motion,
+sound, approved and rejected beats) and wins over anything below or in a reference. Update it
+whenever the user approves or rejects something.
+
+- Everything visual comes from `src/design/tokens.ts`, which is yours to define.
+- **Brand essentials:** your display typeface only, at every weight (headlines/stats 800). One accent: accent
+  `your accent` on ink and cream/white. No blue, no purple, no serif. Signature emphasis is the accent
+  marker behind the key phrase — use `<HighlightMark>`; don't invent other emphasis styles.
+  Headlines are short two-part fragments with the payoff highlighted. Numbers are shown raw and
+  bold ("$1.3M", "11x") and roll in. Eyebrows are uppercase pills with a accent-ringed dot.
+  Radii are generous, shadows soft, buttons/badges pills.
+- Secondary text uses `COLOR.fgSecondary`; `COLOR.fgMuted` fails contrast on cream — decoration only.
+- **User style decisions (first project):**
+  - Captions are **crisp white** (`CAPTION` token, tight + soft dark shadow). Never ink text with a light glow.
+    Over the cream background white is invisible, so in card layouts captions go **inside the video
+    card's bottom edge** on the card's dark scrim (`StageState.scrim`).
+  - Big headline text is **accent with a glow** (`HeroBlock` / `HeroTag`, `heroGlow()`).
+  - Pointer is a **solid accent arrow** like the reference (`Cursor`), ~68px.
+  - Brand logos are **real full-colour logos** (`LogoIcon`, SVG Logos CC0 via `src/design/logos.json` —
+    extract only the icons used). Never approximate a logo that isn't in the set; use a neutral
+    icon and ask for the official file (Klaviyo is missing).
+  - A corner tag (e.g. "11 MINUTES" pill) is removed when the video returns full screen.
+- **Text behind the subject must stay readable:** the head covers only the lower ~20–30% of the
+  headline. Head height changes shot to shot (leaning forward lifts it ~80px) — check a still of
+  EVERY hero moment and raise the block (`top`; put labels above as `eyebrow`) where needed.
+- Keep accent highlights away from the accent background glow so they don't disappear into it.
+- Stats use proportional figures, not tabular (tabular makes "11" look gappy in your display typeface).
+- **Web design systems do not map 1:1 to video.** Keep colour, font families/weights, type-scale
+  ratios, radii, spacing rhythm, iconography and imagery style — but rescale sizes for a
+  1080-wide frame viewed on a phone (body roughly 40–48px, not 16px). Web UI components mostly
+  do not apply.
+- Respect safe zones: `LAYOUT.safeTop` / `LAYOUT.safeBottom` for Reels/Shorts UI.
+- Text contrast >= 4.5:1 against whatever is behind it, including over footage.
+- Draw graphics in code (SVG/CSS) so every part can animate. Use flat images only for things
+  that must be real (logos, screenshots, photos). Avoid AI-generated imagery for anything the
+  viewer is meant to look at.
+- Icons: SVG drawn in code or an installed icon library, never image files.
+
 ---
 
-## Compositing: text behind the subject
-
-Layer order, bottom to top:
-
-```
-background plate (designed, or the original footage)
-  text / graphics          <- 1–3px blur to sit on the background's focal plane
-    subject cutout         <- same clip, frame-aligned
-      light wrap           <- blurred background screened onto the subject's inner edge, 15–30%
-        grain + grade      <- applied over everything so layers share one look
-```
-
-- **The cutout must come from the same clip as its background plate**, frame-aligned. Never
-  combine a cutout from one take with footage from another.
-- **The matte is built automatically from ordinary footage.** No green screen, and never ask the
-  user for one — most people have never shot against green and do not know the term. Segment the
-  subject per frame, then **temporally smooth the alpha**, which is not optional: a per-frame matte
-  shimmers along the edge, and type sitting against a head is exactly where that shows. Finish with
-  spill-free cleanup: ~0.5px choke, 0.5–1px feather.
-- **Quality is worst where it is most visible:** flyaway hair, motion blur, and a hand crossing in
-  front of the text. The light wrap below hides a good deal of it. If a shot simply will not hold,
-  say so and move the text rather than shipping a halo.
-- **If the user happens to have a background-free or green version, prefer it** — chroma keying
-  still beats automatic matting on hair. Use it **only for the alpha** and take the subject's colour
-  from the original, so no green ever reaches the edges. Verify the pair first: identical duration,
-  fps, resolution and frame count, subject aligned on the same frame (one frame out makes a ghost).
-  This is an upgrade for people who already work that way, never a requirement.
-- **Supplied cutouts** must have real transparency (ProRes 4444, WebM with alpha, or PNG sequence).
-  An MP4 cannot hold transparency — if one arrives, stop and tell the user.
-- Play transparent video with `<OffthreadVideo transparent src={staticFile(...)} />`.
-- Text behind a moving subject gets 0.85–0.95x counter-parallax; static text reads as a sticker.
-- Text should animate in while already partly occluded, not appear fully and then get covered.
-- Pull text colour toward the footage's black/white points; pure white over graded footage looks
-  pasted on.
-
+## Compositing: text behind the subject
+
+Layer order, bottom to top:
+
+```
+background plate (designed, or the original footage)
+  text / graphics          <- 1–3px blur to sit on the background's focal plane
+    subject cutout         <- same clip, frame-aligned
+      light wrap           <- blurred background screened onto the subject's inner edge, 15–30%
+        grain + grade      <- applied over everything so layers share one look
+```
+
+- **The cutout must come from the same clip as its background plate**, frame-aligned. Never
+  combine a cutout from one take with footage from another.
+- **The matte is built automatically from ordinary footage.** No green screen, and never ask the
+  user for one — most people have never shot against green and do not know the term. Segment the
+  subject per frame, then **temporally smooth the alpha**, which is not optional: a per-frame matte
+  shimmers along the edge, and type sitting against a head is exactly where that shows. Finish with
+  spill-free cleanup: ~0.5px choke, 0.5–1px feather.
+- **Quality is worst where it is most visible:** flyaway hair, motion blur, and a hand crossing in
+  front of the text. The light wrap below hides a good deal of it. If a shot simply will not hold,
+  say so and move the text rather than shipping a halo.
+- **If the user happens to have a background-free or green version, prefer it** — chroma keying
+  still beats automatic matting on hair. Use it **only for the alpha** and take the subject's colour
+  from the original, so no green ever reaches the edges. Verify the pair first: identical duration,
+  fps, resolution and frame count, subject aligned on the same frame (one frame out makes a ghost).
+  This is an upgrade for people who already work that way, never a requirement.
+- **Supplied cutouts** must have real transparency (ProRes 4444, WebM with alpha, or PNG sequence).
+  An MP4 cannot hold transparency — if one arrives, stop and tell the user.
+- Play transparent video with `<OffthreadVideo transparent src={staticFile(...)} />`.
+- Text behind a moving subject gets 0.85–0.95x counter-parallax; static text reads as a sticker.
+- Text should animate in while already partly occluded, not appear fully and then get covered.
+- Pull text colour toward the footage's black/white points; pure white over graded footage looks
+  pasted on.
+
 ---
 
-## Per-video pipeline
-
-1. **Ingest:** probe every clip (fps, resolution, colour, alpha).
-   - **Phone footage is usually variable frame rate (VFR).** Conform it to constant frame rate
-     with ffmpeg before use, or it stutters and drifts out of sync in Remotion.
-   - Conform everything to one fps. Never mix frame rates.
-2. **Spine:** word-level timings + music beats -> `work/<video>/spine.json`.
-   Cut pauses/filler from word gaps. All animation timing reads from the spine.
-   - If the user supplies a script or SRT, it is the **text truth** (spelling, names, brand words):
-     force-align that exact text to the audio with WhisperX's aligner. Never use SRT timings
-     directly — they are line-level and padded for readability, not word-accurate.
-   - With no script, transcribe with WhisperX, then show the transcript for correction before building.
-3. **Cutouts:** build the matte from the footage automatically, or validate a supplied cutout (see above). Only needed for shots that want text behind the subject.
-4. **Beat sheet:** from the script and the user's marked punch lines, write a short plan — which
-   moment gets which treatment — and confirm with the user before building.
-   - **Read their saved references first** (`editing_os_references`). They are the whole reason
-     the edit should look like theirs rather than like the defaults, and a plan written without
-     them is a plan written for anybody. Say which reference each decision came from, so the
-     user can see their own taste being applied and correct it when it is being misread.
-   - Where references are silent, the defaults in STYLE.md apply. Where references and defaults
-     disagree, the reference wins — it is a real preference, and the default is only a sensible
-     starting point.
-5. **Build** in `src/compositions/<Video>.tsx` from components + helpers + tokens only.
-6. **Verify** (below), then show the user.
-7. **Sound:** the user adds SFX and music themselves. Deliver a cue list (timestamps of every
-   transition and hit, with suggested whoosh start = `TRANSITION.sfxLeadMs` before the change) so
-   they can place sounds quickly. Render without music unless asked.
-8. **Render** at `--scale=2`, downscaled to 1080x1920 unless told otherwise.
-
+## Per-video pipeline
+
+1. **Ingest:** probe every clip (fps, resolution, colour, alpha).
+   - **Phone footage is usually variable frame rate (VFR).** Conform it to constant frame rate
+     with ffmpeg before use, or it stutters and drifts out of sync in Remotion.
+   - Conform everything to one fps. Never mix frame rates.
+2. **Spine:** word-level timings + music beats -> `work/<video>/spine.json`.
+   Cut pauses/filler from word gaps. All animation timing reads from the spine.
+   - If the user supplies a script or SRT, it is the **text truth** (spelling, names, brand words):
+     force-align that exact text to the audio with WhisperX's aligner. Never use SRT timings
+     directly — they are line-level and padded for readability, not word-accurate.
+   - With no script, transcribe with WhisperX, then show the transcript for correction before building.
+3. **Cutouts:** build the matte from the footage automatically, or validate a supplied cutout (see above). Only needed for shots that want text behind the subject.
+4. **Beat sheet:** from the script and the user's marked punch lines, write a short plan — which
+   moment gets which treatment — and confirm with the user before building.
+   - **Read their saved references first** (`editing_os_references`). They are the whole reason
+     the edit should look like theirs rather than like the defaults, and a plan written without
+     them is a plan written for anybody. Say which reference each decision came from, so the
+     user can see their own taste being applied and correct it when it is being misread.
+   - Where references are silent, the defaults in STYLE.md apply. Where references and defaults
+     disagree, the reference wins — it is a real preference, and the default is only a sensible
+     starting point.
+5. **Build** in `src/compositions/<Video>.tsx` from components + helpers + tokens only.
+6. **Verify** (below), then show the user.
+7. **Sound:** the user adds SFX and music themselves. Deliver a cue list (timestamps of every
+   transition and hit, with suggested whoosh start = `TRANSITION.sfxLeadMs` before the change) so
+   they can place sounds quickly. Render without music unless asked.
+8. **Render** at `--scale=2`, downscaled to 1080x1920 unless told otherwise.
+
 ---
 
-## Audio standard (audio is half the reel — the user will not accept a bad mix)
-
-What went wrong on an early video: the voice itself was bit-for-bit intact (measured against the source),
-but 2.3–3.5s whoosh files and a 2.4s riser kept playing UNDER the speech, which made the voice sound
-wrong. Claude cannot hear, so the mix must be engineered and measured, never guessed.
-
-1. **The voice is never touched.** Render the picture `--muted`. The voice in every deliverable is the
-   original recording's audio (stream-copied, or at most one encode), plus only a single gain change.
-   No limiter, no dynamic normaliser (ffmpeg `loudnorm` single-pass pumps), no repeated AAC encodes.
-2. **Sound effects are short and placed in gaps.** Trim every SFX to what the motion needs (whoosh
-   0.4–0.8s, hits 0.3–0.6s) with a 60–120ms fade-out. Nothing longer than ~0.8s may sit under a spoken
-   word unless it is at least 24 dB under the voice. Risers go in pauses, not under speech.
-3. **Duck SFX under the voice**: mix with ffmpeg `sidechaincompress` keyed from the voice (SFX drop
-   ~6 dB while a word is spoken), and high-pass whooshes/impacts around 120–150 Hz so they don't muddy it.
-4. **Measure before delivering** (the window scan in the project folder used `f32le` PCM from ffmpeg):
-   voice-vs-mix difference per 0.5s window — any window where SFX energy is within 12 dB of the
-   voice while a word is spoken gets fixed. Final: -14 LUFS integrated, true peak <= -1 dBTP, one
-   AAC encode at 256k.
-5. **Always also deliver stems + a cue sheet**: `voice.wav`, `sfx.wav` (the placed, trimmed SFX bus),
-   and `SFX-CUES.txt` with numbered, timecoded SFX files — so the user can rebalance in Premiere in
-   minutes. Picture-only MP4 alongside.
-6. The user picks and judges sounds by ear; Claude says plainly that it cannot hear and asks for
-   timecoded audio notes on the first draft.
-
+## Audio standard (audio is half the reel — the user will not accept a bad mix)
+
+What went wrong on an early video: the voice itself was bit-for-bit intact (measured against the source),
+but 2.3–3.5s whoosh files and a 2.4s riser kept playing UNDER the speech, which made the voice sound
+wrong. Claude cannot hear, so the mix must be engineered and measured, never guessed.
+
+1. **The voice is never touched.** Render the picture `--muted`. The voice in every deliverable is the
+   original recording's audio (stream-copied, or at most one encode), plus only a single gain change.
+   No limiter, no dynamic normaliser (ffmpeg `loudnorm` single-pass pumps), no repeated AAC encodes.
+2. **Sound effects are short and placed in gaps.** Trim every SFX to what the motion needs (whoosh
+   0.4–0.8s, hits 0.3–0.6s) with a 60–120ms fade-out. Nothing longer than ~0.8s may sit under a spoken
+   word unless it is at least 24 dB under the voice. Risers go in pauses, not under speech.
+3. **Duck SFX under the voice**: mix with ffmpeg `sidechaincompress` keyed from the voice (SFX drop
+   ~6 dB while a word is spoken), and high-pass whooshes/impacts around 120–150 Hz so they don't muddy it.
+4. **Measure before delivering** (the window scan in the project folder used `f32le` PCM from ffmpeg):
+   voice-vs-mix difference per 0.5s window — any window where SFX energy is within 12 dB of the
+   voice while a word is spoken gets fixed. Final: -14 LUFS integrated, true peak <= -1 dBTP, one
+   AAC encode at 256k.
+5. **Always also deliver stems + a cue sheet**: `voice.wav`, `sfx.wav` (the placed, trimmed SFX bus),
+   and `SFX-CUES.txt` with numbered, timecoded SFX files — so the user can rebalance in Premiere in
+   minutes. Picture-only MP4 alongside.
+6. The user picks and judges sounds by ear; Claude says plainly that it cannot hear and asks for
+   timecoded audio notes on the first draft.
+
 ---
 
-## Verification (required before saying anything is done)
-
-Claude cannot watch video. Quality is checked with frames and maths, and the user makes the
-final call at playback speed. Be explicit about that when reporting.
-
-1. `npm run check` passes.
-2. `npm run motion-check -- <Comp> --scale=2` reports **no POP, CUT or STUTTER**. Allow intentional
-   cuts with `--allow=<frame>`. For each FAST warning, render that frame and confirm the moving
-   edge is blurred. Read the motion timeline for dead air and rhythm.
-3. Render stills and **look at them**: first frame, each element mid-entrance, peak-speed frames
-   (blur visible), fully settled (crisp), mid-exit, and the **last frame** (clean).
-4. Check: no text collides with the subject's face, safe zones respected, contrast holds,
-   no clipped descenders (g, p, y, commas) in masked text.
-5. Report what was verified and what still needs the user's eyes at full speed.
-
+## Verification (required before saying anything is done)
+
+Claude cannot watch video. Quality is checked with frames and maths, and the user makes the
+final call at playback speed. Be explicit about that when reporting.
+
+1. `npm run check` passes.
+2. `npm run motion-check -- <Comp> --scale=2` reports **no POP, CUT or STUTTER**. Allow intentional
+   cuts with `--allow=<frame>`. For each FAST warning, render that frame and confirm the moving
+   edge is blurred. Read the motion timeline for dead air and rhythm.
+3. Render stills and **look at them**: first frame, each element mid-entrance, peak-speed frames
+   (blur visible), fully settled (crisp), mid-exit, and the **last frame** (clean).
+4. Check: no text collides with the subject's face, safe zones respected, contrast holds,
+   no clipped descenders (g, p, y, commas) in masked text.
+5. Report what was verified and what still needs the user's eyes at full speed.
+
 ---
 
-## Remotion gotchas
-
-- Never use CSS `transition`/`animation` — drive everything from `useCurrentFrame()`.
-- Never use `Math.random()` — use `random(seed)` from `remotion`.
-- Never use `will-change` (render-tab flicker, see Smoothness system).
-- **`<Presence>` owns its element's `transform` and `opacity`.** Any extra transform (centring with
-  `translateX(-50%)`) or opacity (fading content) passed in `style` is silently overwritten — put it
-  on an inner wrapper. This bug appeared twice in the first project (off-centre tag, labels that
-  never faded).
-- em-based spacing (gaps, padding) resolves against the element's own font-size: set `fontSize`
-  on the container, or word gaps collapse.
-- Masked text needs travel > 100% and container padding, or descenders stay visible.
-- Load fonts through `@remotion/fonts` (brand your display typeface is local in `assets/fonts/`) so renders wait for them.
-
+## Remotion gotchas
+
+- Never use CSS `transition`/`animation` — drive everything from `useCurrentFrame()`.
+- Never use `Math.random()` — use `random(seed)` from `remotion`.
+- Never use `will-change` (render-tab flicker, see Smoothness system).
+- **`<Presence>` owns its element's `transform` and `opacity`.** Any extra transform (centring with
+  `translateX(-50%)`) or opacity (fading content) passed in `style` is silently overwritten — put it
+  on an inner wrapper. This bug appeared twice in the first project (off-centre tag, labels that
+  never faded).
+- em-based spacing (gaps, padding) resolves against the element's own font-size: set `fontSize`
+  on the container, or word gaps collapse.
+- Masked text needs travel > 100% and container padding, or descenders stay visible.
+- Load fonts through `@remotion/fonts` (brand your display typeface is local in `assets/fonts/`) so renders wait for them.
+
 ---
 
-## Feedback format from the user
-
-Notes arrive as timecode + specific issue ("0:14 title lands 3 frames late, bounce too strong").
-Translate each note into token or timing changes; if a note conflicts with a law, say so and ask.
-
+## Feedback format from the user
+
+Notes arrive as timecode + specific issue ("0:14 title lands 3 frames late, bounce too strong").
+Translate each note into token or timing changes; if a note conflicts with a law, say so and ask.
+
 ---
 
 ## What is already installed
@@ -541,3 +579,21 @@ and add its name to `templates/BRIEF.md` so it can be asked for by name next tim
 The studio gets updates. When new components, scripts or rules ship, run `editing_os_update`
 and they are written into this project alongside your own work, which is never touched.
 
+## Updating the studio
+
+New effects, fixes and rules ship as releases. The studio's release is in `.studio.json`. To update,
+run this inside the studio folder — add `--dry-run` first to see what it would do:
+
+```bash
+npx creator-editing-studio@latest update
+```
+
+It never touches `src/design/tokens.ts`, your videos or your footage. Every other file is sorted:
+files you never edited are replaced, files you edited are kept, and a file that both you and the
+release changed is left exactly as it is, with the new version saved beside it in `.studio-update/`.
+Merge those keeping your changes, delete `.studio-update/`, then `npm install` if `package.json`
+changed, and `npm run check`.
+
+Do not update by copying files across or comparing them by eye. The command knows every version of
+every file ever shipped, which is the only way to tell your edit from an older release.
+