@officexapp/vidfarm-devcli 0.21.52 → 0.21.54

package/experimental/ugc-reaction-greenscreen.md

@@ -0,0 +1,1963 @@
+---
+name: ugc-reaction-greenscreen
+video_type: UGC reaction cutaways + a keyed greenscreen device carrying the customer's app demo — subtitled, music-led, silent or narrated (TikTok / Reels / Shorts)
+checks:
+  duration_sec: 15-30
+  aspect: 9:16
+  first_frame_visual: required
+  first_frame_text: required
+  text_by_sec: 0.6
+  captions: required
+  audio: required          # a bed in silent mode; a bed + voiceover in narrated mode
+  font_regime: required
+  safe_zone: required
+  # This counts EVERY visual layer, not beats — sticker images land in it too.
+  # The seven-beat structure is a review item, not a machine check: 7 beats plus
+  # up to ~4 stickers is the shape this range is sized for.
+  scenes: 4-12
+  max_scene_sec: 10
+  max_text_cards: 1        # every word is a timed subtitle cue, not a card
+  max_simultaneous_text: 1
+  max_words_per_cue: 7
+  # 1.5 is right for SILENT mode, where text is the only channel and a gap is a free exit.
+  # In NARRATED mode the payoff beat is SUPPOSED to have a stretch with no caption over it —
+  # the voice stops on purpose and the screen does the work. Tighten this back to 1.5 if you
+  # cut the voiceover.
+  max_dead_air_sec: 3.0
+  max_tail_sec: 1.2
+  forbid_text:
+    - link in bio
+    - sign up for a free trial
+    - get started today
+    - book a demo
+    - download now
+---
+
+# UGC Reaction × Greenscreen × App Demo
+
+> A public Vidfarm prompt. Read it end to end before you build. It assumes nothing about the
+> product except that it has a screen you can film.
+
+The format is three streams of footage cut against each other:
+
+| Stream | What it is | Where it comes from | What it does |
+|---|---|---|---|
+| 🙂 **Reaction** | An ordinary person on camera, mid-expression | `vidfarm.cc/discover` → public raws, shelf `ugc-reaction` (180 clips) | Makes the video a *situation* instead of an ad. Carries the hook and the bait |
+| 📱 **Greenscreen device** | A hand holding a phone whose screen is a flat green field | public raws, shelf `greenscreen`, `sourceType: Display Greenscreen` | The frame the product lives inside. Turns a screen recording into something someone is *holding* |
+| 🖥 **App demo** | The customer's real product doing one real thing | the customer's own folder, or you drive their site in a browser | The proof. The only beat where the product exists |
+
+**Only one voice is ever allowed: yours.** The reaction clips are muted, the customer's demo is
+muted, and the cut runs either fully silent under subtitles or under a voiceover you wrote and a
+ducked music bed. Two modes, no third — see *Audio DNA*.
+
+## The one test
+
+> **Does the product arrive as something a person is holding, or as a screen recording someone pasted in?**
+
+The greenscreen device beat is the entire reason this format exists. A screen recording dropped
+full-bleed on a timeline is a demo video with reaction clips stapled to it. A screen recording
+living inside a phone that a real hand is tilting is a person showing you something. The viewer
+reads the difference in well under a second and never articulates it.
+
+## The second test — does the video SHOW what the product is about?
+
+Ask it before you cut and again on the render: **name the noun the product is about, then find it in
+the footage.** A dish-search app is about *food*. A rental app is about *rooms*. A running app is
+about *running*.
+
+This format is unusually good at failing that test, and the reason is structural: its three streams
+are a **face**, a **phone**, and a **UI**. None of them is the subject. On the reference build the
+product finds you food by dish — and the first cut contained no food at all. It was twenty-two
+seconds of people reacting to a screen. Every individual beat was correct and the video still did
+not read as being about dinner.
+
+**The UI is not the subject.** A results list saying *Cucumber Salad · $9* is a row of text. It
+proves the product works; it does not make anyone hungry, and hunger is the thing you are selling.
+
+So: find the noun, and if the raws don't contain it, **put it in** — with a cutaway from the
+`lifestyle` / `b-roll` shelves if one exists, or with a sticker if it doesn't. Getting the subject
+on screen twice in 22 seconds is worth more than any amount of re-cutting.
+
+## Part 0 — who this is for
+
+**Not you — the customer's buyer.** Before anything else, write one line naming them, and one line
+naming the moment they are in. Everything below is decided by those two lines: which reaction face,
+which craving/query/task you type into the demo, which limit you concede.
+
+- **Register:** peer to peer. Someone who had the problem, found the thing, is telling you.
+- **The product enters in beat 3, never beat 1.** Beat 1 is a situation.
+- **Never a brand voice.** No "introducing", no "meet", no "the all-new".
+
+---
+
+## Structural DNA — the beats
+
+Seven beats, ~22s. The rhythm is **reaction → device → reaction → device**: the video cuts *back*
+to a face after the payoff and *back* to the app after the face. One unbroken block of app footage
+is the single most common way this format collapses into an ad.
+
+| # | Beat | ~t | Stream | Job |
+|---|---|---|---|---|
+| 1 | **Hook** | 0:00–0:02.5 | Reaction | The situation, on a real face, before any product exists |
+| 2 | **The wrong way** | 0:02.5–0:05 | Reaction | What they tried instead, and why it failed. This is the concession |
+| 3 | **The move** | 0:05–0:09 | Device | The one action inside the app. Typing, tapping, pasting — at real speed |
+| 4 | **The result** | 0:09–0:14.5 | Device | What came back. Held, legible, uncut. **This is the payoff** |
+| 5 | **The face** | 0:14.5–0:17 | Reaction | The reaction to the result — the emotional label for what was just shown |
+| 6 | **The scope** | 0:17–0:19.5 | Device | The honest limit, said over the app still running |
+| 7 | **The bait** | 0:19.5–0:22 | Reaction | One comment ask, and the same ask in the post caption |
+
+**Cast ONE actor across every reaction beat.** The narration is first person singular — *"I didn't
+want a restaurant… I just picked one"* — so a different face on each beat is not a stylistic choice,
+it is an incoherence: one voice saying "I" over four different people. One face turns four cutaways
+into an arc (exasperated → beaten → convinced → warm), and the arc is what makes the payoff land.
+
+Use several faces only when the video genuinely is a vox-pop — nobody is "I", the narration is
+third person, and the point is *lots of people have this problem*. That is a different video.
+
+**Beat 6 is load-bearing and gets cut first by every agent that reads this.** The limit is what
+buys the rest of the video. Put it over the app so it doesn't read as a disclaimer card.
+
+**One clip per beat — seven beats, seven layers.** Beats 3 and 4 are the same recording, so the
+lazy build puts them on one ~10s layer. Don't: against 2.5s reaction cuts a 10s hold is where the
+retention curve falls off, and `vidfarm qa` will say so (`slow-scene`). Split at the frame the
+result lands — which is a cut the *content* is already asking for — and no layer runs past ~6s.
+
+---
+
+## Sourcing — three streams, three methods
+
+### 🙂 Reaction raws — browse the shelf, don't search it
+
+```bash
+vidfarm public-raws --categories                        # the shelves + live counts
+vidfarm public-raws --category ugc-reaction --limit 100 # the whole shelf, read the descriptions
+```
+
+The shelf's semantic search is thin; **the descriptions are the index**. Pull the shelf as JSON and
+filter the `description` field on the emotion you want (`surpris`, `disgust`, `distress`, `smil`,
+`laugh`, `disbelie`, `confus`). Pick by the description, then confirm by eye — build a contact
+sheet of 4–5 stills per candidate and read them as one image before you commit.
+
+#### Cast the actor, not the clip — the `actor_<uuid>` tag
+
+**A shelf is dozens of clips of a much smaller number of creators**, and nothing in the taxonomy
+says "same face". The `actor_<uuid>` tag does. Every tagged public raw carries one actor id in its
+`summary` (and in `tags.actor`), so you read it off a card you already like and search for it as a
+plain token:
+
+```bash
+vidfarm public-raws --category ugc-reaction --limit 100     # 1. browse, pick a face
+# 2. read the actor_<uuid> token off that card's summary — it is appended at the END
+vidfarm public-raws --query actor_668363ea-…                # 3. every other clip of that person
+```
+
+The token lives at the tail of the card's `summary` string. In the feed response `tags` comes back
+`null`, so **`summary` is the field to parse** — a reader that only looks at `tags.actor` finds
+nothing and concludes the shelf is untagged.
+
+REST twin `GET /api/v1/public-raws?q=actor_<uuid>`, and because it is an ordinary keyword search it
+composes: `?category=ugc-reaction&q=actor_<uuid>`.
+
+**Cast by ARC, not by clip.** You need four reaction beats — hook, the wrong way, the payoff face,
+the bait — so pick the actor whose set can carry all four, not the single best-looking clip. On the
+reference build one actor had five takes and four of them mapped straight onto the beats:
+
+| Beat | Their take |
+|---|---|
+| 1 hook | distressed faces, hand at her mouth |
+| 2 the wrong way | frowning at a **laptop** — which is what "Google gave me a list of fifty" is about |
+| 5 the face | **thumbs up**, outdoors |
+| 7 the bait | a warm smile to camera |
+
+Practical notes, from the catalogue as it stands:
+
+- **Measure the pool, don't take a doc's word for it.** Counted today: **180 `ugc-reaction` raws,
+  53 tagged actors, 3 untagged — and 25 actors with 4+ takes.** That is a far bigger casting pool
+  than the shelf looks like from the outside, and it is the only part of it that can carry this
+  format. Re-count rather than trusting this line; the shelf is actively being tagged.
+- ⚠️ **The feed caps `limit` at 100 and paginates on `cursor`, not `offset`.** `offset=100` is
+  silently ignored and returns page 1 again — a loop built on it looks like it works, reports a
+  plausible number, and has seen half the shelf. Follow `next_cursor` until it is null.
+- ⚠️ **Read the id fresh, and re-read it if it stops matching.** The ids come from a tagging pass
+  that gets re-run: mid-build here, an id that had returned 5 clips started returning **0**, because
+  the shelf had been re-tagged and the same person's clips now carried a different id (with 7 clips
+  grouped under it instead of 5). So an actor id is a lookup key that is good for *this* build, not
+  a permanent name. If a saved id returns nothing, the actor has not gone — re-read the token off a
+  card. And never invent one; a made-up id matches nothing.
+- **No tag means "not tagged yet", not "a different person".** Older raws and raws with nobody on
+  camera have none.
+- **Wardrobe and location will NOT match between takes** — different top, different room, outdoors.
+  That is fine and it is not a continuity error: UGC creators film across days, and the audience
+  reads it as the same person at different moments. **Identity continuity is what matters; wardrobe
+  continuity is not.** What *would* break it is a different face.
+- Same trick answers a director asking *"more of her"* — the actor id on the raw already in the
+  composition is the answer.
+
+⚠️ **`ffprobe` reports CODED dimensions, and phone video is rotated.** Almost every clip on this
+shelf carries a 90° rotation matrix: `ffprobe` says `3840x2160` and ffmpeg **decodes it as
+2160x3840**, already 9:16. Hand-computing a crop from the probed width put the subject off-frame on
+all four beats of the reference build — wall where the face should be. Never compute geometry from
+the probe; let the filter work on the decoded frame:
+
+```bash
+# right: operates on what was decoded, whatever the rotation
+-vf "scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,setsar=1,fps=30"
+```
+
+If you genuinely need an off-centre crop, read the decoded size first
+(`ffprobe -show_entries side_data=rotation`, or decode one frame and measure it).
+
+### 📱 Greenscreen device raws — check `sourceType` before you key anything
+
+The `greenscreen` shelf holds two populations that look identical to a category filter and are
+completely different to a lawyer:
+
+| `sourceType` | What it is | Use it for |
+|---|---|---|
+| **Display Greenscreen** | Device mockups — a hand holding a phone with a green screen, a phone on a notebook. No identifiable person, no character | ✅ Client work. This is the one you want |
+| **MemeScreens** | Keyed celebrities, TV characters, pets, animated figures on a green field | ⚠️ Normal for a meme repost. A rights problem on a customer's paid ad running on owned accounts |
+
+```bash
+vidfarm public-raws --category greenscreen --query "smartphone green screen" --limit 25
+```
+
+There are only a handful of Display Greenscreen clips, so **look at all of them and pick on
+motion, not on looks.** Ranked, best first:
+
+1. **Two hands, thumb on the glass, indoors, native 9:16.** Reads as a person using a phone. Drifts
+   the most — needs the tracked insert below, which is fine, because you are doing that anyway.
+2. **Phone flat on a desk or notebook, top-down.** Calm, minimal drift, but reads as a product shot
+   rather than a person.
+3. **Phone against a plain green background.** Avoid: the plate colour and the screen colour are the
+   same field, so a key gives you a floating phone body and a demo behind *everything*.
+
+### 🖥 App demo raws — the customer's folder first, the browser second
+
+**Ask for a folder before you build one.** A customer who already records their own product gives
+you footage with the right accounts, the right data and the right edge cases. Take it, and then:
+
+> **Cut it. Do not narrate it, and do not keep their narration.**
+>
+> A narrated demo raw is *worse* input than a silent one. Their voice competes with your subtitles,
+> the pacing is theirs and the tone is a webinar. Strip the audio, find the four seconds where the
+> product actually does the thing, and throw the rest away. If they insist their narration ships,
+> that is a different format — use `ugc-testimonial`.
+
+**No folder? Drive their site yourself.** Free, local, repeatable, and it always has current data:
+
+```bash
+vidfarm capture "https://<their site>" --out ./capture   # tokens, copy, screenshots — read this first
+vidfarm browser setup                                    # then drive their real UI
+```
+
+Record the interaction at the **device screen's aspect ratio**, not at desktop and not at a laptop
+viewport. A 440×940 recording drops into a phone screen with no letterbox and no re-crop; a
+1440×900 one arrives as a stamp inside a phone and the whole beat is unreadable.
+
+Four rules for the recording itself, all of them learned the expensive way:
+
+1. **Verify the query returns results before you film it.** Type it yourself first. A product's own
+   advertised example can be broken — in the worked example that produced this file, the exact phrase the
+   customer prints on their own homepage returned *No dishes found*, and the first take was unusable.
+2. **Park the interactive region at the top of the frame before you type.** Otherwise the results
+   render below the fold and the payoff never appears on screen.
+3. **Type at human speed** (~130ms/char) and hold ~2.5s after the result lands. Instant fills read
+   as a mockup; a real keystroke cadence is the cheapest authenticity you will ever buy.
+4. **Draw a soft synthetic cursor.** A UI that changes with nothing touching it looks like a video
+   of a website. A dot that moves to the field first looks like a person.
+
+---
+
+## Visual DNA
+
+### The tracked insert — the technique the whole format rests on
+
+The device is handheld. It **drifts and it is tilted**, so a flat chroma key with the demo pinned
+behind it fails in three named ways, all visible within two seconds:
+
+| Defect | Cause | Fix |
+|---|---|---|
+| The demo **slides under the bezel** | The insert is static; the phone is not | Re-measure the green region *every frame* |
+| A **green wedge** down one edge | The insert is axis-aligned; the phone is rotated a few degrees | Fit to the screen's own axes (PCA on the green mask), not to an upright bounding box |
+| The demo **paints over the thumb** | The insert is pasted into a *box* | Paste by **mask**: every green pixel becomes demo, every non-green pixel (thumb, bezel, room) is left alone |
+
+The mask paste is what sells it — the thumb ends up *on top of* the app, which is the single frame
+that makes a viewer believe someone is holding it. Appendix A is a ~90-line script that does all
+three. `vidfarm remove-greenscreen` is the right tool for a **full-frame** flat plate; it is the
+wrong tool here, because it has no reason to know where the screen went.
+
+```bash
+python3 track-insert.py phone-raw.mp4 demo.mp4 phone-demo.mp4 --demo-start 1.2
+```
+
+`--demo-start` trims the demo's dead head (page load, blank white) so the insert opens on something.
+
+### Punch in on the device beats
+
+A Display Greenscreen raw frames the phone small, with a lot of blurred room around it. Shipped as
+is, the UI is unreadable at phone scale and the demo did not happen. Crop to the device **plus a
+drift margin**, then scale back to canvas:
+
+Measure the green region's **travel** before you choose the crop — a crop sized to one frame clips
+the device on another:
+
+```python
+# per-second bounding box of the green field, on the ORIGINAL device raw
+import subprocess, numpy as np
+W, H, f = 1080, 1920, "device-raw.mp4"
+p = subprocess.run(["ffmpeg","-v","error","-i",f,"-vf","fps=1,scale=320:569",
+                    "-pix_fmt","rgb24","-f","rawvideo","-"], capture_output=True)
+b = np.frombuffer(p.stdout, np.uint8); n = len(b)//(320*569*3)
+for i, fr in enumerate(b[:n*320*569*3].reshape(n,569,320,3).astype(np.int16)):
+    r, g, bl = fr[...,0], fr[...,1], fr[...,2]
+    m = (g > 90) & (g-r > 40) & (g-bl > 40)
+    ys, xs = np.nonzero(m)
+    print(f"t={i}s x[{xs.min()*W//320},{xs.max()*W//320}] y[{ys.min()*H//569},{ys.max()*H//569}]")
+```
+
+Take the union of every box, add ~60px of margin on each side, and round the crop to the canvas
+aspect:
+
+```bash
+ffmpeg -i phone-demo.mp4 -vf "crop=880:1564:20:130,scale=1080:1920,setsar=1,fps=30" s3-move.mp4
+```
+
+Typical punch-in is 1.2–1.4×. Use the **same crop for every device beat** in the video — a punch-in
+that changes between beat 3 and beat 6 reads as two different videos.
+
+### Stickers — allowed, and only ever as annotation
+
+Stickers earn their place in exactly two jobs, and both are about comprehension:
+
+| Job | What it looks like | When you need it |
+|---|---|---|
+| **Annotate** | a ring around the row the narration just named, an arrow at the field being typed into, an underline under the number being read out | the device beat asks a viewer to read a dense UI in about two seconds |
+| **Supply the subject** | the actual thing the product is about — the dish, the room, the shoe — laid over the shot | the raws are faces and a phone, and the product's own noun never appears (see *The second test*) |
+
+**The test: does it make the product clearer?** If yes, use it. If it competes for attention with
+what's already on screen, or a viewer has to work out why it's there, cut it — a confusing sticker
+is worse than none, and this format is dense enough already.
+
+**Never furniture.** A floating icon, a badge, a chip, a logo, a "NEW!" burst, an emoji dropped in
+to fill space — none of those is either job, and `vidfarm qa` is right to call them slop.
+
+- **One on screen at a time, and not on every beat.** Two or three across a 22s cut is plenty. A
+  sticker that sits for the whole video has stopped being punctuation.
+- **It appears on the word that names it and leaves.** Same discipline as the captions: absolute
+  `animation-delay`, and it goes when the thought does.
+- **An in-screen annotation is only valid while the UI under it is STATIC.** This is the one that
+  bites. The reference build's ring was placed over the picked row for 1.3s — and the results list
+  began scrolling 0.3s in, so the last third of the shot had a marker circling the wrong dish.
+  Step the beat frame by frame, find where the content moves, and end the sticker before it:
+  ```bash
+  ffmpeg -i beat.mp4 -vf "fps=2,scale=300:-1,drawgrid=w=iw/20:h=ih/20:t=1:c=red@0.5,tile=6x1" \
+    -frames:v 1 rows.png     # read the row's box off the grid, and see when it moves
+  ```
+- **Hand-drawn for annotation; photographic for the subject.** A crisp vector circle reads as a UI
+  element drawn over the video — ask for a rough felt-tip stroke instead. But a *subject* sticker
+  should look like the real thing: a photographic cutout of the actual dish sells the craving, an
+  illustration of one does not.
+- **A tight face has no room for a sticker.** On a close portrait there is nowhere to put one that
+  isn't a forehead, a temple or an eye, and anything you place there reads as stuck to their head
+  rather than laid on the shot. Put subject stickers on the beats with air in them — the device
+  beats have defocused room on both sides, and a medium shot has wall. If the beat you *want* is a
+  tight face, move the sticker to the next beat rather than shrinking it into a corner.
+
+**Sourcing, cheapest first.** `vidfarm iconscout --free` and `vidfarm media icon` are free but
+almost all require an attribution credit — and an attribution line on screen is brand chrome you
+already said you would not have. So for this format the practical route is one generated cutout:
+
+```bash
+vidfarm cutout --generate "a single thick hand-drawn yellow felt-tip ELLIPSE OUTLINE, stroke
+  ~40px. The ENTIRE rest of the image, INCLUDING THE AREA INSIDE THE ELLIPSE, is solid magenta
+  #FF00FF. No white, no grey, no paper, no shadow, no text." \
+  --key-color "#FF00FF" --key-mode flat --tolerance 0.4 --out stickers/ring.png
+```
+
+**Match the KEY MODE to the shape, and the PLATE COLOUR to the palette.** Getting this wrong is
+silent — the file looks right in a thumbnail and is wrong in the video:
+
+| Art | Key mode | Why |
+|---|---|---|
+| **Hollow** — a ring, a frame, an arrow outline | `--key-mode flat` | the interior never touches the frame edge, so the default connectivity keyer *keeps* it and you get a filled disc instead of a ring |
+| **Solid** — a photographic dish, a product, a person | `--key-mode smart` (the default) | flat mode's soft alpha ramp eats a photograph. Measured on a first attempt: **65% of the cutout came back partially transparent**, so the background showed straight through the food. Smart mode returned the same art at **0.6% partial alpha** |
+
+Pick the plate against the subject's own colours — green plate for red food, magenta for green food
+— and check the result rather than trusting it:
+
+```python
+# any cutout: how much of it is actually opaque?
+a = alpha_channel(png)
+print((a == 0).mean(), ((a > 0) & (a < 255)).mean(), (a == 255).mean())
+# healthy: mostly 0 or 255, a percent or two in between. Tens of percent "partial" = a bad key.
+```
+
+Glass and soft edges pick up the plate colour even after a good key. One numpy pass fixes it: where
+the plate's channel is the dominant one, pull it down to the average of the other two.
+
+Three things in the prompt are load-bearing, and each one cost a wasted image job to learn:
+
+1. **Pin the plate colour and say it twice.** Left to itself the model draws on **white**, the plate
+   never gets keyed, and you get a white box with art in it. Worse, if the art is also white (an
+   arrow, a highlight) you cannot key the background without destroying the subject.
+2. **Say "including the area inside the ellipse".** A ring's interior does not touch the frame
+   edge, so the default connectivity keyer *keeps* it — you get a filled disc, not a ring.
+   `--key-mode flat` removes the colour wherever it appears, which is what an open shape needs.
+3. **Ban white and grey explicitly.** Otherwise you get paper texture and a drop shadow, and the
+   shadow keys as a grey halo.
+
+**Placement.** Drive it from a manifest so the set is reproducible and overlaps get caught —
+Appendix I:
+
+```
+# src | start | dur | left% | top% | width% | height% | label | rotate | fit
+media/stickers/food-chilicrisp.png | 6.60 | 1.90 |  2 | 21   | 27 | 16 | the craving  | -5 | contain
+media/stickers/ring.png            | 10.30| 1.40 | 18 | 38.5 | 62 | 14 | the pick     |  0 | fill
+media/stickers/food-cucumber.png   | 14.70| 1.90 | 56 | 14   | 30 | 18 | what $9 buys |  6 | contain
+```
+
+**`fit` is not cosmetic — the two sticker jobs need opposite values.** A subject sticker must keep
+its aspect (`contain`); a photo of a dish squashed to a box is obviously wrong. An annotation
+sticker must **squash to the shape it marks** (`fill`) — a near-square ring set to `contain` inside
+a wide, short box collapses to the box's *height* and renders as a small circle floating beside the
+row instead of around it. That regression is invisible in the markup and obvious in one frame, so
+look at the frame.
+
+The markup it writes — wrap the image in a `div.clip` exactly like a caption layer. A bare `<img>`
+with `data-start` renders at t=0 and then never shows or hides, because the engine does not manage
+it:
+
+```html
+<div class="clip" id="ann-ring" data-hf-id="ann-ring" data-layer-mode="publish"
+     data-layer-kind="image" data-start="10.3" data-duration="1.4" data-end="11.7"
+     data-track-index="6" data-label="annotation: the dish that was picked"
+     style="position:absolute;inset:auto;left:18%;top:38.5%;width:62%;height:14%;z-index:6">
+  <img class="sticker" src="media/stickers/ring.png"
+       style="width:100%;height:100%;object-fit:fill;animation-delay:10.3s"></div>
+```
+
+`inset:auto` first, because `.clip { inset: 0 }` would otherwise fight the geometry. `object-fit:
+fill` is deliberate — a marker circle around a line of text *should* squash to the row's aspect.
+
+```css
+.sticker{animation-name:vfStickIn;animation-duration:.42s;animation-fill-mode:both;
+  animation-timing-function:cubic-bezier(.2,1.1,.3,1);transform-origin:center}
+@keyframes vfStickIn{
+  0%{opacity:0;transform:scale(.55) rotate(-14deg)}
+  60%{opacity:1;transform:scale(1.06) rotate(2deg)}
+  100%{opacity:1;transform:scale(1) rotate(0deg)}}
+```
+
+### Everything else
+
+- **9:16, 1080×1920, 30fps**, one canvas, no letterboxing anywhere.
+- **Butt cuts.** No crossfades, no whips, no transitions of any kind. This format cuts on the
+  emotional beat; a transition softens exactly the moment you want hard.
+- **The cut from device back to face lands on the result**, not two seconds after it.
+- **No brand chrome.** No logo, no end card, no URL, no title card. The product's own UI is the
+  only branding, and it is already on screen.
+
+---
+
+## Audio DNA
+
+**Two modes. Pick one before you cut, because the subtitles are built differently in each.**
+
+| Mode | Track stack | Subtitles are… |
+|---|---|---|
+| **Silent** | music bed only | authored by hand, timed to the CUTS (`captions.srt` → Appendix C) |
+| **Narrated** | voiceover over a ducked bed | transcribed from the VO, timed to the WORD (Appendix F) |
+
+Narrated is the stronger default: it carries the beats where the picture is quiet, and the read-out
+of a real number lands harder spoken than written. Reach for silent when the poster will drop
+trending platform audio over the whole thing at upload — a voiceover fighting a trending track is
+worse than either alone.
+
+**What never changes, in either mode:**
+
+- **Mute every reaction raw.** They came with real audio about something else entirely. A face
+  visibly saying words that don't match the subtitles is the loudest fake tell in the format, and it
+  survives every other quality pass because nobody watches the render with sound on.
+- **Mute the demo.** Even if the customer's raw has narration. Their voice competes with yours,
+  the pacing is theirs, and the tone is a webinar.
+- **The narration is YOURS, written to the beat table.** A voiceover is not permission to keep the
+  customer's — it is one script, one voice, one delivery, across the whole cut.
+
+### Narrated mode
+
+- **One VO clip per beat, not one long take.** Each clip is placed at its own beat, so a re-cut of
+  one beat re-records one line instead of re-timing everything. It also keeps the VO from drifting
+  against the picture as the edit changes.
+- **Pin the voice.** `vidfarm tts "<line>" --voice <name> --style "<one delivery note>"` — pass the
+  SAME `--voice` and the SAME `--style` string on every line. Generate them in separate calls
+  without pinning and the narrator subtly changes character between beats, which reads as
+  "assembled" long before anyone can say why.
+- **Direct the pace, don't fix it later.** A "dry, considered" style prompt produced 4.6s of speech
+  for four words — nearly double its beat. Re-prompting for "brisk, punchy, quick clipped delivery,
+  no pauses between sentences" brought the same line to 2.2s and it sounds *more* native, because
+  short-form narration is fast. Prefer re-prompting over time-stretching.
+- **Compress pauses; don't stretch speech.** When a line is still slightly long, strip the internal
+  silences rather than `atempo` the whole clip — it preserves the natural word rate and kills dead
+  air, which is what you wanted anyway:
+  ```bash
+  ffmpeg -i vo.wav -af "silenceremove=start_periods=1:start_silence=0.04:start_threshold=-45dB\
+  :detection=peak:stop_periods=-1:stop_duration=0.12:stop_threshold=-40dB,areverse,\
+  silenceremove=start_periods=1:start_silence=0.04:start_threshold=-45dB:detection=peak,areverse" tight.wav
+  ```
+- **Leave the payoff alone.** Do not narrate over the whole runtime. On a 22s cut, ~15s of speech
+  and ~7s of silence is right — the result beat needs a stretch where nothing is being said and the
+  screen is just doing the thing.
+- **A VO may cross a cut.** A line that starts on a face and finishes over the app binds the two
+  shots together. Don't clip narration to shot boundaries.
+- **Duck the bed to `data-volume` ≈ 0.2** and normalise each VO clip to about -16 LUFS. Target
+  **12–15 dB of speech over bed**, and verify it by measuring the two STEMS, because `ebur128` on
+  the finished mix cannot separate them.
+
+### The bed, in both modes
+
+- **Level the bed and measure it.** Target ~-16 LUFS integrated, peak < -1 dBFS
+  (`loudnorm=I=-16:TP=-1.5:LRA=11`). Fade in ≤0.6s, fade out over the last ~1.2s.
+- **`data-volume` multiplies the already-normalised file.** A bed normalised to -16 LUFS sitting on
+  a layer at `data-volume="0.5"` ships at about **-22 LUFS** — quiet enough that a phone speaker in
+  a noisy room gets nothing. The 0.1–0.2 bed level everyone quotes is for ducking *under a
+  voiceover*, and there is no voiceover here. Normalise the file, then leave the layer at `1`, and
+  measure the RENDER (`ffmpeg -i out.mp4 -af ebur128=peak=true -f null -`) rather than the stem.
+- **Source it free.** `vidfarm media bgm "<vibe>" --provider openverse` — prefer **CC0** so nothing
+  has to be credited on screen. A CC-BY track means an attribution line, and an attribution line is
+  brand chrome you just said you would not have.
+### Ship TWO cuts, from ONE render
+
+Do not put the music bed in the composition. **The composition is the voiceover-only master**, and
+the bed is applied at export — which gives you both deliverables for the price of one render:
+
+```bash
+python3 export-versions.py renders/cut-vo.mp4 media/bgm.mp3 --bed-volume 0.22
+#   voiceover only       cut-vo.mp4        publish this
+#   voiceover + music    cut-music.mp4     review / fallback / watermarked
+```
+
+| Cut | What it's for |
+|---|---|
+| **`-vo`** (voiceover, no music) | **The one you publish.** TikTok, Reels and Shorts all let the poster attach a track from the platform's own library at upload — licensed through the platform's deals with the labels, so the music is cleared where viewers actually hear it, and the post gets whatever is trending *this week* rather than whatever was trending when you rendered |
+| **`-music`** (voiceover + bed) | The review copy you send a client, the fallback for anywhere without an in-app music library, and the one that carries a **watermark** if you need one |
+
+**Derive, never re-render.** `-c:v copy` means both files carry the byte-identical video stream, so
+approving one approves the other. Two separate renders are two different videos that merely look
+alike, and the frame you approved is not the frame you shipped. A watermark is the one thing that
+breaks this — it has to be burned in, so that version gets its own encode and stops being
+frame-identical. Say so in the handoff.
+
+**`normalize=0` on the `amix`.** Left at its default, `amix` pulls the voice down to make room for
+the bed and quietly undoes the levelling you just measured.
+
+- **Say which kind of bed it is in the handoff.** If the poster will attach trending audio at
+  upload, the bed in the `-music` cut is a *review* bed. If the `-music` cut ships as is, the bed is
+  the bed. These are different decisions and the customer has to make it.
+
+---
+
+## Subtitle DNA — TikTok-native, or don't bother
+
+Subtitles are not accessibility here. They are the **only** delivery system for the hook, the loop,
+the payoff, the limit and the bait. Get them wrong and the video has no words at all.
+
+**Native means the captions are TIMED TO THE VOICE.** One short phrase on screen at a time, turning
+over as the person speaks. Not a static two-line block, not a designed card, not a lower third.
+
+A per-word *highlight* is one way to do that and it is not required — **plain white text with no
+accent at all is TikTok's own default auto-caption look**, and it is the right choice more often
+than the coloured mechanics: over busy footage, over a UI that already has its own colours, and on
+any beat where the words should carry no emphasis of their own.
+
+### What is FIXED, and what VARIES
+
+Native is a small set of invariants, not a house style. Ship the same colour, case, size and
+mechanic on every video and the catalogue reads as a content farm — which is a worse failure than an
+odd caption, because it is visible across the whole account at once.
+
+| Fixed — this is what "native" means | Varies — pick per video |
+|---|---|
+| **TikTok Sans**, self-hosted, no fallback chain | **weight** 700 / 800 / 900 |
+| captions are **timed to the voice** | **which mechanic** — including *none* |
+| **no phrase plate**; text sits on the picture | **accent colour** |
+| inside the **platform-safe core** | **size** within the standard's ~36–64px band, and **position** within the core |
+| **verbatim**, ≤3–4 words a page, one cue at a time | **case** — uppercase, or sentence case like TikTok's own auto-captions |
+
+**Hold one combination for the length of a single video; change it between videos.** Styling that
+shifts mid-video reads as a bug; styling that never shifts across thirty videos reads as a factory.
+
+### The six mechanics — all native, none of them "the" one
+
+Ordered quietest to loudest. The first two carry **no accent colour whatsoever**.
+
+| `--highlight` | What it does | Reads as |
+|---|---|---|
+| `none` | plain white; the whole page appears at once and the page turns do the work | TikTok's stock auto-captions. The calmest, and the one that never fights the footage |
+| `reveal` | plain white, but each word switches on at its own moment | still word-timed, still no colour — a middle setting when the beat wants pace but not emphasis |
+| `colour` | the active word takes the accent, settles back to white | the quiet accented default; safe on busy footage |
+| `pop` | accent **plus a vertical stretch** | more energy, still calm enough for a talking beat |
+| `underline` | an accent bar wipes under the active word | "reading along"; good under a number being read out |
+| `pill` | a filled accent box behind the active word, dark text inside | the loudest; excellent over a bright UI where white-on-white struggles |
+
+**Every accented one is engineered to take no horizontal space.** That is not a stylistic choice —
+an inline-block word that grows sideways eats the gap beside it and `a restaurant` renders as
+`arestaurant` on the beat the word fires. `pop` therefore scales on **Y only**; `pill` and
+`underline` live inside the word's own box.
+
+**`reveal` deliberately does not re-centre.** A word that has not fired yet is transparent but still
+occupies its slot, so the visible words sit where they will end up rather than sliding left as each
+one arrives. Reflowing to keep the visible text centred makes every word jump, which is far worse
+than the asymmetry.
+
+### Take the accent from the customer's own palette
+
+`vidfarm capture` already wrote it. `capture/extracted/tokens.json` carries the site's CSS
+variables, so the caption accent can come from the product rather than from your habits — different
+per client, for free, and never brand chrome because it is one word at a time rather than a logo:
+
+```bash
+python3 -c "import json;d=json.load(open('capture/extracted/tokens.json'));print(d['cssVariables'])"
+# dishcover.io → --accent #2b3eff · --accent-orange #ff6b00 · --accent-yellow #ffd500 · --accent-red #e5432e
+```
+
+Then **contrast-check it against the band you measured** — a mid-blue accent on a dark scene is a
+word that disappears at the exact moment it matters. If the accent fails, use it as the `pill`
+background with dark text instead of as the type colour; a filled box survives backgrounds that
+coloured type does not.
+
+**The highlight is a COLOUR SWAP, not a zoom.** A scaling active word is a CapCut habit, and it has
+a concrete failure mode as well as a stylistic one: an inline-block word scales from its centre into
+its neighbour, so `a restaurant` renders as `arestaurant` on the exact beat the word pops — and a
+text stroke eats the remaining gap from both sides. Padding the words apart only trades collision
+for letterspaced display type that stops reading as speech. Colour (plus, at most, a ~0.05em
+vertical lift that costs no horizontal room) makes the collision **impossible** rather than tuned.
+
+> ⚠️ **Verify the words actually animate, in the RENDER.** `--style word-pop` writes per-word
+> `animation-delay` / `animation-duration` and leaves the keyframes to the render engine — and on
+> some engine versions that binding silently does not happen, so the cue renders as **one static
+> block with no active-word colour**. Nothing errors. `captions list` shows correct timings. The
+> composition lints clean. You only find it by pulling ~7 consecutive frames from *inside a single
+> cue* and looking:
+>
+> ```bash
+> ffmpeg -i out.mp4 -ss <cue start> -t <cue length> -vf "fps=6,crop=1080:340:0:1180,tile=7x1" \
+>   -frames:v 1 cap-anim.png
+> ```
+>
+> If all seven frames are identical, the format's whole subtitle design did not ship — **unless the
+> mechanic is `none`, where identical frames are exactly right.** Check which one you chose before
+> you go debugging. **Own the
+> keyframes in the composition's own `<style>`** rather than depending on the engine — the emitter
+> in Appendix C does this, and it is the one change that makes the animation a property of the file
+> instead of a property of whatever version rendered it.
+>
+> Two traps inside the fix, both of which look like "the animation is still broken":
+>
+> 1. **`animation-delay` is measured from PAGE time, not from the layer's own start.** A cue at
+>    9.1s with a relative delay has already run to completion by the time the layer is visible, so
+>    every word renders in its end state. Emit `animation-delay: <cue start + word offset>`.
+>    Symptom: cue 1 animates, every later cue is static — which is easy to misread as "it works".
+> 2. **Don't fade the words in.** With a single translucent plate behind the phrase, a progressive
+>    reveal leaves an empty grey box on screen ahead of the words, and that reads as a loading
+>    state. Keep the whole phrase visible and pop only the ACTIVE word (scale + accent colour,
+>    settling back to white) — which is TikTok's own convention anyway. `animation-fill-mode:
+>    forwards`, base style = the settled state.
+
+```bash
+# Appendix C, with the dials shown. There is no default combination to copy —
+# choose one per video and write it into the handoff so the next one differs.
+python3 srt-to-cues.py composition.html cues.json \
+  --font "TikTok Sans" --weight 900 --font-size 64 \
+  --highlight colour --active-color "#FFD500" \   # or: none | reveal | pop | pill | underline
+  --y 57 --x 14 --width 72 --plate none          # add --no-uppercase for sentence case
+```
+
+- **In SILENT mode, hand-author the SRT.** There is no narration to transcribe, and `--text` paging
+  spreads words evenly across a window, which desyncs from your cuts. Write the cue times against
+  the beat table.
+- **In NARRATED mode, never hand-author them.** Captions must be verbatim and sit on the word, so
+  they are derived from the VO's own transcript — Appendix F does it. A karaoke highlight 200ms off
+  the voice is more distracting than no highlight at all.
+
+> ⚠️ **`captions generate --srt` does not respect your cue boundaries.** It flattens the whole file
+> into one word stream and re-pages it by `--max-words`, so words hop the cut: `the dish instead` +
+> `chili crisp` renders as `dish instead chili crisp`, two beats late and over the wrong footage.
+> That is invisible in `captions list` timings and obvious in a contact sheet, which is exactly why
+> you build the sheet. **Always read the generated cue text back before you render.** When the cues
+> are pinned to cuts rather than to speech — which in this format they always are — use the
+> one-layer-per-cue emitter in **Appendix C** instead, and keep `captions generate` for the case
+> where a real narration track exists.
+
+- **A cue is legible at frame 0 — literally `data-start="0"`.** `first_frame_text` grades the
+  frame, not the intent, so a cue that opens at 0.15s fails it. Frame 0 is the thumbnail.
+- **≤3 words per page, ≤7 words per cue.** Longer than that and the page turns faster than it reads.
+- **One cue at a time, ever.** Two simultaneous text objects is this format's version of clutter.
+### The caption standard is NOT this harness's to define
+
+The font regime, the size band, the safe zone and the legal caption backgrounds are **core Vidfarm
+standards**. Read them there and follow them; do not take a restatement from a format harness:
+
+| Where | What it covers |
+|---|---|
+| `vidfarm.cc/skill.md` → *Standards* → **Captions** | the one-paragraph rule: imported display font, size band, safe zone, emptiest part of the frame, 3–5-word cues, the four legal backgrounds |
+| installed `SKILL.md` → **"the TikTok-native caption standard"** | the same, with the `set_captions` presets named |
+| `references/editor-workflows.md` → **"Size → scaled to the line"** and **"Font → the composition regime"** | the numbers, the bundled font list, and why an un-imported font is the slop look |
+
+The parts that bind here, quoted rather than paraphrased: **the bundled display fonts only**
+(Montserrat 700–900 default, **TikTok Sans**, Abel, Source Code Pro, Yesteryear); **~36–64px on a
+1080-wide frame** — above ~64px is a *hook-word* size, one to three words on purpose; **the 8%–85%
+safe zone**; and **exactly one of four backgrounds** — `outline`, `plain`, active-word
+`spotlight`/`karaoke`, or a tight `highlight-solid` band.
+
+> ⚠️ I had this format running at **76px**, outside the band. Measured against the same cut, 76px
+> wrapped 2 of 18 pages and reached 85.5% of frame width; **64px wrapped none and reached 82%** —
+> better on both counts. When a local harness and the core standard disagree, check the standard is
+> not simply right first.
+
+#### What this format ADDS to the standard
+
+Three deltas, each earned, and each a *narrowing* of the standard rather than a departure from it:
+
+1. **Self-host the face; never `<link>` it, and set `font-display: block`.** The standard says use
+   an imported display font. It does not say how, and the obvious how is broken for rendering:
+   Google Fonts' own snippet ends in `&display=swap`, which draws a fallback first. A frame-capture
+   render screenshots inside that window — this shipped **Montserrat for all 666 frames** while the
+   stylesheet returned `200` and named TikTok Sans. Pull the `woff2`, `@font-face` it from disk,
+   `font-display: block`, and no fallback chain (a chain means a missing font becomes a *different*
+   font with nothing to tell you).
+2. **A tighter band than 8%–85%.** The safe zone says where text is *allowed*; the platform's own
+   UI covers part of it. For this format the working band is **y 15%–73%, x 14%–86%** — a subset,
+   not a contradiction. See *Subtitle placement* below for the chrome map.
+3. **Of the four legal backgrounds, this format uses `outline` and `plain`.** No phrase plate: the
+   `highlight-solid` band is legal everywhere but it is the third-party-editor tell on a
+   reaction-led cut. The active-word `pill` mechanic is the standard's `spotlight`/`karaoke`
+   highlight and is fine.
+
+⚠️ **One mechanic below is an extension, not a standard preset.** `underline` is not one of the four
+legal backgrounds. It reads native and renders fine, but treat it as this harness's own and expect
+`vidfarm qa` to have no opinion on it — if a director wants to stay strictly inside the core set,
+use `none`, `reveal`, `colour`, `pop` or `pill`.
+
+- **No plate. The text sits directly on the picture.** A translucent slab behind the phrase is the
+  loudest third-party-editor tell in the format — it is what makes a cut read as *made somewhere
+  else and uploaded*, and it gets worse the moment a page wraps to two lines, because the slab's
+  own edges become a second shape competing with the frame. TikTok's own captions have no plate.
+  Legibility comes from the letterform instead: **a dark stroke under the fill plus a soft diffuse
+  shadow.**
+  ```css
+  -webkit-text-stroke: 3px #000;  paint-order: stroke fill;   /* stroke OUTSIDE the glyph */
+  text-shadow: 0 3px 12px rgba(0,0,0,.42), 0 1px 3px rgba(0,0,0,.55);
+  ```
+  `paint-order: stroke fill` is the part people miss — without it the stroke paints *over* the
+  glyph and eats the face's counters, and TikTok Sans at weight 900 turns to mush.
+- **Still measure the band — the measurement now sets the STROKE, not a plate.** Sample the
+  composited luma and variance in the caption band across every scene (Appendix B). A calm dark
+  band survives on shadow alone; a bright busy one (a white UI, a lit face) needs the full 3px.
+  One value for the whole video.
+- **NOT the lower third. The lower third is under the platform's own UI.** Every platform pastes
+  chrome over your video that you never see in your own render:
+
+  | | blocked |
+  |---|---|
+  | top | 0–12% — status bar, "Following \| For You" tabs |
+  | bottom | 78–100% — username, post caption, music ticker, progress bar |
+  | right | 84–100% (roughly y 45–80%) — like / comment / share / profile rail |
+
+  So the **safe core is about y 15%–73%**, and the default every subtitle tool ships — a lower
+  third at y≈66 with a 14% box — puts its bottom half under the caption block. Put the caption box
+  at the **lowest position that still clears the chrome**: `--y 57` for a 14%-tall box.
+- **Keep the box narrow enough that a long line can't reach the rail.** Centred text needs a
+  symmetric box, so `--x 14 --width 72` (14%–86%) is the widest that stays clear. Then size the
+  type so pages mostly fit on one line inside it — measure, don't guess:
+  ```js
+  // in the render browser: how many pages wrap, and how far right do they reach?
+  [...document.querySelectorAll('[data-layer-kind="caption"]')].map(c => {
+    const w = [...c.querySelectorAll('[data-cap-word]')]
+    return { lines: c.querySelector('[data-vf-text-inline]').getClientRects().length,
+             right: Math.max(...w.map(x => x.getBoundingClientRect().right)) / 10.8 }})
+  ```
+  Measured on the reference build: 88px wrapped 7 of 18 pages and reached 85.7%, 76px wrapped 2 and
+  reached 85.0%, **64px wrapped none and reached 82.0%.** Smaller type that fits beats bigger type
+  that wraps into the rail — and 64px is the top of the standard's band anyway.
+- **Let the measurement rank the bands, but don't let it move the caption over a face.** Appendix G
+  scores every band in the safe core. It will usually report the TOP of the frame as calmest —
+  that reading means "forehead, hair and defocused background", and a caption there covers the
+  performance, which on this format is the content. Take the quiet band only when the subject
+  genuinely sits low in frame.
+- **Never repeat what the app already says on screen.** If the subtitle and the UI render the same
+  words, drop the subtitle. The demo beat is allowed to be almost caption-free — that is correct,
+  not a bug.
+
+---
+
+## The rules
+
+### Rule 1 — the reaction and the app must be about the same moment
+
+A surprised face cut against a beat where nothing surprising happened is worse than no cutaway. The
+face is a *label* for the frame before it. Choose the reaction after you have cut the demo, never
+before, and cut on the emotional beat rather than at a round timecode.
+
+### Rule 2 — align the demo CUT to the subtitle, not the subtitle to the demo
+
+The subtitle is fixed by the beat table; the demo recording is a long take you own every frame of.
+So when the subtitle names the query and the input is still empty, you do **not** move the cue —
+you move the in-point. Lay one frame per second of the composited device clip into a strip, read
+off the timecodes where the action actually happens (`input complete`, `result lands`,
+`scroll begins`), and solve for the in-point:
+
+```bash
+ffmpeg -i phone-demo.mp4 -vf "fps=1,scale=150:-1,tile=<N>x1" -frames:v 1 timeline.png
+```
+
+```
+in_point = <device-clip time of the action> - (<composition time the cue fires> - <beat start>)
+```
+
+Do this for the two anchors that matter — the moment the input is complete, and the moment the
+result appears — and the whole beat locks. Getting this wrong is the defect the format produces
+most often and the one an author is least likely to notice, because the subtitles read correctly
+and the footage reads correctly; only the two together are wrong.
+
+### Rule 3 — the demo shows one action, at real speed, uncut
+
+Speed-ramping dead time is fine and expected. Cutting away at the instant the product does its work
+is not — that is the exact frame the viewer is deciding on. One feature per video. A video covering
+four features teaches none.
+
+### Rule 4 — every number on screen was read off the demo footage
+
+Prices, counts, distances, names: quote what the recording actually shows, exactly. This format
+makes it easy to be honest, because the source of truth is playing in the same frame as the claim —
+and easy to be caught, for the same reason. A number in the subtitle that contradicts the number in
+the app is the defect this format produces most.
+
+### Rule 5 — concede one true, unflattering limit, in beat 6
+
+Coverage gaps, geography, price, what it can't do yet. Take it from the product's own site so it is
+defensible. Over the app, not on a card. It is not a disclaimer — it is the beat that makes the
+other twenty seconds believable.
+
+### Rule 6 — claim the mechanism, never the outcome
+
+Say what it does and what it costs. Don't promise the result. On money, health and appearance
+topics it is also the claim that draws platform enforcement.
+
+### Rule 7 — client work: nothing on screen the customer doesn't already say
+
+Every claim traceable to their own site or app. No real third party named in a negative light. Real
+names, faces and emails visible in their screenshots were a deliberate decision or they don't ship.
+If the customer's own example query is broken, tell them — don't quietly film a different one and
+let them discover it in the comments.
+
+### Rule 8 — production floor
+
+Butt cuts only · no logo, end card, URL or title card · no CTA button, pricing card, feature grid,
+benefit chip row, frosted panel or caption plate · nothing on screen looks clickable · the ask is a subtitle line.
+
+---
+
+## Bulk-generation notes
+
+The variant axis is **the query you type into the app**, paired with the reaction that matches it.
+Same product, same beats, same crop, same bed — five different things a person was actually looking
+for, and five faces that fit those five moments. That is five videos.
+
+Varying the *reaction clip* alone gives you one video five times, and the algorithm treats
+near-duplicates accordingly. Varying the *subtitle wording* alone is worse.
+
+**Vary the caption treatment across the batch too** — mechanic, accent, weight, size. Not because
+any one of them is better, but because thirty videos in identical captions read as one account
+running a template, and that is exactly the read you are trying to avoid. It costs nothing: the
+treatment is four flags.
+
+Because beats 3–6 are one tracked composite, a variant costs one browser recording plus one
+tracker pass — roughly two minutes of compute and $0. That is the reason this format is worth
+building a harness for at all.
+
+Use `vidfarm dedupe <file> --variants N` when the same cut posts to more than one account.
+
+---
+
+## Pre-flight checklist
+
+**Sourcing**
+- [ ] The reaction raws came off the `ugc-reaction` shelf and were chosen from a contact sheet, not from a description alone
+- [ ] ONE actor carries every reaction beat, cast from their `actor_<uuid>` set — not four different faces under a first-person voiceover
+- [ ] The actor was chosen for their ARC (a take per beat), not for one good-looking clip
+- [ ] The actor id was read off a card in THIS build and confirmed to return that person's clips
+- [ ] The shelf was paginated with `cursor`, not `offset` — you saw all of it, not page 1 twice
+- [ ] Beats 1 and 2 are two different people
+- [ ] The greenscreen raw's `sourceType` is `Display Greenscreen` — no identifiable celebrity or character is being keyed into a customer's ad
+- [ ] The demo query was run by hand and confirmed to return results before filming
+- [ ] The demo was recorded at the device screen's aspect ratio
+- [ ] Every 16:9 reaction raw's 9:16 crop was chosen off a still, not centred by default
+
+**The insert**
+- [ ] The demo's in-point was solved against the cue times — the input completes while its own subtitle is up, and the result lands on the cue that names it
+- [ ] The insert is tracked per frame — scrubbed at 3 points, the app does not slide under the bezel
+- [ ] The insert is rotation-fitted — no green wedge down any edge, at any frame
+- [ ] The thumb and the bezel are ON TOP of the app, not painted over
+- [ ] The device beats are punched in, and the UI is readable at phone scale
+- [ ] Every device beat uses the same crop
+
+**Stickers** (skip if none — none is a valid answer)
+- [ ] The product's own noun appears on screen at least twice — not just its UI
+- [ ] Every sticker either annotates something on screen or supplies that missing subject; none is a badge, chip, icon or logo
+- [ ] Any sticker that a viewer would have to puzzle over was cut — a confusing sticker is worse than none
+- [ ] Cutouts were checked for partial alpha (hollow art → flat key, solid subject → smart key) and despilled
+- [ ] Each sticker's `fit` matches its job — subject `contain`, annotation `fill` — checked on a frame, not in the markup
+- [ ] One on screen at a time, and not on every beat
+- [ ] Each sticker's window ends before the UI underneath it moves — checked frame by frame
+- [ ] Hand-drawn, not geometric; wrapped in a `div.clip` so the engine shows and hides it
+
+**Anatomy**
+- [ ] Beat 1 is a situation, not a product claim; frame 0 works as a standalone thumbnail
+- [ ] The product first appears in beat 3
+- [ ] The result plays uncut and long enough to be believed
+- [ ] The video cuts back to a face after the payoff, and back to the app after the face
+- [ ] One honest limit, in beat 6, over the app
+- [ ] One comment ask, in the final beat AND in the post caption
+- [ ] Exactly one feature is covered
+
+**Audio**
+- [ ] The mode was chosen deliberately (silent, or narrated over a ducked bed)
+- [ ] Every reaction raw is muted — no face is visibly saying words the subtitles don't
+- [ ] The demo is muted; the customer's own narration does not ship
+- [ ] Narrated: one pinned `--voice` and one `--style` string across every line
+- [ ] Narrated: captions came from the VO transcript, and the DISPLAY text is the script, not the transcript
+- [ ] Narrated: speech sits 12–15 dB over the bed, measured on the STEMS
+- [ ] Narrated: the payoff beat has a stretch with no speech over it
+- [ ] The bed is NOT in the composition — the render is the voiceover-only master
+- [ ] Both cuts exported from one render; the `-vo` and `-music` video streams are identical (unless watermarked)
+- [ ] The handoff names the `-vo` cut as the one to publish, with platform audio added at upload
+- [ ] The bed is CC0 (or its attribution requirement was accepted deliberately)
+- [ ] The bed was measured ON THE RENDER, not on the stem: ~-16 LUFS, peak < -1 dBFS (`data-volume` multiplies it)
+- [ ] The handoff says whether the bed ships or gets replaced with platform audio at upload
+
+**Subtitles**
+- [ ] The caption box sits inside the platform-safe core (y 15–73%, x 14–86%) — NOT the lower third
+- [ ] Page wrapping and right-edge reach were measured in the browser; nothing crosses into the action rail
+- [ ] The core caption standard was followed (bundled font, ~36–64px, safe zone, one of the four backgrounds) — not a harness restatement of it
+- [ ] The face is self-hosted with `font-display: block` and no fallback chain
+- [ ] `document.fonts.check('900 88px "TikTok Sans"')` was asserted true in the render browser, not assumed
+- [ ] A cue is legible at frame 0 (`data-start="0"`, not 0.15)
+- [ ] ≤3–4 words per page, one cue on screen at a time, timed to the voice
+- [ ] If the mechanic is accented, the words were confirmed to FIRE in the render — 7 consecutive frames from inside one cue, not identical (skip for `none`, where identical frames are correct)
+- [ ] No plate, panel or translucent slab behind the captions — stroke + shadow only
+- [ ] `paint-order: stroke fill` is set, so the stroke sits outside the glyph
+- [ ] The active-word highlight is a colour swap, not a scale — no two words ever touch mid-pop
+- [ ] The band was measured across every scene and ONE stroke weight was chosen for the whole video
+- [ ] The caption treatment was CHOSEN for this video (mechanic, accent, weight, size, case) — not inherited from the last one
+- [ ] The accent was contrast-checked against the measured band; if it failed, it moved to a `pill` background rather than staying as type colour
+- [ ] In a batch: this video's caption treatment differs from its siblings
+- [ ] No cue repeats words the app already has on screen in that frame
+- [ ] Every number in a cue matches the number visible in the demo footage
+
+**Whole-video review** — on the render, not the plan
+- [ ] A contact sheet of ~12 stills was read as one image: one crop convention, one type scale, one accent colour
+- [ ] The reaction beats and the device beats look like the same video — not two edits spliced
+- [ ] Pacing is deliberate, not N identically-long beats; no join is jarring
+- [ ] No frame rests empty >0.5s; nothing runs after the last word for more than ~1.2s
+- [ ] Frames from two different scenes were compared (a frozen render passes duration and frame-count checks)
+- [ ] Audio verified by measurement, not by "it sounds fine"
+- [ ] The MP4's timestamp is newer than the last edit — you reviewed THIS cut, not the previous one
+
+---
+
+## Diagnosing a flop
+
+| What the numbers say | Weak beat | Fix |
+|---|---|---|
+| Barely any views | 1 | The hook is a product claim, or frame 0 is a phone instead of a face |
+| Views, mass exit at 3–6s | 3 | The app arrived before the situation landed, or the move is not legible |
+| Watched through, no reaction | 4 | The result was described in a subtitle instead of shown playing |
+| Good retention, dead comments | 7 | No ask, or the ask was "thoughts?" |
+| Comments arguing it's fake | 5 / audio | A reaction that didn't match its frame, or an unmuted raw |
+
+**Vary one beat at a time.** A batch where the query, the faces and the bed all changed at once
+teaches you nothing.
+
+---
+
+## Appendix A — `track-insert.py`
+
+Free, local, no account, numpy + ffmpeg only. Fits the demo to the device screen's own axes every
+frame and pastes by mask.
+
+```python
+#!/usr/bin/env python3
+"""
+Composite an app-demo recording INTO the green screen of a device raw.
+
+usage: track-insert.py <device.mp4> <demo.mp4> <out.mp4> [--demo-start SEC]
+"""
+import subprocess, sys, numpy as np
+
+device, demo, out = sys.argv[1], sys.argv[2], sys.argv[3]
+demo_start = 0.0
+if "--demo-start" in sys.argv:
+    demo_start = float(sys.argv[sys.argv.index("--demo-start") + 1])
+
+def probe(f, *keys):
+    r = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v",
+                        "-show_entries", "stream=" + ",".join(keys),
+                        "-of", "default=nw=1:nk=1", f], capture_output=True, text=True)
+    return r.stdout.split()
+
+W, H, fr = probe(device, "width", "height", "r_frame_rate")
+W, H = int(W), int(H)
+num, den = fr.split("/")
+FPS = round(float(num) / float(den), 3)
+
+PW, PH = 720, 1530          # demo pre-scaled ONCE with a good filter; per-frame we only
+                            # nearest-resample down a few percent, so there is no shimmer
+demo_pipe = subprocess.Popen(
+    ["ffmpeg", "-v", "error", "-ss", str(demo_start), "-i", demo,
+     "-vf", f"fps={FPS},scale={PW}:{PH}:flags=lanczos", "-pix_fmt", "rgb24",
+     "-f", "rawvideo", "-"], stdout=subprocess.PIPE)
+dev_pipe = subprocess.Popen(
+    ["ffmpeg", "-v", "error", "-i", device, "-pix_fmt", "rgb24", "-f", "rawvideo", "-"],
+    stdout=subprocess.PIPE)
+enc = subprocess.Popen(
+    ["ffmpeg", "-y", "-v", "error", "-f", "rawvideo", "-pix_fmt", "rgb24",
+     "-s", f"{W}x{H}", "-r", str(FPS), "-i", "-", "-an",
+     "-c:v", "libx264", "-pix_fmt", "yuv420p", "-crf", "18", out],
+    stdin=subprocess.PIPE)
+
+def dilate(m, n=2):
+    for _ in range(n):
+        m = (m | np.roll(m, 1, 0) | np.roll(m, -1, 0)
+               | np.roll(m, 1, 1) | np.roll(m, -1, 1))
+    return m
+
+FSZ, DSZ = W * H * 3, PW * PH * 3
+fit = None
+last_demo = None
+n = 0
+while True:
+    raw = dev_pipe.stdout.read(FSZ)
+    if len(raw) < FSZ:
+        break
+    d = demo_pipe.stdout.read(DSZ)
+    if len(d) < DSZ:
+        d = last_demo               # demo ran out — hold its last frame
+    last_demo = d
+    f = np.frombuffer(raw, np.uint8).reshape(H, W, 3).astype(np.float32)
+    dm = np.frombuffer(d, np.uint8).reshape(PH, PW, 3).astype(np.float32)
+
+    r, g, b = f[..., 0], f[..., 1], f[..., 2]
+    greenness = g - np.maximum(r, b)
+    core = (greenness > 55) & (g > 80)
+
+    if core.sum() > 5000:
+        ys, xs = np.nonzero(core)
+        cx, cy = xs.mean(), ys.mean()
+        cov = np.cov(np.stack([xs - cx, ys - cy]))      # the screen's own axes
+        w_, v_ = np.linalg.eigh(cov)
+        major = v_[:, np.argmax(w_)]
+        if major[1] < 0:
+            major = -major
+        sn, cs = major[0], major[1]
+        px, py = xs - cx, ys - cy
+        v = px * sn + py * cs                            # along the long axis
+        u = px * cs - py * sn                            # across it
+        lenV = (np.percentile(v, 99.5) - np.percentile(v, 0.5)) / 2
+        lenU = (np.percentile(u, 99.5) - np.percentile(u, 0.5)) / 2
+        expect = lenV * (PW / PH)     # a thumb eats one side, so trust the LONG axis
+        if lenU < expect * 0.92:
+            lenU = expect
+        fit = (cx, cy, cs, sn, lenU, lenV)
+
+    if fit is None:
+        enc.stdin.write(f.astype(np.uint8).tobytes()); n += 1; continue
+    cx, cy, cs, sn, lenU, lenV = fit
+
+    alpha = np.clip((greenness - 25) / 30.0, 0, 1)
+    paint = dilate(core, 2) | (alpha > 0.15)             # paste by MASK, not by box
+    ys, xs = np.nonzero(paint)
+    if len(xs) == 0:
+        enc.stdin.write(f.astype(np.uint8).tobytes()); n += 1; continue
+
+    px, py = xs - cx, ys - cy
+    vv = px * sn + py * cs
+    uu = px * cs - py * sn
+    sx = ((uu / lenU + 1) * 0.5 * (PW - 1)).astype(np.int32).clip(0, PW - 1)
+    sy = ((vv / lenV + 1) * 0.5 * (PH - 1)).astype(np.int32).clip(0, PH - 1)
+    f[ys, xs] = dm[sy, sx]                               # opaque: no green survives
+
+    enc.stdin.write(np.clip(f, 0, 255).astype(np.uint8).tobytes())
+    n += 1
+
+enc.stdin.close(); enc.wait()
+print(f"{out}  {n} frames @ {FPS}fps  ({n/FPS:.1f}s)")
+```
+
+**Tuning it.** If the device raw's plate is a darker or bluer green, drop `greenness > 55` toward
+40. If the demo comes out mirrored or 90° out, the PCA picked the short axis — that only happens on
+a landscape device, and the fix is to swap `PW`/`PH`. If the screen is only *partly* green (a
+notch, a bezel reflection), raise the dilation from 2 to 3.
+
+## Appendix B — measuring the caption band
+
+Run this before you choose a caption treatment, on every scene, and put the numbers in the handoff.
+
+```python
+import subprocess, sys, numpy as np
+for f in sys.argv[1:]:
+    p = subprocess.run(["ffmpeg","-v","error","-i",f,"-vf","fps=1,scale=270:480",
+                        "-pix_fmt","rgb24","-f","rawvideo","-"], capture_output=True)
+    b = np.frombuffer(p.stdout, np.uint8); n = len(b)//(270*480*3)
+    fr = b[:n*270*480*3].reshape(n,480,270,3).astype(np.float32)
+    luma = 0.2126*fr[...,0] + 0.7152*fr[...,1] + 0.0722*fr[...,2]
+    band = luma[:, 298:374, :]        # the 62-78% lower third
+    print(f"{f}  luma={band.mean():.1f}  var={band.std():.1f}")
+```
+
+| Band | Treatment |
+|---|---|
+| luma < ~70, var < ~42 | White type, shadow only — the stroke can drop to 1–2px |
+| luma > ~160, var < ~42 | White type, full 3px stroke; the shadow does the separating |
+| anything else | White type, full 3px stroke + shadow — this format is nearly always this row |
+
+**Never a plate.** The measurement chooses how much stroke, not whether to put a box behind the
+words. See *Subtitle DNA*.
+
+## Appendix C — `srt-to-cues.py` (one caption layer per SRT cue)
+
+Use this instead of `vidfarm captions generate --srt` whenever the cue times are pinned to cuts.
+It emits the same word-pop markup the CLI emits, and fixes the two things that bite in this format:
+it **keeps every SRT cue as its own page** (no word crosses a cut), and it **carries its own
+`@keyframes`** so the word-by-word pop is a property of the file rather than of whichever render
+engine version picks it up.
+
+```python
+#!/usr/bin/env python3
+"""
+Write word-pop caption layers into a HyperFrames composition, ONE LAYER PER SRT CUE.
+
+`vidfarm captions generate --srt` flattens the SRT into a single word stream and
+re-pages it by --max-words, so words hop across cue boundaries ("the dish instead"
++ "chili crisp" becomes "dish instead chili crisp"). When your cue times are pinned
+to CUTS rather than to speech, that is fatal. This emits the same markup the CLI
+emits, but keeps each SRT cue as its own page.
+
+usage: srt-to-cues.py <composition.html> <captions.srt|cues.json>
+         [--y 57] [--x 14] [--width 72] [--font-size 64] [--weight 900]
+         [--highlight none|reveal|colour|pop|pill|underline] [--active-color '#FFD500']
+         [--font 'TikTok Sans'] [--plate none|phrase] [--stroke 3]
+         [--no-uppercase] [--track 5]
+
+WHAT IS FIXED vs WHAT VARIES. Native means the FONT is TikTok Sans, the captions
+sit on the picture inside the platform-safe core, and the highlight fires
+word-by-word. It does NOT mean one colour, one case, one size and one mechanic on
+every video a studio ships — that is a house style, and at volume it reads as a
+content farm. Vary --highlight / --active-color / --weight / --font-size / --y
+between videos; hold one combination for the length of a single video.
+"""
+import re, sys, html, json
+
+args = sys.argv[1:]
+comp, srt = args[0], args[1]
+def opt(name, default):
+    return args[args.index(name) + 1] if name in args else default
+Y          = opt("--y", "66")
+X          = opt("--x", "8")
+WIDTH      = opt("--width", "84")
+FONT_SIZE  = opt("--font-size", "64")   # core standard: ~36-64px on a 1080 frame
+ACTIVE     = opt("--active-color", "#FFD500")
+TRACK      = opt("--track", "5")
+FONT       = opt("--font", "TikTok Sans")
+WEIGHT     = opt("--weight", "900")        # 700 | 800 | 900
+HILITE     = opt("--highlight", "colour")  # none | reveal | colour | pop | pill | underline
+PLATE_MODE = opt("--plate", "none")        # none | phrase
+STROKE     = opt("--stroke", "3")          # px of dark outline, plate-free mode
+
+# TikTok's own captions sit DIRECTLY on the picture. A translucent slab behind
+# the phrase is a third-party-editor tell — it is the thing that makes a cut read
+# as "made somewhere else and uploaded", and it gets worse the moment two lines
+# wrap, because the slab's own edges become a shape competing with the frame.
+# Legibility without a plate comes from the letterform itself: a dark stroke
+# under the fill (paint-order keeps it outside the glyph, so the face stays
+# crisp) plus a soft diffuse shadow to lift it off a busy background.
+if PLATE_MODE == "phrase":
+    PLATE = ("padding:0.07em 0.46em 0.09em;border-radius:0.32em;"
+             "background:rgba(0,0,0,0.34);")
+    BG_STYLE = "highlight-translucent"
+else:
+    PLATE = "padding:0;background:transparent;"
+    BG_STYLE = "outline"
+# NOTE: no "sans-serif" / Montserrat in the stack on purpose. A fallback chain
+# means a missing font renders as a DIFFERENT font and nothing tells you — the
+# cut just quietly stops looking native. Self-host the face (see the @font-face
+# in the composition head) so there is nothing to fall back FROM.
+UPPER      = "--no-uppercase" not in args
+
+def tsec(t):
+    h, m, rest = t.split(":")
+    s, ms = rest.split(",")
+    return int(h) * 3600 + int(m) * 60 + int(s) + int(ms) / 1000
+
+# Two input shapes. An SRT carries page text only, so word timings are ESTIMATED
+# from word length — right for a silent, subtitle-only cut where the cues are
+# pinned to picture. A cues.json (from vo-align.py) carries a real time per word,
+# which is what you must use once a voiceover exists: a karaoke highlight that is
+# 200ms off the voice is more distracting than no highlight at all.
+cues = []
+if srt.endswith(".json"):
+    for p in json.load(open(srt)):
+        cues.append((p["start"], p["end"],
+                     " ".join(w["text"] for w in p["words"]), p["words"]))
+else:
+    for block in re.split(r"\n\s*\n", open(srt).read().strip()):
+        lines = [l for l in block.strip().splitlines() if l.strip()]
+        if len(lines) < 2:
+            continue
+        tl = next((l for l in lines if "-->" in l), None)
+        if not tl:
+            continue
+        a, b = [x.strip() for x in tl.split("-->")]
+        text = " ".join(lines[lines.index(tl) + 1:]).strip()
+        if text:
+            cues.append((tsec(a), tsec(b), text, None))
+if cues:
+    cues[0] = (0.0, cues[0][1], cues[0][2], cues[0][3])   # frame 0 must carry text
+
+def layer(i, start, dur, text, timed=None):
+    words = text.split()
+    # spread the cue's time across its words by length, with a floor so short
+    # words still get a readable beat
+    weights = [max(len(w), 2) for w in words]
+    total = sum(weights)
+    # animation-delay is measured from PAGE time, not from the layer's own start.
+    # A cue at 9.1s with a relative delay has already finished animating by the
+    # time it becomes visible, and every word renders in its end state — which
+    # looks exactly like "the animation is broken". So the delay is ABSOLUTE
+    # (cue start + word offset). data-word-start/end stay relative, which is the
+    # convention the CLI's own markup uses.
+    #
+    # The highlight is COLOUR plus a small vertical lift — deliberately no
+    # horizontal scale. A scaling word grows from its centre into its neighbour:
+    # "a restaurant" renders as "arestaurant" on the exact beat the word pops,
+    # and a text stroke eats the remaining gap from both sides. Padding it apart
+    # only trades one defect (collision) for another (letterspaced display type
+    # that no longer reads as speech). TikTok's own word highlight is a colour
+    # swap; keeping it that way makes the collision impossible instead of tuned.
+    t, spans = 0.0, []
+    for j, (w, wt) in enumerate(zip(words, weights)):
+        if timed:                       # real word times from the voiceover
+            a0 = timed[j]["start"] - start
+            d = max(timed[j]["end"] - timed[j]["start"], 0.12)
+        else:                           # estimated from word length
+            a0, d = t, dur * wt / total
+        # A highlight should last about as long as the word is spoken — except a
+        # plain REVEAL, which is an on-switch, not a fade: stretched across a
+        # 0.4s word it reads as the caption struggling to load.
+        adur = 0.12 if HILITE == "reveal" else d
+        spans.append(
+            f'<span data-cap-word="true" data-word-start="{a0:.3f}" '
+            f'data-word-end="{a0+d:.3f}" style="animation-delay:{start+a0:.3f}s;'
+            f'animation-duration:{adur:.3f}s">{html.escape(w)}</span>')
+        t += dur * wt / total
+    inner = " ".join(spans)
+    upper = "text-transform:uppercase;" if UPPER else ""
+    return (
+      f'<div class="clip" id="element_cap_srt_{i}" data-hf-id="element_cap_srt_{i}" '
+      f'data-layer-mode="publish" data-layer-kind="caption" data-start="{start:.3f}" '
+      f'data-duration="{dur:.3f}" data-track-index="{TRACK}" '
+      f'data-label="{html.escape(text, quote=True)}" '
+      f'data-text-background-style="{BG_STYLE}" data-text-background-color="#000000" '
+      f'data-font-family="{FONT}" data-caption-animation="word-pop" '
+      f'data-caption-uppercase="{1 if UPPER else 0}" '
+      f'style="position:absolute;left:{X}%;top:{Y}%;width:{WIDTH}%;height:14%;z-index:{TRACK};'
+      f'opacity:1;display:flex;align-items:center;justify-content:center;padding:3px;'
+      f"font-family:'{FONT}', 'Noto Color Emoji';font-weight:{WEIGHT};"
+      f'line-height:1.18;text-align:center;font-size:{FONT_SIZE}px;color:#ffffff;'
+      f'background:transparent;--vf-cap-active:{ACTIVE};{upper}overflow:visible">'
+      f'<span data-vf-text-lines="true" style="display:block;max-width:100%;text-align:inherit;'
+      f'line-height:1.18;white-space:pre-wrap;overflow:visible">'
+      f'<span data-vf-text-inline="true" style="display:inline;box-decoration-break:clone;'
+      f'-webkit-box-decoration-break:clone;line-height:inherit;{PLATE}'
+      f"font-family:'{FONT}', 'Noto Color Emoji';font-weight:{WEIGHT};color:#ffffff\">"
+      f'{inner}</span></span></div>')
+
+doc = open(comp).read()
+# The word-by-word pop itself. The render engine is SUPPOSED to drive this off
+# data-caption-animation + the per-word animation-delay/duration, and on some
+# versions it silently does not — the cue renders as one static block and the
+# video ships without the thing that makes it read as native. Owning the
+# keyframes here makes the animation a property of the file, not of the engine.
+#
+# The whole phrase is visible for the cue's whole life and the ACTIVE word pops
+# — that is TikTok's convention, and it is also the only version that survives a
+# single shared plate behind the phrase. A progressive fade-in leaves an empty
+# translucent box sitting on screen ahead of the words, which reads as a loading
+# state. So: fill-mode FORWARDS, base state is the settled state, and the
+# keyframes describe only the word's own moment.
+LEGIBILITY = ("" if PLATE_MODE == "phrase" else
+  f"-webkit-text-stroke:{STROKE}px #000;paint-order:stroke fill;"
+  "text-shadow:0 3px 12px rgba(0,0,0,.42),0 1px 3px rgba(0,0,0,.55);")
+
+# ── The highlight mechanic ───────────────────────────────────────────────────
+# All four are TikTok-native; none of them is "the" house style. Vary this
+# ACROSS a batch and hold one for the length of a single video.
+#
+# Every one of them is engineered to take NO HORIZONTAL SPACE, because an
+# inline-block word that grows sideways eats the gap beside it and "a restaurant"
+# renders as "arestaurant" on the exact beat the word fires. `pop` scales on Y
+# only for that reason; `pill` and `underline` sit inside the word's own box.
+_HILITE = {
+  "colour": """
+  0%{transform:translateY(-.05em);color:var(--vf-cap-active,#FFD500)}
+  45%{transform:translateY(0);color:var(--vf-cap-active,#FFD500)}
+  80%{transform:translateY(0);color:var(--vf-cap-active,#FFD500)}
+  100%{transform:translateY(0);color:#ffffff}""",
+  "pop": """
+  0%{transform:scaleY(1.18) translateY(-.04em);color:var(--vf-cap-active,#FFD500)}
+  40%{transform:scaleY(1.05) translateY(0);color:var(--vf-cap-active,#FFD500)}
+  75%{transform:scaleY(1);color:var(--vf-cap-active,#FFD500)}
+  100%{transform:scaleY(1);color:#ffffff}""",
+  "pill": """
+  0%{background:var(--vf-cap-active,#FFD500);color:#111;transform:translateY(-.04em)}
+  70%{background:var(--vf-cap-active,#FFD500);color:#111;transform:translateY(0)}
+  100%{background:transparent;color:#ffffff;transform:translateY(0)}""",
+  "underline": """
+  0%{box-shadow:inset 0 -.10em 0 0 var(--vf-cap-active,#FFD500);color:#ffffff}
+  70%{box-shadow:inset 0 -.22em 0 0 var(--vf-cap-active,#FFD500);color:#ffffff}
+  100%{box-shadow:inset 0 -.22em 0 0 transparent;color:#ffffff}""",
+  # PLAIN — no accent at all. This is TikTok's own auto-caption look, and it is
+  # the right choice more often than the coloured ones: over busy footage, over a
+  # UI that already has its own colours, and on any beat where the words should
+  # carry no emphasis of their own. "reveal" is still word-timed (each word turns
+  # on at its own moment); "none" turns the whole page on at once and lets the
+  # page turns do the work.
+  "reveal": """
+  0%{opacity:0}
+  100%{opacity:1}""",
+  "none": None,
+}
+if HILITE not in _HILITE:
+    sys.exit(f"--highlight must be one of {', '.join(_HILITE)}")
+# the pill needs its own breathing room and a radius; the others must not have it
+_PILL_BOX = ("padding:.02em .16em;border-radius:.18em;" if HILITE == "pill"
+             else "padding:0 .02em;")
+
+if _HILITE[HILITE] is None:
+    # plain, page-timed: no per-word animation at all
+    POP_CSS = f"""
+[data-cap-word]{{display:inline-block;{_PILL_BOX}{LEGIBILITY}}}
+"""
+else:
+    _EASE = "linear" if HILITE == "reveal" else "cubic-bezier(.2,.9,.3,1.1)"
+    _FILL = "both" if HILITE == "reveal" else "forwards"
+    POP_CSS = f"""
+[data-cap-word]{{display:inline-block;{_PILL_BOX}animation-name:vfWordPop;
+  {LEGIBILITY}
+  animation-fill-mode:{_FILL};animation-timing-function:{_EASE}}}
+@keyframes vfWordPop{{{_HILITE[HILITE]}
+}}
+"""
+def strip_cues(h):
+    """Remove existing caption layers by BALANCING <div> tags — a regex that
+    guesses the closing sequence silently leaves the old cues in place, and you
+    end up rendering two caption tracks stacked on each other."""
+    out, i = [], 0
+    while True:
+        j = h.find('<div class="clip" id="element_cap_', i)
+        if j < 0:
+            out.append(h[i:]); break
+        out.append(h[i:j])
+        depth, k = 0, j
+        while k < len(h):
+            if h.startswith("<div", k):
+                depth += 1; k += 4
+            elif h.startswith("</div>", k):
+                depth -= 1; k += 6
+                if depth == 0:
+                    break
+            else:
+                k += 1
+        i = k
+    return "".join(out)
+
+doc = strip_cues(doc)
+# strip any PREVIOUS pop CSS by shape, not by its exact text — otherwise tuning
+# the keyframes appends a second copy and the older rule wins the cascade
+doc = re.sub(r'\n?\[data-cap-word\]\{.*?@keyframes vfWordPop\{.*?\}\}\n?', "", doc, flags=re.S)
+if "</style>" in doc:
+    doc = doc.replace("</style>", POP_CSS + "</style>", 1)
+else:
+    doc = doc.replace("</head>", f"<style>{POP_CSS}</style></head>", 1)
+blocks = "\n".join(layer(i, a, b - a, t, wd) for i, (a, b, t, wd) in enumerate(cues))
+idx = doc.rfind("</div>")
+doc = doc[:idx] + blocks + "\n" + doc[idx:]
+open(comp, "w").write(doc)
+print(f"wrote {len(cues)} caption cues, one per SRT cue")
+for a, b, t, _ in cues:
+    print(f"  {a:6.2f} -> {b:6.2f}  {t}")
+```
+
+## Appendix D — rendering notes
+
+- **Render with the standalone `hyperframes` CLI, not only `vidfarm render local`.** The copy of
+  hyperframes bundled inside `vidfarm-devcli` can lag the released one, and a stale engine can abort
+  the render at *Extracting video frames* with `captured 0 of expected N frames` on media that is
+  perfectly valid. Check both versions (`hyperframes doctor`, `vidfarm doctor`) before you spend an
+  hour re-encoding footage that was never the problem.
+- **Pass `--video-frame-format png` on this format.** Every device beat is a UI recording, and JPEG
+  frame extraction softens small type exactly where the payoff lives.
+- **Hand-authored `<video class="clip">` layers render fine and grade as zero.** `vidfarm qa` counts
+  scenes off `data-layer-kind`, so a composition you wrote by hand reports `scenes: 0` and
+  `first_frame_visual: black` while rendering perfectly. Give every media layer the attributes
+  `vidfarm place` writes — `data-layer-kind="video"|"audio"`, `data-layer-mode="publish"`,
+  `data-hf-id`, `data-end`, `data-label`, `data-volume` — and the same file grades correctly. This
+  is a reporting bug in your markup, not in the video, and it is easy to "fix" in the wrong place.
+- `hyperframes render` reads `index.html`; `vidfarm` writes and lints `composition.html`. Keep the
+  two in sync (`cp composition.html index.html`) or you will render a stale cut.
+- **`[sub_timeline_readiness_timeout] … did not become ready within 45000ms` is benign here.** This
+  format has no GSAP timeline — the motion is CSS keyframes and video playback — so there is no
+  sub-timeline to become ready. The render completes and is correct. Don't chase it.
+- **Check the output file's timestamp, not the exit code.** A backgrounded render can exit 0 having
+  written nothing. `ls -la` the MP4 and confirm it is newer than your last edit before you review
+  it — otherwise you will grade the previous cut and conclude your fix didn't work.
+
+## Appendix E — a filled-in beat table
+
+One 22.2s cut built end to end against this file, for a dish-search product with 140 restaurants
+indexed. It is here so the beat table above has a shape, not so you copy the words.
+
+| # | Beat | t | Stream | Subtitle |
+|---|---|---|---|---|
+| 1 | Hook | 0.0–2.6 | Reaction — woman, hand on head, confused | "I didn't want" / "a restaurant" |
+| 2 | Wrong way | 2.6–4.8 | Reaction — man at a laptop, disbelief | "Google gave me" / "a list of fifty" |
+| 3 | Move | 4.8–9.1 | Device — search field, typing | "So I searched" / "the dish instead" / "chili crisp" |
+| 4 | Result | 9.1–14.6 | Device — results list | "It read the menus" / "not the reviews" / "I just picked one" |
+| 5 | Face | 14.6–16.8 | Reaction — hand over mouth, surprise | "Nine dollars" / "Moody Tongue" |
+| 6 | Scope | 16.8–19.4 | Device — results still scrolling | "NYC only" / "140 restaurants" |
+| 7 | Bait | 19.4–22.2 | Reaction — smiling | "Comment the dish" / "you can never find" |
+
+Three things in that table are the harness working rather than the writer working:
+
+- **Beat 4 says "I just picked one" instead of naming the dish and the price.** The app is showing
+  the dish and the price in that same frame. Naming them would be the caption reading the screen
+  aloud. The read-out is deferred to **beat 5**, where the footage is a face and there is nothing
+  to duplicate — which is also where it lands hardest.
+- **Beat 6 is the customer's own published number, used against them.** "140 restaurants" is a
+  small index and saying so out loud is what makes the previous fifteen seconds credible.
+- **Beat 2 characterises a search result, it does not name a competitor.** "A list of fifty" is a
+  true thing about what happens; naming a named product doing something bad is Rule 7.
+
+## Appendix F — `vo-align.py` (captions from the voiceover, in narrated mode)
+
+Once a voice exists, captions are no longer a design decision — they are a synchronisation problem.
+This transcribes each beat's VO clip locally (free, keyless whisper), places it at that beat, and
+emits `cues.json`: balanced pages of ≤3 words, each word carrying an absolute timestamp. Feed that
+straight to Appendix C in place of the SRT.
+
+```bash
+# beats.txt — one line per beat:  <clip.wav>|<place-at-seconds>|<the script you fed the TTS>
+python3 vo-align.py vo/beats.txt cues.json --max-words 3
+python3 srt-to-cues.py composition.html cues.json --font "TikTok Sans" --font-size 88 --y 66
+```
+
+**Timing from the transcript, TEXT from the script.** This split is the whole design. Local STT
+mishears proper nouns precisely where this format needs them — a real run turned
+*"Nine dollars. Moody Tongue."* into *"$9.00 multi-tongue"* — and a caption that ships the
+mishearing is worse than no caption. So the words on screen are always the ones you wrote for the
+TTS; only their timings come from what was heard. Where the transcript's word count matches the
+script's, the two are zipped word-for-word and the sync is exact (6 of 7 beats on the reference
+build); where it doesn't, the script's words are distributed across the *measured* speech span,
+which is still far better than guessing. The script prints which path each beat took — read it.
+
+**Write the script line the way you want it on screen.** "140 restaurants" and "a hundred forty
+restaurants" sound identical and page very differently; the first is two words and one clean page,
+the second breaks as "A HUNDRED AND / FORTY RESTAURANTS". You control this for free at the moment
+you write the TTS input, and not at all afterwards.
+
+**Balance pages inside a sentence.** Fixed-size chunking leaves one-word orphans — a 7-word
+sentence at 3 words a page gives `3,3,1`, and a single word alone for 400ms reads as a flicker
+rather than as emphasis. Split into `ceil(n/max)` pages of as-equal-as-possible size instead
+(`3,2,2`), and never let a page run across a full stop.
+
+```python
+#!/usr/bin/env python3
+"""
+Turn per-beat voiceover clips into caption pages with REAL word timings.
+
+With a voiceover in the mix, captions stop being a design decision and become a
+synchronisation problem: they must be verbatim and they must sit on the word.
+
+Two halves, and keeping them apart is the whole point:
+
+  * TIMING comes from the transcript. Where the transcript's word count matches
+    the script's, the two are zipped word for word — exact. Where it doesn't,
+    the script's words are distributed across the MEASURED speech span, which is
+    still far better than guessing at a duration.
+  * TEXT comes from the SCRIPT you fed the TTS, never from the transcript. Local
+    STT mishears proper nouns exactly where this format needs them most — a real
+    run turned "Nine dollars. Moody Tongue." into "$9.00 multi-tongue" — and a
+    caption that ships the mishearing is worse than no caption at all.
+
+Input:  a beats file, one line per beat:  <clip.wav>|<place-at-seconds>|<script>
+Output: cues.json — pages of <=MAXW words, each word carrying an absolute time.
+
+usage: vo-align.py <beats.txt> <out.json> [--max-words 3]
+"""
+import json, re, subprocess, sys, os
+
+beats_file, out_path = sys.argv[1], sys.argv[2]
+MAXW = int(sys.argv[sys.argv.index("--max-words") + 1]) if "--max-words" in sys.argv else 3
+
+def transcribe(wav):
+    base = os.path.splitext(wav)[0] + ".stt"
+    subprocess.run(["vidfarm", "stt", wav, "--engine", "whisper", "--out", base],
+                   capture_output=True)
+    return json.load(open(base + ".json"))["words"]
+
+pages, report = [], []
+for raw in open(beats_file):
+    raw = raw.strip()
+    if not raw or raw.startswith("#"):
+        continue
+    wav, at, script = [p.strip() for p in raw.split("|", 2)]
+    at = float(at)
+    heard = transcribe(wav)
+    if not heard:
+        continue
+    span0, span1 = heard[0]["start"], heard[-1]["end"]
+    script_words = script.split()
+
+    if len(heard) == len(script_words):
+        timed = [{"text": s, "start": h["start"], "end": h["end"]}
+                 for s, h in zip(script_words, heard)]
+        report.append(f"{os.path.basename(wav)}: exact ({len(heard)} words)")
+    else:
+        weights = [max(len(re.sub(r'\W', '', w)), 2) for w in script_words]
+        total, t = sum(weights), span0
+        timed = []
+        for w, wt in zip(script_words, weights):
+            d = (span1 - span0) * wt / total
+            timed.append({"text": w, "start": t, "end": t + d})
+            t += d
+        report.append(f"{os.path.basename(wav)}: proportional "
+                      f"(heard {len(heard)}, script {len(script_words)})")
+
+    cur = []
+    def flush():
+        global cur
+        if not cur:
+            return
+        pages.append({
+            "start": round(at + cur[0]["start"], 3),
+            "end":   round(at + cur[-1]["end"], 3),
+            "words": [{"text": re.sub(r'[,.!?;:]+$', "", w["text"]),
+                       "start": round(at + w["start"], 3),
+                       "end":   round(at + w["end"], 3)} for w in cur],
+        })
+        cur = []
+
+    # Split into sentences first — a page that runs across a full stop reads as
+    # one thought and isn't — then chunk each sentence into BALANCED pages.
+    # Naive fixed-size chunking leaves one-word orphans ("...the reviews." ->
+    # "It read the" / "menus not the" / "reviews"), and a single word alone on
+    # screen for 400ms reads as a flicker, not as emphasis.
+    # Break on COMMAS as well as full stops. A comma is the writer already telling
+    # you where the thought divides, and honouring it is the difference between
+    # "IT READ THE MENUS / NOT THE REVIEWS" and "IT READ THE / MENUS NOT / THE
+    # REVIEWS" — same words, same timings, and only one of them is readable.
+    fragments, s = [], []
+    for w in timed:
+        s.append(w)
+        if re.search(r'[.!?,;:]$', w["text"]):
+            fragments.append(s); s = []
+    if s:
+        fragments.append(s)
+
+    for frag in fragments:
+        n = len(frag)
+        # let a fragment run one word over the cap rather than split a clause
+        # that fits: 4 words on one line beats 2 + 2 with a break mid-phrase
+        k = 1 if n <= MAXW + 1 else -(-n // MAXW)
+        base, extra = divmod(n, k)         # spread the remainder over the first pages
+        i = 0
+        for p in range(k):
+            size = base + (1 if p < extra else 0)
+            cur = frag[i:i + size]
+            i += size
+            flush()
+
+# a page whose last word is clipped short reads as a flicker; give every page a
+# floor, and never let one overlap the next
+for i, p in enumerate(pages):
+    p["end"] = max(p["end"], p["start"] + 0.45)
+    if i + 1 < len(pages):
+        p["end"] = min(p["end"], pages[i + 1]["start"] - 0.02)
+
+json.dump(pages, open(out_path, "w"), indent=1)
+for r in report:
+    print("  " + r)
+print(f"{len(pages)} pages -> {out_path}")
+for p in pages:
+    print(f"  {p['start']:6.2f} -> {p['end']:6.2f}  {' '.join(w['text'] for w in p['words'])}")
+```
+
+## Appendix G — `caption-place.py` (where the captions go)
+
+Scores every candidate band inside the platform-safe core and recommends one. Run it on the
+prepared beat clips, before you write a single cue.
+
+```bash
+python3 caption-place.py media/s*.mp4
+```
+
+```python
+#!/usr/bin/env python3
+"""
+Choose where the captions go: inside the platform-safe core, above the chrome.
+
+THE CONSTRAINT THAT ACTUALLY DECIDES IT is not legibility — it is that TikTok,
+Reels and Shorts each paste their own UI over your video and you never see it in
+your own render:
+
+    top     0–12%   status bar, "Following | For You" tabs
+    bottom 78–100%  username, post caption, music ticker, progress bar
+    right  84–100%  like / comment / share / profile rail (roughly y 45–80%)
+
+So the safe core is about **y 15%–73%**, and the classic "lower third" — the
+default in every subtitle tool — is the single worst place to put text in
+vertical video. Half of it is under the caption block on at least one platform.
+
+Inside the core, the default is the LOWEST band that still clears the chrome.
+That is where TikTok's own captions sit, and it is below the subject's face,
+which on this format is the content. Busyness is measured and reported, but it
+does not get to move the captions over someone's eyes: the top of the frame
+almost always scores "calmest" precisely because it is forehead, hair and
+defocused background, and a caption there covers the performance.
+
+usage: caption-place.py <clip.mp4> [clip.mp4 ...] [--height 14] [--top 15] [--bottom 73]
+"""
+import subprocess, sys, numpy as np
+
+files = [a for a in sys.argv[1:] if not a.startswith("--")]
+def opt(n, d):
+    return float(sys.argv[sys.argv.index(n) + 1]) if n in sys.argv else d
+H_PCT       = opt("--height", 14)
+SAFE_TOP    = opt("--top", 15)
+SAFE_BOTTOM = opt("--bottom", 73)
+AIR         = 2.0                      # don't sit flush against the chrome
+
+W, H = 240, 426
+def frames(f):
+    p = subprocess.run(["ffmpeg", "-v", "error", "-i", f, "-vf", f"fps=2,scale={W}:{H}",
+                        "-pix_fmt", "rgb24", "-f", "rawvideo", "-"], capture_output=True)
+    b = np.frombuffer(p.stdout, np.uint8)
+    n = len(b) // (W * H * 3)
+    return b[:n * W * H * 3].reshape(n, H, W, 3).astype(np.float32)
+
+F = np.concatenate([frames(f) for f in files])
+luma = 0.2126 * F[..., 0] + 0.7152 * F[..., 1] + 0.0722 * F[..., 2]
+# Busyness = local DETAIL behind the text, not global variance. A band split
+# between a bright wall and a dark jacket has huge variance and reads fine.
+gx = np.abs(np.diff(luma, axis=2))
+gy = np.abs(np.diff(luma, axis=1))
+edge = np.zeros_like(luma)
+edge[:, :, :-1] += gx
+edge[:, :-1, :] += gy
+
+box_h = int(H_PCT / 100 * H)
+def score(top_pct):
+    a = int(top_pct / 100 * H)
+    band = edge[:, a:a + box_h, :]
+    per_frame = band.mean(axis=(1, 2))
+    # worst case matters more than the average: one scene where the caption is
+    # unreadable is a defect however calm the other six are
+    return per_frame.mean(), np.percentile(per_frame, 90)
+
+cands = [(t, *score(t)) for t in np.arange(SAFE_TOP, SAFE_BOTTOM - H_PCT + 0.01, 1.0)]
+default_top = SAFE_BOTTOM - H_PCT - AIR
+d_avg, d_p90 = score(default_top)
+quietest = min(cands, key=lambda c: c[1] + 0.5 * c[2])
+
+print(f"platform-safe core  {SAFE_TOP:.0f}%–{SAFE_BOTTOM:.0f}%   caption box {H_PCT:.0f}% tall")
+print(f"  chrome assumed:  top 0–12%   bottom 78–100%   right rail 84–100%")
+print()
+print(f"  RECOMMENDED   --y {default_top:.0f}   busy {d_avg:5.2f} (p90 {d_p90:5.2f})"
+      f"   [lowest band clearing the chrome]")
+print(f"  quietest      --y {quietest[0]:.0f}   busy {quietest[1]:5.2f} (p90 {quietest[2]:5.2f})")
+if quietest[1] < d_avg * 0.8:
+    print()
+    print(f"  NOTE: the quietest band scores {(1-quietest[1]/d_avg)*100:.0f}% calmer. Look at it before")
+    print( "  taking it — near the top of the frame that reading usually means")
+    print( "  'forehead, hair and defocused background', and a caption there covers")
+    print( "  the face. Only move up if the subject genuinely sits low in frame.")
+print()
+print(f"  {'top%':>5} {'busy':>7} {'p90':>7}")
+for t, m, p in cands[::3]:
+    mark = "  <- recommended" if abs(t - default_top) < 0.5 else ""
+    print(f"  {t:5.0f} {m:7.2f} {p:7.2f}{mark}")
+```
+
+## Appendix H — `export-versions.py` (the two cuts)
+
+```bash
+python3 export-versions.py renders/cut-vo.mp4 media/bgm.mp3 --bed-volume 0.22
+```
+
+```python
+#!/usr/bin/env python3
+"""
+Ship TWO cuts from ONE render: voiceover-only, and voiceover + music bed.
+
+Why two, and why this order:
+
+  * The VOICEOVER-ONLY cut is the one you publish. TikTok, Reels and Shorts all
+    let the poster attach a track from the platform's own library at upload,
+    licensed through the platform's deals with the labels — so the music is
+    cleared where viewers actually hear it, and the post gets whatever is
+    trending that week instead of whatever was trending when you rendered.
+  * The MUSIC cut is the review copy and the fallback: what you send a client to
+    approve, what you post anywhere without an in-app music library, and the one
+    that carries a watermark if you need one.
+
+The music version is derived, never re-rendered. `-c:v copy` means both files
+carry the BYTE-IDENTICAL video stream, so approving one approves the other. Two
+separate renders would be two different videos that merely look alike, and the
+frame you approved would not be the frame you shipped. (A watermark breaks this
+on purpose — see --watermark.)
+
+usage: export-versions.py <render.mp4> <bed.mp3> [--bed-volume 0.22]
+                          [--out-dir DIR] [--name NAME] [--watermark PNG]
+"""
+import os, subprocess, sys
+
+src, bed = sys.argv[1], sys.argv[2]
+def opt(n, d):
+    return sys.argv[sys.argv.index(n) + 1] if n in sys.argv else d
+VOL     = float(opt("--bed-volume", "0.22"))
+OUT     = opt("--out-dir", os.path.dirname(src) or ".")
+NAME    = opt("--name", os.path.splitext(os.path.basename(src))[0].removesuffix("-vo"))
+WM      = opt("--watermark", None)
+
+vo_path    = os.path.join(OUT, f"{NAME}-vo.mp4")
+music_path = os.path.join(OUT, f"{NAME}-music.mp4")
+
+def run(cmd):
+    r = subprocess.run(cmd, capture_output=True, text=True)
+    if r.returncode:
+        sys.exit(f"failed: {' '.join(cmd)}\n{r.stderr[-1500:]}")
+
+# 1. the publish master — untouched. If the render is already sitting at the
+#    -vo path, leave it alone: ffmpeg refuses to read and write one file, and
+#    "re-encode it to itself" would be the wrong fix anyway.
+if os.path.abspath(src) != os.path.abspath(vo_path):
+    run(["ffmpeg", "-y", "-v", "error", "-i", src, "-c", "copy", vo_path])
+
+# 2. the review / fallback cut. The bed is duration-matched to the video and
+#    mixed UNDER the existing voiceover track; `normalize=0` on amix stops it
+#    quietly pulling the voice down to make room for the music.
+afilter = (f"[1:a]volume={VOL},afade=t=in:st=0:d=0.6[bed];"
+           f"[0:a][bed]amix=inputs=2:duration=first:normalize=0[a]")
+cmd = ["ffmpeg", "-y", "-v", "error", "-i", src, "-stream_loop", "-1", "-i", bed,
+       "-filter_complex", afilter, "-map", "0:v", "-map", "[a]",
+       "-c:a", "aac", "-b:a", "192k", "-shortest"]
+if WM:
+    # a watermark has to be burned in, so this version gets its own video encode
+    # and stops being frame-identical to the master. Say so in the handoff.
+    cmd += ["-i", WM, "-filter_complex",
+            afilter + ";[0:v][2:v]overlay=W-w-40:40:format=auto[v]",
+            "-map", "[v]", "-c:v", "libx264", "-preset", "slow", "-crf", "18",
+            "-pix_fmt", "yuv420p"]
+    cmd = [c for c in cmd if c not in ("-map", "0:v")]
+else:
+    cmd += ["-c:v", "copy"]
+run(cmd + [music_path])
+
+def probe(f):
+    r = subprocess.run(["ffmpeg", "-hide_banner", "-nostats", "-i", f,
+                        "-af", "ebur128=peak=true", "-f", "null", "-"],
+                       capture_output=True, text=True).stderr
+    g = lambda k: next((l.split()[-2] for l in r.splitlines() if l.strip().startswith(k)), "?")
+    return g("I:"), g("Peak:")
+
+for label, f in (("voiceover only", vo_path), ("voiceover + music", music_path)):
+    i, pk = probe(f)
+    size = os.path.getsize(f) / 1e6
+    print(f"  {label:20s} {os.path.basename(f):32s} {size:6.1f} MB   {i} LUFS  peak {pk} dBFS")
+print()
+print(f"  PUBLISH: {os.path.basename(vo_path)} — add music from the platform's own library at upload.")
+print(f"  REVIEW : {os.path.basename(music_path)}"
+      + ("  (watermarked; video re-encoded, not frame-identical)" if WM else ""))
+```
+
+## Appendix I — `place-stickers.py` (stickers from a manifest)
+
+Writes the wrapper markup and the pop-in CSS, and warns when two stickers would be on screen at
+once — which is clutter in this format and the kind of thing you only notice on the render.
+
+```bash
+python3 place-stickers.py composition.html stickers.txt
+```
+
+```python
+#!/usr/bin/env python3
+"""
+Write sticker layers into a HyperFrames composition from a manifest.
+
+Two things this exists to get right:
+
+  * A bare <img> with data-start renders at t=0 and then never shows or hides —
+    the engine does not manage it. Each sticker has to be wrapped in a
+    `div.clip` exactly like a caption layer.
+  * `.clip { inset: 0 }` fights any geometry you set, so the wrapper has to
+    reset `inset:auto` BEFORE left/top/width/height.
+
+Manifest, one line per sticker (# comments and blank lines ignored):
+
+    <src>|<start>|<duration>|<left%>|<top%>|<width%>|<height%>|<label>[|<rotate>][|<fit>]
+
+`fit` is `contain` (default) or `fill`, and the choice is not cosmetic:
+
+  * SUBJECT stickers — a dish, a product — must keep their aspect: `contain`.
+  * ANNOTATION stickers — a ring, an underline — must SQUASH to the shape they
+    are marking: `fill`. A near-square ring set to `contain` inside a wide, short
+    box shrinks to the box's HEIGHT and ends up a small circle floating next to
+    the row instead of around it.
+
+usage: place-stickers.py <composition.html> <stickers.txt>
+"""
+import os, re, sys
+
+comp, manifest = sys.argv[1], sys.argv[2]
+
+CSS = """
+.sticker{animation-name:vfStickIn;animation-duration:.42s;animation-fill-mode:both;
+  animation-timing-function:cubic-bezier(.2,1.1,.3,1);transform-origin:center;
+  filter:drop-shadow(0 10px 24px rgba(0,0,0,.35))}
+@keyframes vfStickIn{
+  0%{opacity:0;transform:scale(.55) rotate(-14deg)}
+  60%{opacity:1;transform:scale(1.06) rotate(2deg)}
+  100%{opacity:1;transform:scale(1) rotate(0deg)}}
+"""
+
+doc = open(comp).read()
+# re-runnable: drop any previous sticker layers and CSS
+doc = re.sub(r'<div class="clip" id="stk-[^"]*".*?</div>\s*', '', doc, flags=re.S)
+doc = re.sub(r'\n?\.sticker\{.*?@keyframes vfStickIn\{.*?\}\}\n?', '', doc, flags=re.S)
+doc = doc.replace("</style>", CSS + "</style>", 1)
+
+rows, layers = [], []
+for i, raw in enumerate(open(manifest)):
+    raw = raw.strip()
+    if not raw or raw.startswith("#"):
+        continue
+    parts = [p.strip() for p in raw.split("|")]
+    src, start, dur, left, top, w, h, label = parts[:8]
+    rot = parts[8] if len(parts) > 8 else "0"
+    fit = parts[9] if len(parts) > 9 else "contain"
+    start, dur = float(start), float(dur)
+    layers.append(
+        f'  <div class="clip" id="stk-{i}" data-hf-id="stk-{i}" data-layer-mode="publish" '
+        f'data-layer-kind="image" data-start="{start}" data-duration="{dur}" '
+        f'data-end="{round(start+dur,3)}" data-track-index="6" '
+        f'data-label="{label}" '
+        f'style="position:absolute;inset:auto;left:{left}%;top:{top}%;width:{w}%;height:{h}%;'
+        f'z-index:6;transform:rotate({rot}deg)">'
+        f'<img class="sticker" src="{src}" '
+        f'style="width:100%;height:100%;object-fit:{fit};animation-delay:{start}s"></div>')
+    rows.append((start, start + dur, label))
+
+idx = doc.rfind("</div>")
+doc = doc[:idx] + "\n".join(layers) + "\n" + doc[idx:]
+open(comp, "w").write(doc)
+
+rows.sort()
+print(f"{len(rows)} sticker(s) placed")
+for a, b, label in rows:
+    print(f"  {a:6.2f} -> {b:6.2f}  {label}")
+# two stickers on screen at once is clutter in this format, and it is the kind of
+# thing you only notice on the render — so say it here instead
+for (a1, b1, l1), (a2, b2, l2) in zip(rows, rows[1:]):
+    if a2 < b1:
+        print(f"  ⚠ OVERLAP: '{l1}' and '{l2}' are both on screen {a2:.2f}-{b1:.2f}")
+```
+
+## Appendix J — `cast-actors.py` (group a shelf by actor)
+
+Pulls the whole shelf (cursor-paginated), reads each card's `actor_<uuid>` out of its summary,
+and ranks actors by how many takes they have. Run it before you pick a single clip.
+
+```bash
+python3 cast-actors.py --category ugc-reaction --min 4
+# ugc-reaction: 180 raws · 53 tagged actors · 3 untagged
+# actor_668363ea-… — 7 takes …
+```
+
+```python
+#!/usr/bin/env python3
+"""
+Group a public-raws shelf by ACTOR, so you can cast a face that has enough takes.
+
+A shelf is dozens of clips of a much smaller number of creators, and nothing in
+the taxonomy says "same face" — the `actor_<uuid>` tag does. This pulls the
+shelf, reads each card's actor id out of its summary/tags, and ranks the actors
+by how many takes they have.
+
+This format needs FOUR reaction beats from one person, so the only actors worth
+casting from are the ones with 4+ takes. That list is short.
+
+usage: cast-actors.py [--category ugc-reaction] [--min 2]
+env:   VIDFARM_API_KEY
+"""
+import collections, json, os, re, sys, urllib.parse, urllib.request
+
+def opt(n, d):
+    return sys.argv[sys.argv.index(n) + 1] if n in sys.argv else d
+CATEGORY = opt("--category", "ugc-reaction")
+MIN      = int(opt("--min", "2"))
+HOST     = os.environ.get("VIDFARM_HOST", "https://vidfarm.cc")
+KEY      = os.environ["VIDFARM_API_KEY"]
+
+# The feed caps `limit` at 100 and paginates on `cursor` — NOT `offset`, which is
+# silently ignored and hands you page 1 again. A loop built on offset looks like
+# it works, reports a plausible number, and has seen half the shelf.
+rows, cursor = {}, None
+while True:
+    params = {"category": CATEGORY, "limit": 100}
+    if cursor:
+        params["cursor"] = cursor
+    q = urllib.parse.urlencode(params)
+    req = urllib.request.Request(f"{HOST}/api/v1/public-raws?{q}",
+                                 headers={"Authorization": f"Bearer {KEY}"})
+    page = json.load(urllib.request.urlopen(req))
+    batch = page.get("raws", [])
+    if not batch:
+        break
+    for r in batch:
+        rows[r["rawId"]] = r
+    cursor = page.get("next_cursor")
+    if not cursor:
+        break
+
+ACTOR_RE = re.compile(r"actor_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}", re.I)
+actors, untagged = collections.defaultdict(list), 0
+for r in rows.values():
+    hay = (r.get("summary") or "") + " " + json.dumps(r.get("tags") or {})
+    m = ACTOR_RE.search(hay)
+    # "no tag" means NOT TAGGED YET — never treat it as "a different person"
+    if m:
+        actors[m.group(0)].append(r)
+    else:
+        untagged += 1
+
+print(f"{CATEGORY}: {len(rows)} raws · {len(actors)} tagged actors · {untagged} untagged")
+ranked = sorted(actors.items(), key=lambda kv: -len(kv[1]))
+for actor_id, clips in ranked:
+    if len(clips) < MIN:
+        break
+    print(f"\n{actor_id}  —  {len(clips)} takes")
+    for c in sorted(clips, key=lambda c: -(c.get("durationSeconds") or 0)):
+        print(f"   {round(c.get('durationSeconds') or 0, 1):5}s  {c['rawId']}")
+        print(f"          {(c.get('description') or '')[:96]}")
+print("\nCast from an actor with enough takes to carry all four reaction beats,")
+print("then pick each beat's take by EMOTION — see the harness's casting table.")
+```