@aicopycoders/exodus 2026.11.500-beta.1 → 2026.11.700-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -38,10 +38,13 @@
38
38
  // described above, byte for byte. The same holds for its sound settings, which
39
39
  // reach this file as the manifest's `sound` (see soundOf), and for a voice
40
40
  // that is one song laid whole, the manifest's `wholeVoice` (see wholeVoiceOf).
41
+ import { createHash } from "node:crypto";
41
42
  import { execFileSync, spawnSync } from "node:child_process";
42
43
  import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
43
44
  import path from "node:path";
44
45
  import { pathToFileURL } from "node:url";
46
+ import { planText } from "./first-cut-text.mjs";
47
+ import { createTextRenderer, measuredTextAss, textFrameWindow } from "./first-cut-text-render.mjs";
45
48
 
46
49
  const USAGE = "usage: first-cut.mjs <pulled-dir> [--out cut.mp4] [--skip 2,5] [--no-music] [--still-fill]";
47
50
  const WIDTH = 1080;
@@ -158,9 +161,10 @@ export const TRUE_PEAK_MAX_DB = -1;
158
161
  /**
159
162
  * limitPeaks: after the loudness pass, the sound oversampled 4x through a
160
163
  * limiter at 0.8 (about -1.9 dB), so a peak between two samples is caught too.
161
- * The cut is still measured after and refused over TRUE_PEAK_MAX_DB.
164
+ * The cut is still measured after and refused over TRUE_PEAK_MAX_DB. Its
165
+ * resample is pinned to stereo, as every one after loudnorm is (loudnessApplyArgs).
162
166
  */
163
- export const PEAK_LIMITER = "aresample=192000,alimiter=limit=0.8:level=false:attack=2:release=60";
167
+ export const PEAK_LIMITER = "aresample=192000,aformat=channel_layouts=stereo,alimiter=limit=0.8:level=false:attack=2:release=60";
164
168
 
165
169
  /**
166
170
  * The manifest's finishing settings, or null when none is on. The worker
@@ -282,7 +286,13 @@ export function soundPlan(sound, timeline, storyboard, { levelled, measure }) {
282
286
  const k = spine.findIndex((seg) => cue.startSec < seg.startSec + seg.seconds);
283
287
  const under = Number.isFinite(e.underDb) ? e.underDb : SOUND_UNDER_DB;
284
288
  effects.push({
285
- file: e.file, cueLineId: e.cueLineId, atSec: roundMs(Math.max(0, cue.startSec - SOUND_LEAD_SEC)),
289
+ ...(timeline.mapped ? e : {}),
290
+ file: e.file, cueLineId: e.cueLineId,
291
+ // A mapped cut keeps the intended heard cue independent from the actual file placement.
292
+ ...(timeline.mapped || e.source ? { plannedOnsetSec: cue.startSec } : {}),
293
+ atSec: timeline.mapped
294
+ ? (Math.round(cue.startSec * EDIT_SAMPLE_RATE) - Math.round((e.source?.eventWindow?.fromSec ?? 0) * EDIT_SAMPLE_RATE)) / EDIT_SAMPLE_RATE
295
+ : roundMs(Math.max(0, cue.startSec - SOUND_LEAD_SEC)),
286
296
  gainDb: gainUnder(segLufs[k] ?? voiceLufs, under, measure(e.file), SOUND_FALLBACK_DB),
287
297
  });
288
298
  }
@@ -296,14 +306,17 @@ export function soundPlan(sound, timeline, storyboard, { levelled, measure }) {
296
306
  notes.push(`the bed ${b.file} is left out: ${Number.isFinite(lufs) ? `${lufs} LUFS is under ${BED_FLOOR_LUFS}` : "it has no loudness to measure"}`);
297
307
  } else {
298
308
  const under = Number.isFinite(b.underDb) ? b.underDb : BED_UNDER_DB;
299
- heard.push({ file: b.file, fromScene: b.fromScene, from: seg.startSec, gainDb: round2(bedRef - under - lufs) });
309
+ heard.push({ ...(timeline.mapped ? b : {}), file: b.file, fromScene: b.fromScene, from: seg.startSec, gainDb: round2(bedRef - under - lufs) });
300
310
  }
301
311
  }
302
312
  heard.sort((a, b) => a.from - b.from);
303
313
  const beds = heard.map((b, k) => {
304
- const startSec = k === 0 ? 0 : roundMs(b.from);
314
+ const startSec = k === 0 ? 0 : timeline.mapped ? b.from : roundMs(b.from);
305
315
  const end = k + 1 < heard.length ? heard[k + 1].from : pictureSec;
306
- return { file: b.file, fromScene: b.fromScene, startSec, seconds: roundMs(Math.max(0.1, end - startSec)), gainDb: b.gainDb };
316
+ return {
317
+ ...(timeline.mapped ? b : {}), file: b.file, fromScene: b.fromScene, startSec,
318
+ seconds: timeline.mapped ? end - startSec : roundMs(Math.max(0.1, end - startSec)), gainDb: b.gainDb,
319
+ };
307
320
  });
308
321
  return { voiceLufs, effects, beds, notes };
309
322
  }
@@ -842,19 +855,24 @@ function clipLevels(file, filter = null) {
842
855
  * trims, reaction splits, cue times, captions) works in cut time. The renderer
843
856
  * removes seg.cuts from the picture and the sound before anything else.
844
857
  */
858
+ /** Decoded final-mix levels; callers must not attribute an event to these whole-mix windows. */
859
+ export const measureCutAudio = (file) => clipLevels(file);
860
+
845
861
  function tightenSentenceGaps(spine, reactionCues, scriptLines, readLevels, lineGap = null) {
846
862
  for (const seg of spine) {
847
- if (seg.source !== "clip" || seg.audio !== "clip" || !seg.words?.length) continue;
863
+ if (seg.source !== "clip" || seg.audio !== "clip" || !seg.words?.length || seg.fixedLength) continue;
848
864
  const lines = seg.lineIds.map((id) => ({
849
865
  text: scriptLines.get(id)?.text,
850
866
  asksPause: asksPause(scriptLines.get(id)),
851
867
  cuesBeat: reactionCues.has(id),
852
868
  }));
853
- const cuts = sentenceGapCuts(seg.words, lines, readLevels(seg.file), lineGap);
869
+ const heardCuts = sentenceGapCuts(seg.words, lines, readLevels(seg.file), lineGap);
870
+ // The measured map: on whole slots of the clip's own picture, so both lose the same frames.
871
+ const cuts = seg.map?.picture ? cutsOnSlots(heardCuts, seg.map.deltaSec) : heardCuts;
854
872
  if (cuts.length === 0) continue;
855
873
  const removedBefore = (t) => cuts.reduce((sum, c) => sum + (c.e <= t ? c.e - c.s : 0), 0);
856
874
  const removed = removedBefore(Infinity);
857
- seg.cuts = cuts.map(({ s, e }) => ({ s, e }));
875
+ seg.cuts = cuts.map(({ s, e, slots }) => (slots ? { s, e, slots } : { s, e }));
858
876
  // cutPace: where the take is split, in its time once the gaps are out.
859
877
  const splits = cuts.filter((c) => c.atLine !== undefined).map((c) => ({ at: c.s - removedBefore(c.s), line: c.atLine }));
860
878
  if (splits.length > 0) seg.splits = splits;
@@ -898,10 +916,30 @@ export function narratedScene(scene, storyboard) {
898
916
  return scriptBound && hasText(scene?.voText) && !spoken;
899
917
  }
900
918
 
901
- export function scenePlans(storyboard) {
919
+ /** A voiced suffix belongs to the final explicit source continuation, not necessarily its picture home. */
920
+ function finalWordTailScene(storyboard, beat) {
921
+ const bindings = (storyboard?.pictureBindings ?? []).filter((binding) => binding.beatId === beat.id);
922
+ const finalLineId = bindings.length === 1 ? bindings[0].lineIds?.at(-1) : null;
923
+ const scenes = (storyboard?.scenes ?? []).filter((scene) => bindings.length
924
+ ? finalLineId && scene.lineIds?.includes(finalLineId)
925
+ : scene.planningBeatIds?.includes(beat.id));
926
+ return scenes.length === 1 ? scenes[0] : null;
927
+ }
928
+
929
+ export function scenePlans(storyboard, planningBudget = null) {
902
930
  const plans = new Map();
931
+ const suffixes = new Map();
932
+ for (const beat of planningBudget?.beats ?? []) {
933
+ if (!(beat.picture?.finalWordTailSec > 0)) continue;
934
+ const owner = finalWordTailScene(storyboard, beat);
935
+ if (owner) suffixes.set(owner.sceneIndex, Math.max(suffixes.get(owner.sceneIndex) ?? 0, beat.picture.finalWordTailSec));
936
+ }
903
937
  for (const scene of storyboard?.scenes ?? []) {
904
938
  if (typeof scene?.sceneIndex !== "number") continue;
939
+ const reserved = (planningBudget?.beats ?? []).filter((beat) => scene.planningBeatIds?.includes(beat.id));
940
+ const sequential = reserved.filter((beat) => beat.silent?.composition === "sequential");
941
+ const overlay = reserved.some((beat) => beat.silent?.composition === "overlay");
942
+ const reservation = reserved.reduce((sum, beat) => sum + (beat.silent?.seconds ?? beat.picture?.seconds ?? 0), 0);
905
943
  const speakers = (Array.isArray(scene.dialogue) ? scene.dialogue : [])
906
944
  .filter((turn) => hasText(turn?.line) || hasText(turn?.text))
907
945
  .map((turn) => (hasText(turn.speaker) ? turn.speaker.trim() : null));
@@ -909,14 +947,18 @@ export function scenePlans(storyboard) {
909
947
  firstSpeaker: speakers[0] ?? null,
910
948
  lastSpeaker: speakers.at(-1) ?? null,
911
949
  baseShotId: hasText(scene.baseShotId) ? scene.baseShotId.trim() : null,
912
- cutaway: CUTAWAY_KINDS.has(scene.kind),
950
+ cutaway: CUTAWAY_KINDS.has(scene.kind) && sequential.length === 0,
913
951
  narrated: narratedScene(scene, storyboard),
914
952
  lineIds: Array.isArray(scene.lineIds) ? scene.lineIds : [],
915
953
  cueLineId: typeof scene.cueLineId === "string" ? scene.cueLineId : null,
916
954
  cutawayType: typeof scene.cutawayType === "string" ? scene.cutawayType : null,
917
955
  durationSec: typeof scene.durationSec === "number" ? scene.durationSec : null,
918
- actionTailSec: typeof scene.actionTailSec === "number" && scene.actionTailSec > 0 ? scene.actionTailSec : 0,
956
+ actionTailSec: Math.max(
957
+ typeof scene.actionTailSec === "number" && scene.actionTailSec > 0 ? scene.actionTailSec : 0,
958
+ suffixes.get(scene.sceneIndex) ?? 0,
959
+ ),
919
960
  actionLeadSec: typeof scene.actionLeadSec === "number" && scene.actionLeadSec > 0 ? scene.actionLeadSec : 0,
961
+ ...(planningBudget ? { editSeconds: reservation || null, overlay } : {}),
920
962
  sourceShot: Number.isInteger(scene.sourceShot) && scene.sourceShot > 0 ? scene.sourceShot : null,
921
963
  broll:
922
964
  hasText(scene.broll?.covers) && Number.isFinite(scene.broll?.plannedSec) && scene.broll.plannedSec > 0
@@ -1102,7 +1144,7 @@ function trimJoins(spine, reactionCues, scriptLines, gapMax = null) {
1102
1144
  ? JOIN_LEAD_NEW_SPEAKER_SEC
1103
1145
  : Math.min(JOIN_LEAD_NEW_SPEAKER_SEC, roundMs(gapMax - JOIN_TAIL_SEC));
1104
1146
  spine.forEach((seg, k) => {
1105
- if (seg.source !== "clip" || seg.audio !== "clip" || !seg.words?.length) return;
1147
+ if (seg.source !== "clip" || seg.audio !== "clip" || !seg.words?.length || seg.fixedLength) return;
1106
1148
  const prev = spine[k - 1];
1107
1149
  const sameSpeaker = Boolean(prev?.lastSpeaker) && prev.lastSpeaker === seg.firstSpeaker;
1108
1150
  const lead = sameSpeaker || !prev ? JOIN_LEAD_SAME_SPEAKER_SEC : newSpeakerLead;
@@ -1111,7 +1153,7 @@ function trimJoins(spine, reactionCues, scriptLines, gapMax = null) {
1111
1153
  const before = span ? seg.words.slice(0, span.first) : [];
1112
1154
  const after = span ? seg.words.slice(span.last + 1) : [];
1113
1155
  const firstWord = Math.min(...line.map((w) => w.s));
1114
- const lastWord = Math.max(...line.map((w) => w.e));
1156
+ const lastWord = Math.max(...line.map((w) => seg.map ? wordEnd(w) : w.e));
1115
1157
  let inSec = Math.max(0, floorFrame(firstWord - Math.max(lead, seg.actionLeadSec ?? 0)));
1116
1158
  if (before.length > 0) {
1117
1159
  const clear = ceilFrame(Math.max(...before.map((w) => w.e)) + EXTRA_CLEARANCE_SEC);
@@ -1125,6 +1167,11 @@ function trimJoins(spine, reactionCues, scriptLines, gapMax = null) {
1125
1167
  outSec = Math.min(outSec, Math.max(clear, ceilFrame(lastWord)));
1126
1168
  }
1127
1169
  outSec = Math.min(seg.seconds, outSec);
1170
+ // The measured map: a scripted word the clip's own picture ends before is lost media, said, never trimmed away quietly.
1171
+ if (seg.map) {
1172
+ const lost = line.filter((w) => w.e > outSec + 1e-6);
1173
+ if (lost.length > 0) seg.lostWords = lost.map((w) => ({ w: w.w, s: w.s, e: w.e, pictureEndSec: outSec }));
1174
+ }
1128
1175
  if (outSec <= inSec) return;
1129
1176
  const how = [];
1130
1177
  if (inSec > 0) how.push(`lead-in trimmed ${inSec.toFixed(2)}s`);
@@ -1146,9 +1193,9 @@ function trimJoins(spine, reactionCues, scriptLines, gapMax = null) {
1146
1193
  * the end of the voice file stands in for the last word, its own trailing
1147
1194
  * silence counted as part of the air.
1148
1195
  */
1149
- function narrationEnd(voiceSeconds, voiceWords, endsAd) {
1196
+ function narrationEnd(voiceSeconds, voiceWords, endsAd, measured = false) {
1150
1197
  return {
1151
- spokenEndSec: voiceWords?.length ? Math.max(...voiceWords.map((w) => w.e)) : voiceSeconds,
1198
+ spokenEndSec: voiceWords?.length ? Math.max(...voiceWords.map((w) => measured ? wordEnd(w) : w.e)) : voiceSeconds,
1152
1199
  airSec: endsAd ? END_AIR_SEC : NARRATION_JOIN_AIR_SEC,
1153
1200
  };
1154
1201
  }
@@ -1170,7 +1217,10 @@ function placeReaction(spine, counts, reaction) {
1170
1217
  const cut = Math.min(seg.seconds, ceilFrame(cueEnd));
1171
1218
  const beat = {
1172
1219
  sceneIndex: reaction.sceneIndex, source: reaction.source, file: reaction.file,
1173
- clipSeconds: reaction.source === "clip" ? reaction.seconds : null, inSec: 0,
1220
+ // The measured map: a measured beat's own sound runs deltaSec ahead of its picture's slots.
1221
+ clipSeconds: reaction.source !== "clip" ? null
1222
+ : reaction.map && reaction.hasAudio ? Math.max(0, reaction.seconds - reaction.map.deltaSec) : reaction.seconds,
1223
+ inSec: 0, ...(reaction.map ? { map: reaction.map } : {}),
1174
1224
  seconds: Math.min(reaction.seconds, REACTION_MAX_SEC), holdSec: 0,
1175
1225
  audio: reaction.hasAudio ? "clip" : "silence", voice: null, words: null, lineIds: [],
1176
1226
  reaction: { cueLineId: reaction.cueLineId, cueSceneIndex: seg.sceneIndex },
@@ -1298,6 +1348,22 @@ const PUNCH_IN_RUNS = new Map([
1298
1348
  sameSpeaker(prev, seg) && Boolean(seg.baseShotId) && seg.baseShotId === prev.baseShotId],
1299
1349
  ]);
1300
1350
 
1351
+ /** Only an explicitly selected terminal hold may freeze a retained frame.
1352
+ * A format name, discarded tail or source EOF cannot create this binding. */
1353
+ function selectedEditorialHold(manifest, storyboard, sceneIndex) {
1354
+ const permission = manifest?.outputPermission;
1355
+ if (permission?.ending?.mode !== "native" || permission.ending.kind !== "editorial-hold") return null;
1356
+ const scenes = storyboard?.scenes ?? [];
1357
+ const scene = scenes.at(-1);
1358
+ const hold = scene?.editorialHold;
1359
+ const beat = manifest.planningBudget?.beats?.at(-1);
1360
+ if (scene?.sceneIndex !== sceneIndex || hold?.boundary !== "retained-end" ||
1361
+ !Number.isInteger(hold.sourceSceneIndex) || scenes.at(-2)?.sceneIndex !== hold.sourceSceneIndex ||
1362
+ !(hold.seconds > 0) || !Number.isFinite(hold.seconds) ||
1363
+ !scene.planningBeatIds?.includes(beat?.id) || beat?.picture?.seconds !== hold.seconds) return null;
1364
+ return hold;
1365
+ }
1366
+
1301
1367
  /**
1302
1368
  * #3365: the scenes the cut cannot be made without, by number. A scene the
1303
1369
  * storyboard plans needs a clip unless --skip names it, even one the pull has
@@ -1310,6 +1376,10 @@ export function scenesWithNoClip({ manifest, storyboard, skip, exists = Boolean
1310
1376
  const clipped = new Set(
1311
1377
  (manifest?.scenes ?? []).filter((scene) => exists(scene.clip)).map((scene) => scene.sceneIndex),
1312
1378
  );
1379
+ for (const scene of storyboard?.scenes ?? []) {
1380
+ const hold = selectedEditorialHold(manifest, storyboard, scene.sceneIndex);
1381
+ if (hold && !skip.has(hold.sourceSceneIndex) && clipped.has(hold.sourceSceneIndex)) clipped.add(scene.sceneIndex);
1382
+ }
1313
1383
  return [...new Set(planned.length > 0 ? planned : listed)]
1314
1384
  .filter((n) => !skip.has(n) && !clipped.has(n))
1315
1385
  .sort((a, b) => a - b);
@@ -1344,12 +1414,21 @@ const roundFrame = (t) => Math.round(t * FPS) / FPS;
1344
1414
  * word, so every later line still lands on its words; one with no room left
1345
1415
  * is dropped. Scenes before the first stretch play first and the voice starts
1346
1416
  * after them. Returns where the voice starts and what was dropped.
1417
+ *
1418
+ * The measured map (`whole.measured`): `whole.seconds` is the song's decoded length, so
1419
+ * its last stretch carries the whole musical tail; each stretch is returned
1420
+ * as frames into the song (`intervals`), the scenes between stretches keep the
1421
+ * length given here (`fixedLength`: no later trim may move a line off its
1422
+ * words), and a stretch that is not inside the decoded song, or not after the
1423
+ * one before, is a `problem`, never a guess.
1347
1424
  */
1348
1425
  export function fitWholeVoice(spine, whole) {
1349
1426
  const on = spine.flatMap((seg, k) => (whole.starts.has(seg.sceneIndex) ? [k] : []));
1350
1427
  if (on.length === 0) return null;
1351
1428
  const startSec = spine.slice(0, on[0]).reduce((t, seg) => t + seg.seconds, 0);
1352
1429
  const gone = new Set();
1430
+ const intervals = [];
1431
+ const problems = [];
1353
1432
  on.forEach((k, j) => {
1354
1433
  const seg = spine[k];
1355
1434
  const next = on[j + 1];
@@ -1359,6 +1438,7 @@ export function fitWholeVoice(spine, whole) {
1359
1438
  let room = Math.max(0, to - from - spoken);
1360
1439
  let given = 0;
1361
1440
  for (const b of next === undefined ? [] : spine.slice(k + 1, next)) {
1441
+ if (whole.measured) b.fixedLength = true;
1362
1442
  const seconds = Math.min(b.seconds, floorFrame(room));
1363
1443
  if (seconds < 1 / FPS) {
1364
1444
  gone.add(b);
@@ -1374,12 +1454,22 @@ export function fitWholeVoice(spine, whole) {
1374
1454
  seg.holdSec = holdFor(seg);
1375
1455
  seg.wholeVoice = true;
1376
1456
  seg.note = withHow(seg.note, [`on the whole voice from ${from.toFixed(2)}s to ${to.toFixed(2)}s`]);
1457
+ if (whole.measured) {
1458
+ const at = whole.starts.get(seg.sceneIndex);
1459
+ const before = j === 0 ? null : intervals.at(-1);
1460
+ if (!Number.isFinite(at) || at < 0 || at >= whole.seconds) {
1461
+ problems.push(`scene ${seg.sceneIndex}'s stretch starts at ${at}s, outside the song's decoded ${r6(whole.seconds)}s`);
1462
+ } else if (before && Math.round(from * FPS) <= before.fromFrame) {
1463
+ problems.push(`scene ${seg.sceneIndex}'s stretch does not start after scene ${before.scene}'s`);
1464
+ }
1465
+ intervals.push({ scene: seg.sceneIndex, fromFrame: Math.round(from * FPS), toFrame: Math.round(to * FPS) });
1466
+ }
1377
1467
  });
1378
1468
  const dropped = spine
1379
1469
  .filter((seg) => gone.has(seg))
1380
1470
  .map((seg) => ({ n: seg.sceneIndex, reason: `scene ${seg.sceneIndex}: no room left between two lines of the voice` }));
1381
1471
  for (let k = spine.length - 1; k >= 0; k--) if (gone.has(spine[k])) spine.splice(k, 1);
1382
- return { startSec, dropped };
1472
+ return { startSec, dropped, ...(whole.measured ? { intervals, problems } : {}) };
1383
1473
  }
1384
1474
 
1385
1475
  /**
@@ -1435,11 +1525,684 @@ export function mapSourceTime(groups, t) {
1435
1525
  return Math.min(g.cut[1], Math.max(g.cut[0], g.cut[0] + (t - g.src[0]) * k));
1436
1526
  }
1437
1527
 
1528
+ /**
1529
+ * B29/B31 (only with the manifest's `sourceMap`): the one clock model the
1530
+ * map records and the renderer cuts, read from what each file decodes to and
1531
+ * never from a container duration, a stream's start_time or an assumed rate.
1532
+ *
1533
+ * Picture: every decoded frame's integer pts in its stream's time base. The
1534
+ * mapped render re-stamps the first decoded frame to 0 and resamples with
1535
+ * MAP_PICTURE (fps=24:round=up), which shows on edit slot n the last decoded
1536
+ * frame whose pts is at or before n/24 and makes slots while n/24 is before the
1537
+ * last frame's pts plus its duration. So a decoded frame's first slot is
1538
+ * ceil(pts * 24): 24 fps, 30 fps, VFR and a nonzero first pts are one rule,
1539
+ * and the map names the decoded frame index each slot shows.
1540
+ *
1541
+ * Sound: every decoded frame's pts and nb_samples. Samples with a negative pts
1542
+ * are encoder priming the container asks a player to skip, so the sound's
1543
+ * zero (and its words', the clock the scribe heard) is the first sample after
1544
+ * them, said explicitly as primingSamples. Every sound is resampled to
1545
+ * EDIT_SAMPLE_RATE, where one edit frame is exactly SAMPLES_PER_FRAME samples,
1546
+ * and cut by sample count. A clip's sound meets its picture by the pts gap of
1547
+ * the two zeros (deltaSec, rounded to one edit sample), so picture slot n
1548
+ * meets edit sample zeroSample + n * SAMPLES_PER_FRAME, before and after any
1549
+ * sentence gap, which comes out of both by whole slots.
1550
+ */
1551
+ const MEDIA_ENTRIES =
1552
+ "stream=index,codec_type,time_base,sample_rate:stream_disposition=attached_pic:" +
1553
+ "frame=stream_index,media_type,pts,best_effort_timestamp,duration,pkt_duration,nb_samples";
1554
+ export const EDIT_SAMPLE_RATE = 48000;
1555
+ export const SAMPLES_PER_FRAME = EDIT_SAMPLE_RATE / FPS;
1556
+ /** One AAC frame: the most the encoder's own priming and padding may move the rendered sound. The picture gets no allowance. */
1557
+ export const RENDER_SAMPLE_TOLERANCE = 1024;
1558
+ const MAP_PICTURE = `fps=${FPS}:round=up`;
1559
+ const r6 = (n) => Math.round(n * 1e6) / 1e6;
1560
+ const safeInt = (v) => {
1561
+ const n = typeof v === "number" ? v : v === undefined || v === null || v === "" ? Number.NaN : Number(v);
1562
+ return Number.isSafeInteger(n) ? n : null;
1563
+ };
1564
+ const timeBaseOf = (v) => {
1565
+ const m = /^(\d+)\/(\d+)$/.exec(String(v ?? ""));
1566
+ return m && Number(m[1]) > 0 && Number(m[2]) > 0 ? { num: Number(m[1]), den: Number(m[2]) } : null;
1567
+ };
1568
+ /** ceil(a / b) for integers a >= 0, b > 0, exactly: the float quotient corrected by one either way. */
1569
+ function ceilDiv(a, b) {
1570
+ let c = Math.ceil(a / b);
1571
+ if ((c - 1) * b >= a) c -= 1;
1572
+ else if (c * b < a) c += 1;
1573
+ return c;
1574
+ }
1575
+ const stampOf = (f) => safeInt(f.pts) ?? safeInt(f.best_effort_timestamp);
1576
+ const notAfter = (ticks) => ticks.findIndex((t, i) => i > 0 && t !== null && ticks[i - 1] !== null && t <= ticks[i - 1]);
1577
+
1578
+ function pictureClock(stream, frames) {
1579
+ const problems = [];
1580
+ const tb = timeBaseOf(stream.time_base);
1581
+ const ticks = frames.map(stampOf);
1582
+ if (!tb) problems.push("the picture stream names no time base");
1583
+ if (frames.length === 0) problems.push("the picture decodes no frame");
1584
+ const unstamped = ticks.filter((t) => t === null).length;
1585
+ if (unstamped > 0) problems.push(`${unstamped} decoded picture frame(s) carry no timestamp`);
1586
+ const back = notAfter(ticks);
1587
+ if (back > 0) problems.push(`decoded picture frame ${back} does not come after frame ${back - 1}`);
1588
+ const last = frames.at(-1);
1589
+ const lastTicks = last ? safeInt(last.duration) ?? safeInt(last.pkt_duration) : null;
1590
+ if (last && !(lastTicks > 0)) problems.push("the last decoded picture frame carries no duration, so where the picture ends is not known");
1591
+ if (problems.length > 0) return { problems, frames: frames.length };
1592
+ const sec = (t) => (t * tb.num) / tb.den;
1593
+ const rel = ticks.map((t) => t - ticks[0]);
1594
+ const slot = (r) => ceilDiv(r * FPS * tb.num, tb.den);
1595
+ const endTicks = rel.at(-1) + lastTicks;
1596
+ return {
1597
+ problems, timeBase: `${tb.num}/${tb.den}`, frames: frames.length,
1598
+ originSec: sec(ticks[0]), endSec: sec(endTicks), ptsSec: rel.map(sec), slots: rel.map(slot), endSlot: slot(endTicks),
1599
+ };
1600
+ }
1601
+
1602
+ function soundClock(stream, frames) {
1603
+ const problems = [];
1604
+ const tb = timeBaseOf(stream.time_base);
1605
+ const sampleRate = safeInt(stream.sample_rate);
1606
+ const ticks = frames.map(stampOf);
1607
+ const counts = frames.map((f) => safeInt(f.nb_samples));
1608
+ if (!tb) problems.push("the sound stream names no time base");
1609
+ if (!(sampleRate > 0)) problems.push("the sound stream names no sample rate");
1610
+ if (frames.length === 0) problems.push("the sound decodes no sample");
1611
+ const unstamped = ticks.filter((t) => t === null).length;
1612
+ if (unstamped > 0) problems.push(`${unstamped} decoded sound frame(s) carry no timestamp`);
1613
+ const uncounted = counts.filter((n) => !(n > 0)).length;
1614
+ if (uncounted > 0) problems.push(`${uncounted} decoded sound frame(s) carry no sample count`);
1615
+ const back = notAfter(ticks);
1616
+ if (back > 0) problems.push(`decoded sound frame ${back} does not come after frame ${back - 1}`);
1617
+ if (problems.length > 0) return { problems };
1618
+ const sec = (t) => (t * tb.num) / tb.den;
1619
+ const samples = counts.reduce((a, b) => a + b, 0);
1620
+ const spanned = Math.round((sec(ticks.at(-1)) - sec(ticks[0])) * sampleRate) + counts.at(-1);
1621
+ // A gap or overlap in the sound's own clock is at least one coded frame; less is the time base's rounding.
1622
+ if (Math.abs(spanned - samples) > Math.max(1, Math.min(...counts) / 2)) {
1623
+ return { problems: [`the ${samples} decoded samples do not fill the sound's own clock of ${spanned}: it has a gap or an overlap`] };
1624
+ }
1625
+ const originSec = sec(ticks[0]);
1626
+ const primingSamples = originSec < 0 ? Math.min(samples, Math.round(-originSec * sampleRate)) : 0;
1627
+ const toEdit = (n) => Math.round((n * EDIT_SAMPLE_RATE) / sampleRate);
1628
+ return {
1629
+ problems, timeBase: `${tb.num}/${tb.den}`, sampleRate, originSec, samples, primingSamples,
1630
+ zeroSec: originSec + primingSamples / sampleRate,
1631
+ decodedSec: (samples - primingSamples) / sampleRate,
1632
+ edit: { priming: toEdit(primingSamples), samples: toEdit(samples) },
1633
+ };
1634
+ }
1635
+
1636
+ /**
1637
+ * ffprobe json (streams + decoded frames, integer pts) -> { picture, audio }:
1638
+ * null where the file has no such stream, else that stream's clock or the
1639
+ * `problems` that keep it from being one. Nothing missing is filled in.
1640
+ */
1641
+ export function parseMedia(info) {
1642
+ const streams = info?.streams ?? [];
1643
+ const pick = (type) => streams.find((s) => s.codec_type === type && !s.disposition?.attached_pic);
1644
+ const framesOf = (s) => (info?.frames ?? []).filter((f) => f.stream_index === s.index);
1645
+ const video = pick("video");
1646
+ const audio = pick("audio");
1647
+ return {
1648
+ picture: video ? pictureClock(video, framesOf(video)) : null,
1649
+ audio: audio ? soundClock(audio, framesOf(audio)) : null,
1650
+ };
1651
+ }
1652
+
1653
+ /** The decoded frame MAP_PICTURE shows on picture slot n: the last whose first slot is at or before n. */
1654
+ export function frameAtSlot(picture, n) {
1655
+ let lo = 0;
1656
+ let hi = picture.slots.length - 1;
1657
+ while (lo < hi) {
1658
+ const mid = (lo + hi + 1) >> 1;
1659
+ if (picture.slots[mid] <= n) lo = mid;
1660
+ else hi = mid - 1;
1661
+ }
1662
+ return lo;
1663
+ }
1664
+
1665
+ function measureMedia(file) {
1666
+ const res = spawnSync("ffprobe", ["-v", "error", "-show_entries", MEDIA_ENTRIES, "-of", "json", file], {
1667
+ encoding: "utf8", maxBuffer: 1 << 30,
1668
+ });
1669
+ if (res.status !== 0) return null;
1670
+ try {
1671
+ return parseMedia(JSON.parse(res.stdout));
1672
+ } catch {
1673
+ return null;
1674
+ }
1675
+ }
1676
+
1677
+ /**
1678
+ * A file's clocks as the cut uses them; `measured` false when it could not be
1679
+ * read at all. deltaSec: the sound's zero minus the picture's first frame, in
1680
+ * pts, on whole edit samples. zeroSample: the edit sample of the decoded sound
1681
+ * (priming counted, as the filter counts it) that meets picture slot 0.
1682
+ */
1683
+ export function clockOf(media) {
1684
+ const picture = media?.picture && media.picture.problems.length === 0 ? media.picture : null;
1685
+ const audio = media?.audio && media.audio.problems.length === 0 ? media.audio : null;
1686
+ const deltaSamples = picture && audio ? Math.round((audio.zeroSec - picture.originSec) * EDIT_SAMPLE_RATE) : 0;
1687
+ return {
1688
+ measured: Boolean(media), media: media ?? null, picture, audio,
1689
+ deltaSec: deltaSamples / EDIT_SAMPLE_RATE,
1690
+ zeroSample: (audio?.edit.priming ?? 0) - deltaSamples,
1691
+ };
1692
+ }
1693
+
1694
+ /** Why a clock cannot carry a route, or null: `need` is "picture" or "audio". */
1695
+ function clockProblem(clock, need) {
1696
+ if (!clock?.measured) return "its decoded frames and samples could not be read";
1697
+ const stream = clock.media[need];
1698
+ if (!stream) return `it has no ${need === "picture" ? "picture" : "sound"} stream`;
1699
+ return stream.problems.length > 0 ? stream.problems.join("; ") : null;
1700
+ }
1701
+
1702
+ /**
1703
+ * A sentence gap cut on a clip's own word clock, moved inward to whole slots
1704
+ * of its picture (never into the words it lies between) and back, so the
1705
+ * picture and the sound lose the same slots and the words after it move by
1706
+ * exactly that. A cut under one slot is dropped.
1707
+ */
1708
+ function cutsOnSlots(cuts, deltaSec) {
1709
+ return cuts.flatMap((c) => {
1710
+ const from = Math.ceil((c.s + deltaSec) * FPS - 1e-6);
1711
+ const to = Math.floor((c.e + deltaSec) * FPS + 1e-6);
1712
+ return to > from ? [{ ...c, s: from / FPS - deltaSec, e: to / FPS - deltaSec, slots: [from, to] }] : [];
1713
+ });
1714
+ }
1715
+
1716
+ const removedSlots = (cuts) => (cuts ?? []).reduce((n, c) => n + (c.slots ? c.slots[1] - c.slots[0] : 0), 0);
1717
+
1718
+ /** A post-cut picture slot back on the clip's own slots: every cut that starts at or before it is added back. */
1719
+ function preCutSlot(cuts, m) {
1720
+ let removed = 0;
1721
+ for (const c of cuts ?? []) if (c.slots && c.slots[0] - removed <= m) removed += c.slots[1] - c.slots[0];
1722
+ return m + removed;
1723
+ }
1724
+
1725
+ /**
1726
+ * A word's last sound on its own clock: where the scribe gave phonemes, the
1727
+ * last one's end (kept as phoneEndAfterSec, so it moves with the word);
1728
+ * otherwise the word's end, which is no proof of its last phoneme.
1729
+ */
1730
+ const wordEnd = (w) => w.e + Math.max(0, w.phoneEndAfterSec ?? 0);
1731
+ export function withPhonemeEnds(words) {
1732
+ if (!Array.isArray(words)) return words;
1733
+ return words.map((w) => {
1734
+ const ends = (Array.isArray(w?.phonemes) ? w.phonemes : []).map((p) => Number(p?.e)).filter(Number.isFinite);
1735
+ return ends.length > 0 ? { ...w, phoneEndAfterSec: Math.max(...ends) - w.e } : w;
1736
+ });
1737
+ }
1738
+
1739
+ /**
1740
+ * The measured map: each piece on whole slots of its own picture and whole frames of the
1741
+ * edit. A piece's picture starts on a slot of its post-cut picture and its
1742
+ * sound's in-point is derived from that slot, its words moved with it, so
1743
+ * picture and sound never part by a rounding. Ends are rounded cumulatively,
1744
+ * so the edit never drifts more than a frame whatever the number of pieces;
1745
+ * never inside a piece's last word, and never past the picture it has unless
1746
+ * a word needs it (holdSec, which the map refuses).
1747
+ */
1748
+ function snapToFrames(spine) {
1749
+ let exact = 0;
1750
+ let frame = 0;
1751
+ for (const seg of spine) {
1752
+ exact += seg.seconds;
1753
+ let available = Infinity;
1754
+ if (seg.editorialHold) {
1755
+ const source = spine[spine.indexOf(seg) - 1];
1756
+ const clock = source && pieceClock(source);
1757
+ if (!source || source.sceneIndex !== seg.editorialHold.sourceSceneIndex || source.editorialHold ||
1758
+ !clock.picture || clock.picture.shown !== clock.frames || clock.frames < 1) {
1759
+ throw new SourceMapRefusal("The selected editorial hold has no retained source-frame provenance", [
1760
+ { severity: "refuse", code: "editorial-hold-source-unproven", scene: seg.sceneIndex, detail: "the immediately preceding selected source must retain a complete measured picture interval" },
1761
+ ]);
1762
+ }
1763
+ const sourceSlot = preCutSlot(source.cuts, clock.picture.inSlot + clock.frames - 1);
1764
+ seg.editorialHold = { ...seg.editorialHold, sourceSlot, sourceFrame: frameAtSlot(source.map.picture, sourceSlot) };
1765
+ seg.file = source.file;
1766
+ seg.map = { ...seg.map, picture: source.map.picture, media: source.map.media, slot: sourceSlot, availableSlots: Infinity };
1767
+ }
1768
+ if (seg.source === "clip" && seg.map?.picture && !seg.editorialHold) {
1769
+ const own = seg.audio === "clip";
1770
+ const delta = own ? seg.map.deltaSec : 0;
1771
+ const slot = Math.max(0, Math.round(((seg.inSec ?? 0) + delta) * FPS));
1772
+ const inSec = slot / FPS - delta;
1773
+ const shift = (seg.inSec ?? 0) - inSec;
1774
+ if (own && seg.words) seg.words = seg.words.map((w) => ({ ...w, s: w.s + shift, e: w.e + shift }));
1775
+ seg.inSec = inSec;
1776
+ available = Math.max(0, seg.map.picture.endSlot - removedSlots(seg.cuts) - slot);
1777
+ seg.map = { ...seg.map, slot, availableSlots: available };
1778
+ }
1779
+ const words = seg.words ?? [];
1780
+ const lastEnd = words.length ? Math.max(...words.map(wordEnd)) : 0;
1781
+ const needed = lastEnd > 0 ? Math.ceil(lastEnd * FPS - 1e-6) : 0;
1782
+ let end = Math.max(Math.round(exact * FPS), frame + needed, frame + 1);
1783
+ // A stretch of a whole voice has the song's length, not the clip's: short picture there is a hold, refused.
1784
+ const fixed = seg.wholeVoice || seg.fixedLength;
1785
+ if (!fixed && end - frame > available && available >= Math.max(needed, 1)) end = frame + available;
1786
+ if (seg.editorialHold && end - frame !== Math.ceil(seg.editorialHold.seconds * FPS - 1e-6)) {
1787
+ throw new SourceMapRefusal("The selected editorial hold does not fit its authorized clock", [
1788
+ { severity: "refuse", code: "editorial-hold-clock-mismatch", scene: seg.sceneIndex,
1789
+ detail: "the continuing narration/word clock cannot be shortened or padded by changing the selected retained-frame hold" },
1790
+ ]);
1791
+ }
1792
+ seg.map = { ...(seg.map ?? {}), residualFrames: end - exact * FPS };
1793
+ seg.seconds = (end - frame) / FPS;
1794
+ seg.holdSec = Math.max(0, end - frame - available) / FPS;
1795
+ if (seg.reaction?.tail) seg.reaction.tail.fromSec = seg.inSec + seg.seconds;
1796
+ frame = end;
1797
+ }
1798
+ }
1799
+
1800
+ /**
1801
+ * The one reading of a piece on the measured clocks, which the map records
1802
+ * and the renderer cuts: its post-cut picture slots and the sentence-gap slots
1803
+ * taken out first; its sound's edit samples, derived from the picture slot
1804
+ * (a clip's own sound) or from the same slot of its voice (narration). Sample
1805
+ * ranges past what decodes are silence the map names, never a word.
1806
+ */
1807
+ export function pieceClock(seg) {
1808
+ const m = seg.map ?? null;
1809
+ const frames = Math.round(seg.seconds * FPS);
1810
+ const out = { frames, picture: null, sound: null };
1811
+ if (seg.source !== "clip" || !m?.picture || !Number.isInteger(m.slot)) return out;
1812
+ const cutSlots = (seg.cuts ?? []).filter((c) => c.slots).map((c) => c.slots);
1813
+ out.picture = { inSlot: m.slot, shown: seg.editorialHold ? frames : Math.min(frames, m.availableSlots), cutSlots };
1814
+ const own = seg.audio === "clip";
1815
+ const clock = own ? m : seg.audio === "narration" && !seg.wholeVoice ? m.voice ?? null : null;
1816
+ if (!clock?.audio) return out;
1817
+ const zero = own ? m.zeroSample : clock.audio.edit.priming;
1818
+ const from = zero + (seg.editorialHold ? 0 : m.slot * SAMPLES_PER_FRAME);
1819
+ const cutSamples = own ? cutSlots.map(([s, e]) => [zero + s * SAMPLES_PER_FRAME, zero + e * SAMPLES_PER_FRAME]) : [];
1820
+ out.sound = {
1821
+ zeroSample: zero, fromSample: from, toSample: from + frames * SAMPLES_PER_FRAME, cutSamples,
1822
+ available: clock.audio.edit.samples - cutSamples.reduce((n, [s, e]) => n + e - s, 0),
1823
+ };
1824
+ return out;
1825
+ }
1826
+
1827
+ /** A time on the edit side of a piece's sentence-gap cuts, back on the source's own word clock. */
1828
+ function sourceTimeOf(seg, t, isEnd) {
1829
+ const post = t + (seg.inSec ?? 0);
1830
+ let removed = 0;
1831
+ for (const c of seg.cuts ?? []) {
1832
+ const at = c.s - removed;
1833
+ if (isEnd ? post > at + 1e-9 : post >= at - 1e-9) removed += c.e - c.s;
1834
+ }
1835
+ return post + removed;
1836
+ }
1837
+
1838
+ /** Each script line a piece speaks, as its own part: `lineId@scene.piece`, unique when a line is split across scenes or takes. */
1839
+ function lineParts(seg, scriptLines) {
1840
+ const ids = seg.lineIds ?? [];
1841
+ const words = seg.words ?? [];
1842
+ const n = seg.piece?.n ?? 1;
1843
+ const parts = [];
1844
+ let cursor = 0;
1845
+ for (const lineId of ids) {
1846
+ const part = `${lineId}@${seg.sceneIndex}.${n}`;
1847
+ const remaining = words.slice(cursor);
1848
+ const span = remaining.length === 0 ? null
1849
+ : ids.length === 1 ? { first: 0, last: remaining.length - 1 }
1850
+ : scriptedSpan(remaining, [scriptLines.get(lineId)?.text]);
1851
+ if (!span) {
1852
+ parts.push({ part, lineId, measured: false });
1853
+ continue;
1854
+ }
1855
+ const heard = remaining.slice(span.first, span.last + 1);
1856
+ const s = Math.min(...heard.map((x) => x.s));
1857
+ const e = Math.max(...heard.map(wordEnd));
1858
+ const last = heard.find((x) => wordEnd(x) === e);
1859
+ parts.push({
1860
+ part, lineId, measured: true, words: heard.length, firstWord: cursor + span.first, lastWord: cursor + span.last,
1861
+ sourceSpan: scriptLines.get(lineId)?.sourceSpan ?? null,
1862
+ local: { startSec: s, endSec: e },
1863
+ src: { startSec: r6(sourceTimeOf(seg, s, false)), endSec: r6(sourceTimeOf(seg, e, true)) },
1864
+ edit: {
1865
+ startSec: r6(seg.startSec + s), endSec: r6(seg.startSec + e),
1866
+ startFrame: Math.floor((seg.startSec + s) * FPS + 1e-6),
1867
+ lastFrame: Math.ceil((seg.startSec + e) * FPS - 1e-6) - 1,
1868
+ },
1869
+ endEvidence: Number.isFinite(last?.phoneEndAfterSec) ? "phoneme" : "asr-word-end",
1870
+ });
1871
+ cursor += span.last + 1;
1872
+ }
1873
+ return parts;
1874
+ }
1875
+
1876
+ /**
1877
+ * Where a planned action lead or tail stands. Only a picture event measured on
1878
+ * the clip's own decoded picture clock (the manifest scene's actionEvidence:
1879
+ * { leadStartSec, tailEndSec }, seconds from its first decoded frame) can show
1880
+ * it kept; a word time or the planned length is no evidence.
1881
+ */
1882
+ function actionOf(wantedSec, eventSec, shownSec, isLead) {
1883
+ if (!(wantedSec > 0)) return { wantedSec: 0, status: "not-asked" };
1884
+ if (!Number.isFinite(eventSec) || !shownSec) return { wantedSec, status: "unproven", eventSec: null };
1885
+ const kept = isLead ? shownSec.fromSec <= eventSec + 1e-9 : shownSec.toSec >= eventSec - 1e-9;
1886
+ return { wantedSec, status: kept ? "kept" : "short", eventSec: r6(eventSec), shownSec: { fromSec: r6(shownSec.fromSec), toSec: r6(shownSec.toSec) } };
1887
+ }
1888
+
1889
+ /**
1890
+ * The measured source-to-edit map: for every piece of the spine, its picture
1891
+ * and sound routes, the decoded frame range and sample range it plays, where it
1892
+ * sits on the edit's frame and sample grid, the script-line parts it speaks,
1893
+ * its action lead/tail evidence; then the overlays and the whole voice. Every
1894
+ * number is the one the renderer cuts with (pieceClock). `findings` are what
1895
+ * it could not honor; each "refuse" stops the cut (SourceMapRefusal): nothing
1896
+ * unmeasured, frozen, padded into a song or cut out of one is delivered.
1897
+ * "declared" ones are measured facts the cut carries out, said.
1898
+ */
1899
+ export function buildSourceMap({ spine, cutaways, scriptLines, wholeVoice = null, pictureFrames, sourceMeta = null }) {
1900
+ const findings = [];
1901
+ const flag = (severity, code, seg, detail) =>
1902
+ findings.push({ severity, code, scene: seg?.sceneIndex ?? null, detail });
1903
+ // What the cut lets be heard, from the route each piece actually plays, and
1904
+ // the pictures whose own sound it does not: no listen to a source may count
1905
+ // for a muted picture. Owner, accepted lines and storage id are only what
1906
+ // the pull's sourceMeta says of that exact file, else null (unknown).
1907
+ const audibleSources = [];
1908
+ const mutedPictures = [];
1909
+ const metaOf = (file) => {
1910
+ const meta = sourceMeta && typeof sourceMeta === "object" ? sourceMeta[file] : null;
1911
+ return {
1912
+ owner: typeof meta?.owner === "string" ? meta.owner : null,
1913
+ acceptedLineIds: Array.isArray(meta?.acceptedLineIds) ? meta.acceptedLineIds.filter((id) => typeof id === "string") : null,
1914
+ storageId: typeof meta?.storageId === "string" ? meta.storageId : null,
1915
+ // The producing artifact's own kind, only as the pull states it: a whole voice is never labelled a song here.
1916
+ kind: ["native-clip", "voiceover", "song-master"].includes(meta?.kind) ? meta.kind : null,
1917
+ };
1918
+ };
1919
+ const pieces = spine.map((seg) => {
1920
+ const m = seg.map ?? null;
1921
+ const startFrame = Math.round(seg.startSec * FPS);
1922
+ const clock = pieceClock(seg);
1923
+ const { frames } = clock;
1924
+ const own = seg.audio === "clip";
1925
+ const voiced = seg.audio === "narration" && !seg.wholeVoice;
1926
+ if (seg.source === "still") flag("refuse", "still-picture", seg, "a keyframe held as a still has no decoded clock: it is one frozen frame");
1927
+ const noPicture = seg.source === "clip" ? clockProblem(m, "picture") : null;
1928
+ if (noPicture) flag("refuse", "unmeasured-picture", seg, `${seg.file}: ${noPicture}`);
1929
+ const noSound = own ? clockProblem(m, "audio") : voiced ? clockProblem(m?.voice, "audio") : null;
1930
+ if (noSound) flag("refuse", own ? "unmeasured-sound" : "unmeasured-voice", seg, `${own ? seg.file : seg.voice}: ${noSound}`);
1931
+ for (const w of seg.lostWords ?? []) {
1932
+ flag("refuse", "word-past-picture-eof", seg, `"${w.w}" ends at ${r6(w.e)}s on its sound's clock, after the clip's picture ends at ${r6(w.pictureEndSec)}s`);
1933
+ }
1934
+ const parts = lineParts(seg, scriptLines);
1935
+ const spoken = parts.filter((p) => p.measured);
1936
+ if ((seg.lineIds?.length ?? 0) > 0 && spoken.length < seg.lineIds.length) {
1937
+ const unplaced = parts.filter((p) => !p.measured).map((p) => p.part).join(", ");
1938
+ flag("refuse", "unmeasured-words", seg, `no heard word times place ${unplaced}`);
1939
+ }
1940
+
1941
+ let picture = null;
1942
+ let shownSec = null;
1943
+ if (clock.picture) {
1944
+ const pic = m.picture;
1945
+ const { inSlot, shown } = clock.picture;
1946
+ const pre = (k) => seg.editorialHold ? seg.editorialHold.sourceSlot : preCutSlot(seg.cuts, inSlot + k);
1947
+ let repeated = 0;
1948
+ let skipped = 0;
1949
+ let prev = null;
1950
+ for (let k = 0; k < shown; k++) {
1951
+ const i = frameAtSlot(pic, pre(k));
1952
+ if (prev !== null && i === prev.i) repeated++;
1953
+ else if (prev !== null && pre(k) === prev.slot + 1) skipped += Math.max(0, i - prev.i - 1);
1954
+ prev = { i, slot: pre(k) };
1955
+ }
1956
+ const first = shown > 0 ? frameAtSlot(pic, pre(0)) : null;
1957
+ const last = shown > 0 ? frameAtSlot(pic, pre(shown - 1)) : null;
1958
+ picture = {
1959
+ inSlot: pre(0), lastSlot: shown > 0 ? pre(shown - 1) : null,
1960
+ firstFrame: first, lastFrame: last,
1961
+ firstPtsSec: first === null ? null : r6(pic.ptsSec[first]), lastPtsSec: last === null ? null : r6(pic.ptsSec[last]),
1962
+ cutSlots: clock.picture.cutSlots, repeatedSlots: repeated, skippedFrames: skipped, heldFrames: frames - shown,
1963
+ };
1964
+ if (seg.editorialHold) picture.editorialHold = {
1965
+ sourceSceneIndex: seg.editorialHold.sourceSceneIndex, sourceSlot: seg.editorialHold.sourceSlot,
1966
+ sourceFrame: seg.editorialHold.sourceFrame, frames, boundary: "retained-end",
1967
+ };
1968
+ if (shown > 0) shownSec = { fromSec: pre(0) / FPS, toSec: (pre(shown - 1) + 1) / FPS };
1969
+ if (frames > shown) {
1970
+ flag("refuse", "picture-hold", seg, `${frames - shown} edit frame(s) past the clip's last decoded frame (slot ${pic.endSlot}) would be a frozen copy`);
1971
+ }
1972
+ }
1973
+ let sound = null;
1974
+ if (clock.sound) {
1975
+ const { fromSample, toSample, available } = clock.sound;
1976
+ sound = {
1977
+ ...clock.sound,
1978
+ leadSilenceSamples: Math.max(0, -fromSample), tailSilenceSamples: Math.max(0, toSample - available),
1979
+ };
1980
+ if (sound.leadSilenceSamples > 0) flag("declared", "sound-starts-late", seg, `the decoded sound starts ${sound.leadSilenceSamples} samples into the piece`);
1981
+ if (sound.tailSilenceSamples > 0) flag("declared", "sound-ends-early", seg, `the decoded sound ends ${sound.tailSilenceSamples} samples before the piece`);
1982
+ for (const p of spoken) {
1983
+ const endSample = fromSample + Math.ceil(p.local.endSec * EDIT_SAMPLE_RATE - 1e-6);
1984
+ if (endSample > available) {
1985
+ flag("refuse", "word-past-audio-eof", seg, `${p.part} ends on sample ${endSample} but the sound decodes ${available}`);
1986
+ }
1987
+ if (fromSample + Math.floor(p.local.startSec * EDIT_SAMPLE_RATE + 1e-6) < (own ? m.audio : m.voice.audio).edit.priming) {
1988
+ flag("refuse", "word-before-sound", seg, `${p.part} starts before the sound's first presented sample`);
1989
+ }
1990
+ }
1991
+ }
1992
+ for (const p of spoken) {
1993
+ if (p.local.startSec < -1e-6) flag("refuse", "word-before-piece", seg, `${p.part} starts ${r6(-p.local.startSec)}s before its piece`);
1994
+ if (p.edit.lastFrame >= startFrame + frames) {
1995
+ flag("refuse", "word-past-piece", seg, `${p.part}'s last word ends on frame ${p.edit.lastFrame}, after its piece's ${startFrame + frames - 1}`);
1996
+ }
1997
+ }
1998
+ const ev = seg.actionEvidence ?? null;
1999
+ const action = {
2000
+ lead: actionOf(seg.actionLeadSec ?? 0, Number(ev?.leadStartSec), shownSec, true),
2001
+ tail: actionOf(seg.actionTailSec ?? 0, Number(ev?.tailEndSec), shownSec, false),
2002
+ };
2003
+ for (const [side, a] of Object.entries(action)) {
2004
+ if (a.status === "unproven") flag("refuse", `action-${side}-unproven`, seg, `the storyboard asks ${a.wantedSec}s of action ${side} and no picture event was measured to show it is kept`);
2005
+ if (a.status === "short") flag("refuse", `action-${side}-short`, seg, `the measured action ${side === "lead" ? "starts" : "ends"} at ${a.eventSec}s, outside the picture the piece shows`);
2006
+ }
2007
+ const pieceId = seg.piece ? `${seg.sceneIndex}.${seg.piece.n}` : String(seg.sceneIndex);
2008
+ if (seg.source === "clip" && !own) mutedPictures.push({ file: seg.file, sceneIndex: seg.sceneIndex, piece: pieceId });
2009
+ if (sound) {
2010
+ const file = own ? seg.file : seg.voice;
2011
+ audibleSources.push({
2012
+ file, route: own ? "clip" : "narration", sceneIndex: seg.sceneIndex, sceneIndexes: [seg.sceneIndex], piece: pieceId,
2013
+ edit: { fromSample: startFrame * SAMPLES_PER_FRAME + sound.leadSilenceSamples, toSample: (startFrame + frames) * SAMPLES_PER_FRAME - sound.tailSilenceSamples },
2014
+ source: { fromSample: Math.max(0, sound.fromSample), toSample: Math.min(sound.toSample, sound.available), cutSamples: sound.cutSamples },
2015
+ // A reaction's tail: the same file heard on past its beat, under the next line.
2016
+ ...(own && seg.reaction?.tail ? {
2017
+ tail: {
2018
+ editFromSample: Math.round(seg.reaction.tail.atSec * FPS) * SAMPLES_PER_FRAME,
2019
+ samples: Math.round(seg.reaction.tail.seconds * EDIT_SAMPLE_RATE),
2020
+ },
2021
+ } : {}),
2022
+ lineParts: spoken.map((p) => p.part),
2023
+ ...metaOf(file),
2024
+ });
2025
+ }
2026
+ const media = m?.media ?? null;
2027
+ const audioClock = own ? m?.audio : voiced ? m?.voice?.audio : null;
2028
+ return {
2029
+ piece: seg.piece ? `${seg.sceneIndex}.${seg.piece.n}` : String(seg.sceneIndex),
2030
+ sceneIndex: seg.sceneIndex,
2031
+ route: { picture: seg.source, audio: seg.wholeVoice ? "whole-voice" : seg.audio, file: seg.file, voice: seg.voice ?? null },
2032
+ source: media ? {
2033
+ picture: m.picture ? {
2034
+ timeBase: m.picture.timeBase, originSec: r6(m.picture.originSec), frames: m.picture.frames,
2035
+ endSec: r6(m.picture.endSec), slots: m.picture.endSlot,
2036
+ } : null,
2037
+ audio: audioClock ? {
2038
+ timeBase: audioClock.timeBase, sampleRate: audioClock.sampleRate, originSec: r6(audioClock.originSec),
2039
+ samples: audioClock.samples, primingSamples: audioClock.primingSamples, decodedSec: r6(audioClock.decodedSec),
2040
+ } : null,
2041
+ audioMinusPictureSec: own ? r6(m.deltaSec) : null,
2042
+ } : null,
2043
+ edit: {
2044
+ startFrame, frames, startSample: startFrame * SAMPLES_PER_FRAME, samples: frames * SAMPLES_PER_FRAME,
2045
+ residualFrames: r6(m?.residualFrames ?? 0),
2046
+ },
2047
+ picture,
2048
+ sound,
2049
+ lineParts: parts.map(({ local, ...p }) => p),
2050
+ action,
2051
+ };
2052
+ });
2053
+ const overlays = cutaways.map((c) => {
2054
+ const startFrame = Math.round(c.startSec * FPS);
2055
+ const frames = Math.round(c.seconds * FPS);
2056
+ if (c.source === "still") flag("refuse", "still-picture", c, "a keyframe laid over the cut has no decoded clock: it is one frozen frame");
2057
+ const problem = c.source === "clip" ? clockProblem(c.map, "picture") : null;
2058
+ if (problem) flag("refuse", "unmeasured-picture", c, `${c.file}: ${problem}`);
2059
+ const pic = problem ? null : c.map?.picture ?? null;
2060
+ if (pic && frames > pic.endSlot) flag("refuse", "picture-hold", c, `the overlay needs ${frames} slots, its clip decodes ${pic.endSlot}`);
2061
+ if (c.source === "clip") mutedPictures.push({ file: c.file, sceneIndex: c.sceneIndex, piece: null });
2062
+ return {
2063
+ scene: c.sceneIndex, source: c.source, method: c.method ?? null, onPiece: c.spineSceneIndex ?? null,
2064
+ startFrame, frames, startSec: r6(c.startSec), seconds: r6(c.seconds),
2065
+ picture: pic && frames > 0 ? { firstFrame: 0, lastFrame: frameAtSlot(pic, Math.min(frames, pic.endSlot) - 1) } : null,
2066
+ };
2067
+ });
2068
+ let whole = null;
2069
+ if (wholeVoice) {
2070
+ const c = wholeVoice.clock;
2071
+ const problem = clockProblem(c, "audio");
2072
+ whole = {
2073
+ file: wholeVoice.file, startFrame: wholeVoice.startFrame, startSample: wholeVoice.startFrame * SAMPLES_PER_FRAME,
2074
+ declaredSec: r6(wholeVoice.declaredSec), intervals: wholeVoice.intervals,
2075
+ };
2076
+ if (problem) flag("refuse", "unmeasured-whole-voice", null, `${wholeVoice.file}: ${problem}`);
2077
+ for (const p of wholeVoice.problems) flag("refuse", "whole-voice-interval", null, p);
2078
+ if (!problem) {
2079
+ const songSamples = c.audio.edit.samples - c.audio.edit.priming;
2080
+ const endSample = whole.startSample + songSamples;
2081
+ const pictureSamples = pictureFrames * SAMPLES_PER_FRAME;
2082
+ Object.assign(whole, {
2083
+ sampleRate: c.audio.sampleRate, primingSamples: c.audio.primingSamples, decodedSec: r6(c.audio.decodedSec),
2084
+ samples: songSamples, endSample, pictureEndSample: pictureSamples,
2085
+ });
2086
+ // The song is one input heard whole from its first stretch's frame, never sliced per scene.
2087
+ audibleSources.push({
2088
+ file: wholeVoice.file, route: "whole-voice", sceneIndex: null,
2089
+ sceneIndexes: pieces.filter((p) => p.route.audio === "whole-voice").map((p) => p.sceneIndex), piece: "whole-voice",
2090
+ edit: { fromSample: whole.startSample, toSample: Math.min(endSample, pictureSamples) },
2091
+ source: { fromSample: c.audio.edit.priming, toSample: c.audio.edit.priming + songSamples, cutSamples: [] },
2092
+ lineParts: pieces.filter((p) => p.route.audio === "whole-voice").flatMap((p) => p.lineParts.filter((l) => l.measured).map((l) => l.part)),
2093
+ ...metaOf(wholeVoice.file),
2094
+ });
2095
+ if (endSample > pictureSamples) {
2096
+ flag("refuse", "whole-voice-tail-cut", null, `the song ends on edit sample ${endSample} but the picture on ${pictureSamples}: its tail would be cut, never stretched`);
2097
+ } else if (pictureSamples - endSample >= SAMPLES_PER_FRAME) {
2098
+ flag("refuse", "whole-voice-short", null, `the picture runs ${pictureSamples - endSample} samples past the song's last decoded sample; the song is never padded or looped to fill it`);
2099
+ }
2100
+ for (const iv of wholeVoice.intervals) {
2101
+ const seg = spine.find((s) => s.wholeVoice && s.sceneIndex === iv.scene);
2102
+ const at = seg ? Math.round(seg.startSec * FPS) - wholeVoice.startFrame : null;
2103
+ if (at !== iv.fromFrame) {
2104
+ flag("refuse", "whole-voice-drift", seg ?? null, `scene ${iv.scene} starts ${at} frames into the song, its stretch of it at ${iv.fromFrame}`);
2105
+ }
2106
+ }
2107
+ }
2108
+ }
2109
+ return {
2110
+ version: "source-edit-map.v2", fps: FPS, sampleRate: EDIT_SAMPLE_RATE, samplesPerFrame: SAMPLES_PER_FRAME,
2111
+ clock: "edit frames at 1/24 s and edit samples at 48 kHz from 0, before any loudness pass; a picture slot is ceil(pts*24) of the clip's first decoded frame; a sound's zero is its first decoded sample after any negative-pts priming, and word times count from it",
2112
+ frames: pictureFrames, samples: pictureFrames * SAMPLES_PER_FRAME, pieces, overlays, wholeVoice: whole,
2113
+ audibleSources, mutedPictures, findings,
2114
+ };
2115
+ }
2116
+
2117
+ /**
2118
+ * The rendered cut against its map, on what the output decodes to: its
2119
+ * picture exactly the map's frames, each on the 1/24 s grid from the first,
2120
+ * and its sound the map's samples and start within RENDER_SAMPLE_TOLERANCE
2121
+ * (one AAC frame, the encoder's own priming and padding). Every piece's picture
2122
+ * is cut to at most its frames and its sound padded to exactly its samples, so
2123
+ * the whole cut's counts holding is every boundary holding. No container
2124
+ * duration is read.
2125
+ */
2126
+ export function renderFindings(map, decoded, planningBudget = null) {
2127
+ const findings = [];
2128
+ const refuse = (code, detail) => findings.push({ severity: "refuse", code, scene: null, detail });
2129
+ const render = { frames: null, frameDelta: null, samples: null, sampleDelta: null, soundStartSamples: null };
2130
+ const pic = decoded?.picture ?? null;
2131
+ const aud = decoded?.audio ?? null;
2132
+ if (!decoded) refuse("render-unmeasured", "the rendered cut's decoded frames and samples could not be read");
2133
+ if (decoded && (!pic || pic.problems.length > 0)) refuse("render-picture-clock", pic ? pic.problems.join("; ") : "the cut has no picture");
2134
+ if (decoded && (!aud || aud.problems.length > 0)) refuse("render-sound-clock", aud ? aud.problems.join("; ") : "the cut has no sound");
2135
+ if (pic && pic.problems.length === 0) {
2136
+ render.frames = pic.frames;
2137
+ render.frameDelta = map ? pic.frames - map.frames : null;
2138
+ if (map && render.frameDelta !== 0) refuse("render-frames", `the cut decodes ${pic.frames} frames, its map ${map.frames}`);
2139
+ const off = pic.ptsSec.findIndex((t, k) => Math.abs(t * FPS - k) > 1e-3);
2140
+ if (off >= 0) refuse("render-picture-grid", `rendered frame ${off} is at ${r6(pic.ptsSec[off])}s, off the 1/24 s grid`);
2141
+ }
2142
+ if (aud && aud.problems.length === 0) {
2143
+ render.samples = Math.round(((aud.samples - aud.primingSamples) * EDIT_SAMPLE_RATE) / aud.sampleRate);
2144
+ render.sampleDelta = map ? render.samples - map.samples : null;
2145
+ if (map && Math.abs(render.sampleDelta) > RENDER_SAMPLE_TOLERANCE) {
2146
+ refuse("render-samples", `the cut decodes ${render.samples} samples, its map ${map.samples}`);
2147
+ }
2148
+ if (pic && pic.problems.length === 0) {
2149
+ render.soundStartSamples = Math.round((aud.zeroSec - pic.originSec) * EDIT_SAMPLE_RATE);
2150
+ if (Math.abs(render.soundStartSamples) > RENDER_SAMPLE_TOLERANCE) {
2151
+ refuse("render-av-start", `the cut's sound starts ${render.soundStartSamples} samples from its first frame`);
2152
+ }
2153
+ }
2154
+ }
2155
+ if (!planningBudget) return { findings, render };
2156
+ const ceilingSeconds = planningBudget.targetSeconds + planningBudget.overrun.seconds;
2157
+ // The selected budget is a maximum, never a request to pad or shorten.
2158
+ // Counts certify seconds only on the actual complete decoded 24 fps clock.
2159
+ const measured = Number.isSafeInteger(render.frames) && render.frames > 0 &&
2160
+ pic?.ptsSec.length === render.frames && pic.ptsSec.every((t, k) => Number.isFinite(t) && Math.abs(t * FPS - k) <= 1e-3) &&
2161
+ Number.isFinite(pic.endSec) && Math.abs(pic.endSec * FPS - render.frames) <= 1e-3 &&
2162
+ (!map || render.frameDelta === 0) && Number.isFinite(ceilingSeconds) &&
2163
+ !findings.some((finding) => ["render-unmeasured", "render-picture-clock", "render-picture-grid", "render-frames"].includes(finding.code));
2164
+ const planningTiming = {
2165
+ basis: "decoded-final-picture-clock",
2166
+ finalSha256: null,
2167
+ planned: { targetSeconds: planningBudget.targetSeconds, overrun: { ...planningBudget.overrun }, ceilingSeconds },
2168
+ decoded: measured ? { frames: render.frames, fps: FPS, seconds: render.frames / FPS } : null,
2169
+ status: !measured ? "unknown" : render.frames > ceilingSeconds * FPS + 1e-7 ? "over-budget" : "within-budget",
2170
+ };
2171
+ if (planningTiming.status === "unknown") refuse("planning-budget-clock-unmeasured", "the selected final total budget cannot be checked without a complete valid decoded final picture clock on the measured 24 fps grid");
2172
+ if (planningTiming.status === "over-budget") refuse("planning-budget-exceeded", `the decoded final cut is ${planningTiming.decoded.seconds}s, exceeding ${planningBudget.targetSeconds}s + ${planningBudget.overrun.name} ${planningBudget.overrun.seconds}s; retain approved words and actions, change approved allocation/copy or model rather than truncating or speeding up`);
2173
+ return { findings, render, planningTiming };
2174
+ }
2175
+
2176
+ /** Budget-only measurement of an actual final file, including unmapped cuts.
2177
+ * No source map is synthesized. Both existing render routes already emit 24fps. */
2178
+ export function measureCutPlanningTiming(file, planningBudget) {
2179
+ let finalSha256 = null;
2180
+ try { finalSha256 = createHash("sha256").update(readFileSync(file)).digest("hex"); }
2181
+ catch { /* Unavailable actual bytes cannot inherit a known decoded receipt. */ }
2182
+ const result = renderFindings(null, measureMedia(file), planningBudget);
2183
+ const findings = result.findings.filter((finding) => ["planning-budget-clock-unmeasured", "planning-budget-exceeded"].includes(finding.code));
2184
+ const planningTiming = { ...result.planningTiming, finalSha256 };
2185
+ if (!finalSha256) {
2186
+ planningTiming.status = "unknown";
2187
+ planningTiming.decoded = null;
2188
+ if (!findings.some((finding) => finding.code === "planning-budget-clock-unmeasured")) findings.push({
2189
+ severity: "refuse", code: "planning-budget-clock-unmeasured", scene: null,
2190
+ detail: "the actual final bytes could not be hashed, so the final decoded timing is not byte-bound",
2191
+ });
2192
+ }
2193
+ return { planningTiming, findings };
2194
+ }
2195
+
1438
2196
  export function buildTimeline({
1439
2197
  manifest, storyboard, skip, probe, exists, readWords, readLevels = () => null, stillFill = false, finish = null,
1440
- wholeVoice = null, sourceAd = null,
2198
+ wholeVoice = null, sourceAd = null, measure = null,
1441
2199
  }) {
1442
- const plans = scenePlans(storyboard);
2200
+ if (measure) {
2201
+ // The measured map: a word's last phoneme end rides with the word through every shift.
2202
+ const heard = readWords;
2203
+ readWords = (file) => withPhonemeEnds(heard(file));
2204
+ }
2205
+ const plans = scenePlans(storyboard, measure ? manifest.planningBudget : null);
1443
2206
  const counts = lineWordCounts(storyboard);
1444
2207
  const spine = [];
1445
2208
  const cutaways = [];
@@ -1462,16 +2225,38 @@ export function buildTimeline({
1462
2225
  continue;
1463
2226
  }
1464
2227
  const nothing = `nothing to cut with (clip ${scene.clipStatus}${scene.error ? `: ${scene.error}` : ""})`;
2228
+ const editorialHold = measure ? selectedEditorialHold(manifest, storyboard, n) : null;
2229
+ if (editorialHold) {
2230
+ const source = spine.at(-1);
2231
+ if (source?.sceneIndex !== editorialHold.sourceSceneIndex || !source.map?.picture) throw new SourceMapRefusal(
2232
+ "The selected editorial hold has no measured preceding picture", [
2233
+ { severity: "refuse", code: "editorial-hold-source-unproven", scene: n, detail: "hold binding cannot use an absent, skipped or unrelated source" },
2234
+ ]);
2235
+ const voice = exists(scene.voice) ? scene.voice : null;
2236
+ const vm = voice ? clockOf(measure(voice)) : null;
2237
+ spine.push({
2238
+ sceneIndex: n, source: "clip", file: source.file, clipSeconds: editorialHold.seconds, inSec: 0,
2239
+ seconds: editorialHold.seconds, holdSec: 0, fixedLength: true, editorialHold,
2240
+ audio: voice ? "narration" : "silence", voice, map: { ...source.map, ...(vm ? { voice: vm } : {}) },
2241
+ words: scene.wordsFrom === "voice" ? readWords(scene.words) : null,
2242
+ lineIds: plan.lineIds, firstSpeaker: null, lastSpeaker: null, actionLeadSec: 0, actionTailSec: 0,
2243
+ note: ", explicitly selected editorial hold of the preceding retained frame",
2244
+ });
2245
+ continue;
2246
+ }
1465
2247
 
1466
2248
  if (plan.cutaway) {
1467
2249
  const cue = {
1468
- cueLineId: plan.cueLineId, reaction: plan.cutawayType === "reaction", broll: plan.broll ?? null,
2250
+ cueLineId: plan.cueLineId, reaction: plan.cutawayType === "reaction" && !plan.overlay, broll: plan.broll ?? null,
2251
+ ...(measure && plan.editSeconds ? { reservedSeconds: plan.editSeconds } : {}),
1469
2252
  };
1470
2253
  if (exists(scene.clip)) {
1471
2254
  const clip = probe(scene.clip);
2255
+ const m = measure ? clockOf(measure(scene.clip)) : null;
1472
2256
  waiting.push({
1473
2257
  sceneIndex: n, source: "clip", file: scene.clip,
1474
- seconds: clip.seconds, hasAudio: clip.hasAudio, ...cue,
2258
+ seconds: m ? (m.picture ? m.picture.endSlot / FPS : 0) : clip.seconds, hasAudio: clip.hasAudio, ...cue,
2259
+ ...(m ? { map: m } : {}),
1475
2260
  });
1476
2261
  } else if (stillFill && exists(scene.keyframe)) {
1477
2262
  filled.add(n);
@@ -1488,23 +2273,33 @@ export function buildTimeline({
1488
2273
  const narrated = plan.narrated || scene.wordsFrom === "voice";
1489
2274
  const voice = exists(scene.voice) ? scene.voice : null;
1490
2275
  const flag = scene.flagged ? " (flagged)" : "";
2276
+ if (measure && scene.words && scene.wordsDescribe === "original-performance") {
2277
+ throw new SourceMapRefusal("The word observation describes a replaced performance, not the selected audible bytes", [
2278
+ { severity: "refuse", code: "word-source-mismatch", scene: n, detail: scene.words },
2279
+ ]);
2280
+ }
1491
2281
 
1492
2282
  if (exists(scene.clip)) {
1493
2283
  const clip = probe(scene.clip);
2284
+ // The measured map: the picture's length is its slots on the edit grid, never the container's.
2285
+ const m = measure ? clockOf(measure(scene.clip)) : null;
2286
+ const pictureSec = m ? (m.picture ? m.picture.endSlot / FPS : 0) : clip.seconds;
1494
2287
  const base = {
1495
- sceneIndex: n, source: "clip", file: scene.clip, clipSeconds: clip.seconds, inSec: 0,
2288
+ sceneIndex: n, source: "clip", file: scene.clip, clipSeconds: pictureSec, inSec: 0,
2289
+ ...(m ? { map: m, ...(scene.actionEvidence ? { actionEvidence: scene.actionEvidence } : {}) } : {}),
1496
2290
  lineIds: plan.lineIds, firstSpeaker: plan.firstSpeaker, lastSpeaker: plan.lastSpeaker,
1497
2291
  baseShotId: plan.baseShotId ?? null, actionTailSec: plan.actionTailSec ?? 0,
1498
2292
  actionLeadSec: plan.actionLeadSec ?? 0,
1499
2293
  };
1500
2294
  if (voice && (narrated || !clip.hasAudio)) {
1501
- const voiceSeconds = probe(voice).seconds;
2295
+ const vm = m ? clockOf(measure(voice)) : null;
2296
+ const voiceSeconds = vm ? (vm.audio ? vm.audio.decodedSec : 0) : probe(voice).seconds;
1502
2297
  const words = readWords(scene.words);
1503
2298
  // A clip's own word times describe the clip, not the voice that replaces its audio.
1504
2299
  const voiceWords = scene.wordsFrom === "voice" ? words : null;
1505
2300
  const fitted = (endsAd) => {
1506
2301
  const fit = fitNarration({
1507
- clipSeconds: clip.seconds, ...narrationEnd(voiceSeconds, voiceWords, endsAd),
2302
+ clipSeconds: base.clipSeconds, ...narrationEnd(voiceSeconds, voiceWords, endsAd, Boolean(m)),
1508
2303
  actionTailSec: plan.actionTailSec ?? 0,
1509
2304
  });
1510
2305
  const how = [];
@@ -1515,23 +2310,29 @@ export function buildTimeline({
1515
2310
  note: `${flag}, ${voice} replaces the clip's audio${how.length ? ` (${how.join(", ")})` : ""}`,
1516
2311
  };
1517
2312
  };
1518
- const seg = { ...base, audio: "narration", voice, words, ...fitted(false) };
2313
+ const seg = {
2314
+ ...base, audio: "narration", voice, words: m ? voiceWords : words, ...fitted(false),
2315
+ ...(vm ? { map: { ...m, voice: vm } } : {}),
2316
+ };
1519
2317
  spine.push(seg);
1520
2318
  refits.set(seg, fitted);
1521
2319
  } else if (narrated) {
1522
2320
  spine.push({
1523
- ...base, audio: "silence", voice: null, seconds: clip.seconds, holdSec: 0,
2321
+ ...base, audio: "silence", voice: null, seconds: base.clipSeconds, holdSec: 0,
1524
2322
  words: null,
1525
2323
  note: `${flag}, narrated scene without its voice track: the clip's own audio is muted`,
1526
2324
  });
1527
2325
  } else if (clip.hasAudio) {
2326
+ // A clip's own words are on its sound's clock: its picture runs deltaSec behind it.
2327
+ const ownSec = m ? Math.max(0, pictureSec - m.deltaSec) : clip.seconds;
1528
2328
  spine.push({
1529
- ...base, audio: "clip", voice: null, seconds: clip.seconds, holdSec: 0,
2329
+ ...base, clipSeconds: ownSec,
2330
+ audio: "clip", voice: null, seconds: ownSec, holdSec: 0,
1530
2331
  words: readWords(scene.words), note: `${flag}, its own dialogue`,
1531
2332
  });
1532
2333
  } else {
1533
2334
  spine.push({
1534
- ...base, audio: "silence", voice: null, seconds: clip.seconds, holdSec: 0,
2335
+ ...base, audio: "silence", voice: null, seconds: base.clipSeconds, holdSec: 0,
1535
2336
  words: null, note: `${flag}, silent clip`,
1536
2337
  });
1537
2338
  }
@@ -1578,7 +2379,13 @@ export function buildTimeline({
1578
2379
  })));
1579
2380
  }
1580
2381
 
1581
- const whole = wholeVoice ? fitWholeVoice(spine, wholeVoice) : null;
2382
+ // The measured map: the song's last stretch ends on its own decoded last sample, never
2383
+ // narration.json's declared length, and its stretches are checked against it.
2384
+ const wholeClock = wholeVoice && measure ? clockOf(measure(wholeVoice.file)) : null;
2385
+ const laid = wholeClock
2386
+ ? { ...wholeVoice, declaredSec: wholeVoice.seconds, seconds: wholeClock.audio ? wholeClock.audio.decodedSec : wholeVoice.seconds, measured: true }
2387
+ : wholeVoice;
2388
+ const whole = laid ? fitWholeVoice(spine, laid) : null;
1582
2389
  if (whole) dropped.push(...whole.dropped);
1583
2390
 
1584
2391
  const sameShot = PUNCH_IN_RUNS.get(manifest?.shots?.pacing);
@@ -1627,15 +2434,41 @@ export function buildTimeline({
1627
2434
  const e = sourceAd?.shots.find((x) => x.n === shotOf(n));
1628
2435
  return e ? e.t1 - e.t0 : null;
1629
2436
  };
1630
- if (sourceAd) {
2437
+ if (sourceAd && !measure) {
1631
2438
  for (const seg of spine) {
1632
- const len = seg.audio === "silence" && !seg.reaction ? shotSec(seg.sceneIndex) : null;
2439
+ const len = seg.audio === "silence" && !seg.reaction && !seg.fixedLength ? shotSec(seg.sceneIndex) : null;
1633
2440
  if (len === null) continue;
1634
2441
  seg.seconds = ceilFrame(len);
1635
2442
  seg.holdSec = holdFor(seg);
1636
2443
  seg.note = withHow(seg.note, [`its source shot's ${len.toFixed(2)}s`]);
1637
2444
  }
1638
2445
  }
2446
+ if (measure) {
2447
+ const takes = new Map();
2448
+ for (const seg of spine) {
2449
+ const same = takes.get(seg.sceneIndex) ?? [];
2450
+ same.push(seg);
2451
+ takes.set(seg.sceneIndex, same);
2452
+ }
2453
+ for (const pieces of takes.values()) {
2454
+ if (pieces.length > 1) pieces.forEach((seg, i) => { seg.piece = { take: seg.sceneIndex, n: i + 1, of: pieces.length }; });
2455
+ }
2456
+ for (const pieces of takes.values()) {
2457
+ const seg = pieces.at(-1);
2458
+ const reserved = plans.get(seg.sceneIndex)?.editSeconds;
2459
+ if (reserved > 0 && !seg.wholeVoice) {
2460
+ // Reserve once per take. Earlier pieces must stop at their split: extending
2461
+ // one would play source speech that the resumed piece will play again.
2462
+ const before = pieces.slice(0, -1).reduce((sum, piece) => sum + piece.seconds, 0);
2463
+ const lastWord = Math.max(0, ...(seg.words ?? []).map(wordEnd));
2464
+ seg.seconds = Math.max(pieces.length > 1 ? seg.seconds : 0,
2465
+ ceilFrame(reserved) - before, ceilFrame(lastWord + (seg.actionTailSec ?? 0)));
2466
+ seg.fixedLength = true;
2467
+ seg.holdSec = holdFor(seg); // the measured map refuses source-short/frozen coverage
2468
+ }
2469
+ }
2470
+ }
2471
+ if (measure) snapToFrames(spine);
1639
2472
  let total = 0;
1640
2473
  for (const seg of spine) {
1641
2474
  seg.startSec = total;
@@ -1644,10 +2477,11 @@ export function buildTimeline({
1644
2477
  spine.forEach((seg, k) => {
1645
2478
  if (seg.reaction?.tail) seg.reaction.tail.atSec = spine[k + 1].startSec;
1646
2479
  });
1647
- const groups = sourceAd ? sourceGroups(spine, sourceAd, shotOf) : null;
2480
+ const groups = sourceAd && !measure ? sourceGroups(spine, sourceAd, shotOf) : null;
1648
2481
 
1649
2482
  const lineTexts = new Map([...scriptLines].map(([id, line]) => [id, line?.text]));
1650
2483
  const beats = spine.filter((seg) => seg.reaction);
2484
+ const reservedThrough = new Map();
1651
2485
  for (const c of waiting.filter((w) => !w.reaction)) {
1652
2486
  // A copied shot lands where its shot sits in the source, through its group.
1653
2487
  const copied = groups?.length ? sourceAd.shots.find((e) => e.n === shotOf(c.sceneIndex)) : null;
@@ -1660,13 +2494,21 @@ export function buildTimeline({
1660
2494
  });
1661
2495
  continue;
1662
2496
  }
1663
- const cue = c.cueLineId ? cueOffsetOnSpine(spine, counts, c.cueLineId) : null;
2497
+ let cue = c.cueLineId ? cueOffsetOnSpine(spine, counts, c.cueLineId) : null;
2498
+ if (measure && c.cueLineId) {
2499
+ const owner = spine.find((seg) => seg.lineIds?.includes(c.cueLineId));
2500
+ const part = owner ? lineParts(owner, scriptLines).find((p) => p.lineId === c.cueLineId && p.measured) : null;
2501
+ cue = part ? { startSec: part.edit.startSec, method: "words", spineSceneIndex: owner.sceneIndex, owner } : null;
2502
+ if (!cue) throw new SourceMapRefusal("The cutaway has no measured owner-word clock; a proportional placement is not delivered", [
2503
+ { severity: "refuse", code: "cutaway-clock-unmeasured", scene: c.sceneIndex, detail: c.cueLineId },
2504
+ ]);
2505
+ }
1664
2506
  if (!cue) {
1665
2507
  dropped.push({ n: c.sceneIndex, reason: `cutaway ${c.sceneIndex}: ${noCue(c)}` });
1666
2508
  continue;
1667
2509
  }
1668
2510
  const placed = { ...c, startSec: cue.startSec, method: cue.method, spineSceneIndex: cue.spineSceneIndex };
1669
- const seg = c.broll ? spine.find((s) => s.lineIds.includes(c.cueLineId)) : null;
2511
+ const seg = c.broll ? cue.owner ?? spine.find((s) => s.lineIds.includes(c.cueLineId)) : null;
1670
2512
  const win = seg
1671
2513
  ? brollWindow(seg, counts, c.cueLineId, lineTexts, c.broll)
1672
2514
  : null;
@@ -1678,8 +2520,26 @@ export function buildTimeline({
1678
2520
  placed.seconds = c.source === "clip" ? Math.min(win.holdSec, c.seconds) : win.holdSec;
1679
2521
  placed.coversFound = win.found;
1680
2522
  }
2523
+ if (measure && c.reservedSeconds > 0) {
2524
+ const key = c.cueLineId;
2525
+ placed.startSec = Math.max(placed.startSec, reservedThrough.get(key) ?? placed.startSec);
2526
+ placed.seconds = ceilFrame(c.reservedSeconds);
2527
+ const owner = cue.owner;
2528
+ if (!owner || placed.startSec + placed.seconds > owner.startSec + owner.seconds + 1e-7) {
2529
+ throw new SourceMapRefusal("The selected overlay cannot return within its unchanged audible source", [
2530
+ { severity: "refuse", code: "overlay-owner-window-short", scene: c.sceneIndex, detail: "the authored picture reservation crosses its retained cue owner's return boundary; no words or elapsed silence are inserted" },
2531
+ ]);
2532
+ }
2533
+ reservedThrough.set(key, placed.startSec + placed.seconds);
2534
+ }
1681
2535
  cutaways.push(placed);
1682
2536
  }
2537
+ if (measure) {
2538
+ for (const c of cutaways) {
2539
+ c.startSec = Math.round(c.startSec * FPS) / FPS;
2540
+ c.seconds = Math.round(c.seconds * FPS) / FPS;
2541
+ }
2542
+ }
1683
2543
  cutaways.sort((a, b) => a.startSec - b.startSec);
1684
2544
  for (let i = 0; i < cutaways.length; i++) {
1685
2545
  const c = cutaways[i];
@@ -1691,17 +2551,46 @@ export function buildTimeline({
1691
2551
  stops.push({ at: total, by: "the ad ends" });
1692
2552
  const stop = stops.reduce((a, b) => (b.at < a.at ? b : a));
1693
2553
  if (c.startSec + c.seconds > stop.at) {
2554
+ if (measure && c.reservedSeconds > 0) throw new SourceMapRefusal("The selected overlay reservation does not fit its retained cue window", [
2555
+ { severity: "refuse", code: "overlay-reservation-short", scene: c.sceneIndex, detail: `${c.reservedSeconds}s is required before ${stop.by}; speech is not paused or extended to make room` },
2556
+ ]);
1694
2557
  c.seconds = Math.max(0, stop.at - c.startSec);
1695
2558
  c.cutShortBy = stop.by;
1696
2559
  }
1697
2560
  }
2561
+ if (measure) {
2562
+ // The measured map: each overlay on whole edit frames, and no longer than its clip's slots.
2563
+ for (const c of cutaways) {
2564
+ const from = Math.round(c.startSec * FPS);
2565
+ const slots = c.map?.picture ? c.map.picture.endSlot : Infinity;
2566
+ if (c.reservedSeconds > 0 && c.seconds * FPS > slots + 1e-6) throw new SourceMapRefusal("The selected overlay source is shorter than its authored reservation", [
2567
+ { severity: "refuse", code: "overlay-source-short", scene: c.sceneIndex, detail: `${c.reservedSeconds}s requires decoded picture coverage, not frozen fill` },
2568
+ ]);
2569
+ const to = Math.min(Math.round((c.startSec + c.seconds) * FPS), Math.round(total * FPS), from + slots);
2570
+ c.startSec = from / FPS;
2571
+ c.seconds = Math.max(0, to - from) / FPS;
2572
+ }
2573
+ }
1698
2574
 
2575
+ const wholeAt = whole && measure ? spine.find((seg) => seg.wholeVoice) : null;
2576
+ const sourceMap = measure
2577
+ ? buildSourceMap({
2578
+ spine, cutaways, scriptLines, pictureFrames: Math.round(total * FPS), sourceMeta: manifest?.sourceMeta ?? null,
2579
+ wholeVoice: whole ? {
2580
+ file: wholeVoice.file, clock: wholeClock, declaredSec: wholeVoice.seconds,
2581
+ startFrame: wholeAt ? Math.round(wholeAt.startSec * FPS) : Math.round(whole.startSec * FPS),
2582
+ intervals: whole.intervals ?? [], problems: whole.problems ?? [],
2583
+ } : null,
2584
+ })
2585
+ : null;
2586
+ const wholeStartSec = sourceMap?.wholeVoice ? sourceMap.wholeVoice.startFrame / FPS : whole?.startSec;
1699
2587
  return {
1700
2588
  spine,
1701
2589
  cutaways,
1702
2590
  left: dropped.sort((a, b) => a.n - b.n).map((d) => d.reason),
1703
- ...(whole ? { wholeVoice: { file: wholeVoice.file, startSec: whole.startSec } } : {}),
2591
+ ...(whole ? { wholeVoice: { file: wholeVoice.file, startSec: wholeStartSec, ...(wholeClock ? { clock: wholeClock } : {}) } } : {}),
1704
2592
  ...(groups ? { sourceGroups: groups } : {}),
2593
+ ...(sourceMap ? { mapped: true, sourceMap } : {}),
1705
2594
  };
1706
2595
  }
1707
2596
 
@@ -1791,6 +2680,79 @@ function sec(n) {
1791
2680
  return (Number.isFinite(n) ? Math.max(0, n) : 0).toFixed(3);
1792
2681
  }
1793
2682
 
2683
+ /** The measured map: the picture re-stamped from its first decoded frame, then resampled by MAP_PICTURE (see pieceClock). */
2684
+ const mappedNorm = (label) =>
2685
+ `[${label}]scale=${WIDTH}:${HEIGHT}:force_original_aspect_ratio=decrease,` +
2686
+ `pad=${WIDTH}:${HEIGHT}:(ow-iw)/2:(oh-ih)/2,setsar=1,setpts=PTS-STARTPTS,${MAP_PICTURE},format=yuv420p`;
2687
+
2688
+ /**
2689
+ * The measured map: one piece cut on pieceClock's numbers, the same the map records:
2690
+ * the picture's sentence-gap slots out, then its slots from inSlot for the
2691
+ * piece's frames; its sound re-stamped from its first decoded sample, the same
2692
+ * gaps out by sample, then from fromSample, with silence only where the map
2693
+ * says the decoded sound is not there, and exactly the piece's samples long.
2694
+ * Nothing is held, stretched or sped. Returns the piece's concat pair.
2695
+ */
2696
+ function mappedPiece(seg, i, { addInput, filters, tails, level, resolve }) {
2697
+ const clock = pieceClock(seg);
2698
+ const samples = clock.frames * SAMPLES_PER_FRAME;
2699
+ const fit = [];
2700
+ if (seg.editorialHold) {
2701
+ fit.push(`trim=start_frame=${seg.editorialHold.sourceSlot}:end_frame=${seg.editorialHold.sourceSlot + 1},setpts=PTS-STARTPTS,tpad=stop_mode=clone:stop=${clock.frames - 1},trim=end_frame=${clock.frames}`);
2702
+ } else if (clock.picture) {
2703
+ const { inSlot, cutSlots } = clock.picture;
2704
+ if (cutSlots.length > 0) {
2705
+ fit.push(`select=not(${cutSlots.map(([s, e]) => `between(n\\,${s}\\,${e - 1})`).join("+")}),setpts=N/FRAME_RATE/TB`);
2706
+ }
2707
+ fit.push(`trim=start_frame=${inSlot}:end_frame=${inSlot + clock.frames},setpts=PTS-STARTPTS`);
2708
+ }
2709
+ if (seg.punchIn) fit.push(PUNCH_IN);
2710
+ filters.push(`${mappedNorm(`${i}:v`)}${fit.length ? `,${fit.join(",")}` : ""}[v${i}]`);
2711
+ const s = clock.sound;
2712
+ if (!s) {
2713
+ filters.push(`anullsrc=r=${EDIT_SAMPLE_RATE}:cl=stereo,atrim=end_sample=${samples}[a${i}]`);
2714
+ return `[v${i}][a${i}]`;
2715
+ }
2716
+ const input = seg.audio === "clip" ? i : addInput("-i", resolve(seg.voice));
2717
+ let heard = `[${input}:a]${stereo},asetpts=PTS-STARTPTS,`;
2718
+ if (s.cutSamples.length > 0) {
2719
+ const kept = [0, ...s.cutSamples.flat()];
2720
+ const pieces = s.cutSamples.length + 1;
2721
+ filters.push(`${heard}asplit=${pieces}${Array.from({ length: pieces }, (_, p) => `[ap${i}_${p}]`).join("")}`);
2722
+ for (let p = 0; p < pieces; p++) {
2723
+ const end = p < s.cutSamples.length ? `:end_sample=${kept[2 * p + 1]}` : "";
2724
+ filters.push(`[ap${i}_${p}]atrim=start_sample=${kept[2 * p]}${end},asetpts=PTS-STARTPTS[aq${i}_${p}]`);
2725
+ }
2726
+ filters.push(`${Array.from({ length: pieces }, (_, p) => `[aq${i}_${p}]`).join("")}concat=n=${pieces}:v=0:a=1[ac${i}]`);
2727
+ heard = `[ac${i}]`;
2728
+ }
2729
+ const start = Math.max(0, s.fromSample);
2730
+ const lead = Math.max(0, -s.fromSample);
2731
+ const tail = seg.audio === "clip" ? seg.reaction?.tail ?? null : null;
2732
+ // A reaction's tail plays on from where its beat stops, so its beat's sound is not ended here.
2733
+ const end = tail ? "" : `:end_sample=${Math.max(start, s.toSample)}`;
2734
+ const head = `${heard}atrim=start_sample=${start}${end},asetpts=PTS-STARTPTS${lead > 0 ? `,adelay=delays=${lead}S:all=1` : ""}`;
2735
+ const [fadeIn, fadeOut] = [seg.fadeInSec ?? EDGE_FADE_SEC, seg.fadeOutSec ?? EDGE_FADE_SEC];
2736
+ const rise = fadeIn > EDGE_FADE_SEC ? ":curve=cub" : "";
2737
+ const fitLength =
2738
+ `apad,atrim=end_sample=${samples},afade=t=in:d=${sec(fadeIn)}${rise},` +
2739
+ `afade=t=out:st=${sec(seg.seconds - fadeOut)}:d=${sec(fadeOut)}`;
2740
+ if (!tail) {
2741
+ filters.push(`${head},${level},${fitLength}[a${i}]`);
2742
+ return `[v${i}][a${i}]`;
2743
+ }
2744
+ const tailSamples = Math.round(tail.seconds * EDIT_SAMPLE_RATE);
2745
+ filters.push(`${head},${level},asplit=2[as${i}][at${i}]`);
2746
+ filters.push(`[as${i}]${fitLength}[a${i}]`);
2747
+ filters.push(
2748
+ `[at${i}]atrim=start_sample=${samples}:end_sample=${samples + tailSamples},asetpts=PTS-STARTPTS,` +
2749
+ `volume=${tail.gain},afade=t=in:d=${EDGE_FADE_SEC},afade=t=out:st=0:d=${sec(tail.seconds)},` +
2750
+ `adelay=delays=${Math.round(tail.atSec * FPS) * SAMPLES_PER_FRAME}S:all=1[tail${i}]`,
2751
+ );
2752
+ tails.push(`[tail${i}]`);
2753
+ return `[v${i}][a${i}]`;
2754
+ }
2755
+
1794
2756
  /**
1795
2757
  * The render. `finish` (null: today's render) carries the finishing settings'
1796
2758
  * part of it: levelSegments false leaves each segment's sound as it is for the
@@ -1811,12 +2773,18 @@ export function buildFfmpegArgs(timeline, { resolve, music, out, finish = null,
1811
2773
  const filters = [];
1812
2774
  const pairs = [];
1813
2775
  const tails = [];
2776
+ // The measured map: every piece, overlay and the whole voice on pieceClock's numbers.
2777
+ const mapped = timeline.mapped === true;
1814
2778
 
1815
2779
  for (const seg of timeline.spine) {
1816
2780
  const i =
1817
2781
  seg.source === "clip"
1818
2782
  ? addInput("-i", resolve(seg.file))
1819
2783
  : addInput("-loop", "1", "-t", String(seg.seconds), "-i", resolve(seg.file));
2784
+ if (mapped) {
2785
+ pairs.push(mappedPiece(seg, i, { addInput, filters, tails, level, resolve }));
2786
+ continue;
2787
+ }
1820
2788
  const fit = [];
1821
2789
  const inSec = seg.inSec ?? 0;
1822
2790
  // #2544: sentence gaps come out first, the picture by frame number and the
@@ -1890,17 +2858,30 @@ export function buildFfmpegArgs(timeline, { resolve, music, out, finish = null,
1890
2858
  // ends on its own. No -shortest: ffmpeg 8 held the whole ad's frames for it,
1891
2859
  // and Debian's ffmpeg 5.1 (the worker's) never ended at all (#2988).
1892
2860
  const pictureSec = timeline.spine.reduce((sum, seg) => sum + seg.seconds, 0);
2861
+ // The measured map: the spoken sound is exactly the picture's samples, and a song laid
2862
+ // whole is its own decoded samples from its first scene's frame, whole: never
2863
+ // padded, looped or cut (the map refused a picture it would not fit).
2864
+ const pictureSamples = timeline.spine.reduce((n, seg) => n + Math.round(seg.seconds * FPS), 0) * SAMPLES_PER_FRAME;
2865
+ const toPicture = mapped ? `atrim=end_sample=${pictureSamples}` : `atrim=end=${pictureSec.toFixed(6)}`;
1893
2866
  if (timeline.wholeVoice) {
1894
2867
  // The voice laid whole from where its first scene starts, under the spine's own sound.
1895
2868
  const k = addInput("-i", resolve(timeline.wholeVoice.file));
1896
- filters.push(`[voicecat]apad,atrim=end=${pictureSec.toFixed(6)}[spoken]`);
1897
- filters.push(
1898
- `[${k}:a]${stereo},${level},adelay=delays=${Math.round(timeline.wholeVoice.startSec * 1000)}:all=1,` +
1899
- `apad,atrim=end=${pictureSec.toFixed(6)}[whole]`,
1900
- );
2869
+ filters.push(`[voicecat]apad,${toPicture}[spoken]`);
2870
+ if (mapped) {
2871
+ const delay = Math.round(timeline.wholeVoice.startSec * FPS) * SAMPLES_PER_FRAME;
2872
+ filters.push(
2873
+ `[${k}:a]${stereo},asetpts=PTS-STARTPTS,atrim=start_sample=${timeline.wholeVoice.clock?.audio?.edit.priming ?? 0},` +
2874
+ `asetpts=PTS-STARTPTS,${level}${delay > 0 ? `,adelay=delays=${delay}S:all=1` : ""}[whole]`,
2875
+ );
2876
+ } else {
2877
+ filters.push(
2878
+ `[${k}:a]${stereo},${level},adelay=delays=${Math.round(timeline.wholeVoice.startSec * 1000)}:all=1,` +
2879
+ `apad,atrim=end=${pictureSec.toFixed(6)}[whole]`,
2880
+ );
2881
+ }
1901
2882
  filters.push("[spoken][whole]amix=inputs=2:duration=first:dropout_transition=0:normalize=0[voice]");
1902
2883
  } else {
1903
- filters.push(`[voicecat]apad,atrim=end=${pictureSec.toFixed(6)}[voice]`);
2884
+ filters.push(`[voicecat]apad,${toPicture}[voice]`);
1904
2885
  }
1905
2886
 
1906
2887
  let videoLabel = "vcat";
@@ -1910,6 +2891,16 @@ export function buildFfmpegArgs(timeline, { resolve, music, out, finish = null,
1910
2891
  ? addInput("-i", resolve(c.file))
1911
2892
  : addInput("-loop", "1", "-t", String(c.seconds), "-i", resolve(c.file));
1912
2893
  const end = c.startSec + c.seconds;
2894
+ if (mapped) {
2895
+ // The measured map: the overlay's own slots from its first decoded frame, on the edit's frames.
2896
+ const [from, frames] = [Math.round(c.startSec * FPS), Math.round(c.seconds * FPS)];
2897
+ filters.push(`${mappedNorm(`${i}:v`)},trim=end_frame=${frames},setpts=PTS-STARTPTS+${from}/(${FPS}*TB)[cv${j}]`);
2898
+ filters.push(
2899
+ `[${videoLabel}][cv${j}]overlay=enable=between(t\\,${(from / FPS).toFixed(6)}\\,${((from + frames - 0.5) / FPS).toFixed(6)}):eof_action=pass[ov${j}]`,
2900
+ );
2901
+ videoLabel = `ov${j}`;
2902
+ return;
2903
+ }
1913
2904
  // speedUpSlowBroll: a slow cutaway plays faster; brollMinSec: one that plays on past its clip holds its last frame.
1914
2905
  const faster = c.speed > 1 ? `,setpts=PTS/${c.speed}` : "";
1915
2906
  const hold = c.holdSec > 0 ? `,tpad=stop_mode=clone:stop_duration=${sec(c.holdSec)}` : "";
@@ -1949,21 +2940,33 @@ export function buildFfmpegArgs(timeline, { resolve, music, out, finish = null,
1949
2940
  if (sound?.beds?.length) {
1950
2941
  sound.beds.forEach((b, j) => {
1951
2942
  const k = addInput("-stream_loop", "-1", "-i", resolve(b.file));
1952
- filters.push(
1953
- `[${k}:a]${stereo},atrim=0:${sec(b.seconds)},asetpts=PTS-STARTPTS,volume=${b.gainDb}dB,` +
2943
+ const samples = Math.round(b.seconds * EDIT_SAMPLE_RATE);
2944
+ const delay = Math.round(b.startSec * EDIT_SAMPLE_RATE);
2945
+ filters.push(timeline.mapped
2946
+ ? `[${k}:a]${stereo},asetpts=PTS-STARTPTS,atrim=start_sample=${b.sourcePrimingSamples ?? 0}:end_sample=${samples + (b.sourcePrimingSamples ?? 0)},asetpts=PTS-STARTPTS,volume=${b.gainDb}dB,` +
2947
+ `afade=t=in:ns=${Math.round(BED_FADE_SEC * EDIT_SAMPLE_RATE)},afade=t=out:ss=${Math.max(0, samples - Math.round(BED_FADE_SEC * EDIT_SAMPLE_RATE))}:ns=${Math.round(BED_FADE_SEC * EDIT_SAMPLE_RATE)},` +
2948
+ `adelay=delays=${delay}S:all=1[set${j}]`
2949
+ : `[${k}:a]${stereo},atrim=0:${sec(b.seconds)},asetpts=PTS-STARTPTS,volume=${b.gainDb}dB,` +
1954
2950
  `afade=t=in:d=${BED_FADE_SEC},afade=t=out:st=${sec(Math.max(0, b.seconds - BED_FADE_SEC))}:d=${BED_FADE_SEC},` +
1955
2951
  `adelay=delays=${Math.round(b.startSec * 1000)}:all=1[set${j}]`,
1956
2952
  );
1957
2953
  beds.push(`[set${j}]`);
1958
2954
  });
1959
- } else {
1960
- filters.push(`${ROOM_TONE}[room]`);
2955
+ } else if (!timeline.mapped || !timeline.wholeVoice) {
2956
+ filters.push(timeline.mapped
2957
+ ? `${ROOM_TONE},atrim=end_sample=${Math.round(pictureSec * EDIT_SAMPLE_RATE)}[room]`
2958
+ : `${ROOM_TONE}[room]`);
1961
2959
  beds.push("[room]");
1962
2960
  }
1963
2961
  beds.push(...tails);
1964
2962
  (sound?.effects ?? []).forEach((e, j) => {
1965
2963
  const k = addInput("-i", resolve(e.file));
1966
- filters.push(`[${k}:a]${stereo},volume=${e.gainDb}dB,adelay=delays=${Math.round(e.atSec * 1000)}:all=1[sfx${j}]`);
2964
+ const atSample = Math.round(e.atSec * EDIT_SAMPLE_RATE);
2965
+ const skip = Math.max(0, -atSample);
2966
+ const delay = Math.max(0, atSample);
2967
+ filters.push(timeline.mapped
2968
+ ? `[${k}:a]${stereo},asetpts=PTS-STARTPTS,atrim=start_sample=${skip + (e.sourcePrimingSamples ?? 0)},asetpts=PTS-STARTPTS,volume=${e.gainDb}dB,adelay=delays=${delay}S:all=1[sfx${j}]`
2969
+ : `[${k}:a]${stereo},volume=${e.gainDb}dB,adelay=delays=${Math.round(e.atSec * 1000)}:all=1[sfx${j}]`);
1967
2970
  beds.push(`[sfx${j}]`);
1968
2971
  });
1969
2972
  let voice = "[voice]";
@@ -1973,7 +2976,9 @@ export function buildFfmpegArgs(timeline, { resolve, music, out, finish = null,
1973
2976
  const duck = clean ? null : sound?.music?.duck;
1974
2977
  if (duck) {
1975
2978
  filters.push("[voice]asplit=2[voiced][duckkey]");
1976
- filters.push(`[${m}:a]${stereo},atrim=0:${pictureSec.toFixed(6)},asetpts=PTS-STARTPTS,volume=${sound.music.gainDb}dB[bedraw]`);
2979
+ filters.push(timeline.mapped
2980
+ ? `[${m}:a]${stereo},asetpts=PTS-STARTPTS,atrim=start_sample=${timeline.musicPrimingSamples ?? 0}:end_sample=${Math.round(pictureSec * EDIT_SAMPLE_RATE) + (timeline.musicPrimingSamples ?? 0)},asetpts=PTS-STARTPTS,volume=${sound.music.gainDb}dB[bedraw]`
2981
+ : `[${m}:a]${stereo},atrim=0:${pictureSec.toFixed(6)},asetpts=PTS-STARTPTS,volume=${sound.music.gainDb}dB[bedraw]`);
1977
2982
  filters.push(
1978
2983
  `[bedraw][duckkey]sidechaincompress=threshold=${duck.threshold}:ratio=${duck.ratio}:attack=${duck.attack}:release=${duck.release}[bed]`,
1979
2984
  );
@@ -1981,7 +2986,9 @@ export function buildFfmpegArgs(timeline, { resolve, music, out, finish = null,
1981
2986
  } else if (clean && sound?.music) {
1982
2987
  filters.push(`[${m}:a]${stereo},atrim=0:${pictureSec.toFixed(6)},asetpts=PTS-STARTPTS,volume=${sound.music.gainDb}dB[bed]`);
1983
2988
  } else {
1984
- filters.push(`[${m}:a]${stereo},volume=${MUSIC_VOLUME}[bed]`);
2989
+ filters.push(timeline.mapped
2990
+ ? `[${m}:a]${stereo},asetpts=PTS-STARTPTS,atrim=start_sample=${timeline.musicPrimingSamples ?? 0}:end_sample=${Math.round(pictureSec * EDIT_SAMPLE_RATE) + (timeline.musicPrimingSamples ?? 0)},asetpts=PTS-STARTPTS,volume=${MUSIC_VOLUME}[bed]`
2991
+ : `[${m}:a]${stereo},volume=${MUSIC_VOLUME}[bed]`);
1985
2992
  }
1986
2993
  beds.push("[bed]");
1987
2994
  }
@@ -2060,7 +3067,9 @@ export function sceneTimes(timeline) {
2060
3067
  return pieces.map((p) => ({ sceneIndex: seg.sceneIndex, startSec: p.from, seconds: p.to - p.from }));
2061
3068
  });
2062
3069
  return [...visible, ...timeline.cutaways]
2063
- .map((p) => ({ scene: p.sceneIndex, startSec: roundMs(p.startSec), seconds: roundMs(p.seconds) }))
3070
+ .map((p) => timeline.mapped
3071
+ ? { scene: p.sceneIndex, startSec: p.startSec, seconds: p.seconds }
3072
+ : { scene: p.sceneIndex, startSec: roundMs(p.startSec), seconds: roundMs(p.seconds) })
2064
3073
  .filter((p) => p.seconds > 0)
2065
3074
  .sort((a, b) => a.startSec - b.startSec);
2066
3075
  }
@@ -2068,12 +3077,20 @@ export function sceneTimes(timeline) {
2068
3077
  export function wordRows(timeline) {
2069
3078
  const rows = [];
2070
3079
  for (const seg of timeline.spine) {
2071
- for (const w of seg.words ?? []) {
3080
+ const pieceId = seg.piece ? `${seg.sceneIndex}.${seg.piece.n}` : String(seg.sceneIndex);
3081
+ const parts = timeline.sourceMap?.pieces.find((p) => p.piece === pieceId)?.lineParts ?? [];
3082
+ for (const [index, w] of (seg.words ?? []).entries()) {
2072
3083
  const text = (w.w ?? "").trim();
2073
3084
  const start = seg.startSec + w.s;
2074
- const end = seg.startSec + w.e;
3085
+ const end = seg.startSec + (timeline.mapped ? wordEnd(w) : w.e);
2075
3086
  if (text && end > start) {
2076
- rows.push({ text, start: roundMs(start), end: roundMs(end), scene: seg.sceneIndex });
3087
+ const owner = parts.find((p) => p.measured && index >= p.firstWord && index <= p.lastWord);
3088
+ rows.push(timeline.mapped
3089
+ ? {
3090
+ text, start, end, scene: seg.sceneIndex, lineId: owner?.lineId ?? null,
3091
+ partId: owner?.sourceSpan?.partId ?? owner?.part ?? null,
3092
+ }
3093
+ : { text, start: roundMs(start), end: roundMs(end), scene: seg.sceneIndex });
2077
3094
  }
2078
3095
  }
2079
3096
  }
@@ -2535,6 +3552,15 @@ export function endCardOf(storyboard, seconds) {
2535
3552
  return { text: overlay.text.trim(), in: roundMs(Math.max(0, seconds - END_CARD_SEC)), out: roundMs(seconds + 1) };
2536
3553
  }
2537
3554
 
3555
+ /**
3556
+ * COP-217: the source ad's own shots for the pace report. A fast-cut ad's shot list joins its short shots into fewer
3557
+ * entries (the worker's sourceShots), so `shots` is the list the board copies and `adShots`, when the worker wrote
3558
+ * it, the ad's real cuts.
3559
+ */
3560
+ export function sourceAdPaceShots(sourceAd) {
3561
+ return Array.isArray(sourceAd?.adShots) && sourceAd.adShots.length > 0 ? sourceAd.adShots : sourceAd.shots;
3562
+ }
3563
+
2538
3564
  /**
2539
3565
  * The pace report: cuts a minute, mean and longest shot, shots over
2540
3566
  * LONG_SHOT_SEC, words a minute and pauses over 0.3 s, against a source ad's
@@ -2751,6 +3777,10 @@ export function readLoudness(stderr) {
2751
3777
  * the picture copied as it is. Without them (pass one could not read the
2752
3778
  * sound) loudnorm runs on its own, in one pass. `limiter` (limitPeaks) runs
2753
3779
  * after it.
3780
+ * Every resample after loudnorm is pinned to stereo, which the mix is (each
3781
+ * sound joins it through `stereo`). Without the pin Debian's ffmpeg 5.1, the
3782
+ * worker's, stops the pass: "Cannot select channel layout for the link between
3783
+ * filters". ffmpeg 8 makes the same sound either way.
2754
3784
  */
2755
3785
  export function loudnessApplyArgs(mix, measured, out, limiter = null) {
2756
3786
  const second = measured
@@ -2760,7 +3790,7 @@ export function loudnessApplyArgs(mix, measured, out, limiter = null) {
2760
3790
  return [
2761
3791
  "-y", "-hide_banner", "-loglevel", "error", "-i", mix,
2762
3792
  "-map", "0:v:0", "-map", "0:a:0", "-c:v", "copy",
2763
- "-af", `loudnorm=${LOUDNORM_TARGET}${second}${limiter ? `,${limiter}` : ""},aresample=48000`,
3793
+ "-af", `loudnorm=${LOUDNORM_TARGET}${second}${limiter ? `,${limiter}` : ""},${stereo}`,
2764
3794
  "-c:a", "aac", "-b:a", "192k", "-movflags", "+faststart", out,
2765
3795
  ];
2766
3796
  }
@@ -2788,14 +3818,24 @@ function measureLufs(file) {
2788
3818
  return measured ? round2(measured.i) : null;
2789
3819
  }
2790
3820
 
3821
+ /** ffmpeg's first printed line, as a sentence, or how it stopped when it printed nothing. */
3822
+ function ffmpegReason(res) {
3823
+ const line = String(res.stderr ?? "").split("\n").map((l) => l.trim()).find(Boolean);
3824
+ if (line) return /[.!?]$/.test(line) ? line : `${line}.`;
3825
+ return res.signal ? `it was stopped by ${res.signal}.` : "it printed no reason.";
3826
+ }
3827
+
2791
3828
  /** Both passes on the rendered mix, then the finished cut measured again; throws LoudnessRefusal over the limit. */
2792
3829
  export function finishLoudnessPass(mix, out, limiter = null) {
2793
3830
  const measured = measureLoudness(mix);
2794
3831
  const args = loudnessApplyArgs(mix, measured, out, limiter);
2795
- const res = spawnSync("ffmpeg", args, { stdio: "inherit" });
3832
+ const res = spawnSync("ffmpeg", args, { stdio: ["inherit", "inherit", "pipe"], encoding: "utf8", maxBuffer: 1 << 26 });
2796
3833
  if (res.status !== 0) {
3834
+ // ffmpeg's words still reach the log, and its reason leads the error:
3835
+ // a run keeps only the first 500 characters of a failed cut's message.
3836
+ if (res.stderr) process.stderr.write(res.stderr);
2797
3837
  const quoted = args.map((a) => (/[\s\[\];]/.test(a) ? `'${a}'` : a)).join(" ");
2798
- throw new FirstCutError(1, `ffmpeg failed on the loudness pass. The command it ran:\n ffmpeg ${quoted}`);
3838
+ throw new FirstCutError(1, `ffmpeg failed on the loudness pass: ${ffmpegReason(res)} The command it ran:\n ffmpeg ${quoted}`);
2799
3839
  }
2800
3840
  const finished = measureLoudness(out);
2801
3841
  const refusal = truePeakRefusal(finished);
@@ -2854,6 +3894,460 @@ export class LoudnessRefusal extends FirstCutError {
2854
3894
  }
2855
3895
  }
2856
3896
 
3897
+ /** The measured map found a required word, frame or tail the cut cannot hold on its real clocks. */
3898
+ export class SourceMapRefusal extends FirstCutError {
3899
+ constructor(message, findings) {
3900
+ super(1, message);
3901
+ this.name = "SourceMapRefusal";
3902
+ this.findings = findings;
3903
+ }
3904
+ }
3905
+
3906
+ /** Throws SourceMapRefusal for the map's refusals; its "declared" findings are carried out and recorded. */
3907
+ function refuseUnholdable(map, deferredScenes = new Set()) {
3908
+ const refused = map.findings.filter((f) => f.severity === "refuse" &&
3909
+ !(deferredScenes.has(f.scene) && ["action-lead-unproven", "action-tail-unproven"].includes(f.code)));
3910
+ if (refused.length === 0) return;
3911
+ const lines = refused.map((f) => ` ${f.scene === null ? "cut" : `scene ${f.scene}`}: ${f.code}: ${f.detail}`);
3912
+ throw new SourceMapRefusal(
3913
+ `The source-to-edit map cannot hold the cut without hiding a clock (no speed-up, stretch or frozen frame is used):\n${lines.join("\n")}`,
3914
+ refused,
3915
+ );
3916
+ }
3917
+
3918
+ /** The decoded clocks of each file, measured once; `files` lists every file read, for the map's byte record. */
3919
+ function mediaReader(here, exists) {
3920
+ const seen = new Map();
3921
+ const read = (file) => {
3922
+ if (!seen.has(file)) seen.set(file, exists(file) ? measureMedia(here(file)) : null);
3923
+ return seen.get(file);
3924
+ };
3925
+ read.files = () => [...seen.keys()];
3926
+ return read;
3927
+ }
3928
+
3929
+ export const sourceMapPath = (outPath) =>
3930
+ path.join(path.dirname(outPath), `${path.basename(outPath, path.extname(outPath))}.source-map.json`);
3931
+
3932
+ /** A required text/fulfillment obligation cannot be claimed as delivered. */
3933
+ export class TextFinishRefusal extends FirstCutError {
3934
+ constructor(holds) {
3935
+ super(1, `The finish is held; no partial cut is delivered:\n${holds.map((h) => ` ${h.id}: ${h.code}: ${h.reason}`).join("\n")}`);
3936
+ this.name = "TextFinishRefusal";
3937
+ this.holds = holds;
3938
+ }
3939
+ }
3940
+
3941
+ /** Author-selected geometry is planned layout, not an observation of source pixels. */
3942
+ export function textMaterial(cut, board, policy) {
3943
+ const words = wordRows(cut.timeline);
3944
+ const sourceAd = sourceAdOf(cut.manifest);
3945
+ const permission = policy.outputPermission;
3946
+ const selection = { outputPermission: permission };
3947
+ if (permission?.ending) selection.ending = { ...permission.ending };
3948
+ const items = [];
3949
+ const pictureHolds = [];
3950
+ const skippedPictures = [];
3951
+ let cardIndex = 0;
3952
+ const order = new Map((board.script ?? []).map((line, index) => [line.lineId, index]));
3953
+ const ordered = [...(board.overlays ?? [])].sort((a, b) =>
3954
+ (order.get(a.cueLineId) ?? Infinity) - (order.get(b.cueLineId) ?? Infinity));
3955
+ for (const o of ordered) {
3956
+ const authored = o.render ?? {};
3957
+ if (PICTURE_OVERLAY.test(o.type ?? "")) {
3958
+ const missing = { id: o.overlayId, code: "picture-overlay-undelivered", reason: "the authored screenshot/chart has no delivered selected picture asset; literal text is not a picture substitute" };
3959
+ if (authored.required === true) pictureHolds.push(missing);
3960
+ else skippedPictures.push(missing);
3961
+ continue;
3962
+ }
3963
+ if (!hasText(o.text) && authored.required !== true) continue;
3964
+ const heard = words.filter((w) => w.lineId === o.cueLineId);
3965
+ const isHook = o.type === "question-sticker" || /hook/i.test(o.placement ?? "");
3966
+ const isEnd = o.overlayId === board.cta?.overlayId;
3967
+ const isOffer = o.type === "offer";
3968
+ if (policy.cards === false && !["physical-readout", "authentic-lettering"].includes(authored.provenance)) {
3969
+ const missing = { id: o.overlayId, code: "cards-not-selected", reason: "the frozen cards setting is off; permission alone does not select a graphic" };
3970
+ if (authored.required === true) pictureHolds.push(missing);
3971
+ else skippedPictures.push(missing);
3972
+ continue;
3973
+ }
3974
+ // Only ordinary unboxed cards consume source-reference card geometry.
3975
+ // CTA/offer selections and authored boxes have their own layout authority.
3976
+ const refBox = authored.box || isEnd || isOffer ? undefined
3977
+ : isHook ? sourceAd?.hook?.box : sourceAd?.cards?.[cardIndex++]?.box;
3978
+ const item = {
3979
+ id: o.overlayId, kind: isHook ? "question-sticker" : "card", text: o.text,
3980
+ required: isEnd && !permission?.endCard || isOffer && !permission?.offer
3981
+ ? authored.required === true : authored.required !== false,
3982
+ provenance: authored.provenance ?? "post",
3983
+ ...(authored.box ?? refBox ? { box: authored.box ?? refBox } : {}),
3984
+ in: authored.startSec ?? (heard.length ? Math.min(...heard.map((w) => w.start)) : undefined),
3985
+ out: authored.endSec ?? (heard.length ? Math.max(...heard.map((w) => w.end)) : undefined),
3986
+ ...(authored.opening !== undefined ? { opening: authored.opening } : {}),
3987
+ ...(authored.value !== undefined ? { value: authored.value } : {}),
3988
+ ...(authored.unit !== undefined ? { unit: authored.unit } : {}),
3989
+ ...(authored.minReadableSec !== undefined ? { minReadableSec: authored.minReadableSec } : {}),
3990
+ layoutOrigin: authored.box ? "approved-board-planned-layout" : refBox ? "source-record-reference-layout" : "missing",
3991
+ };
3992
+ if (isEnd) {
3993
+ if (permission?.endCard) selection.endCard = { ...item, kind: "end" };
3994
+ else items.push({ ...item, kind: "end" });
3995
+ }
3996
+ else if (isOffer) {
3997
+ if (permission?.offer) selection.offer = { ...item, kind: "offer", photo: null };
3998
+ else items.push({ ...item, kind: "offer" }); // helper skips optional output or holds an explicitly required unauthorized offer
3999
+ } else items.push(item);
4000
+ }
4001
+ return {
4002
+ treatment: policy.treatment, words, items, selection, pictureHolds, skippedPictures,
4003
+ captions: {
4004
+ on: policy.captions === true,
4005
+ cap: {
4006
+ ...(sourceAd?.captions ?? {}), ...(board.audio?.captionStyle ?? {}),
4007
+ ...(board.audio?.captionStyle?.box ? { place: undefined } : {}),
4008
+ },
4009
+ names: (board.cast ?? []).map((c) => c.name).filter(hasText),
4010
+ ...(cut.timeline.wholeVoice ? { lyricLines: (board.script ?? []).map((line) => line.text) } : {}),
4011
+ },
4012
+ cuts: [...new Set([
4013
+ ...cut.timeline.spine.flatMap((s) => [s.startSec, s.startSec + s.seconds]),
4014
+ ...cut.timeline.cutaways.flatMap((s) => [s.startSec, s.startSec + s.seconds]),
4015
+ ])].sort((a, b) => a - b),
4016
+ W: WIDTH, H: HEIGHT, totalSec: cut.sourceMap.frames / FPS,
4017
+ };
4018
+ }
4019
+
4020
+ /** Resolve authored anchors on the actual visible edit and retained word clock, never planning seconds. */
4021
+ export function resolveTemporalRequirements(cut, board) {
4022
+ const words = wordRows(cut.timeline);
4023
+ const pictures = sceneTimes(cut.timeline);
4024
+ const requirements = [];
4025
+ const owners = [];
4026
+ const holds = [];
4027
+ const covers = (start, end, spans) => {
4028
+ let at = start;
4029
+ for (const span of spans) {
4030
+ if (span.end <= at) continue;
4031
+ if (span.start > at + 1e-7) return false;
4032
+ at = Math.max(at, span.end);
4033
+ if (at >= end - 1e-7) return true;
4034
+ }
4035
+ return false;
4036
+ };
4037
+ for (const scene of board.scenes ?? []) {
4038
+ const visible = pictures.filter((p) => p.scene === scene.sceneIndex).map((p) => ({ start: p.startSec, end: p.startSec + p.seconds }));
4039
+ const anchor = (a) => {
4040
+ if (a?.boundary === "scene-start") return visible.length ? visible[0].start : null;
4041
+ if (a?.boundary === "scene-end") return visible.length ? visible.at(-1).end : null;
4042
+ const heard = words.filter((w) => w.lineId === a?.lineId);
4043
+ if (!heard.length) return null;
4044
+ return a.edge === "start" ? Math.min(...heard.map((w) => w.start)) : a.edge === "end" ? Math.max(...heard.map((w) => w.end)) : null;
4045
+ };
4046
+ for (const phase of scene.actionPhases ?? []) {
4047
+ const startSec = anchor(phase.window?.start);
4048
+ const endSec = anchor(phase.window?.end);
4049
+ const invalid = phase.required !== true || !hasText(phase.id) || !hasText(phase.description) ||
4050
+ !["contact", "completion", "interior-hold", "living-tail"].includes(phase.kind) ||
4051
+ (["contact", "completion"].includes(phase.kind) && (!hasText(phase.before) || !hasText(phase.after))) ||
4052
+ requirements.some((p) => p.id === phase.id) ||
4053
+ (phase.afterPhaseId && !requirements.some((p) => p.id === phase.afterPhaseId));
4054
+ if (invalid || startSec === null || endSec === null || !(endSec > startSec) || !covers(startSec, endSec, visible)) {
4055
+ holds.push({ code: "temporal-window-unresolved", id: phase.id ?? `scene:${scene.sceneIndex}`, reason: "the authored phase/state/cue does not resolve to an in-order, fully visible actual edit interval" });
4056
+ continue;
4057
+ }
4058
+ requirements.push({
4059
+ id: phase.id, kind: phase.kind, description: phase.description, startSec, endSec,
4060
+ ...(scene.planningBeatIds?.length === 1 ? { beatId: scene.planningBeatIds[0] } : {}),
4061
+ ...(phase.before !== undefined ? { before: phase.before } : {}),
4062
+ ...(phase.after !== undefined ? { after: phase.after } : {}),
4063
+ ...(phase.afterPhaseId !== undefined ? { afterPhaseId: phase.afterPhaseId } : {}),
4064
+ });
4065
+ owners.push({ id: phase.id, sceneIndex: scene.sceneIndex });
4066
+ }
4067
+ }
4068
+ return { requirements, owners, holds };
4069
+ }
4070
+
4071
+ /** A trusted dense receipt must cover this exact authored phase on this exact pre-text source. */
4072
+ function phasePassed(temporal, id) {
4073
+ return temporal?.retention?.status === "pass" && temporal.receipt?.phases.some((phase) => phase.id === id && phase.status === "pass");
4074
+ }
4075
+
4076
+ /** Required spoken lines are checked against what the route-owned track retained, not proportional scene durations. */
4077
+ export function finishFulfillment(cut, board, policy, temporal = null) {
4078
+ const words = wordRows(cut.timeline);
4079
+ const holds = [];
4080
+ const lines = [];
4081
+ const tokens = (text) => spokenTokens(scriptWords(text)).tokens;
4082
+ for (const line of board.script ?? []) {
4083
+ const kept = words.filter((w) => w.lineId === line.lineId);
4084
+ const want = tokens(line.text);
4085
+ const got = tokens(kept.map((w) => w.text).join(" "));
4086
+ const exact = want.length === got.length && want.every((token, i) => token === got[i]);
4087
+ lines.push({ lineId: line.lineId, sourceSpan: line.sourceSpan ?? null, retained: kept.map((w) => w.text), exactCanonicalWords: exact });
4088
+ if (!exact) holds.push({ code: "required-words-not-retained", id: line.lineId, reason: `the final audible route does not retain the complete approved line: ${line.text}` });
4089
+ }
4090
+ const beats = [];
4091
+ for (const beat of policy.planningBudget?.beats ?? []) {
4092
+ const owners = (board.scenes ?? []).filter((s) => s.planningBeatIds?.includes(beat.id));
4093
+ const windows = sceneTimes(cut.timeline).filter((s) => owners.some((o) => o.sceneIndex === s.scene))
4094
+ .map((s) => ({ start: s.startSec, end: s.startSec + s.seconds }));
4095
+ const seconds = windows.reduce((sum, w) => sum + w.end - w.start, 0);
4096
+ const reserved = beat.silent?.seconds ?? beat.picture?.seconds ?? null;
4097
+ const retained = owners.length > 0 && windows.length > 0 && (reserved === null || seconds * FPS + 1e-6 >= Math.ceil(reserved * FPS - 1e-6));
4098
+ const pictureAction = beat.picture?.binding === "concrete"
4099
+ ? board.pictureBindings?.find((binding) => binding.beatId === beat.id)?.picture?.action
4100
+ : beat.picture?.action;
4101
+ const observed = owners.length > 0 && owners.every((scene) => {
4102
+ const phases = temporal?.owners?.filter((owner) => owner.sceneIndex === scene.sceneIndex) ?? [];
4103
+ return phases.length > 0 && phases.every((phase) => phasePassed(temporal, phase.id)) &&
4104
+ (!beat.picture?.action || hasText(pictureAction) && temporal.requirements.some((phase) =>
4105
+ phase.description.trim() === pictureAction.trim() && phases.some((owner) => owner.id === phase.id) && phasePassed(temporal, phase.id)));
4106
+ });
4107
+ beats.push({ id: beat.id, windows, seconds, reservedSeconds: reserved, retained, action: beat.picture?.action ? observed ? "observed" : "not-temporally-observed" : "not-asked" });
4108
+ if (!retained) holds.push({ code: "required-beat-not-retained", id: beat.id, reason: "the required picture/action/hold reservation is missing or shortened in the actual edit" });
4109
+ if (beat.picture?.action && !observed) holds.push({ code: "required-action-unobserved", id: beat.id, reason: "no exact-source dense observation proves the authored contact/completion/hold/tail phases" });
4110
+ if (beat.picture?.finalWordTailSec > 0) {
4111
+ const owner = finalWordTailScene(board, beat);
4112
+ const endFrame = cut.sourceMap?.frames;
4113
+ const endSec = endFrame / FPS;
4114
+ const finalWord = words.length ? Math.max(...words.map((word) => word.end)) : null;
4115
+ const finalPiece = owner && cut.sourceMap?.pieces?.find((piece) =>
4116
+ piece.sceneIndex === owner.sceneIndex && piece.edit.startFrame + piece.edit.frames === endFrame &&
4117
+ piece.picture && !piece.picture.editorialHold && piece.picture.heldFrames === 0 &&
4118
+ piece.sound && piece.sound.tailSilenceSamples === 0 && ["clip", "narration"].includes(piece.route.audio));
4119
+ const finalOwnedWord = finalWord !== null && words.some((word) =>
4120
+ word.scene === owner?.sceneIndex && Math.abs(word.end - finalWord) < 1e-7);
4121
+ const visibleTail = finalWord !== null && sceneTimes(cut.timeline).some((window) =>
4122
+ window.scene === owner?.sceneIndex && window.startSec <= finalWord + 1e-7 &&
4123
+ window.startSec + window.seconds >= endSec - 1e-7);
4124
+ const livingTail = temporal?.requirements?.some((phase) =>
4125
+ phase.kind === "living-tail" && hasText(pictureAction) && phase.description.trim() === pictureAction.trim() &&
4126
+ temporal.owners?.some((binding) => binding.id === phase.id && binding.sceneIndex === owner?.sceneIndex) &&
4127
+ finalWord !== null && Math.abs(phase.startSec - finalWord) < 1e-6 &&
4128
+ Math.abs(phase.endSec - endSec) < 1e-6 && phasePassed(temporal, phase.id));
4129
+ if (!finalPiece || !finalOwnedWord || !visibleTail || !livingTail ||
4130
+ finalPiece.edit.startFrame / FPS > finalWord + 1e-7 ||
4131
+ endSec - finalWord + 1e-7 < beat.picture.finalWordTailSec) {
4132
+ holds.push({ code: "final-word-tail-unproven", id: beat.id,
4133
+ reason: `the selected living suffix requires at least ${beat.picture.finalWordTailSec}s after the complete final heard word inside the same final voiced take, fully visible through EOF with exact-source living-tail observation; no appended silent picture or frozen fill` });
4134
+ }
4135
+ }
4136
+ }
4137
+ let ending = { status: "unselected" };
4138
+ if (policy.outputPermission?.ending?.mode === "native") {
4139
+ const terminalBeat = policy.planningBudget?.beats?.at(-1);
4140
+ const owners = (board.scenes ?? []).filter((scene) => scene.planningBeatIds?.includes(terminalBeat?.id));
4141
+ const owner = owners.length === 1 ? owners[0] : null;
4142
+ const visible = sceneTimes(cut.timeline);
4143
+ const last = visible.at(-1);
4144
+ const endFrame = cut.sourceMap?.frames;
4145
+ const endSec = endFrame / FPS;
4146
+ const spans = owner ? visible.filter((span) => span.scene === owner.sceneIndex) : [];
4147
+ const uninterrupted = spans.length === 1 && last === spans[0] &&
4148
+ Math.abs(last.startSec + last.seconds - endSec) < 1e-7;
4149
+ const terminalPiece = owner && cut.sourceMap?.pieces?.find((piece) =>
4150
+ piece.sceneIndex === owner.sceneIndex && piece.picture && piece.edit.startFrame + piece.edit.frames === endFrame);
4151
+ const terminalOverlay = owner && cut.sourceMap?.overlays?.find((overlay) =>
4152
+ overlay.scene === owner.sceneIndex && overlay.picture && overlay.startFrame + overlay.frames === endFrame);
4153
+ const held = terminalPiece?.picture?.editorialHold;
4154
+ const predecessor = held && cut.sourceMap.pieces.find((piece) =>
4155
+ piece.sceneIndex === held.sourceSceneIndex && piece.edit.startFrame + piece.edit.frames === terminalPiece.edit.startFrame);
4156
+ const heldProven = !!held && !!predecessor && policy.outputPermission.ending.kind === "editorial-hold" &&
4157
+ predecessor.picture?.lastFrame === held.sourceFrame &&
4158
+ predecessor.picture?.lastSlot === held.sourceSlot;
4159
+ const releaseScene = heldProven ? held.sourceSceneIndex : owner?.sceneIndex;
4160
+ const releaseEnd = heldProven ? terminalPiece.edit.startFrame / FPS : endSec;
4161
+ const releaseStart = heldProven ? predecessor.edit.startFrame / FPS : last?.startSec ?? Infinity;
4162
+ const release = owner && temporal?.requirements?.find((phase) =>
4163
+ (heldProven ? phase.kind === "completion" : ["completion", "living-tail", "interior-hold"].includes(phase.kind)) &&
4164
+ temporal.owners?.some((binding) => binding.id === phase.id && binding.sceneIndex === releaseScene) &&
4165
+ phase.startSec >= releaseStart - 1e-7 && Math.abs(phase.endSec - releaseEnd) < 1e-7 &&
4166
+ phasePassed(temporal, phase.id));
4167
+ const mapped = !!(terminalPiece || terminalOverlay) && (policy.outputPermission.ending.kind === "editorial-hold" ? heldProven : !held);
4168
+ const fulfilled = !!terminalBeat && uninterrupted && !!release && !!mapped &&
4169
+ lines.every((line) => line.exactCanonicalWords);
4170
+ ending = { kind: policy.outputPermission.ending.kind, status: fulfilled ? "fulfilled" : "hold",
4171
+ beatId: terminalBeat?.id ?? null, sceneIndex: owner?.sceneIndex ?? null,
4172
+ startFrame: last ? Math.round(last.startSec * FPS) : null, endFrame: endFrame ?? null,
4173
+ phaseId: release?.id ?? null };
4174
+ if (!fulfilled) holds.push({ code: "native-ending-unproven", id: terminalBeat?.id ?? "ending",
4175
+ reason: "native permission is not fulfillment: the selected terminal job must be the uninterrupted final mapped picture through EOF, with complete approved words and an exact-source observed completion/release" });
4176
+ }
4177
+ for (const phase of temporal?.requirements ?? []) {
4178
+ if (!phasePassed(temporal, phase.id)) holds.push({ code: "temporal-observation-unproven", id: phase.id, reason: temporal.receipt?.phases.find((p) => p.id === phase.id)?.reason ?? "the required temporal phase was not observed on this exact source" });
4179
+ }
4180
+ holds.push(...(temporal?.holds ?? []));
4181
+ const resolvedPlanningFindings = [];
4182
+ for (const piece of cut.sourceMap?.pieces ?? []) {
4183
+ for (const side of ["lead", "tail"]) {
4184
+ const action = piece.action?.[side];
4185
+ if (!action || action.status !== "unproven") continue;
4186
+ const heard = words.filter((w) => w.scene === piece.sceneIndex);
4187
+ const start = piece.edit.startFrame / FPS;
4188
+ const end = (piece.edit.startFrame + piece.edit.frames) / FPS;
4189
+ const wordStart = heard.length ? Math.min(...heard.map((w) => w.start)) : start + action.wantedSec;
4190
+ const wordEnd = heard.length ? Math.max(...heard.map((w) => w.end)) : end - action.wantedSec;
4191
+ const requiredStart = side === "lead" ? wordStart - action.wantedSec : wordEnd;
4192
+ const requiredEnd = side === "lead" ? wordStart : wordEnd + action.wantedSec;
4193
+ const phase = temporal?.requirements.find((p) =>
4194
+ temporal.owners.some((owner) => owner.id === p.id && owner.sceneIndex === piece.sceneIndex) &&
4195
+ p.startSec <= requiredStart + 1e-7 && p.endSec >= requiredEnd - 1e-7 && phasePassed(temporal, p.id));
4196
+ if (!phase) holds.push({ code: `action-${side}-unobserved`, id: `scene:${piece.sceneIndex}`, reason: "the required action handle has no complete exact-source temporal observation" });
4197
+ else resolvedPlanningFindings.push({ scene: piece.sceneIndex, code: `action-${side}-unproven`, phaseId: phase.id });
4198
+ }
4199
+ }
4200
+ return { ok: holds.length === 0, lines, beats, ending, holds, resolvedPlanningFindings };
4201
+ }
4202
+
4203
+ /**
4204
+ * Completes a prepared, already transformed cut. Async observer sees exactly
4205
+ * that file's bytes. No scene is re-cut under its receipt; the second pass
4206
+ * changes only pixels via ASS and STREAM-COPIES its already finished audio.
4207
+ */
4208
+ export async function completeFirstCutText(cut, { out, prepareReadoutVerifier, observeTemporalAction, checkTemporalRetention, renderer: suppliedRenderer } = {}) {
4209
+ if (!cut.textStage || !cut.sourceMap?.render || !cut.timeline?.mapped) throw new FirstCutError(1, "Text completion requires the prepared mapped pre-text artifact");
4210
+ const { dir, board, policy } = cut.textStage;
4211
+ if (!board || !Array.isArray(board.scenes)) throw new TextFinishRefusal([{ code: "approved-board-missing", id: "cut", reason: "the approved board is required to retain selected words, actions and text" }]);
4212
+ const material = textMaterial(cut, board, policy);
4213
+ let fulfillment = finishFulfillment(cut, board, policy);
4214
+ const needsRaster = material.captions.on || material.items.some((item) => !["physical-readout", "authentic-lettering"].includes(item.provenance)) ||
4215
+ material.selection.endCard || material.selection.offer;
4216
+ const renderer = suppliedRenderer ?? (needsRaster
4217
+ ? createTextRenderer({ dir, W: WIDTH, H: HEIGHT })
4218
+ : { libass: false, measureText: undefined });
4219
+ const sourceBytes = readFileSync(cut.out);
4220
+ const source = { id: `${cut.manifest.runId ?? "cut"}:pre-text`, sha256: createHash("sha256").update(sourceBytes).digest("hex") };
4221
+ const resolved = resolveTemporalRequirements(cut, board);
4222
+ let receipt = null;
4223
+ let retention = null;
4224
+ const wordOrPictureMissing = fulfillment.holds.some((h) => ["required-words-not-retained", "required-beat-not-retained"].includes(h.code));
4225
+ if (!wordOrPictureMissing && !resolved.holds.length && resolved.requirements.length && observeTemporalAction && checkTemporalRetention) {
4226
+ receipt = await observeTemporalAction({ source, sourceBytes, requirements: resolved.requirements, approvedContext: board });
4227
+ retention = checkTemporalRetention({
4228
+ receipt, source, requirements: resolved.requirements, approvedContext: board, spans: [{ in: 0, out: material.totalSec }],
4229
+ });
4230
+ }
4231
+ const temporal = { ...resolved, receipt, retention };
4232
+ fulfillment = finishFulfillment(cut, board, policy, temporal);
4233
+ const selectedItems = [
4234
+ ...material.items,
4235
+ ...(material.selection.endCard ? [{ ...material.selection.endCard, id: "end-card" }] : []),
4236
+ ...(material.selection.offer ? [{ ...material.selection.offer, id: "offer" }] : []),
4237
+ ];
4238
+ const observedItems = selectedItems.filter((item) => ["physical-readout", "authentic-lettering"].includes(item.provenance));
4239
+ const verifyObservation = fulfillment.ok && observedItems.length && prepareReadoutVerifier
4240
+ ? await prepareReadoutVerifier({
4241
+ source, sourceBytes, items: observedItems,
4242
+ heardWords: material.words.map((w) => ({ word: w.text, start: w.start, end: w.end, cueLineId: w.lineId ?? undefined })),
4243
+ })
4244
+ : undefined;
4245
+ const text = planText({
4246
+ ...material, libass: renderer.libass, measureText: renderer.measureText,
4247
+ source, verifyObservation, inheritedHolds: [...fulfillment.holds, ...material.pictureHolds],
4248
+ });
4249
+ text.skipped.push(...material.skippedPictures);
4250
+ const directives = text.directives;
4251
+ const clocked = [
4252
+ ...directives.captions.map((caption, i) => ({ id: `caption:${i}`, start: caption.s, end: caption.e })),
4253
+ ...[...directives.cards, directives.hook, directives.endCard].filter(Boolean).map((card) => ({ id: card.id, start: card.in, end: card.out })),
4254
+ ];
4255
+ for (const item of clocked) {
4256
+ const frames = textFrameWindow(item.start, item.end).frames;
4257
+ const minimum = selectedItems.find((selected) => selected.id === item.id)?.minReadableSec;
4258
+ if (frames < 1 || (Number.isFinite(minimum) && frames / FPS + 1e-9 < minimum)) {
4259
+ text.ok = false;
4260
+ text.holds.push({ code: "text-frame-window-invalid", id: item.id, reason: "the exact delivered frame interval cannot meet the authored text window/readability; no text clock is extended" });
4261
+ }
4262
+ }
4263
+ const destination = path.resolve(out ?? path.join(dir, "cut.mp4"));
4264
+ const reportPath = destination.replace(/\.[^.]+$/, "") + ".text.json";
4265
+ writeFileSync(reportPath, `${JSON.stringify({ source, text, fulfillment, temporal }, null, 2)}\n`);
4266
+ if (!text.ok) throw new TextFinishRefusal(text.holds);
4267
+ if (destination === path.resolve(cut.out)) throw new FirstCutError(1, "The text output must differ from its immutable observed pre-text source");
4268
+ const ass = ".final-text.ass";
4269
+ const assPath = path.join(dir, ass);
4270
+ const hasBurn = directives.captions.length || directives.cards.length || directives.hook || directives.endCard;
4271
+ let assSha256 = null;
4272
+ try {
4273
+ const args = ["-y", "-hide_banner", "-loglevel", "error", "-i", cut.out];
4274
+ if (hasBurn) {
4275
+ if (renderer.assertFont && !renderer.assertFont()) throw new TextFinishRefusal([{ code: "font-changed", id: "text", reason: "the resolved measured font changed before the final burn" }]);
4276
+ let assContent;
4277
+ try {
4278
+ assContent = measuredTextAss(directives, { W: WIDTH, H: HEIGHT, style: material.captions.cap?.style });
4279
+ } catch (error) {
4280
+ throw new TextFinishRefusal([{ code: "text-frame-window-invalid", id: "burn", reason: error.message }]);
4281
+ }
4282
+ assSha256 = createHash("sha256").update(assContent).digest("hex");
4283
+ writeFileSync(assPath, assContent);
4284
+ args.push("-vf", `subtitles=filename=${ass}`, "-c:v", "libx264", "-preset", "medium", "-crf", "20");
4285
+ } else args.push("-c:v", "copy");
4286
+ // Never resample/re-encode/remix sound or reset PTS under an observation.
4287
+ args.push("-map", "0:v:0", "-map", "0:a:0", "-c:a", "copy", "-movflags", "+faststart", destination);
4288
+ if (spawnSync("ffmpeg", args, { cwd: dir, stdio: "inherit" }).status !== 0) throw new FirstCutError(1, "The measured same-file ASS burn failed; no plain-cut fallback is delivered");
4289
+ } finally { rmSync(assPath, { force: true }); }
4290
+ // Check source immutability and the actual target's clocks after the ONLY
4291
+ // subsequent transform. The audio stream is copied, not AAC-encoded again.
4292
+ if (createHash("sha256").update(readFileSync(cut.out)).digest("hex") !== source.sha256) throw new FirstCutError(1, "The pre-text source changed while its observation was being used");
4293
+ const { findings, render, planningTiming } = renderFindings(cut.sourceMap, measureMedia(destination), policy.planningBudget);
4294
+ cut.sourceMap.findings.push(...findings);
4295
+ cut.sourceMap.render = render;
4296
+ if (planningTiming) cut.sourceMap.planningTiming = planningTiming;
4297
+ const rasters = [
4298
+ ...directives.captions.map((c, i) => ({ ...c, id: `caption:${i}`, kind: "caption", startSec: c.s, endSec: c.e, renderBox: material.captions.cap?.box })),
4299
+ ...[...directives.cards, directives.hook, directives.endCard].filter(Boolean).map((c) => ({ ...c, startSec: c.in, endSec: c.out })),
4300
+ ].map((entry) => {
4301
+ const { lines, ...measurement } = entry.measurement;
4302
+ return {
4303
+ id: entry.id, kind: entry.kind, startSec: entry.startSec, endSec: entry.endSec,
4304
+ renderBox: entry.renderBox, box: entry.box, fs: entry.fs,
4305
+ textSha256: createHash("sha256").update(JSON.stringify(entry.lines)).digest("hex"), measurement,
4306
+ raster: textFrameWindow(entry.startSec, entry.endSec),
4307
+ };
4308
+ });
4309
+ cut.sourceMap.text = {
4310
+ source, report: path.basename(reportPath), permissions: text.permissions, fulfillment,
4311
+ styleVersion: "literal-ass.v1", assSha256, rasters, readouts: text.readouts,
4312
+ };
4313
+ const planningResolved = (finding) => fulfillment.resolvedPlanningFindings.some((p) => p.scene === finding.scene && p.code === finding.code);
4314
+ cut.sourceMap.semanticPlanningFindings = cut.sourceMap.findings.filter(planningResolved);
4315
+ cut.sourceMap.findings = cut.sourceMap.findings.filter((finding) => !planningResolved(finding));
4316
+ cut.sourceMap.temporal = temporal;
4317
+ try {
4318
+ cut.sourceMap.final = { sha256: createHash("sha256").update(readFileSync(destination)).digest("hex") };
4319
+ } catch (error) {
4320
+ if (!planningTiming) throw error;
4321
+ delete cut.sourceMap.final;
4322
+ planningTiming.status = "unknown";
4323
+ planningTiming.decoded = null;
4324
+ cut.sourceMap.findings.push({ severity: "refuse", code: "planning-budget-clock-unmeasured", scene: null, detail: "the actual final bytes could not be hashed, so the final decoded timing is not byte-bound" });
4325
+ }
4326
+ if (planningTiming) planningTiming.finalSha256 = cut.sourceMap.final?.sha256 ?? null;
4327
+ const sidecars = { ...sidecarPaths(destination), sourceMap: sourceMapPath(destination), text: reportPath };
4328
+ writeFileSync(sidecars.sourceMap, `${JSON.stringify(cut.sourceMap, null, 2)}\n`);
4329
+ refuseUnholdable(cut.sourceMap);
4330
+ writeFileSync(sidecars.words, `${JSON.stringify(material.words, null, 2)}\n`);
4331
+ writeFileSync(sidecars.scenes, `${JSON.stringify(sceneTimes(cut.timeline), null, 2)}\n`);
4332
+ writeFileSync(sidecars.srt, toSrt(material.words));
4333
+ const { textStage, ...finished } = cut;
4334
+ const paths = finishPaths(destination);
4335
+ if (cut.musicOnlyMaster) {
4336
+ // Preserve the selected alternate audio, but pair it with the SAME final
4337
+ // text pixels, rather than exporting stale pre-text pictures.
4338
+ const args = [
4339
+ "-y", "-hide_banner", "-loglevel", "error", "-i", destination, "-i", cut.musicOnlyMaster,
4340
+ "-map", "0:v:0", "-map", "1:a:0", "-c:v", "copy", "-c:a", "copy", "-movflags", "+faststart", paths.master,
4341
+ ];
4342
+ if (spawnSync("ffmpeg", args, { stdio: "inherit" }).status !== 0) throw new FirstCutError(1, "The selected music-only master's final picture copy failed");
4343
+ finished.musicOnlyMaster = paths.master;
4344
+ if (finished.sound) finished.sound = { ...finished.sound, master: path.basename(paths.master) };
4345
+ }
4346
+ if (finished.pace) writeFileSync(paths.pace, `${JSON.stringify(finished.pace, null, 2)}\n`);
4347
+ if (finished.sound) writeFileSync(paths.sound, `${JSON.stringify(finished.sound, null, 2)}\n`);
4348
+ return { ...finished, out: destination, durationSec: cut.sourceMap.frames / FPS, sourceMap: cut.sourceMap, sidecars, text };
4349
+ }
4350
+
2857
4351
  function parseArgs(argv) {
2858
4352
  const opts = { dir: undefined, out: undefined, skip: new Set(), music: true, stillFill: false };
2859
4353
  for (let i = 0; i < argv.length; i++) {
@@ -2876,7 +4370,7 @@ function parseArgs(argv) {
2876
4370
  * sidecars, and throws FirstCutError where the CLI would exit. The CLI's report
2877
4371
  * is printed by main() from what this returns.
2878
4372
  */
2879
- export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn = true, stillFill = false }) {
4373
+ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn = true, stillFill = false, prepareText = false }) {
2880
4374
  for (const bin of ["ffmpeg", "ffprobe"]) {
2881
4375
  if (spawnSync(bin, ["-version"]).status !== 0) {
2882
4376
  throw new FirstCutError(2, `${bin} is not installed. Install ffmpeg (brew install ffmpeg / apt install ffmpeg).`);
@@ -2928,6 +4422,7 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
2928
4422
  if (manifest.wholeVoice === true && !wholeVoice) {
2929
4423
  console.error("Warning: the manifest asks for the voice laid whole, but the narration track or its narration.json is missing, so each scene's voice is laid on its own.");
2930
4424
  }
4425
+ const readClocks = manifest.sourceMap === true ? mediaReader(here, exists) : null;
2931
4426
  const timeline = buildTimeline({
2932
4427
  manifest,
2933
4428
  storyboard,
@@ -2940,6 +4435,7 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
2940
4435
  return Array.isArray(rows) && rows.length > 0 ? rows : null;
2941
4436
  },
2942
4437
  readLevels: (file) => clipLevels(here(file)),
4438
+ ...(readClocks ? { measure: readClocks } : {}),
2943
4439
  ...(finish ? { finish } : {}),
2944
4440
  ...(wholeVoice ? { wholeVoice } : {}),
2945
4441
  ...(sourceAd ? { sourceAd } : {}),
@@ -2954,12 +4450,40 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
2954
4450
  const pictureSec = timeline.spine.reduce((sum, seg) => sum + seg.seconds, 0);
2955
4451
  // A voice laid whole is a song: it is never sped up.
2956
4452
  const speed = finish?.cutPace && !timeline.wholeVoice ? speedFor(pictureSec, finish.targetSeconds) : 1;
2957
- if (finish?.brollMinSec) {
4453
+ if (timeline.sourceMap) {
4454
+ // The exact bytes every measured clock was read from, for whoever binds an approval to them.
4455
+ timeline.sourceMap.sources = readClocks.files().filter(exists).map((file) => {
4456
+ const bytes = readFileSync(here(file));
4457
+ return { file, bytes: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex") };
4458
+ });
4459
+ const shaOf = new Map(timeline.sourceMap.sources.map((s) => [s.file, s.sha256]));
4460
+ for (const s of [...timeline.sourceMap.audibleSources, ...timeline.sourceMap.mutedPictures]) s.sha256 = shaOf.get(s.file) ?? null;
4461
+ if (manifest.wholeVoice === true && !wholeVoice) {
4462
+ timeline.sourceMap.findings.push({
4463
+ severity: "refuse", code: "whole-voice-missing", scene: null,
4464
+ detail: "the manifest lays a song whole, but its narration track or narration.json is not in the pull",
4465
+ });
4466
+ }
4467
+ if (speed !== 1) {
4468
+ timeline.sourceMap.findings.push({
4469
+ severity: "refuse", code: "cut-speedup", scene: null,
4470
+ detail: `the kind's cutPace would speed the whole cut ${speed}x`,
4471
+ });
4472
+ }
4473
+ refuseUnholdable(timeline.sourceMap, prepareText ? new Set((storyboard?.scenes ?? []).filter((s) => s.actionPhases?.length).map((s) => s.sceneIndex)) : new Set());
4474
+ }
4475
+ // A mapped cut is laid sample-exact on its measured map, so these finishes, which retime or refilter it, stay off.
4476
+ if (timeline.mapped) {
4477
+ for (const key of ["brollMinSec", "speedUpSlowBroll", "cleanVoice"]) {
4478
+ if (finish?.[key]) notes.push(`${key} is not applied to a cut laid on its measured map`);
4479
+ }
4480
+ }
4481
+ if (finish?.brollMinSec && !timeline.mapped) {
2958
4482
  const held = holdBroll(timeline, finish.brollMinSec, speed, (file) => probe(file).seconds);
2959
4483
  timeline.left.push(...held);
2960
4484
  notes.push(...held);
2961
4485
  }
2962
- if (finish?.speedUpSlowBroll && timeline.cutaways.length > 0) {
4486
+ if (finish?.speedUpSlowBroll && !timeline.mapped && timeline.cutaways.length > 0) {
2963
4487
  const motionOf = (file, from, seconds) => {
2964
4488
  const res = spawnSync("ffmpeg", motionArgs(here(file), from, seconds), { encoding: "utf8", maxBuffer: 1 << 28 });
2965
4489
  if (res.status !== 0) return null;
@@ -2974,7 +4498,7 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
2974
4498
  const copied = sourceAd && finish?.cards ? sourceAdEdit(storyboard, sourceAd, timeline.sourceGroups ?? []) : null;
2975
4499
  if (copied) notes.push(...copied.notes);
2976
4500
  let pictures = [];
2977
- if (sourceAd && finish?.cards && sourceAd.pictures.length > 0) {
4501
+ if (!timeline.mapped && sourceAd && finish?.cards && sourceAd.pictures.length > 0) {
2978
4502
  if (exists(manifest.productSheet)) {
2979
4503
  pictures = sourceAd.pictures.map((p) => ({
2980
4504
  file: manifest.productSheet, box: p.box,
@@ -2985,7 +4509,7 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
2985
4509
  notes.push(`the pull has no product sheet picture, so the source's ${sourceAd.pictures.length} product card(s) were not drawn`);
2986
4510
  }
2987
4511
  }
2988
- if (finish && (finish.captions || finish.cards)) {
4512
+ if (finish && (finish.captions || finish.cards) && !(prepareText && timeline.mapped)) {
2989
4513
  if (hasFilter("subtitles")) {
2990
4514
  ass = "edit.ass";
2991
4515
  const cap = sourceAd?.captions ?? null;
@@ -3010,7 +4534,7 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
3010
4534
  }
3011
4535
  // cleanVoice, where this ffmpeg has the filters. A voice laid whole is a song, kept as it is.
3012
4536
  let clean = null;
3013
- if (finish?.cleanVoice) {
4537
+ if (finish?.cleanVoice && !timeline.mapped) {
3014
4538
  const missing = timeline.wholeVoice ? [] : missingFilters(CLEAN_FILTERS);
3015
4539
  if (timeline.wholeVoice) notes.push("the voice is a song laid whole, so it was kept as it is, not cleaned");
3016
4540
  else if (missing.length > 0) notes.push(`this ffmpeg has no ${missing.join(", ")} filter, so the voice was not cleaned`);
@@ -3047,6 +4571,51 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
3047
4571
  notes: [...missing.map((f) => `${f} is not in the folder, so it is left out`), ...plan.notes],
3048
4572
  };
3049
4573
  }
4574
+ if (timeline.sourceMap) {
4575
+ const record = (file, metadata) => {
4576
+ const bytes = readFileSync(here(file));
4577
+ const sha256 = createHash("sha256").update(bytes).digest("hex");
4578
+ if (metadata?.kind === "library" && metadata.sha256 !== sha256) {
4579
+ throw new SourceMapRefusal("A licensed sound changed before the mix; unchecked bytes are not delivered", [
4580
+ { severity: "refuse", code: "sound-source-hash", scene: null, detail: file },
4581
+ ]);
4582
+ }
4583
+ const audio = clockOf(readClocks(file)).audio;
4584
+ const event = metadata?.kind === "library" ? metadata.eventWindow : null;
4585
+ if (!audio || (event && Math.ceil(event.toSec * EDIT_SAMPLE_RATE) > audio.edit.samples - audio.edit.priming)) {
4586
+ throw new SourceMapRefusal("A sound lacks decoded coverage of its registered event; declared duration is not EOF evidence", [
4587
+ { severity: "refuse", code: "sound-event-eof", scene: null, detail: file },
4588
+ ]);
4589
+ }
4590
+ if (!timeline.sourceMap.sources.some((s) => s.file === file)) timeline.sourceMap.sources.push({ file, bytes: bytes.length, sha256 });
4591
+ return { sourceSha256: sha256, sourcePrimingSamples: audio.edit.priming, sourceSamples: audio.edit.samples, sourceOriginSec: audio.originSec };
4592
+ };
4593
+ if (mixSound) {
4594
+ mixSound.effects = mixSound.effects.map((e) => {
4595
+ const decoded = record(e.file, e.source);
4596
+ const event = e.source?.kind === "library" ? e.source.eventWindow : null;
4597
+ if (event && e.atSec + event.toSec > timeline.sourceMap.frames / FPS + 1 / EDIT_SAMPLE_RATE) {
4598
+ throw new SourceMapRefusal("A required registered sound event would be truncated by the final cut", [
4599
+ { severity: "refuse", code: "sound-event-cutoff", scene: e.fromScene ?? null, detail: e.file },
4600
+ ]);
4601
+ }
4602
+ return {
4603
+ ...e, ...decoded, placementOffsetSec: e.atSec,
4604
+ editStartSample: Math.max(0, Math.round(e.atSec * EDIT_SAMPLE_RATE)),
4605
+ sourceStartSample: decoded.sourcePrimingSamples + Math.max(0, -Math.round(e.atSec * EDIT_SAMPLE_RATE)),
4606
+ };
4607
+ });
4608
+ mixSound.beds = mixSound.beds.map((b) => ({
4609
+ ...b, ...record(b.file, b.source), loop: true,
4610
+ editStartSample: Math.round(b.startSec * EDIT_SAMPLE_RATE), samples: Math.round(b.seconds * EDIT_SAMPLE_RATE),
4611
+ }));
4612
+ }
4613
+ if (music) {
4614
+ const decoded = record(music);
4615
+ timeline.musicPrimingSamples = decoded.sourcePrimingSamples;
4616
+ timeline.musicSource = { file: music, ...decoded, loop: true };
4617
+ }
4618
+ }
3050
4619
  const ffmpegArgs = buildFfmpegArgs(timeline, {
3051
4620
  resolve: at,
3052
4621
  music: music ? at(music) : null,
@@ -3087,7 +4656,7 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
3087
4656
  const scenes = sceneTimes(timeline).map((p) =>
3088
4657
  speed === 1 ? p : { ...p, startSec: faster(p.startSec), seconds: faster(p.seconds) },
3089
4658
  );
3090
- const sidecars = sidecarPaths(out);
4659
+ const sidecars = { ...sidecarPaths(out), ...(timeline.sourceMap ? { sourceMap: sourceMapPath(out) } : {}) };
3091
4660
  if (rows.length > 0) {
3092
4661
  writeFileSync(sidecars.words, `${JSON.stringify(rows, null, 2)}\n`);
3093
4662
  writeFileSync(sidecars.srt, toSrt(rows));
@@ -3101,6 +4670,19 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
3101
4670
  "-v", "error", "-show_entries", "format=duration", "-of", "default=nw=1:nk=1", out,
3102
4671
  ]).toString().trim();
3103
4672
  const durationSec = Number(duration);
4673
+ if (timeline.sourceMap) {
4674
+ // The cut as it decodes after every pass, never its container's duration.
4675
+ const { findings, render } = renderFindings(timeline.sourceMap, measureMedia(out));
4676
+ timeline.sourceMap.render = render;
4677
+ timeline.sourceMap.findings.push(...findings);
4678
+ timeline.sourceMap.mix = {
4679
+ fallback: mixSound?.beds?.length || timeline.wholeVoice ? "none" : "brown-noise",
4680
+ effects: mixSound?.effects ?? [], beds: mixSound?.beds ?? [],
4681
+ ...(timeline.musicSource ? { music: timeline.musicSource } : {}),
4682
+ };
4683
+ writeFileSync(sidecars.sourceMap, `${JSON.stringify(timeline.sourceMap, null, 2)}\n`);
4684
+ refuseUnholdable(timeline.sourceMap, prepareText ? new Set((storyboard?.scenes ?? []).filter((s) => s.actionPhases?.length).map((s) => s.sceneIndex)) : new Set());
4685
+ }
3104
4686
 
3105
4687
  // The sound record beside the cut, and the music-only master the kind asked for.
3106
4688
  let soundRecord;
@@ -3126,7 +4708,13 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
3126
4708
  };
3127
4709
  writeFileSync(paths.sound, `${JSON.stringify(soundRecord, null, 2)}\n`);
3128
4710
  }
3129
- const withSound = (cut) => (soundRecord ? { ...cut, sound: soundRecord, ...(soundRecord.master ? { musicOnlyMaster: paths.master } : {}) } : cut);
4711
+ const withSound = (cut0) => {
4712
+ const cut = {
4713
+ ...cut0, ...(timeline.sourceMap ? { sourceMap: timeline.sourceMap } : {}),
4714
+ ...(prepareText && timeline.mapped ? { textStage: { dir: path.resolve(dir), board: storyboard, policy: { ...manifest.textFinish, outputPermission: manifest.outputPermission, planningBudget: manifest.planningBudget } } } : {}),
4715
+ };
4716
+ return soundRecord ? { ...cut, sound: soundRecord, ...(soundRecord.master ? { musicOnlyMaster: paths.master } : {}) } : cut;
4717
+ };
3130
4718
  if (!finish) return withSound({ out, durationSec, manifest, timeline, music, rows, sidecars });
3131
4719
 
3132
4720
  const checks = finish.cutChecks
@@ -3137,7 +4725,7 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
3137
4725
  const pace = {
3138
4726
  ...paceReport({
3139
4727
  ourShots: scenes.map((p) => ({ start: p.startSec, end: roundMs(p.startSec + p.seconds) })),
3140
- ...(sourceAd ? { srcShots: sourceAd.shots, srcSec: sourceAd.seconds } : {}),
4728
+ ...(sourceAd ? { srcShots: sourceAdPaceShots(sourceAd), srcSec: sourceAd.seconds } : {}),
3141
4729
  ourSec: durationSec,
3142
4730
  ourWords: rows.length,
3143
4731
  ourSilences: voicePauses(rows).filter((x) => x.s > 0.3 && x.e < durationSec - 0.3),