@aicopycoders/exodus 2026.9.2000-beta.2 → 2026.9.2000-beta.21

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,
+// and its sound fades out quietly under the next line rather than stopping.
 //
 //   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,48 @@ 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.
+ */
+const LOUDNORM = "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;
+/**
+ * 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 +96,226 @@ 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;
+/** 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. 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++;
+  let resumed = -1;
+  for (let i = quiet; i < last; i = resumed + SETTLED_WINDOWS) {
+    while (i < last && db[i] < SOUND_DB) 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. */
+function clipLevels(file) {
+  const res = spawnSync(
+    "ffmpeg",
+    ["-v", "error", "-i", file, "-map", "0:a:0", "-ac", "1", "-ar", "16000", "-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,11 +339,17 @@ 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,
     });
   }
@@ -90,12 +358,12 @@ 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.
  */
 export function fitNarration({ clipSeconds, voiceSeconds }) {
-  const target = voiceSeconds + TAIL_AIR_SEC;
+  const target = ceilFrame(voiceSeconds + TAIL_AIR_SEC);
   if (clipSeconds === null) return { seconds: target, holdSec: 0, trimmedBy: 0 };
   if (target <= clipSeconds) {
     return { seconds: target, holdSec: 0, trimmedBy: clipSeconds - target };
@@ -126,18 +394,157 @@ 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,
+ * and leaves the ad's first lead-in and last tail alone; 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.
+ */
+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 ? 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 = prev ? Math.max(0, floorFrame(firstWord - lead)) : 0;
+    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 + JOIN_TAIL_SEC);
+    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): the clip's
+ * own sound past the beat when it has some (older 4 s pulls), else its last
+ * stretch replayed, so a clip exactly as long as its beat still fades out.
+ */
+function reactionTail(seg, next) {
+  const clipLen = seg.clipSeconds ?? seg.seconds;
+  const beatEnd = seg.inSec + seg.seconds;
+  const fromSec = Math.max(0, Math.min(beatEnd, clipLen - REACTION_TAIL_SEC));
+  const seconds = Math.min(REACTION_TAIL_SEC, next.seconds, clipLen - fromSec);
+  return { atSec: next.startSec, fromSec, seconds, gain: REACTION_TAIL_GAIN };
+}
+
+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 +552,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,8 +577,8 @@ 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,
       };
       if (voice && (narrated || !clip.hasAudio)) {
         const fit = fitNarration({ clipSeconds: clip.seconds, voiceSeconds: probe(voice).seconds });
@@ -198,7 +607,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 +614,67 @@ 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)}` });
+    }
+  }
+  let total = 0;
+  for (const seg of spine) {
+    seg.startSec = total;
+    total += seg.seconds;
+  }
+  spine.forEach((seg, k) => {
+    const next = spine[k + 1];
+    if (!seg.reaction || seg.audio !== "clip" || !next) return;
+    seg.reaction.tail = reactionTail(seg, next);
+  });
+
+  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 +698,7 @@ export function buildFfmpegArgs(timeline, { resolve, music, out }) {
   };
   const filters = [];
   const pairs = [];
+  const tails = [];
 
   for (const seg of timeline.spine) {
     const i =
@@ -269,16 +706,61 @@ 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 fitLength =
+      `apad,atrim=0:${sec(seg.seconds)},afade=t=in:d=${EDGE_FADE_SEC},` +
+      `afade=t=out:st=${sec(seg.seconds - EDGE_FADE_SEC)}:d=${EDGE_FADE_SEC}`;
+    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}]`);
     }
@@ -308,7 +790,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]`);
@@ -398,6 +880,20 @@ 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 fades = tail
+        ? `, fading out under the next line at ${tail.atSec.toFixed(2)}s over ${tail.seconds.toFixed(2)}s`
+        : "";
+      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) {
@@ -420,7 +916,7 @@ export function inTheCut(timeline) {
 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;
 }
@@ -478,11 +974,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"),
     };
   };
@@ -501,6 +1000,7 @@ function main() {
       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}`);