@aicopycoders/exodus 2026.11.200-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;
@@ -155,11 +158,19 @@ export const FINISH_LUFS = -14;
155
158
  export const FINISH_TRUE_PEAK = -1.5;
156
159
  export const FINISH_LRA = 11;
157
160
  export const TRUE_PEAK_MAX_DB = -1;
161
+ /**
162
+ * limitPeaks: after the loudness pass, the sound oversampled 4x through a
163
+ * limiter at 0.8 (about -1.9 dB), so a peak between two samples is caught too.
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).
166
+ */
167
+ export const PEAK_LIMITER = "aresample=192000,aformat=channel_layouts=stereo,alimiter=limit=0.8:level=false:attack=2:release=60";
158
168
 
159
169
  /**
160
170
  * The manifest's finishing settings, or null when none is on. The worker
161
171
  * writes them from the run's frozen kind settings, so a redo of the run cuts
162
- * with the same ones.
172
+ * with the same ones. A setting added after the first four is present only
173
+ * when it is on and can act (captionsByLine needs captions).
163
174
  */
164
175
  export function finishingOf(manifest) {
165
176
  const f = manifest?.finishing;
@@ -170,9 +181,17 @@ export function finishingOf(manifest) {
170
181
  cards: f.cards === true,
171
182
  finishLoudness: f.finishLoudness === true,
172
183
  };
173
- if (!Object.values(on).some(Boolean)) return null;
184
+ const added = {
185
+ ...(on.captions && f.captionsByLine === true ? { captionsByLine: true } : {}),
186
+ ...(f.cleanVoice === true ? { cleanVoice: true } : {}),
187
+ ...(on.finishLoudness && f.limitPeaks === true ? { limitPeaks: true } : {}),
188
+ ...(Number.isFinite(f.brollMinSec) && f.brollMinSec > 0 ? { brollMinSec: f.brollMinSec } : {}),
189
+ ...(f.speedUpSlowBroll === true ? { speedUpSlowBroll: true } : {}),
190
+ ...(f.cutChecks === true ? { cutChecks: true } : {}),
191
+ };
192
+ if (!Object.values(on).some(Boolean) && Object.keys(added).length === 0) return null;
174
193
  const target = f.targetSeconds;
175
- return on.cutPace && Number.isFinite(target) && target > 0 ? { ...on, targetSeconds: target } : on;
194
+ return on.cutPace && Number.isFinite(target) && target > 0 ? { ...on, targetSeconds: target, ...added } : { ...on, ...added };
176
195
  }
177
196
 
178
197
  /**
@@ -198,6 +217,18 @@ const BED_FADE_SEC = 0.15;
198
217
  export const MUSIC_UNDER_DB = 16.8;
199
218
  const MUSIC_FALLBACK_DB = -20;
200
219
  export const DUCK = { threshold: 0.05, ratio: 2.5, attack: 20, release: 350 };
220
+ /**
221
+ * cleanVoice: the voice's chain (rumble cut, light noise reduction, de-essing,
222
+ * gentle compression), and what happens to the room, sounds and music under
223
+ * it: down UNDER_VOICE.db, trimmed under `highpass` and over `lowpass` Hz, and
224
+ * ducked by a compressor keyed on the cleaned voice. It is the one duck: the
225
+ * music's own (DUCK) is left out. A reaction's tail is a voice, so it is
226
+ * neither cleaned nor ducked.
227
+ */
228
+ export const VOICE_CLEAN =
229
+ "highpass=f=90,afftdn=nr=8:nf=-38,deesser=i=0.35,acompressor=threshold=0.125:ratio=2.5:attack=8:release=150:makeup=1.5";
230
+ export const UNDER_VOICE = { db: -6, highpass: 60, lowpass: 9000, duck: { threshold: 0.03, ratio: 5, attack: 15, release: 300 } };
231
+ const CLEAN_FILTERS = ["highpass", "lowpass", "afftdn", "deesser", "acompressor", "sidechaincompress"];
201
232
  const SEGMENT_LUFS = -16;
202
233
  /** A voice at or under this is no level to set a sound against. */
203
234
  const VOICE_FLOOR_LUFS = -60;
@@ -255,7 +286,13 @@ export function soundPlan(sound, timeline, storyboard, { levelled, measure }) {
255
286
  const k = spine.findIndex((seg) => cue.startSec < seg.startSec + seg.seconds);
256
287
  const under = Number.isFinite(e.underDb) ? e.underDb : SOUND_UNDER_DB;
257
288
  effects.push({
258
- 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)),
259
296
  gainDb: gainUnder(segLufs[k] ?? voiceLufs, under, measure(e.file), SOUND_FALLBACK_DB),
260
297
  });
261
298
  }
@@ -269,14 +306,17 @@ export function soundPlan(sound, timeline, storyboard, { levelled, measure }) {
269
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"}`);
270
307
  } else {
271
308
  const under = Number.isFinite(b.underDb) ? b.underDb : BED_UNDER_DB;
272
- 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) });
273
310
  }
274
311
  }
275
312
  heard.sort((a, b) => a.from - b.from);
276
313
  const beds = heard.map((b, k) => {
277
- const startSec = k === 0 ? 0 : roundMs(b.from);
314
+ const startSec = k === 0 ? 0 : timeline.mapped ? b.from : roundMs(b.from);
278
315
  const end = k + 1 < heard.length ? heard[k + 1].from : pictureSec;
279
- 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
+ };
280
320
  });
281
321
  return { voiceLufs, effects, beds, notes };
282
322
  }
@@ -815,19 +855,24 @@ function clipLevels(file, filter = null) {
815
855
  * trims, reaction splits, cue times, captions) works in cut time. The renderer
816
856
  * removes seg.cuts from the picture and the sound before anything else.
817
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
+
818
861
  function tightenSentenceGaps(spine, reactionCues, scriptLines, readLevels, lineGap = null) {
819
862
  for (const seg of spine) {
820
- 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;
821
864
  const lines = seg.lineIds.map((id) => ({
822
865
  text: scriptLines.get(id)?.text,
823
866
  asksPause: asksPause(scriptLines.get(id)),
824
867
  cuesBeat: reactionCues.has(id),
825
868
  }));
826
- 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;
827
872
  if (cuts.length === 0) continue;
828
873
  const removedBefore = (t) => cuts.reduce((sum, c) => sum + (c.e <= t ? c.e - c.s : 0), 0);
829
874
  const removed = removedBefore(Infinity);
830
- seg.cuts = cuts.map(({ s, e }) => ({ s, e }));
875
+ seg.cuts = cuts.map(({ s, e, slots }) => (slots ? { s, e, slots } : { s, e }));
831
876
  // cutPace: where the take is split, in its time once the gaps are out.
832
877
  const splits = cuts.filter((c) => c.atLine !== undefined).map((c) => ({ at: c.s - removedBefore(c.s), line: c.atLine }));
833
878
  if (splits.length > 0) seg.splits = splits;
@@ -871,10 +916,30 @@ export function narratedScene(scene, storyboard) {
871
916
  return scriptBound && hasText(scene?.voText) && !spoken;
872
917
  }
873
918
 
874
- 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) {
875
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
+ }
876
937
  for (const scene of storyboard?.scenes ?? []) {
877
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);
878
943
  const speakers = (Array.isArray(scene.dialogue) ? scene.dialogue : [])
879
944
  .filter((turn) => hasText(turn?.line) || hasText(turn?.text))
880
945
  .map((turn) => (hasText(turn.speaker) ? turn.speaker.trim() : null));
@@ -882,14 +947,18 @@ export function scenePlans(storyboard) {
882
947
  firstSpeaker: speakers[0] ?? null,
883
948
  lastSpeaker: speakers.at(-1) ?? null,
884
949
  baseShotId: hasText(scene.baseShotId) ? scene.baseShotId.trim() : null,
885
- cutaway: CUTAWAY_KINDS.has(scene.kind),
950
+ cutaway: CUTAWAY_KINDS.has(scene.kind) && sequential.length === 0,
886
951
  narrated: narratedScene(scene, storyboard),
887
952
  lineIds: Array.isArray(scene.lineIds) ? scene.lineIds : [],
888
953
  cueLineId: typeof scene.cueLineId === "string" ? scene.cueLineId : null,
889
954
  cutawayType: typeof scene.cutawayType === "string" ? scene.cutawayType : null,
890
955
  durationSec: typeof scene.durationSec === "number" ? scene.durationSec : null,
891
- 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
+ ),
892
960
  actionLeadSec: typeof scene.actionLeadSec === "number" && scene.actionLeadSec > 0 ? scene.actionLeadSec : 0,
961
+ ...(planningBudget ? { editSeconds: reservation || null, overlay } : {}),
893
962
  sourceShot: Number.isInteger(scene.sourceShot) && scene.sourceShot > 0 ? scene.sourceShot : null,
894
963
  broll:
895
964
  hasText(scene.broll?.covers) && Number.isFinite(scene.broll?.plannedSec) && scene.broll.plannedSec > 0
@@ -1075,7 +1144,7 @@ function trimJoins(spine, reactionCues, scriptLines, gapMax = null) {
1075
1144
  ? JOIN_LEAD_NEW_SPEAKER_SEC
1076
1145
  : Math.min(JOIN_LEAD_NEW_SPEAKER_SEC, roundMs(gapMax - JOIN_TAIL_SEC));
1077
1146
  spine.forEach((seg, k) => {
1078
- 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;
1079
1148
  const prev = spine[k - 1];
1080
1149
  const sameSpeaker = Boolean(prev?.lastSpeaker) && prev.lastSpeaker === seg.firstSpeaker;
1081
1150
  const lead = sameSpeaker || !prev ? JOIN_LEAD_SAME_SPEAKER_SEC : newSpeakerLead;
@@ -1084,7 +1153,7 @@ function trimJoins(spine, reactionCues, scriptLines, gapMax = null) {
1084
1153
  const before = span ? seg.words.slice(0, span.first) : [];
1085
1154
  const after = span ? seg.words.slice(span.last + 1) : [];
1086
1155
  const firstWord = Math.min(...line.map((w) => w.s));
1087
- const lastWord = Math.max(...line.map((w) => w.e));
1156
+ const lastWord = Math.max(...line.map((w) => seg.map ? wordEnd(w) : w.e));
1088
1157
  let inSec = Math.max(0, floorFrame(firstWord - Math.max(lead, seg.actionLeadSec ?? 0)));
1089
1158
  if (before.length > 0) {
1090
1159
  const clear = ceilFrame(Math.max(...before.map((w) => w.e)) + EXTRA_CLEARANCE_SEC);
@@ -1098,6 +1167,11 @@ function trimJoins(spine, reactionCues, scriptLines, gapMax = null) {
1098
1167
  outSec = Math.min(outSec, Math.max(clear, ceilFrame(lastWord)));
1099
1168
  }
1100
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
+ }
1101
1175
  if (outSec <= inSec) return;
1102
1176
  const how = [];
1103
1177
  if (inSec > 0) how.push(`lead-in trimmed ${inSec.toFixed(2)}s`);
@@ -1119,9 +1193,9 @@ function trimJoins(spine, reactionCues, scriptLines, gapMax = null) {
1119
1193
  * the end of the voice file stands in for the last word, its own trailing
1120
1194
  * silence counted as part of the air.
1121
1195
  */
1122
- function narrationEnd(voiceSeconds, voiceWords, endsAd) {
1196
+ function narrationEnd(voiceSeconds, voiceWords, endsAd, measured = false) {
1123
1197
  return {
1124
- 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,
1125
1199
  airSec: endsAd ? END_AIR_SEC : NARRATION_JOIN_AIR_SEC,
1126
1200
  };
1127
1201
  }
@@ -1143,7 +1217,10 @@ function placeReaction(spine, counts, reaction) {
1143
1217
  const cut = Math.min(seg.seconds, ceilFrame(cueEnd));
1144
1218
  const beat = {
1145
1219
  sceneIndex: reaction.sceneIndex, source: reaction.source, file: reaction.file,
1146
- 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 } : {}),
1147
1224
  seconds: Math.min(reaction.seconds, REACTION_MAX_SEC), holdSec: 0,
1148
1225
  audio: reaction.hasAudio ? "clip" : "silence", voice: null, words: null, lineIds: [],
1149
1226
  reaction: { cueLineId: reaction.cueLineId, cueSceneIndex: seg.sceneIndex },
@@ -1271,6 +1348,22 @@ const PUNCH_IN_RUNS = new Map([
1271
1348
  sameSpeaker(prev, seg) && Boolean(seg.baseShotId) && seg.baseShotId === prev.baseShotId],
1272
1349
  ]);
1273
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
+
1274
1367
  /**
1275
1368
  * #3365: the scenes the cut cannot be made without, by number. A scene the
1276
1369
  * storyboard plans needs a clip unless --skip names it, even one the pull has
@@ -1283,6 +1376,10 @@ export function scenesWithNoClip({ manifest, storyboard, skip, exists = Boolean
1283
1376
  const clipped = new Set(
1284
1377
  (manifest?.scenes ?? []).filter((scene) => exists(scene.clip)).map((scene) => scene.sceneIndex),
1285
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
+ }
1286
1383
  return [...new Set(planned.length > 0 ? planned : listed)]
1287
1384
  .filter((n) => !skip.has(n) && !clipped.has(n))
1288
1385
  .sort((a, b) => a - b);
@@ -1317,12 +1414,21 @@ const roundFrame = (t) => Math.round(t * FPS) / FPS;
1317
1414
  * word, so every later line still lands on its words; one with no room left
1318
1415
  * is dropped. Scenes before the first stretch play first and the voice starts
1319
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.
1320
1424
  */
1321
1425
  export function fitWholeVoice(spine, whole) {
1322
1426
  const on = spine.flatMap((seg, k) => (whole.starts.has(seg.sceneIndex) ? [k] : []));
1323
1427
  if (on.length === 0) return null;
1324
1428
  const startSec = spine.slice(0, on[0]).reduce((t, seg) => t + seg.seconds, 0);
1325
1429
  const gone = new Set();
1430
+ const intervals = [];
1431
+ const problems = [];
1326
1432
  on.forEach((k, j) => {
1327
1433
  const seg = spine[k];
1328
1434
  const next = on[j + 1];
@@ -1332,6 +1438,7 @@ export function fitWholeVoice(spine, whole) {
1332
1438
  let room = Math.max(0, to - from - spoken);
1333
1439
  let given = 0;
1334
1440
  for (const b of next === undefined ? [] : spine.slice(k + 1, next)) {
1441
+ if (whole.measured) b.fixedLength = true;
1335
1442
  const seconds = Math.min(b.seconds, floorFrame(room));
1336
1443
  if (seconds < 1 / FPS) {
1337
1444
  gone.add(b);
@@ -1347,12 +1454,22 @@ export function fitWholeVoice(spine, whole) {
1347
1454
  seg.holdSec = holdFor(seg);
1348
1455
  seg.wholeVoice = true;
1349
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
+ }
1350
1467
  });
1351
1468
  const dropped = spine
1352
1469
  .filter((seg) => gone.has(seg))
1353
1470
  .map((seg) => ({ n: seg.sceneIndex, reason: `scene ${seg.sceneIndex}: no room left between two lines of the voice` }));
1354
1471
  for (let k = spine.length - 1; k >= 0; k--) if (gone.has(spine[k])) spine.splice(k, 1);
1355
- return { startSec, dropped };
1472
+ return { startSec, dropped, ...(whole.measured ? { intervals, problems } : {}) };
1356
1473
  }
1357
1474
 
1358
1475
  /**
@@ -1408,11 +1525,684 @@ export function mapSourceTime(groups, t) {
1408
1525
  return Math.min(g.cut[1], Math.max(g.cut[0], g.cut[0] + (t - g.src[0]) * k));
1409
1526
  }
1410
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
+
1411
2196
  export function buildTimeline({
1412
2197
  manifest, storyboard, skip, probe, exists, readWords, readLevels = () => null, stillFill = false, finish = null,
1413
- wholeVoice = null, sourceAd = null,
2198
+ wholeVoice = null, sourceAd = null, measure = null,
1414
2199
  }) {
1415
- 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);
1416
2206
  const counts = lineWordCounts(storyboard);
1417
2207
  const spine = [];
1418
2208
  const cutaways = [];
@@ -1435,16 +2225,38 @@ export function buildTimeline({
1435
2225
  continue;
1436
2226
  }
1437
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
+ }
1438
2247
 
1439
2248
  if (plan.cutaway) {
1440
2249
  const cue = {
1441
- 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 } : {}),
1442
2252
  };
1443
2253
  if (exists(scene.clip)) {
1444
2254
  const clip = probe(scene.clip);
2255
+ const m = measure ? clockOf(measure(scene.clip)) : null;
1445
2256
  waiting.push({
1446
2257
  sceneIndex: n, source: "clip", file: scene.clip,
1447
- 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 } : {}),
1448
2260
  });
1449
2261
  } else if (stillFill && exists(scene.keyframe)) {
1450
2262
  filled.add(n);
@@ -1461,23 +2273,33 @@ export function buildTimeline({
1461
2273
  const narrated = plan.narrated || scene.wordsFrom === "voice";
1462
2274
  const voice = exists(scene.voice) ? scene.voice : null;
1463
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
+ }
1464
2281
 
1465
2282
  if (exists(scene.clip)) {
1466
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;
1467
2287
  const base = {
1468
- 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 } : {}) } : {}),
1469
2290
  lineIds: plan.lineIds, firstSpeaker: plan.firstSpeaker, lastSpeaker: plan.lastSpeaker,
1470
2291
  baseShotId: plan.baseShotId ?? null, actionTailSec: plan.actionTailSec ?? 0,
1471
2292
  actionLeadSec: plan.actionLeadSec ?? 0,
1472
2293
  };
1473
2294
  if (voice && (narrated || !clip.hasAudio)) {
1474
- 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;
1475
2297
  const words = readWords(scene.words);
1476
2298
  // A clip's own word times describe the clip, not the voice that replaces its audio.
1477
2299
  const voiceWords = scene.wordsFrom === "voice" ? words : null;
1478
2300
  const fitted = (endsAd) => {
1479
2301
  const fit = fitNarration({
1480
- clipSeconds: clip.seconds, ...narrationEnd(voiceSeconds, voiceWords, endsAd),
2302
+ clipSeconds: base.clipSeconds, ...narrationEnd(voiceSeconds, voiceWords, endsAd, Boolean(m)),
1481
2303
  actionTailSec: plan.actionTailSec ?? 0,
1482
2304
  });
1483
2305
  const how = [];
@@ -1488,23 +2310,29 @@ export function buildTimeline({
1488
2310
  note: `${flag}, ${voice} replaces the clip's audio${how.length ? ` (${how.join(", ")})` : ""}`,
1489
2311
  };
1490
2312
  };
1491
- 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
+ };
1492
2317
  spine.push(seg);
1493
2318
  refits.set(seg, fitted);
1494
2319
  } else if (narrated) {
1495
2320
  spine.push({
1496
- ...base, audio: "silence", voice: null, seconds: clip.seconds, holdSec: 0,
2321
+ ...base, audio: "silence", voice: null, seconds: base.clipSeconds, holdSec: 0,
1497
2322
  words: null,
1498
2323
  note: `${flag}, narrated scene without its voice track: the clip's own audio is muted`,
1499
2324
  });
1500
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;
1501
2328
  spine.push({
1502
- ...base, audio: "clip", voice: null, seconds: clip.seconds, holdSec: 0,
2329
+ ...base, clipSeconds: ownSec,
2330
+ audio: "clip", voice: null, seconds: ownSec, holdSec: 0,
1503
2331
  words: readWords(scene.words), note: `${flag}, its own dialogue`,
1504
2332
  });
1505
2333
  } else {
1506
2334
  spine.push({
1507
- ...base, audio: "silence", voice: null, seconds: clip.seconds, holdSec: 0,
2335
+ ...base, audio: "silence", voice: null, seconds: base.clipSeconds, holdSec: 0,
1508
2336
  words: null, note: `${flag}, silent clip`,
1509
2337
  });
1510
2338
  }
@@ -1551,7 +2379,13 @@ export function buildTimeline({
1551
2379
  })));
1552
2380
  }
1553
2381
 
1554
- 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;
1555
2389
  if (whole) dropped.push(...whole.dropped);
1556
2390
 
1557
2391
  const sameShot = PUNCH_IN_RUNS.get(manifest?.shots?.pacing);
@@ -1600,15 +2434,41 @@ export function buildTimeline({
1600
2434
  const e = sourceAd?.shots.find((x) => x.n === shotOf(n));
1601
2435
  return e ? e.t1 - e.t0 : null;
1602
2436
  };
1603
- if (sourceAd) {
2437
+ if (sourceAd && !measure) {
1604
2438
  for (const seg of spine) {
1605
- 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;
1606
2440
  if (len === null) continue;
1607
2441
  seg.seconds = ceilFrame(len);
1608
2442
  seg.holdSec = holdFor(seg);
1609
2443
  seg.note = withHow(seg.note, [`its source shot's ${len.toFixed(2)}s`]);
1610
2444
  }
1611
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);
1612
2472
  let total = 0;
1613
2473
  for (const seg of spine) {
1614
2474
  seg.startSec = total;
@@ -1617,10 +2477,11 @@ export function buildTimeline({
1617
2477
  spine.forEach((seg, k) => {
1618
2478
  if (seg.reaction?.tail) seg.reaction.tail.atSec = spine[k + 1].startSec;
1619
2479
  });
1620
- const groups = sourceAd ? sourceGroups(spine, sourceAd, shotOf) : null;
2480
+ const groups = sourceAd && !measure ? sourceGroups(spine, sourceAd, shotOf) : null;
1621
2481
 
1622
2482
  const lineTexts = new Map([...scriptLines].map(([id, line]) => [id, line?.text]));
1623
2483
  const beats = spine.filter((seg) => seg.reaction);
2484
+ const reservedThrough = new Map();
1624
2485
  for (const c of waiting.filter((w) => !w.reaction)) {
1625
2486
  // A copied shot lands where its shot sits in the source, through its group.
1626
2487
  const copied = groups?.length ? sourceAd.shots.find((e) => e.n === shotOf(c.sceneIndex)) : null;
@@ -1633,13 +2494,21 @@ export function buildTimeline({
1633
2494
  });
1634
2495
  continue;
1635
2496
  }
1636
- 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
+ }
1637
2506
  if (!cue) {
1638
2507
  dropped.push({ n: c.sceneIndex, reason: `cutaway ${c.sceneIndex}: ${noCue(c)}` });
1639
2508
  continue;
1640
2509
  }
1641
2510
  const placed = { ...c, startSec: cue.startSec, method: cue.method, spineSceneIndex: cue.spineSceneIndex };
1642
- 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;
1643
2512
  const win = seg
1644
2513
  ? brollWindow(seg, counts, c.cueLineId, lineTexts, c.broll)
1645
2514
  : null;
@@ -1651,8 +2520,26 @@ export function buildTimeline({
1651
2520
  placed.seconds = c.source === "clip" ? Math.min(win.holdSec, c.seconds) : win.holdSec;
1652
2521
  placed.coversFound = win.found;
1653
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
+ }
1654
2535
  cutaways.push(placed);
1655
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
+ }
1656
2543
  cutaways.sort((a, b) => a.startSec - b.startSec);
1657
2544
  for (let i = 0; i < cutaways.length; i++) {
1658
2545
  const c = cutaways[i];
@@ -1664,20 +2551,117 @@ export function buildTimeline({
1664
2551
  stops.push({ at: total, by: "the ad ends" });
1665
2552
  const stop = stops.reduce((a, b) => (b.at < a.at ? b : a));
1666
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
+ ]);
1667
2557
  c.seconds = Math.max(0, stop.at - c.startSec);
1668
2558
  c.cutShortBy = stop.by;
1669
2559
  }
1670
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
+ }
1671
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;
1672
2587
  return {
1673
2588
  spine,
1674
2589
  cutaways,
1675
2590
  left: dropped.sort((a, b) => a.n - b.n).map((d) => d.reason),
1676
- ...(whole ? { wholeVoice: { file: wholeVoice.file, startSec: whole.startSec } } : {}),
2591
+ ...(whole ? { wholeVoice: { file: wholeVoice.file, startSec: wholeStartSec, ...(wholeClock ? { clock: wholeClock } : {}) } } : {}),
1677
2592
  ...(groups ? { sourceGroups: groups } : {}),
2593
+ ...(sourceMap ? { mapped: true, sourceMap } : {}),
1678
2594
  };
1679
2595
  }
1680
2596
 
2597
+ /**
2598
+ * brollMinSec: a cutaway on screen for less than `minSec` of the finished ad
2599
+ * (its time in the cut over `speed`) is left out, and the shot before it plays
2600
+ * on over its time: the cutaway that ends where it starts, its last frame held
2601
+ * if its clip runs out, else the scene under it. `clipSeconds(file)` is a
2602
+ * clip's length. Returns a line for each cutaway left out.
2603
+ */
2604
+ export function holdBroll(timeline, minSec, speed, clipSeconds) {
2605
+ const kept = [];
2606
+ const left = [];
2607
+ for (const c of timeline.cutaways) {
2608
+ const shown = c.seconds / speed;
2609
+ if (shown >= minSec - 1e-6) {
2610
+ kept.push(c);
2611
+ continue;
2612
+ }
2613
+ const why = `cutaway ${c.sceneIndex}: ${shown.toFixed(2)}s on screen, under the ${minSec}s B-roll minimum, so it is left out and`;
2614
+ const before = kept.at(-1);
2615
+ if (before && Math.abs(before.startSec + before.seconds - c.startSec) < 0.5 / FPS) {
2616
+ before.seconds = roundMs(c.startSec + c.seconds - before.startSec);
2617
+ if (c.cutShortBy) before.cutShortBy = c.cutShortBy;
2618
+ else delete before.cutShortBy;
2619
+ const hold = before.source === "clip" ? roundMs(before.seconds - clipSeconds(before.file)) : 0;
2620
+ if (hold > 0) before.holdSec = hold;
2621
+ left.push(`${why} cutaway ${before.sceneIndex} plays on over it`);
2622
+ } else {
2623
+ left.push(`${why} the scene under it plays on`);
2624
+ }
2625
+ }
2626
+ timeline.cutaways = kept;
2627
+ return left;
2628
+ }
2629
+
2630
+ /** speedUpSlowBroll: the most a slow cutaway is sped up. */
2631
+ export const SLOW_SHOT_SPEED_MAX = 1.6;
2632
+
2633
+ /**
2634
+ * speedUpSlowBroll: every shot's motion is read off its clip before the render
2635
+ * (`motionOf(file, fromSec, seconds)`), and a cutaway that slowShots finds slow
2636
+ * plays its clip faster, at most SLOW_SHOT_SPEED_MAX, so it shows more of its
2637
+ * clip in the same time on screen. A cutaway whose clip is no longer than its
2638
+ * time on screen cannot be, and is noted. Returns a line for each slow cutaway.
2639
+ */
2640
+ export function speedUpSlowBroll(timeline, motionOf, clipSeconds) {
2641
+ const shots = [
2642
+ ...timeline.spine
2643
+ .filter((seg) => seg.source === "clip")
2644
+ .map((seg) => ({ n: seg.sceneIndex, role: roleOf(seg), file: seg.file, from: seg.inSec ?? 0, sec: seg.seconds - (seg.holdSec ?? 0) })),
2645
+ ...timeline.cutaways
2646
+ .filter((c) => c.source === "clip")
2647
+ .map((c) => ({ n: c.sceneIndex, role: "b-roll", file: c.file, from: 0, sec: c.seconds, cutaway: c })),
2648
+ ].filter((s) => s.sec > 0);
2649
+ const measured = shots.map((s) => ({ ...s, motion: motionOf(s.file, s.from, s.sec) }));
2650
+ const notes = [];
2651
+ for (const slow of slowShots(measured)) {
2652
+ const c = slow.cutaway;
2653
+ if (!c) continue;
2654
+ const have = clipSeconds(c.file);
2655
+ if (!(have > c.seconds + 0.05)) {
2656
+ notes.push(`cutaway ${c.sceneIndex} barely moves, but its clip (${have.toFixed(2)}s) is no longer than its time on screen (${c.seconds.toFixed(2)}s), so it plays as it is`);
2657
+ continue;
2658
+ }
2659
+ c.speed = roundMs(Math.min(have / c.seconds, SLOW_SHOT_SPEED_MAX));
2660
+ notes.push(`cutaway ${c.sceneIndex} barely moves, so it plays ${c.speed}x faster: ${(c.seconds * c.speed).toFixed(2)}s of its clip in ${c.seconds.toFixed(2)}s`);
2661
+ }
2662
+ return notes;
2663
+ }
2664
+
1681
2665
  /** #3365: why the cut stopped on scenes with no clip, and the person's three ways on. */
1682
2666
  function noClipRefusal(missing) {
1683
2667
  const scenes = missing.map((m) => `scene ${m.n} (${m.status})`).join(", ");
@@ -1696,12 +2680,87 @@ function sec(n) {
1696
2680
  return (Number.isFinite(n) ? Math.max(0, n) : 0).toFixed(3);
1697
2681
  }
1698
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
+
1699
2756
  /**
1700
2757
  * The render. `finish` (null: today's render) carries the finishing settings'
1701
2758
  * part of it: levelSegments false leaves each segment's sound as it is for the
1702
2759
  * whole mix's loudness pass, `ass` names the captions and cards file burned in
1703
- * (read from the folder ffmpeg runs in), and `speed` over 1 speeds the whole
1704
- * cut, picture and sound, after the burn.
2760
+ * (read from the folder ffmpeg runs in), `speed` over 1 speeds the whole
2761
+ * cut, picture and sound, after the burn, `clean` (cleanVoice) is the voice's
2762
+ * chain and the duck under it, and `meters` (cutChecks) names the two files
2763
+ * the voice and everything under it are also written to.
1705
2764
  */
1706
2765
  export function buildFfmpegArgs(timeline, { resolve, music, out, finish = null, sound = null }) {
1707
2766
  const level = finish && finish.levelSegments === false ? "anull" : LOUDNORM;
@@ -1714,12 +2773,18 @@ export function buildFfmpegArgs(timeline, { resolve, music, out, finish = null,
1714
2773
  const filters = [];
1715
2774
  const pairs = [];
1716
2775
  const tails = [];
2776
+ // The measured map: every piece, overlay and the whole voice on pieceClock's numbers.
2777
+ const mapped = timeline.mapped === true;
1717
2778
 
1718
2779
  for (const seg of timeline.spine) {
1719
2780
  const i =
1720
2781
  seg.source === "clip"
1721
2782
  ? addInput("-i", resolve(seg.file))
1722
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
+ }
1723
2788
  const fit = [];
1724
2789
  const inSec = seg.inSec ?? 0;
1725
2790
  // #2544: sentence gaps come out first, the picture by frame number and the
@@ -1793,17 +2858,30 @@ export function buildFfmpegArgs(timeline, { resolve, music, out, finish = null,
1793
2858
  // ends on its own. No -shortest: ffmpeg 8 held the whole ad's frames for it,
1794
2859
  // and Debian's ffmpeg 5.1 (the worker's) never ended at all (#2988).
1795
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)}`;
1796
2866
  if (timeline.wholeVoice) {
1797
2867
  // The voice laid whole from where its first scene starts, under the spine's own sound.
1798
2868
  const k = addInput("-i", resolve(timeline.wholeVoice.file));
1799
- filters.push(`[voicecat]apad,atrim=end=${pictureSec.toFixed(6)}[spoken]`);
1800
- filters.push(
1801
- `[${k}:a]${stereo},${level},adelay=delays=${Math.round(timeline.wholeVoice.startSec * 1000)}:all=1,` +
1802
- `apad,atrim=end=${pictureSec.toFixed(6)}[whole]`,
1803
- );
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
+ }
1804
2882
  filters.push("[spoken][whole]amix=inputs=2:duration=first:dropout_transition=0:normalize=0[voice]");
1805
2883
  } else {
1806
- filters.push(`[voicecat]apad,atrim=end=${pictureSec.toFixed(6)}[voice]`);
2884
+ filters.push(`[voicecat]apad,${toPicture}[voice]`);
1807
2885
  }
1808
2886
 
1809
2887
  let videoLabel = "vcat";
@@ -1813,8 +2891,21 @@ export function buildFfmpegArgs(timeline, { resolve, music, out, finish = null,
1813
2891
  ? addInput("-i", resolve(c.file))
1814
2892
  : addInput("-loop", "1", "-t", String(c.seconds), "-i", resolve(c.file));
1815
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
+ }
2904
+ // speedUpSlowBroll: a slow cutaway plays faster; brollMinSec: one that plays on past its clip holds its last frame.
2905
+ const faster = c.speed > 1 ? `,setpts=PTS/${c.speed}` : "";
2906
+ const hold = c.holdSec > 0 ? `,tpad=stop_mode=clone:stop_duration=${sec(c.holdSec)}` : "";
1816
2907
  filters.push(
1817
- `${norm(`${i}:v`)},trim=0:${sec(c.seconds)},setpts=PTS-STARTPTS+${sec(c.startSec)}/TB[cv${j}]`,
2908
+ `${norm(`${i}:v`)}${faster}${hold},trim=0:${sec(c.seconds)},setpts=PTS-STARTPTS+${sec(c.startSec)}/TB[cv${j}]`,
1818
2909
  );
1819
2910
  // eof_action=pass keeps the spine showing once the cutaway's frames end.
1820
2911
  filters.push(
@@ -1849,41 +2940,87 @@ export function buildFfmpegArgs(timeline, { resolve, music, out, finish = null,
1849
2940
  if (sound?.beds?.length) {
1850
2941
  sound.beds.forEach((b, j) => {
1851
2942
  const k = addInput("-stream_loop", "-1", "-i", resolve(b.file));
1852
- filters.push(
1853
- `[${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,` +
1854
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},` +
1855
2951
  `adelay=delays=${Math.round(b.startSec * 1000)}:all=1[set${j}]`,
1856
2952
  );
1857
2953
  beds.push(`[set${j}]`);
1858
2954
  });
1859
- } else {
1860
- 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]`);
1861
2959
  beds.push("[room]");
1862
2960
  }
1863
2961
  beds.push(...tails);
1864
2962
  (sound?.effects ?? []).forEach((e, j) => {
1865
2963
  const k = addInput("-i", resolve(e.file));
1866
- 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}]`);
1867
2970
  beds.push(`[sfx${j}]`);
1868
2971
  });
1869
2972
  let voice = "[voice]";
2973
+ const clean = finish?.clean ?? null;
1870
2974
  if (music) {
1871
2975
  const m = addInput("-stream_loop", "-1", "-i", music);
1872
- const duck = sound?.music?.duck;
2976
+ const duck = clean ? null : sound?.music?.duck;
1873
2977
  if (duck) {
1874
2978
  filters.push("[voice]asplit=2[voiced][duckkey]");
1875
- 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]`);
1876
2982
  filters.push(
1877
2983
  `[bedraw][duckkey]sidechaincompress=threshold=${duck.threshold}:ratio=${duck.ratio}:attack=${duck.attack}:release=${duck.release}[bed]`,
1878
2984
  );
1879
2985
  voice = "[voiced]";
2986
+ } else if (clean && sound?.music) {
2987
+ filters.push(`[${m}:a]${stereo},atrim=0:${pictureSec.toFixed(6)},asetpts=PTS-STARTPTS,volume=${sound.music.gainDb}dB[bed]`);
1880
2988
  } else {
1881
- 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]`);
1882
2992
  }
1883
2993
  beds.push("[bed]");
1884
2994
  }
2995
+ let under = beds;
2996
+ if (clean) {
2997
+ // Each bed is trimmed to the picture, then ducked on its own by the same key, which ducks their sum the same.
2998
+ const ducked = beds.filter((label) => !tails.includes(label));
2999
+ const u = clean.under;
3000
+ filters.push(`[voice]${clean.voice},asplit=${ducked.length + 1}[voiced]${ducked.map((_, j) => `[vkey${j}]`).join("")}`);
3001
+ ducked.forEach((label, j) => {
3002
+ filters.push(`${label}atrim=end=${pictureSec.toFixed(6)},highpass=f=${u.highpass},lowpass=f=${u.lowpass},volume=${u.db}dB[uc${j}]`);
3003
+ filters.push(
3004
+ `[uc${j}][vkey${j}]sidechaincompress=threshold=${u.duck.threshold}:ratio=${u.duck.ratio}:attack=${u.duck.attack}:release=${u.duck.release}[ud${j}]`,
3005
+ );
3006
+ });
3007
+ voice = "[voiced]";
3008
+ under = [...ducked.map((_, j) => `[ud${j}]`), ...tails];
3009
+ }
3010
+ if (finish?.meters) {
3011
+ // cutChecks: the voice, and everything under it mixed, each also written alone to be measured.
3012
+ filters.push(`${voice}asplit=2[metered][vmeter]`);
3013
+ voice = "[metered]";
3014
+ under = under.map((label, j) => {
3015
+ filters.push(`${label}asplit=2[mu${j}][mb${j}]`, `[mb${j}]atrim=end=${pictureSec.toFixed(6)}[mt${j}]`);
3016
+ return `[mu${j}]`;
3017
+ });
3018
+ filters.push(
3019
+ `${under.map((_, j) => `[mt${j}]`).join("")}amix=inputs=${under.length}:duration=longest:dropout_transition=0:normalize=0[bedmeter]`,
3020
+ );
3021
+ }
1885
3022
  filters.push(
1886
- `${voice}${beds.join("")}amix=inputs=${beds.length + 1}:duration=first:dropout_transition=0:normalize=0[mix]`,
3023
+ `${voice}${under.join("")}amix=inputs=${under.length + 1}:duration=first:dropout_transition=0:normalize=0[mix]`,
1887
3024
  );
1888
3025
  let audioLabel = "mix";
1889
3026
  if (speed) {
@@ -1900,6 +3037,9 @@ export function buildFfmpegArgs(timeline, { resolve, music, out, finish = null,
1900
3037
  "-c:a", "aac", "-b:a", "192k",
1901
3038
  "-movflags", "+faststart",
1902
3039
  out,
3040
+ ...(finish?.meters
3041
+ ? ["-map", "[vmeter]", "-c:a", "pcm_s16le", finish.meters.voice, "-map", "[bedmeter]", "-c:a", "pcm_s16le", finish.meters.bed]
3042
+ : []),
1903
3043
  ];
1904
3044
  }
1905
3045
 
@@ -1927,7 +3067,9 @@ export function sceneTimes(timeline) {
1927
3067
  return pieces.map((p) => ({ sceneIndex: seg.sceneIndex, startSec: p.from, seconds: p.to - p.from }));
1928
3068
  });
1929
3069
  return [...visible, ...timeline.cutaways]
1930
- .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) })
1931
3073
  .filter((p) => p.seconds > 0)
1932
3074
  .sort((a, b) => a.startSec - b.startSec);
1933
3075
  }
@@ -1935,12 +3077,20 @@ export function sceneTimes(timeline) {
1935
3077
  export function wordRows(timeline) {
1936
3078
  const rows = [];
1937
3079
  for (const seg of timeline.spine) {
1938
- 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()) {
1939
3083
  const text = (w.w ?? "").trim();
1940
3084
  const start = seg.startSec + w.s;
1941
- const end = seg.startSec + w.e;
3085
+ const end = seg.startSec + (timeline.mapped ? wordEnd(w) : w.e);
1942
3086
  if (text && end > start) {
1943
- 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 });
1944
3094
  }
1945
3095
  }
1946
3096
  }
@@ -2195,15 +3345,114 @@ export function captionScreens(words, cap = null) {
2195
3345
  });
2196
3346
  }
2197
3347
 
3348
+ /**
3349
+ * captionsByLine: a caption screen holds the words of one script line only, a
3350
+ * few a screen (`cap`, a source record's caption style, else 3), breaks on a
3351
+ * pause over CAPTION_LINE_GAP_SEC, stays up CAPTION_TAIL_SEC after its last
3352
+ * word at most and goes off CAPTION_CLEAR_SEC before the next comes on. A
3353
+ * screen shorter than CAPTION_MIN_SEC joins the next one of its line, else the
3354
+ * one before, one word over the few at most. `words`: [{ text, start, end, line }].
3355
+ */
3356
+ export const CAPTION_LINE_GAP_SEC = 0.5;
3357
+ export const CAPTION_TAIL_SEC = 0.15;
3358
+ export const CAPTION_CLEAR_SEC = 0.02;
3359
+ export const CAPTION_MIN_SEC = 0.35;
3360
+ /** captionsByLine: the caption font is at most this share of the frame's height (69 px of 1920). */
3361
+ export const CAPTION_MAX_SHARE = 0.036;
3362
+
3363
+ export function lineCaptionScreens(words, cap = null) {
3364
+ const per = Math.max(1, Math.round(cap?.wordsPerLine?.median ?? 3));
3365
+ const caps = /all-caps|capitals|upper/i.test(cap?.style ?? "");
3366
+ let chunks = [];
3367
+ let cur = [];
3368
+ for (const w of words) {
3369
+ const last = cur.at(-1);
3370
+ // Script words timed by one heard word ("twenty five" for "25") stay on one screen.
3371
+ const oneHeard = last && w.line === last.line && w.start === last.start && w.end === last.end;
3372
+ if (last && !oneHeard && (cur.length >= per || w.line !== last.line || w.start - last.end > CAPTION_LINE_GAP_SEC)) {
3373
+ chunks.push(cur);
3374
+ cur = [];
3375
+ }
3376
+ cur.push(w);
3377
+ }
3378
+ if (cur.length) chunks.push(cur);
3379
+ for (let k = 0; k < chunks.length; k++) {
3380
+ const c = chunks[k];
3381
+ if (c.at(-1).end - c[0].start >= CAPTION_MIN_SEC) continue;
3382
+ const next = chunks[k + 1];
3383
+ const prev = chunks[k - 1];
3384
+ const joins = (a, b) => a && b && b[0].line === a[0].line && b[0].start - a.at(-1).end <= CAPTION_LINE_GAP_SEC && a.length + b.length <= per + 1;
3385
+ if (joins(c, next)) {
3386
+ chunks[k + 1] = [...c, ...next];
3387
+ chunks[k] = null;
3388
+ } else if (joins(prev, c)) {
3389
+ chunks[k - 1] = [...prev, ...c];
3390
+ chunks[k] = null;
3391
+ }
3392
+ }
3393
+ chunks = chunks.filter(Boolean);
3394
+ return chunks.map((ws, k) => {
3395
+ const next = chunks[k + 1]?.[0];
3396
+ const text = ws.map((w) => assText(w.text)).join(" ").replace(/[.,;:]+$/, "");
3397
+ const off = next ? next.start - CAPTION_CLEAR_SEC : Infinity;
3398
+ const e = Math.min(Math.max(ws[0].start + 0.12, ws.at(-1).end + CAPTION_TAIL_SEC), off);
3399
+ return { text: caps ? text.toUpperCase() : text, s: roundMs(ws[0].start), e: roundMs(e), line: ws[0].line };
3400
+ });
3401
+ }
3402
+
3403
+ /**
3404
+ * captionsByLine: the cut's words in its own time, each with the script line
3405
+ * it belongs to. Where a segment's script is heard in order (alignScript),
3406
+ * they are the script's words as written, each timed by the heard words that
3407
+ * say it; elsewhere they are the heard words, each on the line its place among
3408
+ * the script's words gives it, the way a cue line is found (lineInSegment).
3409
+ */
3410
+ export function lineWords(timeline, storyboard) {
3411
+ const texts = new Map((storyboard?.script ?? []).map((line) => [line?.lineId, line?.text]));
3412
+ const counts = lineWordCounts(storyboard);
3413
+ const rows = [];
3414
+ for (const seg of timeline.spine) {
3415
+ const heard = seg.words ?? [];
3416
+ if (heard.length === 0) continue;
3417
+ const at = (t) => roundMs(seg.startSec + t);
3418
+ const lines = seg.lineIds.map((id) => scriptWords(texts.get(id)));
3419
+ const aligned = lines.some((l) => l.length > 0) ? alignScript(heard, lines.flat()) : null;
3420
+ if (aligned) {
3421
+ const lineOf = lines.flatMap((ws, j) => ws.map(() => seg.lineIds[j]));
3422
+ const { expected, heard: tokens, heardTokenOf } = aligned;
3423
+ lines.flat().forEach((text, i) => {
3424
+ const said = heardTokenOf.filter((_, e) => expected.sourceIndex[e] <= i && i <= expected.lastSourceIndex[e]);
3425
+ if (said.length === 0) return;
3426
+ const start = at(heard[tokens.sourceIndex[said[0]]].s);
3427
+ const end = at(heard[tokens.lastSourceIndex[said.at(-1)]].e);
3428
+ if (end > start) rows.push({ text, start, end, line: lineOf[i] });
3429
+ });
3430
+ continue;
3431
+ }
3432
+ const ends = [];
3433
+ let n = 0;
3434
+ for (const id of seg.lineIds) ends.push((n += counts.get(id) ?? 0));
3435
+ heard.forEach((w, i) => {
3436
+ const text = (w.w ?? "").trim();
3437
+ const start = at(w.s);
3438
+ const end = at(w.e);
3439
+ if (!text || end <= start) return;
3440
+ const j = ends.findIndex((last) => Math.min(i, n - 1) < last);
3441
+ rows.push({ text, start, end, line: seg.lineIds[j] ?? seg.lineIds.at(-1) ?? `scene ${seg.sceneIndex}` });
3442
+ });
3443
+ }
3444
+ return rows;
3445
+ }
3446
+
2198
3447
  /**
2199
3448
  * One ASS file for the burn: the caption screens in their band, the cards in
2200
3449
  * their boxes, the hook box and the end card. Boxes are [x0, y0, x1, y1] as
2201
3450
  * shares of the frame. Every word on screen is the script's or the storyboard's.
2202
3451
  */
2203
- export function editAss({ captions = [], cap = null, cards = [], hook = null, endCard = null }, W = WIDTH, H = HEIGHT) {
3452
+ export function editAss({ captions = [], cap = null, cards = [], hook = null, endCard = null, capMaxShare = null }, W = WIDTH, H = HEIGHT) {
2204
3453
  const thick = /thick black outline/i.test(cap?.style ?? "");
2205
3454
  const y = cap?.place ? Math.round(((cap.place[0] + cap.place[1]) / 2) * H) : Math.round(H * 0.7);
2206
- const capSize = Math.round(H * (thick ? 0.05 : 0.034));
3455
+ const capSize = Math.min(Math.round(H * (thick ? 0.05 : 0.034)), capMaxShare ? Math.round(H * capMaxShare) : Infinity);
2207
3456
  const box = (b) => `\\pos(${Math.round(((b[0] + b[2]) / 2) * W)},${Math.round(((b[1] + b[3]) / 2) * H)})`;
2208
3457
  return [
2209
3458
  "[Script Info]", "ScriptType: v4.00+", `PlayResX: ${W}`, `PlayResY: ${H}`, "WrapStyle: 0", "ScaledBorderAndShadow: yes", "",
@@ -2303,6 +3552,15 @@ export function endCardOf(storyboard, seconds) {
2303
3552
  return { text: overlay.text.trim(), in: roundMs(Math.max(0, seconds - END_CARD_SEC)), out: roundMs(seconds + 1) };
2304
3553
  }
2305
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
+
2306
3564
  /**
2307
3565
  * The pace report: cuts a minute, mean and longest shot, shots over
2308
3566
  * LONG_SHOT_SEC, words a minute and pauses over 0.3 s, against a source ad's
@@ -2339,6 +3597,157 @@ export function voicePauses(rows) {
2339
3597
  return pauses;
2340
3598
  }
2341
3599
 
3600
+ // ---- cutChecks: the finished cut checked before anyone grades it ----
3601
+
3602
+ /**
3603
+ * The bars a checked cut is held to. voiceOverBedDb and the slow-shot ratio
3604
+ * are guesses, to be tuned against the graders' notes on the cuts they mark.
3605
+ */
3606
+ export const CHECK_BARS = { voiceOverBedDb: 10, minBrollSec: 1.2, truePeak: -1.0, lufs: -14 };
3607
+ /** A shot is slow when it moves under this share of the cut's median motion, or under SLOW_SHOT_FLOOR. */
3608
+ const SLOW_SHOT_RATIO = 0.35;
3609
+ const SLOW_SHOT_FLOOR = 0.6;
3610
+ /** A phrase of this many words said again within REPEAT_WITHIN words is a repeat. */
3611
+ const REPEAT_WORDS = 3;
3612
+ const REPEAT_WITHIN = 14;
3613
+ const NUMBER_WORDS_AS_DIGITS = { zero: "0", one: "1", two: "2", three: "3", four: "4", five: "5", six: "6", seven: "7", eight: "8", nine: "9", ten: "10", twenty: "20", thirty: "30" };
3614
+ /** A heard word as the checks compare it: lower case, no punctuation, a number word as its digits. */
3615
+ export const checkWord = (s) => {
3616
+ const t = String(s).toLowerCase().replace(/[’']/g, "").replace(/[^a-z0-9%$]/g, "");
3617
+ return NUMBER_WORDS_AS_DIGITS[t] ?? t;
3618
+ };
3619
+
3620
+ /** Caption screens that hold words of two script lines. `words` carry their line (lineWords). */
3621
+ export function lineMixes(screens, words) {
3622
+ return screens
3623
+ .filter((c) => new Set(words.filter((w) => w.start >= c.s - 0.01 && w.start < c.e).map((w) => w.line)).size > 1)
3624
+ .map((c) => ({ s: c.s, text: c.text }));
3625
+ }
3626
+
3627
+ /** A phrase of REPEAT_WORDS or more words said again within REPEAT_WITHIN words. `heard`: [{ w, s }]. */
3628
+ export function repeats(heard) {
3629
+ const t = heard.map((h) => checkWord(h.w));
3630
+ const out = [];
3631
+ for (let i = 0; i + REPEAT_WORDS <= t.length; i++) {
3632
+ const phrase = t.slice(i, i + REPEAT_WORDS).join(" ");
3633
+ for (let j = i + REPEAT_WORDS; j + REPEAT_WORDS <= Math.min(t.length, i + REPEAT_WORDS + REPEAT_WITHIN); j++) {
3634
+ if (t.slice(j, j + REPEAT_WORDS).join(" ") === phrase) {
3635
+ out.push({ phrase, firstAt: roundMs(heard[i].s), againAt: roundMs(heard[j].s) });
3636
+ i += REPEAT_WORDS - 1;
3637
+ break;
3638
+ }
3639
+ }
3640
+ }
3641
+ return out;
3642
+ }
3643
+
3644
+ /** B-roll and narrated shots on screen for less than CHECK_BARS.minBrollSec. `shots`: [{ n, role, start, end }]. */
3645
+ export function shortShots(shots, minSec = CHECK_BARS.minBrollSec) {
3646
+ return shots
3647
+ .filter((s) => ["b-roll", "overlay", "vo-enactment"].includes(s.role) && s.end - s.start < minSec)
3648
+ .map((s) => ({ n: s.n, role: s.role, at: s.start, sec: roundMs(s.end - s.start) }));
3649
+ }
3650
+
3651
+ /**
3652
+ * Shots whose motion is far under the cut's median. A shot of someone talking
3653
+ * to camera (a-roll) sits still at natural speed, so it is never slow here.
3654
+ * `motion`: [{ n, role, sec, motion }].
3655
+ */
3656
+ export function slowShots(motion) {
3657
+ const values = motion.map((m) => m.motion).filter((x) => x != null).sort((a, b) => a - b);
3658
+ if (!values.length) return [];
3659
+ const median = values[Math.floor(values.length / 2)];
3660
+ return motion
3661
+ .filter((m) => m.role !== "a-roll" && m.motion != null && m.sec >= 1 && (m.motion < median * SLOW_SHOT_RATIO || m.motion < SLOW_SHOT_FLOOR))
3662
+ .map((m) => ({ ...m, median: roundMs(median) }));
3663
+ }
3664
+
3665
+ /** The voice's loudness over the rest's, in dB; null when the voice is silent, 60 when the rest is. */
3666
+ export const voiceOverBed = (voiceLufs, bedLufs) =>
3667
+ voiceLufs == null || bedLufs == null || voiceLufs < -60 ? null : bedLufs < -60 ? 60 : roundMs(voiceLufs - bedLufs);
3668
+
3669
+ /** What fails the bars, in words; the cut passes when nothing does. */
3670
+ export function checkVerdict(c, bars = CHECK_BARS) {
3671
+ const fails = [];
3672
+ if (c.lineMixes?.length) fails.push(`${c.lineMixes.length} caption screens mix two lines`);
3673
+ if (c.voiceOverBedDb != null && c.voiceOverBedDb < bars.voiceOverBedDb) fails.push(`voice ${c.voiceOverBedDb} dB over the bed (bar ${bars.voiceOverBedDb})`);
3674
+ if (c.repeats?.length) fails.push(`${c.repeats.length} phrase(s) said twice`);
3675
+ if (c.shortShots?.length) fails.push(`${c.shortShots.length} b-roll shot(s) under ${bars.minBrollSec} s`);
3676
+ if (c.slowShots === null) fails.push("shot motion could not be measured");
3677
+ else if (c.slowShots?.length) fails.push(`${c.slowShots.length} slow shot(s)`);
3678
+ if (c.truePeak != null && c.truePeak > bars.truePeak) fails.push(`true peak ${c.truePeak} dBTP (bar ${bars.truePeak})`);
3679
+ if (c.lufs != null && Math.abs(c.lufs - bars.lufs) > 1) fails.push(`loudness ${c.lufs} LUFS (bar ${bars.lufs} ± 1)`);
3680
+ return { pass: !fails.length, fails };
3681
+ }
3682
+
3683
+ /** Frame-to-frame change of a file's picture, on a 90 px wide copy, printed per frame. `from`/`seconds` read a stretch. */
3684
+ export function motionArgs(file, from = null, seconds = null) {
3685
+ return [
3686
+ "-hide_banner", "-nostats",
3687
+ ...(from !== null ? ["-ss", sec(from)] : []), ...(seconds !== null ? ["-t", sec(seconds)] : []),
3688
+ "-i", file, "-an",
3689
+ "-vf", "scale=90:-2,tblend=all_mode=difference,signalstats,metadata=print:key=lavfi.signalstats.YAVG:file=-",
3690
+ "-f", "null", "-",
3691
+ ];
3692
+ }
3693
+
3694
+ /** motionArgs' printout as [{ t, y }]: each frame's time and its mean change. */
3695
+ export function readMotion(stdout) {
3696
+ const rows = [];
3697
+ let t = null;
3698
+ for (const line of String(stdout ?? "").split("\n")) {
3699
+ const time = line.match(/pts_time:([\d.]+)/);
3700
+ if (time) {
3701
+ t = Number(time[1]);
3702
+ continue;
3703
+ }
3704
+ const y = line.match(/YAVG=([\d.]+)/);
3705
+ if (y && t !== null) rows.push({ t, y: Number(y[1]) });
3706
+ }
3707
+ return rows;
3708
+ }
3709
+
3710
+ /** Each shot's mean motion, its first and last 0.1 s left out so a cut is not counted as motion. */
3711
+ export function motionByShot(rows, shots) {
3712
+ return shots.map((s) => {
3713
+ const v = rows.filter((r) => r.t > s.start + 0.1 && r.t < s.end - 0.1).map((r) => r.y);
3714
+ return { n: s.n, role: s.role, at: roundMs(s.start), sec: roundMs(s.end - s.start), motion: v.length ? roundMs(v.reduce((x, y) => x + y, 0) / v.length) : null };
3715
+ });
3716
+ }
3717
+
3718
+ /** The part a spine segment plays on screen, as the checks read shots: a scene speaking its own lines (or a reaction) is a-roll. */
3719
+ const roleOf = (seg) => (seg.reaction || seg.audio === "clip" ? "a-roll" : seg.audio === "narration" ? "vo-enactment" : "b-roll");
3720
+
3721
+ /**
3722
+ * cutChecks: the finished cut against CHECK_BARS. `screens` are the caption
3723
+ * screens burned in (null for none), `rows` and `scenes` the cut's words and
3724
+ * shots as written beside it, `levels` the voice's and the bed's loudness from
3725
+ * the render. Caption sync is not checked: it needs a transcription of the
3726
+ * finished cut of its own, and the cut's words are the ones its captions came from.
3727
+ */
3728
+ function checkCut({ timeline, storyboard, screens, rows, scenes, out, loudness, levels }) {
3729
+ const roles = new Map(timeline.spine.map((seg) => [seg.sceneIndex, roleOf(seg)]));
3730
+ for (const c of timeline.cutaways) roles.set(c.sceneIndex, "b-roll");
3731
+ const shots = scenes.map((p) => ({ n: p.scene, role: roles.get(p.scene) ?? "b-roll", start: p.startSec, end: roundMs(p.startSec + p.seconds) }));
3732
+ const read = spawnSync("ffmpeg", motionArgs(out), { encoding: "utf8", maxBuffer: 1 << 28 });
3733
+ const motion = read.status === 0 ? readMotion(read.stdout) : [];
3734
+ const finished = loudness ? { i: loudness.lufs, tp: loudness.truePeak } : measureLoudness(out);
3735
+ const checks = {
3736
+ lineMixes: screens ? lineMixes(screens, lineWords(timeline, storyboard)) : null,
3737
+ // A song laid whole is the voice and the music at once, so it has no level over a bed.
3738
+ voiceOverBedDb: timeline.wholeVoice ? null : voiceOverBed(levels.voiceLufs, levels.bedLufs),
3739
+ voiceLufs: levels.voiceLufs,
3740
+ bedLufs: levels.bedLufs,
3741
+ repeats: repeats(rows.map((r) => ({ w: r.text, s: r.start }))),
3742
+ shortShots: shortShots(shots),
3743
+ // null: ffmpeg could not read the motion, so no shot was checked.
3744
+ slowShots: motion.length ? slowShots(motionByShot(motion, shots)) : null,
3745
+ lufs: finished ? round2(finished.i) : null,
3746
+ truePeak: finished ? round2(finished.tp) : null,
3747
+ };
3748
+ return { ...checks, verdict: checkVerdict(checks) };
3749
+ }
3750
+
2342
3751
  const LOUDNORM_TARGET = `I=${FINISH_LUFS}:TP=${FINISH_TRUE_PEAK}:LRA=${FINISH_LRA}`;
2343
3752
 
2344
3753
  /** finishLoudness, pass one: measure a file's sound. Its numbers come back on stderr as JSON. */
@@ -2366,9 +3775,14 @@ export function readLoudness(stderr) {
2366
3775
  /**
2367
3776
  * finishLoudness, pass two: the whole mix normalized with pass one's numbers,
2368
3777
  * the picture copied as it is. Without them (pass one could not read the
2369
- * sound) loudnorm runs on its own, in one pass.
3778
+ * sound) loudnorm runs on its own, in one pass. `limiter` (limitPeaks) runs
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.
2370
3784
  */
2371
- export function loudnessApplyArgs(mix, measured, out) {
3785
+ export function loudnessApplyArgs(mix, measured, out, limiter = null) {
2372
3786
  const second = measured
2373
3787
  ? `:measured_I=${measured.i}:measured_TP=${measured.tp}:measured_LRA=${measured.lra}` +
2374
3788
  `:measured_thresh=${measured.thresh}:offset=${measured.offset}:linear=true`
@@ -2376,7 +3790,7 @@ export function loudnessApplyArgs(mix, measured, out) {
2376
3790
  return [
2377
3791
  "-y", "-hide_banner", "-loglevel", "error", "-i", mix,
2378
3792
  "-map", "0:v:0", "-map", "0:a:0", "-c:v", "copy",
2379
- "-af", `loudnorm=${LOUDNORM_TARGET}${second},aresample=48000`,
3793
+ "-af", `loudnorm=${LOUDNORM_TARGET}${second}${limiter ? `,${limiter}` : ""},${stereo}`,
2380
3794
  "-c:a", "aac", "-b:a", "192k", "-movflags", "+faststart", out,
2381
3795
  ];
2382
3796
  }
@@ -2404,28 +3818,46 @@ function measureLufs(file) {
2404
3818
  return measured ? round2(measured.i) : null;
2405
3819
  }
2406
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
+
2407
3828
  /** Both passes on the rendered mix, then the finished cut measured again; throws LoudnessRefusal over the limit. */
2408
- export function finishLoudnessPass(mix, out) {
3829
+ export function finishLoudnessPass(mix, out, limiter = null) {
2409
3830
  const measured = measureLoudness(mix);
2410
- const args = loudnessApplyArgs(mix, measured, out);
2411
- const res = spawnSync("ffmpeg", args, { stdio: "inherit" });
3831
+ const args = loudnessApplyArgs(mix, measured, out, limiter);
3832
+ const res = spawnSync("ffmpeg", args, { stdio: ["inherit", "inherit", "pipe"], encoding: "utf8", maxBuffer: 1 << 26 });
2412
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);
2413
3837
  const quoted = args.map((a) => (/[\s\[\];]/.test(a) ? `'${a}'` : a)).join(" ");
2414
- 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}`);
2415
3839
  }
2416
3840
  const finished = measureLoudness(out);
2417
3841
  const refusal = truePeakRefusal(finished);
2418
3842
  if (refusal) throw new LoudnessRefusal(refusal, finished);
2419
- return { lufs: round2(finished.i), truePeak: round2(finished.tp), passes: measured ? 2 : 1 };
3843
+ return { lufs: round2(finished.i), truePeak: round2(finished.tp), passes: measured ? 2 : 1, ...(limiter ? { limited: true } : {}) };
3844
+ }
3845
+
3846
+ /** The filters of `names` this ffmpeg does not have. */
3847
+ function missingFilters(names) {
3848
+ const listed = spawnSync("ffmpeg", ["-hide_banner", "-filters"]).stdout?.toString() ?? "";
3849
+ return names.filter((name) => !new RegExp(`^\\s*\\S+\\s+${name}\\s`, "m").test(listed));
2420
3850
  }
2421
3851
 
2422
3852
  /** Whether this ffmpeg has a filter (the captions and cards need `subtitles`, which needs libass). */
2423
3853
  function hasFilter(name) {
2424
- const listed = spawnSync("ffmpeg", ["-hide_banner", "-filters"]).stdout?.toString() ?? "";
2425
- return new RegExp(`^\\s*\\S+\\s+${name}\\s`, "m").test(listed);
3854
+ return missingFilters([name]).length === 0;
2426
3855
  }
2427
3856
 
2428
- /** The files the finishing settings write beside the cut: the pace record, and the mix before the loudness pass. */
3857
+ /**
3858
+ * The files the finishing settings write beside the cut: the pace record, the
3859
+ * mix before the loudness pass, and the voice and bed cutChecks measures.
3860
+ */
2429
3861
  export function finishPaths(outPath) {
2430
3862
  const dir = path.dirname(outPath);
2431
3863
  const base = path.basename(outPath, path.extname(outPath));
@@ -2434,6 +3866,8 @@ export function finishPaths(outPath) {
2434
3866
  mix: path.join(dir, `${base}.mix${path.extname(outPath)}`),
2435
3867
  sound: path.join(dir, `${base}.sound.json`),
2436
3868
  master: path.join(dir, `${base}.music-only${path.extname(outPath)}`),
3869
+ voice: path.join(dir, `${base}.voice.wav`),
3870
+ bed: path.join(dir, `${base}.bed.wav`),
2437
3871
  };
2438
3872
  }
2439
3873
 
@@ -2460,6 +3894,460 @@ export class LoudnessRefusal extends FirstCutError {
2460
3894
  }
2461
3895
  }
2462
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
+
2463
4351
  function parseArgs(argv) {
2464
4352
  const opts = { dir: undefined, out: undefined, skip: new Set(), music: true, stillFill: false };
2465
4353
  for (let i = 0; i < argv.length; i++) {
@@ -2482,7 +4370,7 @@ function parseArgs(argv) {
2482
4370
  * sidecars, and throws FirstCutError where the CLI would exit. The CLI's report
2483
4371
  * is printed by main() from what this returns.
2484
4372
  */
2485
- 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 }) {
2486
4374
  for (const bin of ["ffmpeg", "ffprobe"]) {
2487
4375
  if (spawnSync(bin, ["-version"]).status !== 0) {
2488
4376
  throw new FirstCutError(2, `${bin} is not installed. Install ffmpeg (brew install ffmpeg / apt install ffmpeg).`);
@@ -2534,6 +4422,7 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
2534
4422
  if (manifest.wholeVoice === true && !wholeVoice) {
2535
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.");
2536
4424
  }
4425
+ const readClocks = manifest.sourceMap === true ? mediaReader(here, exists) : null;
2537
4426
  const timeline = buildTimeline({
2538
4427
  manifest,
2539
4428
  storyboard,
@@ -2546,6 +4435,7 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
2546
4435
  return Array.isArray(rows) && rows.length > 0 ? rows : null;
2547
4436
  },
2548
4437
  readLevels: (file) => clipLevels(here(file)),
4438
+ ...(readClocks ? { measure: readClocks } : {}),
2549
4439
  ...(finish ? { finish } : {}),
2550
4440
  ...(wholeVoice ? { wholeVoice } : {}),
2551
4441
  ...(sourceAd ? { sourceAd } : {}),
@@ -2560,12 +4450,55 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
2560
4450
  const pictureSec = timeline.spine.reduce((sum, seg) => sum + seg.seconds, 0);
2561
4451
  // A voice laid whole is a song: it is never sped up.
2562
4452
  const speed = finish?.cutPace && !timeline.wholeVoice ? speedFor(pictureSec, finish.targetSeconds) : 1;
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) {
4482
+ const held = holdBroll(timeline, finish.brollMinSec, speed, (file) => probe(file).seconds);
4483
+ timeline.left.push(...held);
4484
+ notes.push(...held);
4485
+ }
4486
+ if (finish?.speedUpSlowBroll && !timeline.mapped && timeline.cutaways.length > 0) {
4487
+ const motionOf = (file, from, seconds) => {
4488
+ const res = spawnSync("ffmpeg", motionArgs(here(file), from, seconds), { encoding: "utf8", maxBuffer: 1 << 28 });
4489
+ if (res.status !== 0) return null;
4490
+ return motionByShot(readMotion(res.stdout), [{ n: 0, role: null, start: 0, end: seconds }])[0].motion;
4491
+ };
4492
+ notes.push(...speedUpSlowBroll(timeline, motionOf, (file) => probe(file).seconds));
4493
+ }
2563
4494
  let ass = null;
4495
+ // The caption screens burned in, which cutChecks reads.
4496
+ let burned = null;
2564
4497
  // A copied ad: its words in the record's boxes and its product photos from the product sheet.
2565
4498
  const copied = sourceAd && finish?.cards ? sourceAdEdit(storyboard, sourceAd, timeline.sourceGroups ?? []) : null;
2566
4499
  if (copied) notes.push(...copied.notes);
2567
4500
  let pictures = [];
2568
- if (sourceAd && finish?.cards && sourceAd.pictures.length > 0) {
4501
+ if (!timeline.mapped && sourceAd && finish?.cards && sourceAd.pictures.length > 0) {
2569
4502
  if (exists(manifest.productSheet)) {
2570
4503
  pictures = sourceAd.pictures.map((p) => ({
2571
4504
  file: manifest.productSheet, box: p.box,
@@ -2576,13 +4509,20 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
2576
4509
  notes.push(`the pull has no product sheet picture, so the source's ${sourceAd.pictures.length} product card(s) were not drawn`);
2577
4510
  }
2578
4511
  }
2579
- if (finish && (finish.captions || finish.cards)) {
4512
+ if (finish && (finish.captions || finish.cards) && !(prepareText && timeline.mapped)) {
2580
4513
  if (hasFilter("subtitles")) {
2581
4514
  ass = "edit.ass";
2582
4515
  const cap = sourceAd?.captions ?? null;
4516
+ const screens = !finish.captions
4517
+ ? []
4518
+ : finish.captionsByLine
4519
+ ? lineCaptionScreens(lineWords(timeline, storyboard), cap)
4520
+ : captionScreens(wordRows(timeline), cap);
4521
+ if (finish.captions) burned = screens;
2583
4522
  writeFileSync(here(ass), editAss({
2584
- captions: finish.captions ? captionScreens(wordRows(timeline), cap) : [],
4523
+ captions: screens,
2585
4524
  cap,
4525
+ ...(finish.captionsByLine ? { capMaxShare: CAPTION_MAX_SHARE } : {}),
2586
4526
  cards: finish.cards ? (copied ? copied.cards : storyboardCards(storyboard, timeline)) : [],
2587
4527
  hook: copied?.hook ?? null,
2588
4528
  // A copied ad has an end card only where its source does.
@@ -2592,8 +4532,22 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
2592
4532
  notes.push("this ffmpeg has no subtitles filter (libass), so the captions and cards were not burned in");
2593
4533
  }
2594
4534
  }
4535
+ // cleanVoice, where this ffmpeg has the filters. A voice laid whole is a song, kept as it is.
4536
+ let clean = null;
4537
+ if (finish?.cleanVoice && !timeline.mapped) {
4538
+ const missing = timeline.wholeVoice ? [] : missingFilters(CLEAN_FILTERS);
4539
+ if (timeline.wholeVoice) notes.push("the voice is a song laid whole, so it was kept as it is, not cleaned");
4540
+ else if (missing.length > 0) notes.push(`this ffmpeg has no ${missing.join(", ")} filter, so the voice was not cleaned`);
4541
+ else clean = { voice: VOICE_CLEAN, under: UNDER_VOICE };
4542
+ }
4543
+ let limiter = null;
4544
+ if (finish?.limitPeaks) {
4545
+ if (hasFilter("alimiter")) limiter = PEAK_LIMITER;
4546
+ else notes.push("this ffmpeg has no alimiter filter, so the loudness pass ran without the limiter");
4547
+ }
2595
4548
  const paths = finishPaths(out);
2596
4549
  const rendered = finish?.finishLoudness ? paths.mix : out;
4550
+ const meters = finish?.cutChecks ? { voice: paths.voice, bed: paths.bed } : null;
2597
4551
  // The burn reads its file from the folder ffmpeg runs in, so every path is absolute then.
2598
4552
  const at = ass ? (file) => path.resolve(dir, file) : here;
2599
4553
 
@@ -2617,11 +4571,63 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
2617
4571
  notes: [...missing.map((f) => `${f} is not in the folder, so it is left out`), ...plan.notes],
2618
4572
  };
2619
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
+ }
2620
4619
  const ffmpegArgs = buildFfmpegArgs(timeline, {
2621
4620
  resolve: at,
2622
4621
  music: music ? at(music) : null,
2623
4622
  out: rendered,
2624
- ...(finish ? { finish: { levelSegments: !finish.finishLoudness, ass, speed, ...(pictures.length ? { pictures } : {}) } } : {}),
4623
+ ...(finish
4624
+ ? {
4625
+ finish: {
4626
+ levelSegments: !finish.finishLoudness, ass, speed,
4627
+ ...(pictures.length ? { pictures } : {}), ...(clean ? { clean } : {}), ...(meters ? { meters } : {}),
4628
+ },
4629
+ }
4630
+ : {}),
2625
4631
  ...(mixSound ? { sound: mixSound } : {}),
2626
4632
  });
2627
4633
  const res = spawnSync("ffmpeg", ffmpegArgs, { stdio: "inherit", ...(ass ? { cwd: path.resolve(dir) } : {}) });
@@ -2629,10 +4635,16 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
2629
4635
  const quoted = ffmpegArgs.map((a) => (/[\s\[\];]/.test(a) ? `'${a}'` : a)).join(" ");
2630
4636
  throw new FirstCutError(1, `ffmpeg failed. The command it ran:\n ffmpeg ${quoted}`);
2631
4637
  }
4638
+ let meterLevels = null;
4639
+ if (meters) {
4640
+ meterLevels = { voiceLufs: measureLufs(meters.voice), bedLufs: measureLufs(meters.bed) };
4641
+ rmSync(meters.voice, { force: true });
4642
+ rmSync(meters.bed, { force: true });
4643
+ }
2632
4644
  let loudness = null;
2633
4645
  if (finish?.finishLoudness) {
2634
4646
  try {
2635
- loudness = finishLoudnessPass(rendered, out);
4647
+ loudness = finishLoudnessPass(rendered, out, limiter);
2636
4648
  } finally {
2637
4649
  rmSync(rendered, { force: true });
2638
4650
  }
@@ -2644,7 +4656,7 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
2644
4656
  const scenes = sceneTimes(timeline).map((p) =>
2645
4657
  speed === 1 ? p : { ...p, startSec: faster(p.startSec), seconds: faster(p.seconds) },
2646
4658
  );
2647
- const sidecars = sidecarPaths(out);
4659
+ const sidecars = { ...sidecarPaths(out), ...(timeline.sourceMap ? { sourceMap: sourceMapPath(out) } : {}) };
2648
4660
  if (rows.length > 0) {
2649
4661
  writeFileSync(sidecars.words, `${JSON.stringify(rows, null, 2)}\n`);
2650
4662
  writeFileSync(sidecars.srt, toSrt(rows));
@@ -2658,6 +4670,19 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
2658
4670
  "-v", "error", "-show_entries", "format=duration", "-of", "default=nw=1:nk=1", out,
2659
4671
  ]).toString().trim();
2660
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
+ }
2661
4686
 
2662
4687
  // The sound record beside the cut, and the music-only master the kind asked for.
2663
4688
  let soundRecord;
@@ -2683,15 +4708,24 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
2683
4708
  };
2684
4709
  writeFileSync(paths.sound, `${JSON.stringify(soundRecord, null, 2)}\n`);
2685
4710
  }
2686
- 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
+ };
2687
4718
  if (!finish) return withSound({ out, durationSec, manifest, timeline, music, rows, sidecars });
2688
4719
 
4720
+ const checks = finish.cutChecks
4721
+ ? checkCut({ timeline, storyboard, screens: burned, rows, scenes, out, loudness, levels: meterLevels })
4722
+ : null;
2689
4723
  // The pace record: the cut's own numbers, the settings it was cut with (so
2690
- // a redo of the run matches), and its loudness once the pass ran.
4724
+ // a redo of the run matches), its loudness once the pass ran, and its checks.
2691
4725
  const pace = {
2692
4726
  ...paceReport({
2693
4727
  ourShots: scenes.map((p) => ({ start: p.startSec, end: roundMs(p.startSec + p.seconds) })),
2694
- ...(sourceAd ? { srcShots: sourceAd.shots, srcSec: sourceAd.seconds } : {}),
4728
+ ...(sourceAd ? { srcShots: sourceAdPaceShots(sourceAd), srcSec: sourceAd.seconds } : {}),
2695
4729
  ourSec: durationSec,
2696
4730
  ourWords: rows.length,
2697
4731
  ourSilences: voicePauses(rows).filter((x) => x.s > 0.3 && x.e < durationSec - 0.3),
@@ -2699,6 +4733,7 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
2699
4733
  }),
2700
4734
  finishing: finish,
2701
4735
  ...(loudness ? { loudness } : {}),
4736
+ ...(checks ? { checks } : {}),
2702
4737
  ...(notes.length > 0 ? { notes } : {}),
2703
4738
  };
2704
4739
  writeFileSync(paths.pace, `${JSON.stringify(pace, null, 2)}\n`);