@aicopycoders/exodus 2026.9.2000-beta.8 → 2026.9.2000

package/assets/skills/exodus-video/scripts/first-cut.mjs

@@ -2,7 +2,10 @@
 // A plain first cut from a folder written by `exodus video pull`: the A-roll
 // scenes in the manifest's order make the spine, each cutaway lays over the
 // spine at the moment its cued line is spoken, a room-tone bed and the music
-// bed go underneath, and one MP4 comes out ready to upload.
+// bed go underneath, and one MP4 comes out ready to upload. A reaction
+// cutaway is the exception: it is its own short beat in the spine right after
+// its cued line ends, heard with its own sound while the speaker is silent,
+// fading in across any quiet start and out rather than stopping dead.
 //
 //   node first-cut.mjs <pulled-dir> [--out cut.mp4] [--skip 2,5] [--no-music]
 //
@@ -11,9 +14,15 @@
 // recorded: the voice replaces the clip's audio, and the picture is fitted to
 // the voice, trimmed when the clip runs longer and held on its last frame when
 // the voice runs longer. The voice itself is never altered. A dialogue scene
-// keeps the audio it performed. A scene with no clip but a keyframe becomes a
-// still for the length of its voice track, else the storyboard's planned
-// duration. Every segment is loudness-normalized to -16 LUFS before the join.
+// keeps the audio it performed; at each join its silence before the first word
+// and after the last is cut back to a short beat, read from its word times.
+// Inside it, a silence over 0.9 s between two sentences is cut down to 0.8 s,
+// picture and sound together, unless the script writes that pause in. A
+// sound in such a break that holds no heard word (a burp, a click) is cut
+// out, read from the clip's loudness, and the same rule then applies. A
+// scene with no clip but a keyframe becomes a still for the length of its voice
+// track, else the storyboard's planned duration. Every segment is
+// loudness-normalized to -16 LUFS before the join.
 // --skip drops scenes.
 //
 // After the render it writes the whole ad's word times beside the MP4, as
@@ -30,15 +39,54 @@ const FPS = 24;
 const norm = (label) =>
   `[${label}]scale=${WIDTH}:${HEIGHT}:force_original_aspect_ratio=decrease,` +
   `pad=${WIDTH}:${HEIGHT}:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=${FPS},format=yuv420p`;
+/**
+ * Edges the cut chooses (join trims, reaction splits, narration lengths) land
+ * on whole frames, so the picture runs as long as its sound there and the
+ * timeline's times are the cut's times.
+ */
+const floorFrame = (t) => Math.floor(t * FPS + 1e-6) / FPS;
+const ceilFrame = (t) => Math.ceil(t * FPS - 1e-6) / FPS;
 const stereo = "aresample=48000,aformat=channel_layouts=stereo";
-/** Per-segment loudness, the level every clip was normalized to before the join. */
-const LOUDNORM = "loudnorm=I=-16:TP=-1.5:LRA=11,aresample=48000";
+/**
+ * Per-segment loudness, the level every clip was normalized to before the join.
+ * loudnorm stamps its output about 0.1 s late (its look-ahead), so a later
+ * atrim by time kept that much less sound than picture and every join pulled
+ * the sound further ahead (#2387). Re-stamping by sample count undoes it.
+ * Its input is padded to 3 s, its look-ahead window: Debian's ffmpeg 5.1 (the
+ * worker's) all but silenced a shorter sound (#3006). Every use trims after.
+ */
+const LOUDNORM = "apad=whole_dur=3,loudnorm=I=-16:TP=-1.5:LRA=11,aresample=48000,asetpts=N/SR/TB";
+/** A fade this short at each edge of a segment's sound stops a hard cut in the room tone clicking. */
+const EDGE_FADE_SEC = 0.015;
 /** Air after the last spoken word of a narrated scene, so the line lands. */
 export const TAIL_AIR_SEC = 0.8;
 /** A continuous low bed under the whole ad, so the joins between clips do not read as dead air. */
 const ROOM_TONE =
   "anoisesrc=color=brown:amplitude=0.0035:r=48000,highpass=f=60,lowpass=f=900,aformat=channel_layouts=stereo";
 const MUSIC_VOLUME = 0.18;
+/** The longest a reaction beat holds the spine (#2357); older pulls carry 4 s reaction clips. */
+export const REACTION_MAX_SEC = 1.5;
+/**
+ * A reaction's laugh carries into the next line instead of stopping dead at
+ * the join (#2406): it starts well under the speaker, at this share of its own
+ * level (about -9 dB), and fades to silence over this long.
+ */
+export const REACTION_TAIL_SEC = 0.75;
+export const REACTION_TAIL_GAIN = 0.35;
+/** A reaction clip with too little sound for a tail fades out over this long instead (#2666). */
+export const REACTION_FADE_OUT_SEC = 0.4;
+/** The least picture a reaction beat keeps when it gives up its end to a tail (#2700). */
+export const REACTION_MIN_BEAT_SEC = 1.0;
+/**
+ * The air a join keeps around its words (#2388): after one clip's last word, and
+ * before the next clip's first, less when the same speaker carries on than when
+ * someone new answers.
+ */
+export const JOIN_TAIL_SEC = 0.15;
+export const JOIN_LEAD_SAME_SPEAKER_SEC = 0.1;
+export const JOIN_LEAD_NEW_SPEAKER_SEC = 0.25;
+/** The gap a cut keeps from an extra heard sound it leaves out (#2541). */
+const EXTRA_CLEARANCE_SEC = 0.05;
 
 /** The word rule the planner sized every line with (scout models.ts wordCount). */
 export function wordCount(text) {
@@ -54,6 +102,242 @@ export function lineWordCounts(storyboard) {
   return counts;
 }
 
+const wordToken = (word) => String(word ?? "").toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "");
+
+/**
+ * #2541: the indexes of the heard words that deliver the first and last
+ * scripted word, matching the script in order at its earliest delivery, or null
+ * when the whole script is not heard that way.
+ */
+export function scriptedSpan(words, lineTexts) {
+  const script = lineTexts.flatMap((text) => (text ?? "").split(/\s+/)).map(wordToken).filter(Boolean);
+  const at = heardAt(words, script);
+  return at && at.length > 0 ? { first: at[0], last: at.at(-1) } : null;
+}
+
+/** The heard word that delivers each script token, in order at its earliest delivery, or null. */
+function heardAt(words, tokens) {
+  const at = [];
+  let j = 0;
+  for (const token of tokens) {
+    while (j < words.length && wordToken(words[j].w) !== token) j++;
+    if (j === words.length) return null;
+    at.push(j++);
+  }
+  return at;
+}
+
+/** #2544: a silence between two sentences longer than this is cut down to the kept length. */
+export const SENTENCE_GAP_MAX_SEC = 0.9;
+export const SENTENCE_GAP_KEEP_SEC = 0.8;
+/** A pause the script writes in: an ellipsis, a dash, or a hyphen standing between words. */
+const WRITTEN_PAUSE = /…|\.{3}|[—–-]/;
+const SENTENCE_END = /[.?!]/;
+/**
+ * #2554: loudness windows, and the levels that read as a sound and as quiet;
+ * SETTLED_WINDOWS quiet windows in a row (200 ms) end a sound (scout trim.ts).
+ */
+const LEVEL_WINDOW_SEC = 0.02;
+const SOUND_DB = -35;
+const QUIET_DB = -50;
+const SETTLED_WINDOWS = 10;
+/**
+ * #2666: in a gap gone quiet, a fainter sound counts when it stands this far
+ * over the gap's median level and reaches FAINT_SOUND_DB, so a grunt in near
+ * silence goes while a soft breath and room tone stay (scout trim.ts).
+ */
+const SOUND_OVER_FLOOR_DB = 25;
+const FAINT_SOUND_DB = -45;
+/** The directions that ask for a pause (scout clip-qc.ts PAUSE_DIRECTION, NO_PAUSE_DIRECTION, lineWrittenPause). */
+const PAUSE_DIRECTION =
+  /\bpaus(e|es|ed|ing)\b|\bsilence\b|\(beat\)|\b(a|one|brief|short|quick|small|little|long)\s+beat\b|\bbeat\s*(,|before|after|then)/i;
+const NO_PAUSE_DIRECTION =
+  /\b(no|not|without|never|don'?t|avoid\w*)\b[^.;]*\b(beats?|paus\w*|silence)\b|\bpause-?(free|less)\b/i;
+
+export function asksPause(line) {
+  const direction = `${line?.stageDirection ?? ""} ${line?.performanceDirection ?? ""}`;
+  return PAUSE_DIRECTION.test(direction) && !NO_PAUSE_DIRECTION.test(direction);
+}
+
+/**
+ * #2544: the silences inside one clip to cut, as [{ s, e, after, gap }] in the
+ * clip's own time. A heard silence over SENTENCE_GAP_MAX_SEC between two
+ * scripted words at a sentence break (a new line, or . ? ! between them) keeps
+ * half of SENTENCE_GAP_KEEP_SEC after the earlier word and half before the
+ * later one; the rest goes. Kept: a pause the script writes in (a mark between
+ * the words, or a direction on either line asking for one), the laugh beat
+ * after a line a reaction is cued to, and any gap with another heard sound in
+ * it. Nothing is cut when the script is not heard in order.
+ *
+ * #2554: given the clip's loudness ({ windowSec, db } from 0), a sound in a
+ * break that holds no heard word is cut too, whatever the break's length, and
+ * the silence left follows the same rule. Every span of one break carries that
+ * break's gap, the silence it keeps, and whether a sound went.
+ *
+ * lines: [{ text, asksPause, cuesBeat }] in the order the clip speaks them.
+ */
+export function sentenceGapCuts(words, lines, levels = null) {
+  const tokens = [];
+  let between = "";
+  lines.forEach((line, li) => {
+    for (const piece of (line.text ?? "").split(/\s+/)) {
+      const token = wordToken(piece);
+      if (!token) {
+        between += ` ${piece}`;
+        continue;
+      }
+      const [, lead, trail] = piece.match(/^([^\p{L}\p{N}]*).*?([^\p{L}\p{N}]*)$/u);
+      tokens.push({ token, li, before: between + lead });
+      between = trail;
+    }
+    between += " ";
+  });
+  const at = heardAt(words ?? [], tokens.map((t) => t.token));
+  if (!at) return [];
+  const cuts = [];
+  for (let t = 0; t + 1 < tokens.length; t++) {
+    const [a, b] = [tokens[t], tokens[t + 1]];
+    if (at[t + 1] !== at[t] + 1) continue;
+    const newLine = a.li !== b.li;
+    if (!newLine && !SENTENCE_END.test(b.before)) continue;
+    if (WRITTEN_PAUSE.test(b.before) || lines[a.li].asksPause || lines[b.li].asksPause) continue;
+    if (newLine && lines[a.li].cuesBeat) continue;
+    const [earlier, later] = [words[at[t]], words[at[t + 1]]];
+    const gap = later.s - earlier.e;
+    const heard = levels && soundBetween(levels, earlier.e, later.s);
+    // A sound's frame edges widen the cut, so none of it is left in.
+    const sound = heard && { s: Math.max(floorFrame(heard.s), ceilFrame(earlier.e)), e: ceilFrame(heard.e) };
+    const removed = sound ? sound.e - sound.s : 0;
+    const spans = sound ? [sound] : [];
+    if (gap - removed > SENTENCE_GAP_MAX_SEC + 1e-6) {
+      // Placed on the gap with the sound already out, then moved back past it.
+      // Frame edges only ever widen what is kept, so the silence left stays
+      // between the kept length and the longest allowed.
+      const back = (t) => (sound && t > sound.s ? t + removed : t);
+      const s = back(ceilFrame(earlier.e + SENTENCE_GAP_KEEP_SEC / 2));
+      const e = back(floorFrame(later.s - removed - SENTENCE_GAP_KEEP_SEC / 2));
+      if (e > s) spans.push({ s, e });
+    }
+    const merged = [];
+    for (const span of spans.sort((x, y) => x.s - y.s)) {
+      const prev = merged.at(-1);
+      if (prev && span.s <= prev.e + 1e-6) prev.e = Math.max(prev.e, span.e);
+      else merged.push({ ...span });
+    }
+    const kept = gap - merged.reduce((sum, c) => sum + c.e - c.s, 0);
+    for (const { s, e } of merged) cuts.push({ s, e, after: earlier.w, gap, kept, sound: Boolean(sound) });
+  }
+  return cuts;
+}
+
+/**
+ * #2554: a sound between two words that holds no heard word, from where the
+ * earlier word fades under QUIET_DB to where SETTLED_WINDOWS of quiet resume
+ * before the later word, or null when there is none or it runs into the later
+ * word. A sound heard only against the gap's quiet (#2666) must come after the
+ * gap settles, so the earlier word's own release stays. Mirrors scout trim.ts
+ * soundBetween.
+ */
+function soundBetween(levels, fromSec, toSec) {
+  const { db, windowSec } = levels;
+  const windowAt = (sec) => Math.floor(sec / windowSec + 1e-9);
+  const last = Math.min(windowAt(toSec), db.length);
+  let quiet = windowAt(fromSec);
+  while (quiet < last && db[quiet] >= QUIET_DB) quiet++;
+  const gap = db.slice(quiet, last).sort((a, b) => a - b);
+  const faint = Math.min(SOUND_DB, Math.max(FAINT_SOUND_DB, gap[gap.length >> 1] + SOUND_OVER_FLOOR_DB));
+  const calm = settledQuiet(db, quiet);
+  const loud = (i) => db[i] >= (calm >= 0 && i >= calm + SETTLED_WINDOWS ? faint : SOUND_DB);
+  let resumed = -1;
+  for (let i = quiet; i < last; i = resumed + SETTLED_WINDOWS) {
+    while (i < last && !loud(i)) i++;
+    if (i >= last) break;
+    const settled = settledQuiet(db, i);
+    if (settled < 0 || settled + SETTLED_WINDOWS > last) break;
+    resumed = settled;
+  }
+  return resumed < 0 ? null : { s: quiet * windowSec, e: resumed * windowSec };
+}
+
+/** Scanning forward from `from`, the first window of the first run of SETTLED_WINDOWS quiet windows, or -1. */
+function settledQuiet(db, from) {
+  let run = 0;
+  for (let i = from; i < db.length; i++) {
+    run = db[i] < QUIET_DB ? run + 1 : 0;
+    if (run === SETTLED_WINDOWS) return i - (SETTLED_WINDOWS - 1);
+  }
+  return -1;
+}
+
+/** Per-20 ms RMS loudness (dBFS) of mono s16 PCM, digital silence reading -120 (scout ffmpeg-clip.ts audioLevelsFromPcm). */
+export function levelsFromPcm(pcm, sampleRate) {
+  const perWindow = Math.round(sampleRate * LEVEL_WINDOW_SEC);
+  const db = [];
+  for (let from = 0; from < pcm.length; from += perWindow) {
+    const to = Math.min(pcm.length, from + perWindow);
+    let sumSq = 0;
+    for (let i = from; i < to; i++) sumSq += pcm[i] * pcm[i];
+    const rms = Math.sqrt(sumSq / (to - from)) / 32768;
+    db.push(rms > 0 ? Math.max(-120, 20 * Math.log10(rms)) : -120);
+  }
+  return { windowSec: LEVEL_WINDOW_SEC, db };
+}
+
+/** A clip's loudness windows, or null when its audio cannot be decoded; `filter` shapes the sound first. */
+function clipLevels(file, filter = null) {
+  const res = spawnSync(
+    "ffmpeg",
+    [
+      "-v", "error", "-i", file, "-map", "0:a:0", "-ac", "1", "-ar", "16000",
+      ...(filter ? ["-af", filter] : []), "-f", "s16le", "-",
+    ],
+    { maxBuffer: 1 << 28 },
+  );
+  if (res.status !== 0 || !res.stdout?.length) return null;
+  const bytes = new Uint8Array(res.stdout.subarray(0, res.stdout.length & ~1));
+  return levelsFromPcm(new Int16Array(bytes.buffer), 16000);
+}
+
+/**
+ * Take each own-sound clip's long sentence gaps out of its timeline: its words
+ * move onto the cut timeline and it runs shorter, so every later step (join
+ * trims, reaction splits, cue times, captions) works in cut time. The renderer
+ * removes seg.cuts from the picture and the sound before anything else.
+ */
+function tightenSentenceGaps(spine, reactionCues, scriptLines, readLevels) {
+  for (const seg of spine) {
+    if (seg.source !== "clip" || seg.audio !== "clip" || !seg.words?.length) continue;
+    const lines = seg.lineIds.map((id) => ({
+      text: scriptLines.get(id)?.text,
+      asksPause: asksPause(scriptLines.get(id)),
+      cuesBeat: reactionCues.has(id),
+    }));
+    const cuts = sentenceGapCuts(seg.words, lines, readLevels(seg.file));
+    if (cuts.length === 0) continue;
+    const removedBefore = (t) => cuts.reduce((sum, c) => sum + (c.e <= t ? c.e - c.s : 0), 0);
+    const removed = removedBefore(Infinity);
+    seg.cuts = cuts.map(({ s, e }) => ({ s, e }));
+    seg.words = seg.words.map((w) => ({ ...w, s: w.s - removedBefore(w.s), e: w.e - removedBefore(w.s) }));
+    seg.seconds -= removed;
+    seg.clipSeconds -= removed;
+    seg.note = withHow(
+      seg.note,
+      [
+        ...new Set(
+          cuts.map((c) =>
+            c.sound
+              ? `sound after "${c.after}" cut, pause ${c.gap.toFixed(2)}s -> ${c.kept.toFixed(2)}s`
+              : `pause after "${c.after}" tightened ${c.gap.toFixed(2)}s -> ${c.kept.toFixed(2)}s`,
+          ),
+        ),
+      ],
+    );
+  }
+}
+
+const withHow = (note, how) =>
+  note.endsWith(")") ? `${note.slice(0, -1)}, ${how.join(", ")})` : `${note} (${how.join(", ")})`;
+
 const CUTAWAY_KINDS = new Set(["cutaway", "insert"]);
 
 const hasText = (value) => typeof value === "string" && value.trim().length > 0;
@@ -77,12 +361,19 @@ export function scenePlans(storyboard) {
   const plans = new Map();
   for (const scene of storyboard?.scenes ?? []) {
     if (typeof scene?.sceneIndex !== "number") continue;
+    const speakers = (Array.isArray(scene.dialogue) ? scene.dialogue : [])
+      .filter((turn) => hasText(turn?.line) || hasText(turn?.text))
+      .map((turn) => (hasText(turn.speaker) ? turn.speaker.trim() : null));
     plans.set(scene.sceneIndex, {
+      firstSpeaker: speakers[0] ?? null,
+      lastSpeaker: speakers.at(-1) ?? null,
       cutaway: CUTAWAY_KINDS.has(scene.kind),
       narrated: narratedScene(scene, storyboard),
       lineIds: Array.isArray(scene.lineIds) ? scene.lineIds : [],
       cueLineId: typeof scene.cueLineId === "string" ? scene.cueLineId : null,
+      cutawayType: typeof scene.cutawayType === "string" ? scene.cutawayType : null,
       durationSec: typeof scene.durationSec === "number" ? scene.durationSec : null,
+      actionTailSec: typeof scene.actionTailSec === "number" && scene.actionTailSec > 0 ? scene.actionTailSec : 0,
     });
   }
   return plans;
@@ -90,13 +381,16 @@ export function scenePlans(storyboard) {
 
 /**
  * Fit a picture to its voice track. The segment always runs as long as the
- * voice plus a beat of air, because the voice is never altered. A clip that
- * runs longer is trimmed; a clip that runs shorter holds its last frame for the
- * difference. A still (no clip) simply runs the voice's length.
+ * voice plus a beat of air, to the next whole frame, because the voice is never
+ * altered. A clip that runs longer is trimmed; a clip that runs shorter holds
+ * its last frame for the difference. A still (no clip) simply runs the voice's length.
+ * A scene marked with actionTailSec keeps that long after the voice, up to the clip's
+ * end, so the set-down it ends on is seen (#3199).
  */
-export function fitNarration({ clipSeconds, voiceSeconds }) {
-  const target = voiceSeconds + TAIL_AIR_SEC;
-  if (clipSeconds === null) return { seconds: target, holdSec: 0, trimmedBy: 0 };
+export function fitNarration({ clipSeconds, voiceSeconds, actionTailSec = 0 }) {
+  const aired = ceilFrame(voiceSeconds + TAIL_AIR_SEC);
+  if (clipSeconds === null) return { seconds: aired, holdSec: 0, trimmedBy: 0 };
+  const target = Math.max(aired, Math.min(clipSeconds, ceilFrame(voiceSeconds + actionTailSec)));
   if (target <= clipSeconds) {
     return { seconds: target, holdSec: 0, trimmedBy: clipSeconds - target };
   }
@@ -126,18 +420,176 @@ export function cueOffsetOnSpine(spine, counts, cueLineId) {
   return null;
 }
 
-export function buildTimeline({ manifest, storyboard, skip, probe, exists, readWords }) {
+/**
+ * Where a segment's spoken cue line ends, in seconds into the segment, or null
+ * when the segment does not speak it. A cue line that closes the segment ends
+ * where the segment does.
+ */
+export function cueEndInSegment(seg, counts, cueLineId) {
+  const idx = seg.lineIds.indexOf(cueLineId);
+  if (idx === -1) return null;
+  if (idx === seg.lineIds.length - 1) return seg.seconds;
+  let through = 0;
+  let totalWords = 0;
+  seg.lineIds.forEach((id, i) => {
+    const n = counts.get(id) ?? 0;
+    totalWords += n;
+    if (i <= idx) through += n;
+  });
+  if (seg.words && seg.words.length > 0) {
+    const last = seg.words[Math.min(Math.max(through - 1, 0), seg.words.length - 1)];
+    return Math.min(Math.max(0, last?.e ?? 0), seg.seconds);
+  }
+  return totalWords > 0 ? (through / totalWords) * seg.seconds : seg.seconds;
+}
+
+/**
+ * Cut the dead air out of each join between clips that play their own sound: a
+ * clip's lead-in silence stacked on the previous clip's tail ran past a second
+ * (#2388). Each side comes back to a beat that reads as one conversation, a
+ * longer one when someone new answers. Only ever shortens, never into a word.
+ * The ad's first lead-in comes back to the same-speaker beat too, since a clip
+ * can hum before its first word (#2666); its last tail is left alone, and a
+ * clip whose closing line cues a reaction is not the ad's end, since the beat
+ * follows it. Trims land on whole frames so the picture and its sound stay the
+ * same length.
+ *
+ * The beat is measured from the clip's scripted words when the script is heard
+ * in order, and a cut stops short of a sound made up before or after the line
+ * ("Hmm", "Um"), even at the ad's own edges (#2541). Sounds inside the line stay.
+ * A scene the storyboard marks with actionTailSec keeps that long after its last
+ * word, so the action it ends on (her setting the mat down, #3199) is seen.
+ */
+function trimJoins(spine, reactionCues, scriptLines) {
+  spine.forEach((seg, k) => {
+    if (seg.source !== "clip" || seg.audio !== "clip" || !seg.words?.length) return;
+    const prev = spine[k - 1];
+    const sameSpeaker = Boolean(prev?.lastSpeaker) && prev.lastSpeaker === seg.firstSpeaker;
+    const lead = sameSpeaker || !prev ? JOIN_LEAD_SAME_SPEAKER_SEC : JOIN_LEAD_NEW_SPEAKER_SEC;
+    const span = scriptedSpan(seg.words, seg.lineIds.map((id) => scriptLines.get(id)?.text));
+    const line = span ? seg.words.slice(span.first, span.last + 1) : seg.words;
+    const before = span ? seg.words.slice(0, span.first) : [];
+    const after = span ? seg.words.slice(span.last + 1) : [];
+    const firstWord = Math.min(...line.map((w) => w.s));
+    const lastWord = Math.max(...line.map((w) => w.e));
+    let inSec = Math.max(0, floorFrame(firstWord - lead));
+    if (before.length > 0) {
+      const clear = ceilFrame(Math.max(...before.map((w) => w.e)) + EXTRA_CLEARANCE_SEC);
+      inSec = Math.max(inSec, Math.min(clear, floorFrame(firstWord)));
+    }
+    const endsAd = k === spine.length - 1 && !reactionCues.has(seg.lineIds.at(-1));
+    let outSec = endsAd
+      ? after.length > 0 ? ceilFrame(lastWord + TAIL_AIR_SEC) : seg.seconds
+      : ceilFrame(lastWord + Math.max(JOIN_TAIL_SEC, seg.actionTailSec ?? 0));
+    if (after.length > 0) {
+      const clear = floorFrame(Math.min(...after.map((w) => w.s)) - EXTRA_CLEARANCE_SEC);
+      outSec = Math.min(outSec, Math.max(clear, ceilFrame(lastWord)));
+    }
+    outSec = Math.min(seg.seconds, outSec);
+    if (outSec <= inSec) return;
+    const how = [];
+    if (inSec > 0) how.push(`lead-in trimmed ${inSec.toFixed(2)}s`);
+    if (outSec < seg.seconds) how.push(`tail trimmed ${(seg.seconds - outSec).toFixed(2)}s`);
+    if (how.length === 0) return;
+    const kept = seg.words.filter((w) => w.s < outSec && w.e > inSec);
+    if (before.some((w) => !kept.includes(w))) how.push("extra sound before the line trimmed");
+    if (after.some((w) => !kept.includes(w))) how.push("extra sound after the line trimmed");
+    seg.inSec = inSec;
+    seg.seconds = outSec - inSec;
+    seg.words = kept.map((w) => ({ ...w, s: w.s - inSec, e: w.e - inSec }));
+    seg.note = withHow(seg.note, how);
+  });
+}
+
+const holdFor = (seg) =>
+  seg.source === "clip" ? Math.max(0, seg.seconds - Math.max(0, seg.clipSeconds - seg.inSec)) : 0;
+
+/**
+ * Put a reaction beat into the spine right after its cue line ends, splitting
+ * the segment that speaks it when more lines follow in that segment. Returns
+ * the scene that speaks the cue, or null when no segment does.
+ */
+function placeReaction(spine, counts, reaction) {
+  for (let k = 0; k < spine.length; k++) {
+    const seg = spine[k];
+    if (seg.reaction) continue;
+    const cueEnd = cueEndInSegment(seg, counts, reaction.cueLineId);
+    if (cueEnd === null) continue;
+    const cut = Math.min(seg.seconds, ceilFrame(cueEnd));
+    const beat = {
+      sceneIndex: reaction.sceneIndex, source: reaction.source, file: reaction.file,
+      clipSeconds: reaction.source === "clip" ? reaction.seconds : null, inSec: 0,
+      seconds: Math.min(reaction.seconds, REACTION_MAX_SEC), holdSec: 0,
+      audio: reaction.hasAudio ? "clip" : "silence", voice: null, words: null, lineIds: [],
+      reaction: { cueLineId: reaction.cueLineId, cueSceneIndex: seg.sceneIndex },
+    };
+    if (cut >= seg.seconds - 0.05) {
+      spine.splice(k + 1, 0, beat);
+      return seg.sceneIndex;
+    }
+    const idx = seg.lineIds.indexOf(reaction.cueLineId);
+    const head = {
+      ...seg, seconds: cut, lineIds: seg.lineIds.slice(0, idx + 1),
+      words: seg.words ? seg.words.filter((w) => w.s < cut) : null,
+      note: `${seg.note}, until ${reaction.cueLineId} ends at ${cut.toFixed(2)}s`,
+    };
+    const tail = {
+      ...seg, inSec: seg.inSec + cut, seconds: seg.seconds - cut, lineIds: seg.lineIds.slice(idx + 1),
+      words: seg.words
+        ? seg.words.filter((w) => w.s >= cut).map((w) => ({ ...w, s: w.s - cut, e: w.e - cut }))
+        : null,
+      note: `${seg.note}, resumed at ${cut.toFixed(2)}s after reaction ${reaction.sceneIndex}`,
+    };
+    head.holdSec = holdFor(head);
+    tail.holdSec = holdFor(tail);
+    spine.splice(k, 1, head, beat, tail);
+    return seg.sceneIndex;
+  }
+  return null;
+}
+
+/**
+ * The sound a reaction beat carries under the next segment (#2406), as a J/L
+ * cut: the picture moves on early and the clip's sound from where it stops
+ * plays under the next line. A clip that ends with its beat gives up the
+ * beat's end, down to REACTION_MIN_BEAT_SEC, rather than replaying sound the
+ * beat already played, which was heard as a stutter (#2666, #2700). Shortens
+ * the beat, so it runs before the spine's start times are set. Null when
+ * under 0.4 s of sound would carry over; the beat fades itself out then.
+ */
+function carveReactionTail(seg, next) {
+  const clipLen = seg.clipSeconds ?? seg.seconds;
+  const overlap =
+    Math.round(Math.min(REACTION_TAIL_SEC, clipLen - seg.inSec - REACTION_MIN_BEAT_SEC, next.seconds) * 1000) / 1000;
+  if (overlap < REACTION_FADE_OUT_SEC) return null;
+  seg.seconds = Math.min(seg.seconds, Math.round((clipLen - seg.inSec - overlap) * 1000) / 1000);
+  return { fromSec: seg.inSec + seg.seconds, seconds: overlap, gain: REACTION_TAIL_GAIN };
+}
+
+/**
+ * #2666: how long a reaction beat fades in. A generated laugh clip can hum
+ * before the laugh starts, so the fade runs across that quiet start, up to its
+ * first sound; without the clip's loudness it is the plain edge fade.
+ */
+function quietStart(levels, seconds) {
+  const first = levels ? levels.db.findIndex((d) => d >= SOUND_DB) : -1;
+  return first > 0 ? Math.min(seconds, Math.max(EDGE_FADE_SEC, first * levels.windowSec)) : EDGE_FADE_SEC;
+}
+
+export function buildTimeline({ manifest, storyboard, skip, probe, exists, readWords, readLevels = () => null }) {
   const plans = scenePlans(storyboard);
   const counts = lineWordCounts(storyboard);
   const spine = [];
   const cutaways = [];
   const waiting = [];
   const dropped = [];
-  let startSec = 0;
 
   for (const scene of manifest?.scenes ?? []) {
     const n = scene.sceneIndex;
-    const plan = plans.get(n) ?? { cutaway: false, lineIds: [], cueLineId: null, durationSec: null };
+    const plan = plans.get(n) ?? {
+      cutaway: false, lineIds: [], cueLineId: null, cutawayType: null, durationSec: null,
+      firstSpeaker: null, lastSpeaker: null,
+    };
     if (skip.has(n)) {
       dropped.push({ n, reason: `scene ${n}: skipped by --skip` });
       continue;
@@ -145,15 +597,17 @@ export function buildTimeline({ manifest, storyboard, skip, probe, exists, readW
     const nothing = `nothing to cut with (clip ${scene.clipStatus}${scene.error ? `: ${scene.error}` : ""})`;
 
     if (plan.cutaway) {
+      const cue = { cueLineId: plan.cueLineId, reaction: plan.cutawayType === "reaction" };
       if (exists(scene.clip)) {
+        const clip = probe(scene.clip);
         waiting.push({
           sceneIndex: n, source: "clip", file: scene.clip,
-          seconds: probe(scene.clip).seconds, cueLineId: plan.cueLineId,
+          seconds: clip.seconds, hasAudio: clip.hasAudio, ...cue,
         });
       } else if (exists(scene.keyframe)) {
         waiting.push({
           sceneIndex: n, source: "still", file: scene.keyframe,
-          seconds: plan.durationSec ?? 4, cueLineId: plan.cueLineId,
+          seconds: plan.durationSec ?? 4, hasAudio: false, ...cue,
         });
       } else {
         dropped.push({ n, reason: `cutaway ${n}: ${nothing}` });
@@ -168,11 +622,14 @@ export function buildTimeline({ manifest, storyboard, skip, probe, exists, readW
     if (exists(scene.clip)) {
       const clip = probe(scene.clip);
       const base = {
-        sceneIndex: n, source: "clip", file: scene.clip, clipSeconds: clip.seconds,
-        startSec, lineIds: plan.lineIds,
+        sceneIndex: n, source: "clip", file: scene.clip, clipSeconds: clip.seconds, inSec: 0,
+        lineIds: plan.lineIds, firstSpeaker: plan.firstSpeaker, lastSpeaker: plan.lastSpeaker,
+        actionTailSec: plan.actionTailSec ?? 0,
       };
       if (voice && (narrated || !clip.hasAudio)) {
-        const fit = fitNarration({ clipSeconds: clip.seconds, voiceSeconds: probe(voice).seconds });
+        const fit = fitNarration({
+          clipSeconds: clip.seconds, voiceSeconds: probe(voice).seconds, actionTailSec: plan.actionTailSec ?? 0,
+        });
         const how = [];
         if (fit.trimmedBy > 0.05) how.push(`clip trimmed ${clip.seconds.toFixed(1)}s -> ${fit.seconds.toFixed(1)}s`);
         if (fit.holdSec > 0.05) how.push(`last frame held ${fit.holdSec.toFixed(1)}s`);
@@ -198,7 +655,6 @@ export function buildTimeline({ manifest, storyboard, skip, probe, exists, readW
           words: null, note: `${flag}, silent clip`,
         });
       }
-      startSec += spine[spine.length - 1].seconds;
       continue;
     }
     if (exists(scene.keyframe)) {
@@ -206,39 +662,72 @@ export function buildTimeline({ manifest, storyboard, skip, probe, exists, readW
         ? fitNarration({ clipSeconds: null, voiceSeconds: probe(voice).seconds })
         : { seconds: plan.durationSec ?? 4, holdSec: 0 };
       spine.push({
-        sceneIndex: n, source: "still", file: scene.keyframe, clipSeconds: null,
+        sceneIndex: n, source: "still", file: scene.keyframe, clipSeconds: null, inSec: 0,
         seconds: fit.seconds, audio: voice ? "narration" : "silence", voice, holdSec: 0,
-        startSec, lineIds: plan.lineIds,
+        lineIds: plan.lineIds,
         // #1689: on a narrated scene the words are the voice track's, and the
         // voice starts where the segment does, so they need no offset here.
         words: voice ? readWords(scene.words) : null,
         note: `${flag}${voice ? ` + ${voice}` : ", silent"} (${fit.seconds.toFixed(1)}s, clip ${scene.clipStatus})`,
       });
-      startSec += fit.seconds;
       continue;
     }
     dropped.push({ n, reason: `scene ${n}: ${nothing}` });
   }
 
-  for (const c of waiting) {
+  const noCue = (c) =>
+    c.cueLineId ? `${c.cueLineId} is spoken by no scene in the cut` : "the storyboard names no cue line";
+
+  // Sentence gaps and then joins are closed first so a reaction beat lands
+  // right after its cue line ends in the trimmed clip. Reactions change the
+  // spine, so they go in before any overlay is placed on it.
+  const scriptLines = new Map((storyboard?.script ?? []).map((line) => [line?.lineId, line]));
+  const reactionCues = new Set(waiting.filter((w) => w.reaction).map((w) => w.cueLineId));
+  tightenSentenceGaps(spine, reactionCues, scriptLines, readLevels);
+  trimJoins(spine, reactionCues, scriptLines);
+  for (const c of waiting.filter((w) => w.reaction)) {
+    if (!c.cueLineId || placeReaction(spine, counts, c) === null) {
+      dropped.push({ n: c.sceneIndex, reason: `cutaway ${c.sceneIndex}: ${noCue(c)}` });
+    }
+  }
+  spine.forEach((seg, k) => {
+    if (!seg.reaction || seg.audio !== "clip") return;
+    const tail = spine[k + 1] ? carveReactionTail(seg, spine[k + 1]) : null;
+    if (tail) seg.reaction.tail = tail;
+    else seg.fadeOutSec = Math.min(REACTION_FADE_OUT_SEC, seg.seconds);
+    seg.fadeInSec = quietStart(readLevels(seg.file), seg.seconds);
+  });
+  let total = 0;
+  for (const seg of spine) {
+    seg.startSec = total;
+    total += seg.seconds;
+  }
+  spine.forEach((seg, k) => {
+    if (seg.reaction?.tail) seg.reaction.tail.atSec = spine[k + 1].startSec;
+  });
+
+  for (const c of waiting.filter((w) => !w.reaction)) {
     const cue = c.cueLineId ? cueOffsetOnSpine(spine, counts, c.cueLineId) : null;
     if (!cue) {
-      const why = c.cueLineId
-        ? `${c.cueLineId} is spoken by no scene in the cut`
-        : "the storyboard names no cue line";
-      dropped.push({ n: c.sceneIndex, reason: `cutaway ${c.sceneIndex}: ${why}` });
+      dropped.push({ n: c.sceneIndex, reason: `cutaway ${c.sceneIndex}: ${noCue(c)}` });
       continue;
     }
     cutaways.push({ ...c, startSec: cue.startSec, method: cue.method, spineSceneIndex: cue.spineSceneIndex });
   }
   cutaways.sort((a, b) => a.startSec - b.startSec);
+  const beats = spine.filter((seg) => seg.reaction);
   for (let i = 0; i < cutaways.length; i++) {
     const c = cutaways[i];
+    const stops = [];
     const next = cutaways[i + 1];
-    const end = Math.min(startSec, next ? next.startSec : Infinity);
-    if (c.startSec + c.seconds > end) {
-      c.seconds = Math.max(0, end - c.startSec);
-      c.cutShortBy = next && end === next.startSec ? `cutaway ${next.sceneIndex} starts` : "the ad ends";
+    if (next) stops.push({ at: next.startSec, by: `cutaway ${next.sceneIndex} starts` });
+    const beat = beats.find((b) => b.startSec >= c.startSec);
+    if (beat) stops.push({ at: beat.startSec, by: `reaction ${beat.sceneIndex} starts` });
+    stops.push({ at: total, by: "the ad ends" });
+    const stop = stops.reduce((a, b) => (b.at < a.at ? b : a));
+    if (c.startSec + c.seconds > stop.at) {
+      c.seconds = Math.max(0, stop.at - c.startSec);
+      c.cutShortBy = stop.by;
     }
   }
 
@@ -262,6 +751,7 @@ export function buildFfmpegArgs(timeline, { resolve, music, out }) {
   };
   const filters = [];
   const pairs = [];
+  const tails = [];
 
   for (const seg of timeline.spine) {
     const i =
@@ -269,26 +759,76 @@ export function buildFfmpegArgs(timeline, { resolve, music, out }) {
         ? addInput("-i", resolve(seg.file))
         : addInput("-loop", "1", "-t", String(seg.seconds), "-i", resolve(seg.file));
     const fit = [];
-    if (seg.source === "clip" && seg.clipSeconds !== null && seg.seconds < seg.clipSeconds - 0.01) {
-      fit.push(`trim=0:${sec(seg.seconds)},setpts=PTS-STARTPTS`);
+    const inSec = seg.inSec ?? 0;
+    // #2544: sentence gaps come out first, the picture by frame number and the
+    // sound by the same times, so everything after works on the cut timeline.
+    const cuts = seg.cuts ?? [];
+    let heard = `[${i}:a]${stereo},`;
+    if (cuts.length > 0) {
+      const frames = cuts.map((c) => `between(n\\,${Math.round(c.s * FPS)}\\,${Math.round(c.e * FPS) - 1})`);
+      fit.push(`select=not(${frames.join("+")}),setpts=N/FRAME_RATE/TB`);
+      const kept = [0, ...cuts.flatMap((c) => [c.s, c.e])];
+      const pieces = cuts.length + 1;
+      filters.push(`[${i}:a]${stereo},asplit=${pieces}${Array.from({ length: pieces }, (_, p) => `[ap${i}_${p}]`).join("")}`);
+      for (let p = 0; p < pieces; p++) {
+        const end = p < cuts.length ? `:end=${kept[2 * p + 1].toFixed(6)}` : "";
+        filters.push(`[ap${i}_${p}]atrim=start=${kept[2 * p].toFixed(6)}${end},asetpts=PTS-STARTPTS[aq${i}_${p}]`);
+      }
+      filters.push(
+        `${Array.from({ length: pieces }, (_, p) => `[aq${i}_${p}]`).join("")}concat=n=${pieces}:v=0:a=1[ac${i}]`,
+      );
+      heard = `[ac${i}]`;
+    }
+    if (seg.source === "clip" && seg.clipSeconds !== null) {
+      const shown = seg.seconds - seg.holdSec;
+      if (inSec > 0.001 || shown < seg.clipSeconds - 0.01) {
+        // By frame number: a time printed to the millisecond can round past the
+        // frame it names and drop it.
+        const from = Math.round(inSec * FPS);
+        fit.push(`trim=start_frame=${from}:end_frame=${Math.round((inSec + shown) * FPS)},setpts=PTS-STARTPTS`);
+      }
     }
     if (seg.holdSec > 0.01) fit.push(`tpad=stop_mode=clone:stop_duration=${sec(seg.holdSec)}`);
     filters.push(`${norm(`${i}:v`)}${fit.length ? `,${fit.join(",")}` : ""}[v${i}]`);
+    // A segment split around a reaction beat starts partway into its sound too.
+    const skipIn = inSec > 0.001 ? `atrim=start=${sec(inSec)},asetpts=PTS-STARTPTS,` : "";
+    const [fadeIn, fadeOut] = [seg.fadeInSec ?? EDGE_FADE_SEC, seg.fadeOutSec ?? EDGE_FADE_SEC];
+    // A cubic rise keeps a reaction's quiet start near silent until its laugh (#2666).
+    const rise = fadeIn > EDGE_FADE_SEC ? ":curve=cub" : "";
+    const fitLength =
+      `apad,atrim=0:${sec(seg.seconds)},afade=t=in:d=${sec(fadeIn)}${rise},` +
+      `afade=t=out:st=${sec(seg.seconds - fadeOut)}:d=${sec(fadeOut)}`;
+    const fitSound = `${LOUDNORM},${fitLength}`;
     if (seg.audio === "narration") {
       const v = addInput("-i", resolve(seg.voice));
-      filters.push(`[${v}:a]${stereo},${LOUDNORM},apad,atrim=0:${sec(seg.seconds)}[a${i}]`);
+      filters.push(`[${v}:a]${stereo},${skipIn}${fitSound}[a${i}]`);
+    } else if (seg.audio === "clip" && seg.reaction?.tail) {
+      // The tail is cut from the same loudness-normalized sound as the beat,
+      // ducked, faded out, and laid in at the join; the next line's own sound
+      // plays at full level over it (#2406).
+      const t = seg.reaction.tail;
+      filters.push(`${heard}${skipIn}${LOUDNORM},asplit=2[as${i}][at${i}]`);
+      filters.push(`[as${i}]${fitLength}[a${i}]`);
+      filters.push(
+        `[at${i}]atrim=start=${sec(t.fromSec - inSec)}:duration=${sec(t.seconds)},asetpts=PTS-STARTPTS,` +
+          `volume=${t.gain},afade=t=in:d=${EDGE_FADE_SEC},afade=t=out:st=0:d=${sec(t.seconds)},` +
+          `adelay=delays=${Math.round(t.atSec * 1000)}:all=1[tail${i}]`,
+      );
+      tails.push(`[tail${i}]`);
     } else if (seg.audio === "clip") {
-      filters.push(`[${i}:a]${stereo},${LOUDNORM},apad,atrim=0:${sec(seg.seconds)}[a${i}]`);
+      filters.push(`${heard}${skipIn}${fitSound}[a${i}]`);
     } else {
       filters.push(`anullsrc=r=48000:cl=stereo,atrim=0:${sec(seg.seconds)}[a${i}]`);
     }
     pairs.push(`[v${i}][a${i}]`);
   }
 
-  // A clip whose audio ends before its video would otherwise end the whole cut
-  // there under -shortest; padding lets the video decide the length.
   filters.push(`${pairs.join("")}concat=n=${pairs.length}:v=1:a=1[vcat][voicecat]`);
-  filters.push(`[voicecat]apad[voice]`);
+  // The sound is padded or cut to the picture's exact length, so every stream
+  // ends on its own. No -shortest: ffmpeg 8 held the whole ad's frames for it,
+  // and Debian's ffmpeg 5.1 (the worker's) never ended at all (#2988).
+  const pictureSec = timeline.spine.reduce((sum, seg) => sum + seg.seconds, 0);
+  filters.push(`[voicecat]apad,atrim=end=${pictureSec.toFixed(6)}[voice]`);
 
   let videoLabel = "vcat";
   timeline.cutaways.forEach((c, j) => {
@@ -308,7 +848,7 @@ export function buildFfmpegArgs(timeline, { resolve, music, out }) {
   });
 
   filters.push(`${ROOM_TONE}[room]`);
-  const beds = ["[room]"];
+  const beds = ["[room]", ...tails];
   if (music) {
     const m = addInput("-stream_loop", "-1", "-i", music);
     filters.push(`[${m}:a]${stereo},volume=${MUSIC_VOLUME}[bed]`);
@@ -326,7 +866,7 @@ export function buildFfmpegArgs(timeline, { resolve, music, out }) {
     "-map", `[${videoLabel}]`, "-map", `[${audioLabel}]`,
     "-c:v", "libx264", "-preset", "medium", "-crf", "20", "-r", String(FPS),
     "-c:a", "aac", "-b:a", "192k",
-    "-movflags", "+faststart", "-shortest",
+    "-movflags", "+faststart",
     out,
   ];
 }
@@ -398,6 +938,23 @@ export function inTheCut(timeline) {
   const rows = [];
   for (const seg of timeline.spine) {
     const label = seg.source === "clip" ? seg.file : `still ${seg.file}`;
+    if (seg.reaction) {
+      const sound = seg.audio === "clip" ? "its own sound" : "silent: the clip has no sound";
+      const tail = seg.reaction.tail;
+      const fadeIn =
+        seg.fadeInSec > EDGE_FADE_SEC ? `, fading in over its quiet first ${seg.fadeInSec.toFixed(2)}s` : "";
+      const fadeOut = tail
+        ? `, fading out under the next line at ${tail.atSec.toFixed(2)}s over ${tail.seconds.toFixed(2)}s`
+        : seg.fadeOutSec ? `, fading out over its last ${seg.fadeOutSec.toFixed(2)}s` : "";
+      const fades = fadeIn + fadeOut;
+      rows.push({
+        n: seg.sceneIndex,
+        line:
+          `reaction ${seg.sceneIndex}: ${label} for ${seg.seconds.toFixed(1)}s after ` +
+          `${seg.reaction.cueLineId} in scene ${seg.reaction.cueSceneIndex}, ${sound}${fades}`,
+      });
+      continue;
+    }
     rows.push({ n: seg.sceneIndex, line: `scene ${seg.sceneIndex}: ${label}${seg.note}` });
   }
   for (const c of timeline.cutaways) {
@@ -417,10 +974,112 @@ export function inTheCut(timeline) {
   return rows.sort((a, b) => a.n - b.n).map((r) => r.line);
 }
 
+/**
+ * #2666: a generated clip can hum or click where nobody speaks, and the cut
+ * plays that stretch with nothing over it. A hum is HUM_BAND's share of the
+ * sound (the 1 kHz whine heard before a first word) holding for HUM_MIN_SEC
+ * over HUM_FLOOR_DB; a click is a sound of at most CLICK_MAX_WINDOWS with
+ * quiet on both sides, loud as the gap cutter reads a sound in near silence.
+ */
+export const HUM_BAND = "highpass=f=800,highpass=f=800,lowpass=f=1500,lowpass=f=1500";
+// White noise measures about -13.5 dB through HUM_BAND at 16 kHz (-10.6 dB on
+// paper), and the four hums #2666 was calibrated on held -6 to -10 dB.
+const HUM_SHARE_DB = -10;
+const HUM_FLOOR_DB = -70;
+const HUM_MIN_SEC = 0.16;
+const CLICK_MAX_WINDOWS = 3;
+
+/**
+ * Where the cut plays a clip's sound with no word in it, in the clip's own
+ * time: before a dialogue clip's first word, after its last, and a reaction's
+ * quiet start (under its cubic fade-in when the cut fades it).
+ */
+function edgeStretches(seg, levels) {
+  const inSec = seg.inSec ?? 0;
+  if (seg.reaction) {
+    const quiet = quietStart(levels, seg.seconds);
+    if (quiet <= EDGE_FADE_SEC) return [];
+    const fadeIn = seg.fadeInSec ?? 0;
+    return [{ side: "before its laugh", from: inSec, to: inSec + quiet, at: seg.startSec, fadeIn }];
+  }
+  if (!seg.words?.length) return [];
+  // inSec and the words are on the clip's timeline with its sentence gaps
+  // taken out; the levels are the file's own, so each edge goes back through
+  // the cuts before it.
+  const raw = (t) => {
+    let at = t;
+    for (const c of seg.cuts ?? []) if (c.s <= at) at += c.e - c.s;
+    return at;
+  };
+  const first = seg.words[0].s;
+  const last = Math.max(...seg.words.map((w) => w.e));
+  const shown = seg.seconds - (seg.holdSec ?? 0);
+  return [
+    { side: "before its first word", from: raw(inSec), to: raw(inSec + first), at: seg.startSec, fadeIn: 0 },
+    {
+      side: "after its last word", from: raw(inSec + last), to: raw(inSec + shown),
+      at: seg.startSec + last, fadeIn: 0,
+    },
+  ];
+}
+
+/**
+ * The hums and clicks the cut plays at the edges of its clips, one line each,
+ * for the caller to listen to. It never changes the cut. readEdgeLevels(file)
+ * gives { windowSec, db, bandDb } from time 0, or null.
+ */
+export function edgeSounds(timeline, readEdgeLevels) {
+  const found = [];
+  for (const seg of timeline.spine) {
+    if (seg.source !== "clip" || seg.audio !== "clip") continue;
+    const levels = readEdgeLevels(seg.file);
+    if (!levels) continue;
+    const { windowSec, db, bandDb } = levels;
+    for (const stretch of edgeStretches(seg, levels)) {
+      const from = Math.ceil(stretch.from / windowSec - 1e-9);
+      const to = Math.min(db.length, Math.floor(stretch.to / windowSec + 1e-9));
+      if (to - from < 2) continue;
+      const heard = [];
+      for (let i = from; i < to; i++) {
+        const into = (i + 0.5) * windowSec - stretch.from;
+        const faded = stretch.fadeIn > 0 && into < stretch.fadeIn;
+        const gain = faded ? 60 * Math.log10(Math.max(1e-3, into / stretch.fadeIn)) : 0;
+        heard.push({ i, db: db[i] + gain, share: bandDb[i] - db[i] });
+      }
+      const cutAt = (i) => stretch.at + i * windowSec - stretch.from;
+      const where = `scene ${seg.sceneIndex}, ${stretch.side}`;
+      let run = 0;
+      let longest = { length: 0, end: 0 };
+      heard.forEach((w, k) => {
+        run = w.db >= HUM_FLOOR_DB && w.share >= HUM_SHARE_DB ? run + 1 : 0;
+        if (run > longest.length) longest = { length: run, end: k };
+      });
+      if (longest.length * windowSec >= HUM_MIN_SEC - 1e-9) {
+        const start = heard[longest.end - longest.length + 1].i;
+        found.push(
+          `${where}: a hum for ${(longest.length * windowSec).toFixed(2)}s at ${cutAt(start).toFixed(2)}s in the cut`,
+        );
+      }
+      const sorted = heard.map((w) => w.db).sort((a, b) => a - b);
+      const loud = Math.max(FAINT_SOUND_DB, sorted[sorted.length >> 1] + SOUND_OVER_FLOOR_DB);
+      for (let k = 1; k < heard.length - 1; k++) {
+        if (heard[k].db < loud || heard[k - 1].db >= QUIET_DB) continue;
+        let end = k;
+        while (end < heard.length && heard[end].db >= loud) end++;
+        if (end < heard.length && heard[end].db < QUIET_DB && end - k <= CLICK_MAX_WINDOWS) {
+          found.push(`${where}: a click at ${cutAt(heard[k].i).toFixed(2)}s in the cut`);
+        }
+        k = end;
+      }
+    }
+  }
+  return found;
+}
+
 export function noWordTimes(timeline) {
   const rows = timeline.spine
     .filter((seg) => !seg.words || seg.words.length === 0)
-    .map((seg) => `scene ${seg.sceneIndex} (no words.json)`);
+    .map((seg) => `scene ${seg.sceneIndex} (${seg.reaction ? "reaction" : "no words.json"})`);
   for (const c of timeline.cutaways) rows.push(`scene ${c.sceneIndex} (cutaway)`);
   return rows;
 }
@@ -430,6 +1089,15 @@ function fail(code, message) {
   process.exit(code);
 }
 
+/** A refusal the CLI prints to stderr and exits with `code`, so another caller can do the same or not. */
+export class FirstCutError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "FirstCutError";
+    this.code = code;
+  }
+}
+
 function parseArgs(argv) {
   const opts = { dir: undefined, out: undefined, skip: new Set(), music: true };
   for (let i = 0; i < argv.length; i++) {
@@ -445,26 +1113,29 @@ function parseArgs(argv) {
   return opts;
 }
 
-function main() {
-  const opts = parseArgs(process.argv.slice(2));
-
+/**
+ * The whole cut, as the CLI makes it, for any caller (#2988: the worker cuts a
+ * Video-page run with this). Renders `out` (default <dir>/cut.mp4) and its word
+ * sidecars, and throws FirstCutError where the CLI would exit. The CLI's report
+ * is printed by main() from what this returns.
+ */
+export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn = true }) {
   for (const bin of ["ffmpeg", "ffprobe"]) {
     if (spawnSync(bin, ["-version"]).status !== 0) {
-      fail(2, `${bin} is not installed. Install ffmpeg (brew install ffmpeg / apt install ffmpeg).`);
+      throw new FirstCutError(2, `${bin} is not installed. Install ffmpeg (brew install ffmpeg / apt install ffmpeg).`);
     }
   }
   const encoders = spawnSync("ffmpeg", ["-hide_banner", "-encoders"]).stdout?.toString() ?? "";
   if (!/\blibx264\b/.test(encoders)) {
-    fail(2, "This ffmpeg has no libx264 encoder (H.264). Install a full ffmpeg build: brew install ffmpeg / apt install ffmpeg.");
+    throw new FirstCutError(2, "This ffmpeg has no libx264 encoder (H.264). Install a full ffmpeg build: brew install ffmpeg / apt install ffmpeg.");
   }
 
-  const dir = opts.dir;
   const manifestPath = path.join(dir, "manifest.json");
   if (!existsSync(manifestPath)) {
-    fail(2, `${manifestPath} not found. Run: exodus video pull <runId> --out ${dir}`);
+    throw new FirstCutError(2, `${manifestPath} not found. Run: exodus video pull <runId> --out ${dir}`);
   }
   const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
-  const out = path.resolve(opts.out ?? path.join(dir, "cut.mp4"));
+  const out = path.resolve(outOpt ?? path.join(dir, "cut.mp4"));
   const here = (file) => path.join(dir, file);
   const exists = (file) => Boolean(file) && existsSync(here(file));
 
@@ -478,11 +1149,14 @@ function main() {
   };
   const probe = (file) => {
     const raw = execFileSync("ffprobe", [
-      "-v", "error", "-show_entries", "stream=codec_type:format=duration", "-of", "json", here(file),
+      "-v", "error", "-show_entries", "stream=codec_type,duration:stream_disposition=attached_pic:format=duration", "-of", "json", here(file),
     ]).toString();
     const info = JSON.parse(raw);
+    // A clip's container runs a few ms past its picture on the audio's padding;
+    // the picture is what the cut shows, so its length is the clip's length.
+    const picture = Number((info.streams ?? []).find((s) => s.codec_type === "video" && !s.disposition?.attached_pic)?.duration);
     return {
-      seconds: Number(info.format?.duration ?? 0),
+      seconds: picture > 0 ? picture : Number(info.format?.duration ?? 0),
       hasAudio: (info.streams ?? []).some((s) => s.codec_type === "audio"),
     };
   };
@@ -494,19 +1168,20 @@ function main() {
   const timeline = buildTimeline({
     manifest,
     storyboard,
-    skip: opts.skip,
+    skip,
     probe,
     exists,
     readWords: (file) => {
       const rows = readJson(file);
       return Array.isArray(rows) && rows.length > 0 ? rows : null;
     },
+    readLevels: (file) => clipLevels(here(file)),
   });
   if (timeline.spine.length === 0) {
-    fail(1, `No scene has a clip or a keyframe. Check: exodus video status ${manifest.runId}`);
+    throw new FirstCutError(1, `No scene has a clip or a keyframe. Check: exodus video status ${manifest.runId}`);
   }
 
-  const music = opts.music && exists(manifest.music) ? manifest.music : null;
+  const music = musicOn && exists(manifest.music) ? manifest.music : null;
   const ffmpegArgs = buildFfmpegArgs(timeline, {
     resolve: here,
     music: music ? here(music) : null,
@@ -515,7 +1190,7 @@ function main() {
   const res = spawnSync("ffmpeg", ffmpegArgs, { stdio: "inherit" });
   if (res.status !== 0) {
     const quoted = ffmpegArgs.map((a) => (/[\s\[\];]/.test(a) ? `'${a}'` : a)).join(" ");
-    fail(1, `ffmpeg failed. The command it ran:\n  ffmpeg ${quoted}`);
+    throw new FirstCutError(1, `ffmpeg failed. The command it ran:\n  ffmpeg ${quoted}`);
   }
 
   const rows = wordRows(timeline);
@@ -531,7 +1206,22 @@ function main() {
   const duration = execFileSync("ffprobe", [
     "-v", "error", "-show_entries", "format=duration", "-of", "default=nw=1:nk=1", out,
   ]).toString().trim();
-  console.log(`Wrote ${out} (${Number(duration).toFixed(1)}s, ${WIDTH}x${HEIGHT})`);
+  return { out, durationSec: Number(duration), manifest, timeline, music, rows, sidecars };
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  let cut;
+  try {
+    cut = firstCut(opts);
+  } catch (e) {
+    if (e instanceof FirstCutError) fail(e.code, e.message);
+    throw e;
+  }
+  const { out, durationSec, manifest, timeline, music, rows, sidecars } = cut;
+  const here = (file) => path.join(opts.dir, file);
+
+  console.log(`Wrote ${out} (${durationSec.toFixed(1)}s, ${WIDTH}x${HEIGHT})`);
   console.log("In the cut:");
   for (const line of inTheCut(timeline)) console.log("  " + line);
   if (timeline.left.length > 0) {
@@ -548,8 +1238,25 @@ function main() {
   }
   const silent = noWordTimes(timeline);
   if (silent.length > 0) console.log(`No word times: ${silent.join(", ")}`);
+  const edges = edgeSounds(timeline, (file) => {
+    const levels = clipLevels(here(file));
+    const band = levels && clipLevels(here(file), HUM_BAND);
+    return band ? { ...levels, bandDb: band.db } : null;
+  });
+  if (edges.length > 0) {
+    console.log("Sound at the edges (listen before uploading; the cut is unchanged):");
+    for (const line of edges) console.log("  " + line);
+  }
   console.log(`Room tone: under the whole ad. Music bed: ${music ?? "none"}`);
   console.log(`Upload it: exodus video upload ${manifest.runId} --file ${out}`);
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();
+// #2988: the basename test too, because a bundler that inlines this file into
+// its entry would otherwise run the CLI inside whatever imported it.
+if (
+  process.argv[1] &&
+  path.basename(process.argv[1]) === "first-cut.mjs" &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main();
+}