@aicopycoders/exodus 2026.11.1200-beta.2 → 2026.11.1200-beta.20

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.
@@ -49,11 +49,14 @@ import { pathToFileURL } from "node:url";
49
49
  import { planText, READOUT_INSET_BOX } from "./first-cut-text.mjs";
50
50
  import { createTextRenderer, measuredTextAss, textFrameWindow } from "./first-cut-text-render.mjs";
51
51
  import { isZeroDurationSpeech, templateActionWindows, templateJoinAnchors, templateSpeechEdit, TEMPLATE_SPEECH_LEAD_SEC, TEMPLATE_SPEECH_TAIL_SEC } from "./first-cut-speech.mjs";
52
+ import { captionSync, placementHeard, retimeWords, soundPictureCheck } from "./first-cut-sync.mjs";
52
53
 
53
54
  const USAGE = "usage: first-cut.mjs <pulled-dir> [--out cut.mp4] [--skip 2,5] [--no-music] [--still-fill]";
54
55
  const WIDTH = 1080;
55
56
  const HEIGHT = 1920;
56
57
  const FPS = 24;
58
+ /** The speed step's clock, in ticks a second: fine enough that a frame's faster time is not rounded to a whole frame. */
59
+ const SPEED_TIME_BASE = 96000;
57
60
  const norm = (label) =>
58
61
  `[${label}]scale=${WIDTH}:${HEIGHT}:force_original_aspect_ratio=decrease,` +
59
62
  `pad=${WIDTH}:${HEIGHT}:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=${FPS},format=yuv420p`;
@@ -111,6 +114,8 @@ const stereo = "aresample=48000,aformat=channel_layouts=stereo";
111
114
  const LOUDNORM = "apad=whole_dur=3,loudnorm=I=-16:TP=-1.5:LRA=11,aresample=48000,asetpts=N/SR/TB";
112
115
  /** A fade this short at each edge of a segment's sound stops a hard cut in the room tone clicking. */
113
116
  const EDGE_FADE_SEC = 0.015;
117
+ /** COP-300: the fade-out at the end of a sped-up cut's sound, after it is cut to the picture: 10 ms at 48 kHz. */
118
+ const END_FADE_SAMPLES = 480;
114
119
  /**
115
120
  * Air after a narrator's last word. Sizing by the voice file plus 0.8 s left
116
121
  * ~1.1 s of silence at every narrator join, since the file already runs on
@@ -194,11 +199,32 @@ export const FINISH_LRA = 11;
194
199
  export const TRUE_PEAK_MAX_DB = -1;
195
200
  /**
196
201
  * limitPeaks: after the loudness pass, the sound oversampled 4x through a
197
- * limiter at 0.8 (about -1.9 dB), so a peak between two samples is caught too.
202
+ * limiter at PEAK_LIMIT (about -1.9 dB), so a peak between two samples is caught too.
198
203
  * The cut is still measured after and refused over TRUE_PEAK_MAX_DB. Its
199
204
  * resample is pinned to stereo, as every one after loudnorm is (loudnessApplyArgs).
200
205
  */
201
- export const PEAK_LIMITER = "aresample=192000,aformat=channel_layouts=stereo,alimiter=limit=0.8:level=false:attack=2:release=60";
206
+ export const PEAK_LIMIT = 0.8;
207
+ /** The limiter at `limit`, a linear level alimiter takes from 0.0625 to 1. */
208
+ export function peakLimiter(limit = PEAK_LIMIT) {
209
+ return `aresample=192000,aformat=channel_layouts=stereo,alimiter=limit=${limit}:level=false:attack=2:release=60`;
210
+ }
211
+ export const PEAK_LIMITER = peakLimiter();
212
+ /**
213
+ * #4573: the AAC encode after the limiter can put a peak back over
214
+ * TRUE_PEAK_MAX_DB, by a different amount on each cut of the same takes (the
215
+ * room tone is fresh noise every time). A limited cut that lands over is
216
+ * limited again from the same mix, this many times at most, each time lower by
217
+ * what the last one landed over FINISH_TRUE_PEAK; still over, it is refused.
218
+ */
219
+ export const LIMIT_AGAIN_MAX = 2;
220
+ /** The lowest ceiling a limit again goes to (about -6 dB): a cut that needs lower is refused, not squashed. */
221
+ const PEAK_LIMIT_MIN = 0.5;
222
+
223
+ /** The next ceiling down after a limited pass measured `tp` dBTP. */
224
+ export function lowerPeakLimit(limit, tp) {
225
+ const lower = limit * 10 ** (-(tp - FINISH_TRUE_PEAK) / 20);
226
+ return Math.max(PEAK_LIMIT_MIN, Math.round(lower * 10_000) / 10_000);
227
+ }
202
228
  /**
203
229
  * jumpCut: inside a talking clip, a pause over maxGap between two heard words
204
230
  * is cut down, keeping keepAfter after the earlier word and keepBefore before
@@ -261,6 +287,8 @@ export function finishingOf(manifest) {
261
287
  ...(on.captions && f.captionsByLine === true && f.captionColours === true ? { captionColours: true } : {}),
262
288
  ...(f.pacePass === true ? { pacePass: true } : {}),
263
289
  ...(f.pacePass === true && paceSpeedOk(f.paceSpeed) ? { paceSpeed: f.paceSpeed } : {}),
290
+ ...(f.captionCheck === true ? { captionCheck: true } : {}),
291
+ ...(f.keepPauses === true ? { keepPauses: true } : {}),
264
292
  };
265
293
  if (!Object.values(on).some(Boolean) && Object.keys(added).length === 0) return null;
266
294
  const target = f.targetSeconds;
@@ -603,12 +631,21 @@ function spokenWords(word) {
603
631
  return spokenForms(word).flatMap((t) => SPOKEN_FORMS.get(t) ?? [t]).map((t) => SAME_WORD_SPELLINGS.get(t) ?? t);
604
632
  }
605
633
 
634
+ /**
635
+ * COP-311: a scribe writes two words it heard as one with a slash ("probiotic/an" for "probiotic and"): the
636
+ * aligners read them as the words they are, as scout scribe.ts slashParts. A number ("1/2", "24/7") stays whole.
637
+ */
638
+ function slashParts(word) {
639
+ const parts = String(word ?? "").split("/").filter(Boolean);
640
+ return parts.length > 1 && parts.every((p) => /\p{L}/u.test(p)) ? parts : [word];
641
+ }
642
+
606
643
  /** { tokens, sourceIndex }: tokens[i] came from written word sourceIndex[i]. */
607
- function spokenTokens(words) {
644
+ function spokenTokens(words, partsOf = (word) => [word]) {
608
645
  const tokens = [];
609
646
  const sourceIndex = [];
610
647
  words.forEach((word, i) => {
611
- for (const token of spokenWords(word)) {
648
+ for (const token of partsOf(word).flatMap(spokenWords)) {
612
649
  tokens.push(token);
613
650
  sourceIndex.push(i);
614
651
  }
@@ -699,6 +736,24 @@ const soundKey = (token) =>
699
736
  .replace(/(?<=\w{3})oe$/, "o")
700
737
  .replace(/(?<=[aeiou])z$/, "s");
701
738
 
739
+ /**
740
+ * The script's and the heard words' tokens as the aligner compares them, and
741
+ * its word match: matches(e, h) when script token e is said by heard token h.
742
+ * `slash`: both sides read a word written with a slash as its words (COP-311).
743
+ */
744
+ function scriptTokens(words, written, slash = true) {
745
+ const partsOf = slash ? slashParts : undefined;
746
+ const scripted = spokenTokens(written, partsOf);
747
+ const heardWords = spokenTokens(words.map((w) => w.w), partsOf);
748
+ const nameLike = nameLikeWords(written);
749
+ const names = scripted.tokens.filter((_, t) => nameLike[scripted.sourceIndex[t]]);
750
+ const heard = joinSplitWords(heardWords, scripted.tokens, names);
751
+ const expected = joinSplitWords(scripted, heard.tokens);
752
+ const matches = (e, h) =>
753
+ h < heard.tokens.length && sameWord(expected.tokens[e], heard.tokens[h], nameLike[expected.sourceIndex[e]]);
754
+ return { heardWords, heard, expected, matches };
755
+ }
756
+
702
757
  /**
703
758
  * Where the script's first complete, in-order delivery sits in the heard
704
759
  * words, or null. heardTokenOf/heardWordOf give the heard token and word that
@@ -708,15 +763,13 @@ const soundKey = (token) =>
708
763
  * exact delivery wins. Mirrors scout scribe.ts alignScript.
709
764
  */
710
765
  function alignScript(words, written) {
711
- const scripted = spokenTokens(written);
712
- const heardWords = spokenTokens(words.map((w) => w.w));
713
- const nameLike = nameLikeWords(written);
714
- const names = scripted.tokens.filter((_, t) => nameLike[scripted.sourceIndex[t]]);
715
- const heard = joinSplitWords(heardWords, scripted.tokens, names);
716
- const expected = joinSplitWords(scripted, heard.tokens);
766
+ // COP-311: read with the slash words split, else as written, so a take found before ("salt and/or pepper"
767
+ // said "salt and pepper") is still found. Mirrors scout scribe.ts alignScript.
768
+ return alignTokens(scriptTokens(words, written, true)) ?? alignTokens(scriptTokens(words, written, false));
769
+ }
770
+
771
+ function alignTokens({ heardWords, heard, expected, matches }) {
717
772
  if (expected.tokens.length === 0 || heard.tokens.length === 0) return null;
718
- const matches = (e, h) =>
719
- h < heard.tokens.length && sameWord(expected.tokens[e], heard.tokens[h], nameLike[expected.sourceIndex[e]]);
720
773
  const pair = (allowMisheard) => {
721
774
  const tokenOf = [];
722
775
  let j = 0;
@@ -739,6 +792,90 @@ function alignScript(words, written) {
739
792
  };
740
793
  }
741
794
 
795
+ /** scriptTimes: sounds a speaker makes between words; one never stands in the place of a script word. */
796
+ const FILLER_TOKENS = new Set(["um", "umm", "uhm", "uh", "uhh", "er", "erm", "ah", "hmm", "mm", "mhm"]);
797
+ /** scriptTimes: a take with fewer of its script's tokens heard as written than this share is not the script misheard. */
798
+ const MIN_HEARD_SHARE = 0.5;
799
+
800
+ /**
801
+ * COP-311, Mario's "Fix the text, never the times", for a take where
802
+ * alignScript finds no delivery of the whole script in order: the script's
803
+ * tokens and the heard ones are paired by their longest common run, with the
804
+ * aligner's word match. The script tokens left between two pairs take the
805
+ * time of the heard words left in their place, a filler ("um") never one of
806
+ * them: one heard token each when the counts are the same, else, with one
807
+ * heard token more (a word heard as two), the span of them shared evenly by
808
+ * the script words there. Before the first pair or after the last, only one
809
+ * heard token each: a lead-in ("Okay so") or a sign-off ("Thanks guys") is
810
+ * not told apart from a misheard first or last word, so neither is shown.
811
+ * Every other place times nothing: a script word dropped, or said over words
812
+ * the script does not have, is not shown, and a heard word with no script
813
+ * word in its place times nothing. A take with fewer than MIN_HEARD_SHARE of
814
+ * its script tokens heard as written says something else: only those are
815
+ * timed. A script word with a digit ("$23.08", "30%") is timed only where
816
+ * its number words are heard as written ("dollars" may be heard as "oh"),
817
+ * so a number said otherwise is never shown. `times[e]` is script token e's [start, end] on the heard words'
818
+ * clock, or null.
819
+ */
820
+ function scriptTimes(words, written) {
821
+ const { heard, expected, matches } = scriptTokens(words, written);
822
+ const n = expected.tokens.length;
823
+ const m = heard.tokens.length;
824
+ // run[e * (m + 1) + h]: the longest common run of script tokens e.. and heard tokens h..
825
+ const run = new Int32Array((n + 1) * (m + 1));
826
+ const at = (e, h) => run[e * (m + 1) + h];
827
+ for (let e = n - 1; e >= 0; e--) {
828
+ for (let h = m - 1; h >= 0; h--) {
829
+ run[e * (m + 1) + h] = matches(e, h) ? at(e + 1, h + 1) + 1 : Math.max(at(e + 1, h), at(e, h + 1));
830
+ }
831
+ }
832
+ // Each script token on its earliest heard token that keeps the run longest.
833
+ const pairs = [[-1, -1]];
834
+ for (let e = 0, h = 0; e < n && h < m; ) {
835
+ if (matches(e, h)) pairs.push([e++, h++]);
836
+ else if (at(e, h + 1) >= at(e + 1, h)) h++;
837
+ else e++;
838
+ }
839
+ pairs.push([n, m]);
840
+ const span = (from, to) => [words[heard.sourceIndex[from]].s, words[heard.lastSourceIndex[to]].e];
841
+ const times = new Array(n).fill(null);
842
+ const scriptHeard = pairs.length - 2 >= n * MIN_HEARD_SHARE;
843
+ for (let k = 0; k + 1 < pairs.length; k++) {
844
+ const [e0, h0] = pairs[k];
845
+ const [e1, h1] = pairs[k + 1];
846
+ if (e0 >= 0) times[e0] = span(h0, h0);
847
+ const left = e1 - e0 - 1;
848
+ if (!scriptHeard || left === 0) continue;
849
+ const places = [];
850
+ for (let h = h0 + 1; h < h1; h++) if (!FILLER_TOKENS.has(heard.tokens[h])) places.push(h);
851
+ // At an end, a heard word more is a lead-in or a sign-off as likely as a word heard as two.
852
+ if ((e0 < 0 || e1 === n) && places.length !== left) continue;
853
+ if (places.length === left) {
854
+ for (let i = 0; i < left; i++) times[e0 + 1 + i] = span(places[i], places[i]);
855
+ } else if (places.length === left + 1) {
856
+ const [gapStart, gapEnd] = span(places[0], places.at(-1));
857
+ const owners = [...new Set(expected.sourceIndex.slice(e0 + 1, e1))];
858
+ const share = (gapEnd - gapStart) / owners.length;
859
+ for (let t = e0 + 1; t < e1; t++) {
860
+ const u = owners.indexOf(expected.sourceIndex[t]);
861
+ times[t] = [gapStart + u * share, gapStart + (u + 1) * share];
862
+ }
863
+ }
864
+ }
865
+ // A number token of a script word with a digit not heard as written: that word is not shown.
866
+ const paired = new Set(pairs.slice(1, -1).map(([e]) => e));
867
+ const numberToken = (token) => NUMBER_WORDS.has(token) || /\p{N}/u.test(token);
868
+ const unheardNumbers = new Set();
869
+ for (let e = 0; e < n; e++) {
870
+ if (paired.has(e) || !numberToken(expected.tokens[e])) continue;
871
+ for (let i = expected.sourceIndex[e]; i <= expected.lastSourceIndex[e]; i++) if (/\p{N}/u.test(written[i])) unheardNumbers.add(i);
872
+ }
873
+ for (let e = 0; e < n; e++) {
874
+ for (let i = expected.sourceIndex[e]; i <= expected.lastSourceIndex[e]; i++) if (unheardNumbers.has(i)) times[e] = null;
875
+ }
876
+ return { expected, times };
877
+ }
878
+
742
879
  /**
743
880
  * #2541: the indexes of the heard words that deliver the first and last
744
881
  * scripted word, matching the script in order at its earliest delivery, or null
@@ -820,8 +957,12 @@ export function asksPause(line) {
820
957
  * script words, inside a sentence too, keeps jump.keepAfter after the earlier
821
958
  * word and jump.keepBefore before the later one instead (jumpCutSpan), on
822
959
  * whole frames. The pauses kept above stay kept.
960
+ *
961
+ * gapMax (COP-350, keepPauses): the longest silence between two sentences that
962
+ * is kept whole, SENTENCE_GAP_MAX_SEC unless given. Infinity shortens no pause,
963
+ * and only a sound in a break is cut.
823
964
  */
824
- export function sentenceGapCuts(words, lines, levels = null, lineGap = null, jump = null) {
965
+ export function sentenceGapCuts(words, lines, levels = null, lineGap = null, jump = null, gapMax = SENTENCE_GAP_MAX_SEC) {
825
966
  const written = [];
826
967
  const pieces = [];
827
968
  let between = "";
@@ -863,11 +1004,11 @@ export function sentenceGapCuts(words, lines, levels = null, lineGap = null, jum
863
1004
  const sound = heard && { s: Math.max(floorFrame(heard.s), ceilFrame(earlier.e)), e: ceilFrame(heard.e) };
864
1005
  const removed = sound ? sound.e - sound.s : 0;
865
1006
  const spans = sound ? [sound] : [];
866
- const [gapMax, gapKeep] =
867
- lineGap && newLine ? [lineGap.max, lineGap.keep] : [SENTENCE_GAP_MAX_SEC, SENTENCE_GAP_KEEP_SEC];
1007
+ const [breakMax, gapKeep] =
1008
+ lineGap && newLine ? [lineGap.max, lineGap.keep] : [gapMax, SENTENCE_GAP_KEEP_SEC];
868
1009
  // jumpCut: a pause over its longest keeps its two edges, with a sound in it taken out whole.
869
1010
  const jumped = Boolean(jump) && gap - removed > jump.maxGap + 1e-6;
870
- const paused = jumped || (sentenceBreak && gap - removed > gapMax + 1e-6);
1011
+ const paused = jumped || (sentenceBreak && gap - removed > breakMax + 1e-6);
871
1012
  if (paused) {
872
1013
  // Placed on the gap with the sound already out, then moved back past it.
873
1014
  // Frame edges only ever widen what is kept, so the silence left stays
@@ -971,7 +1112,7 @@ function clipLevels(file, filter = null) {
971
1112
  /** Decoded final-mix levels; callers must not attribute an event to these whole-mix windows. */
972
1113
  export const measureCutAudio = (file) => clipLevels(file);
973
1114
 
974
- function tightenSentenceGaps(spine, reactionCues, scriptLines, readLevels, lineGap = null, jump = null, templateBoard = null, editingTreatment = null, notes = []) {
1115
+ function tightenSentenceGaps(spine, reactionCues, scriptLines, readLevels, lineGap = null, jump = null, templateBoard = null, editingTreatment = null, notes = [], gapMax = SENTENCE_GAP_MAX_SEC) {
975
1116
  for (const seg of spine) {
976
1117
  if (seg.source !== "clip" || seg.audio !== "clip" || !seg.words?.length || seg.fixedLength) continue;
977
1118
  const lines = seg.lineIds.map((id) => ({
@@ -993,7 +1134,7 @@ function tightenSentenceGaps(spine, reactionCues, scriptLines, readLevels, lineG
993
1134
  }) : null;
994
1135
  const sentenceCuts = templateBoard
995
1136
  ? edit && lineGap ? sentenceGapCuts(seg.words, lines, null, lineGap) : []
996
- : sentenceGapCuts(seg.words, lines, readLevels(seg.file), lineGap, jump);
1137
+ : sentenceGapCuts(seg.words, lines, readLevels(seg.file), lineGap, jump, gapMax);
997
1138
  const jumpCuts = (edit?.cuts ?? []).map((gap) => ({
998
1139
  s: gap.startSec, e: gap.endSec, after: "speech", gap: gap.endSec - gap.startSec, kept: 0,
999
1140
  atLine: sentenceCuts.find((cut) => cut.s < gap.endSec && cut.e > gap.startSec)?.atLine,
@@ -2060,9 +2201,11 @@ function trimTemplateTerminalSilence(file, timeline, manifest, board, notes) {
2060
2201
  if (Math.max(authoredEnd, reservedEnd, resolvedEnd) > silenceStart + 1 / FPS) notes.push(
2061
2202
  `terminal-silence-authored: measured -50dB EOF silence starts ${silenceStart.toFixed(3)}s; ` +
2062
2203
  `resolved picture/acting reservation retained through ${Math.max(authoredEnd, reservedEnd, resolvedEnd).toFixed(3)}s, not claimed observed`);
2204
+ // #4585: the end card is quiet after the voice on purpose, so a cut with one is never trimmed short of its end.
2205
+ const cardEnd = timeline.endCard ? Math.max(0, ...timeline.spine.map((seg) => seg.startSec + seg.seconds)) : 0;
2063
2206
  const frames = Math.max(Math.ceil(silenceStart * FPS - 1e-6),
2064
2207
  Math.floor((lastWord + .3) * FPS + 1e-6), Math.ceil(authoredEnd * FPS - 1e-6),
2065
- Math.ceil(reservedEnd * FPS - 1e-6), Math.ceil(resolvedEnd * FPS - 1e-6));
2208
+ Math.ceil(reservedEnd * FPS - 1e-6), Math.ceil(resolvedEnd * FPS - 1e-6), Math.ceil(cardEnd * FPS - 1e-6));
2066
2209
  if (frames >= media.picture.frames || frames <= 0) return false;
2067
2210
  const endSec = frames / FPS;
2068
2211
  const spine = timeline.spine.filter((seg) => seg.startSec < endSec).map((seg) => {
@@ -3147,8 +3290,14 @@ function assembleTimeline({
3147
3290
  const lineGap = pace ? { max: PACE_SPLIT_PAUSE_SEC, keep: PACE_GAP_MAX_SEC } : null;
3148
3291
  // jumpCut stays off a template launch's cut, whose selected clocks and windows hold their real time.
3149
3292
  const jump = finish?.jumpCut && manifest?.templateMotion?.enabled !== true ? JUMP_CUT : null;
3150
- tightenSentenceGaps(spine, reactionCues, scriptLines, readLevels, lineGap, jump, template ? storyboard : null,
3151
- template ? manifest.templateMotion.editingTreatment : null, notes);
3293
+ // keepPauses (COP-350, a run's saved sheet): no pause inside a talking clip is shortened, neither a long sentence gap
3294
+ // nor jumpCut's (no gap limit, no jump, no split); a sound in a break that is no heard word is still cut (#2554). A
3295
+ // template launch's own speech edit runs as before.
3296
+ const keepPauses = finish?.keepPauses === true && !template;
3297
+ if (keepPauses) notes.push("keepPauses: no pause inside a clip is shortened; a sound in one that is no heard word is still cut");
3298
+ tightenSentenceGaps(spine, reactionCues, scriptLines, readLevels, keepPauses ? null : lineGap, keepPauses ? null : jump,
3299
+ template ? storyboard : null, template ? manifest.templateMotion.editingTreatment : null, notes,
3300
+ keepPauses ? Infinity : SENTENCE_GAP_MAX_SEC);
3152
3301
  trimJoins(spine, reactionCues, scriptLines, pace ? PACE_GAP_MAX_SEC : null, finish?.talkTrim === true);
3153
3302
  if (pace) {
3154
3303
  // The pieces of one take alternate between the plain frame and the
@@ -3792,10 +3941,11 @@ function mappedPiece(seg, i, { addInput, filters, tails, level, resolve }) {
3792
3941
  * The render. `finish` (null: today's render) carries the finishing settings'
3793
3942
  * part of it: levelSegments false leaves each segment's sound as it is for the
3794
3943
  * whole mix's loudness pass, `ass` names the captions and cards file burned in
3795
- * (read from the folder ffmpeg runs in), `speed` over 1 speeds the whole
3796
- * cut, picture and sound, after the burn, `clean` (cleanVoice) is the voice's
3944
+ * (read from the folder ffmpeg runs in) after the speed step, on the finished
3945
+ * cut's clock, `speed` over 1 speeds the whole cut, picture and sound, `clean` (cleanVoice) is the voice's
3797
3946
  * chain and the duck under it, and `meters` (cutChecks) names the two files
3798
- * the voice and everything under it are also written to.
3947
+ * the voice and everything under it are also written to. `pcmMix` keeps the
3948
+ * render's sound uncompressed, for a mix the loudness pass then encodes once.
3799
3949
  */
3800
3950
  export function buildFfmpegArgs(timeline, { resolve, music, out, finish = null, sound = null }) {
3801
3951
  const level = finish && finish.levelSegments === false ? "anull" : LOUDNORM;
@@ -3859,9 +4009,12 @@ export function buildFfmpegArgs(timeline, { resolve, music, out, finish = null,
3859
4009
  const [fadeIn, fadeOut] = [seg.fadeInSec ?? EDGE_FADE_SEC, seg.fadeOutSec ?? EDGE_FADE_SEC];
3860
4010
  // A cubic rise keeps a reaction's quiet start near silent until its laugh (#2666).
3861
4011
  const rise = fadeIn > EDGE_FADE_SEC ? ":curve=cub" : "";
4012
+ // #4585: the end card's held picture runs on in silence after the segment's own sound has faded out.
4013
+ const sounding = seg.seconds - (seg.endCardHoldSec ?? 0);
3862
4014
  const fitLength =
3863
- `apad,atrim=0:${sec(seg.seconds)},afade=t=in:d=${sec(fadeIn)}${rise},` +
3864
- `afade=t=out:st=${sec(seg.seconds - fadeOut)}:d=${sec(fadeOut)}`;
4015
+ `apad,atrim=0:${sec(sounding)},afade=t=in:d=${sec(fadeIn)}${rise},` +
4016
+ `afade=t=out:st=${sec(sounding - fadeOut)}:d=${sec(fadeOut)}` +
4017
+ (seg.endCardHoldSec ? `,apad,atrim=0:${sec(seg.seconds)}` : "");
3865
4018
  const fitSound = `${level},${fitLength}`;
3866
4019
  if (seg.wholeVoice) {
3867
4020
  filters.push(`anullsrc=r=48000:cl=stereo,atrim=0:${sec(seg.seconds)}[a${i}]`);
@@ -3963,36 +4116,43 @@ export function buildFfmpegArgs(timeline, { resolve, music, out, finish = null,
3963
4116
  );
3964
4117
  videoLabel = `pin${j}`;
3965
4118
  });
3966
- // endCardLayers: the brand's ground over the whole frame, then the pack photo in its box, pushing in slowly.
4119
+ // endCardLayers: the brand's ground over the whole frame and the pack photo in its box, pushing in slowly, made as
4120
+ // one card on its own clock and dissolved in over the last picture (#4585: never the ground alone, never black).
3967
4121
  if (finish?.endCard) {
3968
4122
  const e = finish.endCard;
3969
4123
  const box = END_CARD_PHOTO_BOX;
3970
4124
  const w = even((box[2] - box[0]) * WIDTH);
3971
4125
  const h = even((box[3] - box[1]) * HEIGHT);
3972
4126
  const frames = Math.max(1, Math.round(e.seconds * FPS));
3973
- const k = addInput("-loop", "1", "-t", sec(e.seconds), "-i", resolve(e.file));
3974
- filters.push(`color=c=0x${e.colors.background}:s=${WIDTH}x${HEIGHT}:r=${FPS}:d=${sec(e.out)},format=yuv420p[ecground]`);
3975
- filters.push(`[${videoLabel}][ecground]overlay=enable=between(t\\,${sec(e.in)}\\,${sec(e.out)}):eof_action=pass[ecg]`);
4127
+ const length = sec(e.out - e.in);
4128
+ const k = addInput("-loop", "1", "-t", length, "-i", resolve(e.file));
4129
+ filters.push(`color=c=0x${e.colors.background}:s=${WIDTH}x${HEIGHT}:r=${FPS}:d=${length},format=yuv420p[ecground]`);
3976
4130
  filters.push(
3977
4131
  `[${k}:v]fps=${FPS},scale=${w}:${h}:force_original_aspect_ratio=decrease,` +
3978
4132
  `pad=${w}:${h}:(ow-iw)/2:(oh-ih)/2:color=0x${e.colors.background},setsar=1,` +
3979
4133
  `zoompan=z=1+${END_CARD_PUSH_IN}*on/${frames}:x=iw/2-(iw/zoom/2):y=ih/2-(ih/zoom/2):d=1:s=${w}x${h}:fps=${FPS},` +
3980
- `format=yuv420p,fade=t=in:st=0:d=${END_CARD_PHOTO_FADE_SEC},setpts=PTS-STARTPTS+${sec(e.in)}/TB[ecpic]`,
4134
+ `format=yuv420p[ecpic]`,
3981
4135
  );
3982
4136
  filters.push(
3983
- `[ecg][ecpic]overlay=x=${Math.round(box[0] * WIDTH)}:y=${Math.round(box[1] * HEIGHT)}:enable=between(t\\,${sec(e.in)}\\,${sec(e.out)}):eof_action=pass[ecard]`,
4137
+ `[ecground][ecpic]overlay=x=${Math.round(box[0] * WIDTH)}:y=${Math.round(box[1] * HEIGHT)},` +
4138
+ `format=yuva420p,fade=t=in:st=0:d=${END_CARD_FADE_SEC}:alpha=1,setpts=PTS-STARTPTS+${sec(e.in)}/TB[ecbody]`,
3984
4139
  );
4140
+ filters.push(`[${videoLabel}][ecbody]overlay=enable=between(t\\,${sec(e.in)}\\,${sec(e.out)}):eof_action=pass[ecard]`);
3985
4141
  videoLabel = "ecard";
3986
4142
  }
3987
- if (finish?.ass) {
3988
- filters.push(`[${videoLabel}]subtitles=filename=${finish.ass}[burned]`);
3989
- videoLabel = "burned";
3990
- }
3991
4143
  const speed = finish?.speed > 1 ? finish.speed : null;
3992
4144
  if (speed) {
3993
- filters.push(`[${videoLabel}]setpts=PTS/${speed}[faster]`);
4145
+ // COP-300: on the frames' own 1/24 clock, setpts rounds each faster time to a whole tick and `-r` then shows the
4146
+ // picture about 1.5 frames late; on a fine clock, `fps` puts each frame on the 24 fps tick nearest its true time.
4147
+ filters.push(`[${videoLabel}]settb=1/${SPEED_TIME_BASE},setpts=PTS/${speed},fps=${FPS}:round=near[faster]`);
3994
4148
  videoLabel = "faster";
3995
4149
  }
4150
+ // COP-300: burned after the speed step, on the finished cut's own frames, so no speed step can move the captions
4151
+ // off the voice. The ASS file is timed on that clock (editAss `speed`).
4152
+ if (finish?.ass) {
4153
+ filters.push(`[${videoLabel}]subtitles=filename=${finish.ass}[burned]`);
4154
+ videoLabel = "burned";
4155
+ }
3996
4156
 
3997
4157
  const beds = [];
3998
4158
  if (sound?.beds?.length) {
@@ -4087,7 +4247,11 @@ export function buildFfmpegArgs(timeline, { resolve, music, out, finish = null,
4087
4247
  );
4088
4248
  let audioLabel = "mix";
4089
4249
  if (speed) {
4090
- filters.push(`[mix]atempo=${speed}[mixfaster]`);
4250
+ // COP-300: the faster sound padded or cut to the faster picture's own length, as each segment's is to its
4251
+ // picture's: `fps` ends the picture on round(frames / speed) frames, and atempo runs on past it. The cut can land
4252
+ // in a word's tail, so the last END_FADE_SAMPLES fade out, as each segment's edges do, and the end never clicks.
4253
+ const end = Math.round(Math.round(pictureSec * FPS) / speed + 1e-9) * SAMPLES_PER_FRAME;
4254
+ filters.push(`[mix]atempo=${speed},apad,atrim=end_sample=${end},afade=t=out:ss=${end - END_FADE_SAMPLES}:ns=${END_FADE_SAMPLES}[mixfaster]`);
4091
4255
  audioLabel = "mixfaster";
4092
4256
  }
4093
4257
 
@@ -4097,7 +4261,8 @@ export function buildFfmpegArgs(timeline, { resolve, music, out, finish = null,
4097
4261
  "-filter_complex", filters.join(";"),
4098
4262
  "-map", `[${videoLabel}]`, "-map", `[${audioLabel}]`,
4099
4263
  "-c:v", "libx264", "-preset", "medium", "-crf", "20", "-r", String(FPS),
4100
- "-c:a", "aac", "-b:a", "192k",
4264
+ // COP-300: a mix the loudness pass finishes keeps its sound uncompressed, so the finished cut's sound is AAC-encoded once.
4265
+ ...(finish?.pcmMix ? ["-c:a", "pcm_s16le"] : ["-c:a", "aac", "-b:a", "192k"]),
4101
4266
  "-movflags", "+faststart",
4102
4267
  out,
4103
4268
  ...(finish?.meters
@@ -4194,7 +4359,8 @@ export function sceneTimes(timeline, exact = false) {
4194
4359
  .filter((c) => c.seconds > 0)
4195
4360
  .map((c) => ({ from: c.startSec, to: c.startSec + c.seconds }));
4196
4361
  const visible = timeline.spine.flatMap((seg) => {
4197
- let pieces = [{ from: seg.startSec, to: seg.startSec + seg.seconds }];
4362
+ // #4585: the picture held under the end card is the card's, not the scene's.
4363
+ let pieces = [{ from: seg.startSec, to: seg.startSec + seg.seconds - (seg.endCardHoldSec ?? 0) }];
4198
4364
  for (const c of covers) {
4199
4365
  pieces = pieces.flatMap((p) =>
4200
4366
  c.to <= p.from || c.from >= p.to
@@ -4450,10 +4616,16 @@ export function noWordTimes(timeline) {
4450
4616
 
4451
4617
  const pad2 = (n) => String(n).padStart(2, "0");
4452
4618
  const round2 = (n) => Math.round(n * 100) / 100;
4453
- const assTime = (t) => {
4454
- const cs = Math.round(Math.max(0, t) * 100);
4455
- return `${Math.floor(cs / 360000)}:${pad2(Math.floor(cs / 6000) % 60)}:${pad2(Math.floor(cs / 100) % 60)}.${pad2(cs % 100)}`;
4456
- };
4619
+ const csTime = (cs) => `${Math.floor(cs / 360000)}:${pad2(Math.floor(cs / 6000) % 60)}:${pad2(Math.floor(cs / 100) % 60)}.${pad2(cs % 100)}`;
4620
+ const assTime = (t) => csTime(Math.round(Math.max(0, t) * 100));
4621
+ /**
4622
+ * COP-300: a caption's start, in centiseconds of the finished cut, on the frame that holds its word's start: that
4623
+ * frame's own time floored to the centisecond, so libass draws the caption from that frame on. Rounded to the
4624
+ * centisecond as other times are, it came up on the frame after about half the time.
4625
+ */
4626
+ export const captionStartCs = (t) => Math.floor((Math.floor(Math.max(0, t) * FPS + 1e-6) * 100) / FPS + 1e-9);
4627
+ /** The time a caption starting at `cs` (centiseconds) is first seen: the first frame at or after it. */
4628
+ export const captionSeenSec = (cs) => Math.ceil((cs / 100) * FPS - 1e-6) / FPS;
4457
4629
  const assText = (s) => String(s).replace(/[{}\\]/g, "").replace(/\s*[\r\n]+\s*/g, " ").trim();
4458
4630
 
4459
4631
  /** A caption screen never holds words across a pause longer than this, so a silent beat shows none. */
@@ -4568,14 +4740,14 @@ export function lineCaptionScreens(words, cap = null) {
4568
4740
 
4569
4741
  /**
4570
4742
  * captionsByLine: the cut's words in its own time, each with the script line
4571
- * it belongs to. Where a segment's script is heard in order (alignScript),
4572
- * they are the script's words as written, each timed by the heard words that
4573
- * say it; elsewhere they are the heard words, each on the line its place among
4574
- * the script's words gives it, the way a cue line is found (lineInSegment).
4743
+ * it belongs to. They are the script's words as written, never a heard word
4744
+ * the script does not have (COP-311). Where a segment's script is heard in
4745
+ * order (alignScript), each is timed by the heard words that say it;
4746
+ * elsewhere by the heard words in its place (scriptTimes), and a script word
4747
+ * with nothing heard in its place is left out.
4575
4748
  */
4576
4749
  export function lineWords(timeline, storyboard) {
4577
4750
  const texts = new Map((storyboard?.script ?? []).map((line) => [line?.lineId, line?.text]));
4578
- const counts = lineWordCounts(storyboard);
4579
4751
  const rows = [];
4580
4752
  for (const seg of timeline.spine) {
4581
4753
  const heard = seg.words ?? [];
@@ -4595,27 +4767,62 @@ export function lineWords(timeline, storyboard) {
4595
4767
  });
4596
4768
  continue;
4597
4769
  }
4598
- const ends = [];
4599
- let n = 0;
4600
- for (const id of seg.lineIds) ends.push((n += counts.get(id) ?? 0));
4601
- heard.forEach((w, i) => {
4602
- const text = (w.w ?? "").trim();
4603
- const start = at(w.s);
4604
- const end = at(w.e);
4605
- if (!text || end <= start) return;
4606
- const j = ends.findIndex((last) => Math.min(i, n - 1) < last);
4607
- rows.push({ text, start, end, line: seg.lineIds[j] ?? seg.lineIds.at(-1) ?? `scene ${seg.sceneIndex}` });
4770
+ // COP-311: the script's words still, each on the time of what was heard in its place (scriptTimes).
4771
+ const lineOf = lines.flatMap((ws, j) => ws.map(() => seg.lineIds[j]));
4772
+ const { expected, times } = scriptTimes(heard, lines.flat());
4773
+ lines.flat().forEach((text, i) => {
4774
+ const said = times.filter((time, e) => time && expected.sourceIndex[e] <= i && i <= expected.lastSourceIndex[e]);
4775
+ if (said.length === 0) return;
4776
+ const start = at(said[0][0]);
4777
+ const end = at(said.at(-1)[1]);
4778
+ if (end > start) rows.push({ text, start, end, line: lineOf[i] });
4608
4779
  });
4609
4780
  }
4610
- return rows;
4781
+ return sharedHeardWords(rows);
4782
+ }
4783
+
4784
+ /**
4785
+ * lineWords: script words that start on one heard word but are not timed
4786
+ * alike ("probiotics/and" ending one line and starting the next) take that
4787
+ * word's time (to the earliest of their ends) in turn, so no caption screen
4788
+ * is cleared before its word is said. A word that runs on past it keeps its
4789
+ * own end. Words timed alike on one line stay on one screen
4790
+ * (lineCaptionScreens).
4791
+ */
4792
+ function sharedHeardWords(rows) {
4793
+ const out = [];
4794
+ for (let i = 0; i < rows.length; ) {
4795
+ let j = i + 1;
4796
+ while (j < rows.length && rows[j].start === rows[i].start) j++;
4797
+ const run = rows.slice(i, j);
4798
+ const keys = [...new Set(run.map((r) => `${r.line}|${r.end}`))];
4799
+ if (keys.length === 1) out.push(...run);
4800
+ else {
4801
+ const start = run[0].start;
4802
+ const shared = Math.min(...run.map((r) => r.end));
4803
+ const slot = (shared - start) / keys.length;
4804
+ for (const r of run) {
4805
+ const u = keys.indexOf(`${r.line}|${r.end}`);
4806
+ out.push({ ...r, start: roundMs(start + u * slot), end: r.end > shared ? r.end : roundMs(start + (u + 1) * slot) });
4807
+ }
4808
+ }
4809
+ i = j;
4810
+ }
4811
+ return out;
4611
4812
  }
4612
4813
 
4613
4814
  /**
4614
4815
  * One ASS file for the burn: the caption screens in their band, the cards in
4615
4816
  * their boxes, the hook box and the end card. Boxes are [x0, y0, x1, y1] as
4616
4817
  * shares of the frame. Every word on screen is the script's or the storyboard's.
4818
+ * Every time given is on the cut's clock before its speed-up; the file is on
4819
+ * the finished cut's (each time over `speed`), since it is burned after the speed step.
4617
4820
  */
4618
- export function editAss({ captions = [], cap = null, cards = [], hook = null, endCard = null, endLayers = null, capMaxShare = null }, W = WIDTH, H = HEIGHT) {
4821
+ export function editAss({ captions = [], cap = null, cards = [], hook = null, endCard = null, endLayers = null, capMaxShare = null, speed = 1 }, W = WIDTH, H = HEIGHT) {
4822
+ const at = (t) => assTime(t / speed);
4823
+ // Each caption from the frame of its first word, and off by the time the next one comes up.
4824
+ const starts = captions.map((c) => captionStartCs(c.s / speed));
4825
+ const end = (c, k) => csTime(Math.min(Math.round(Math.max(0, c.e / speed) * 100), starts[k + 1] ?? Infinity));
4619
4826
  const thick = /thick black outline/i.test(cap?.style ?? "");
4620
4827
  const y = cap?.place ? Math.round(((cap.place[0] + cap.place[1]) / 2) * H) : Math.round(H * 0.7);
4621
4828
  const capSize = Math.min(Math.round(H * (thick ? 0.05 : 0.034)), capMaxShare ? Math.round(H * capMaxShare) : Infinity);
@@ -4629,11 +4836,11 @@ export function editAss({ captions = [], cap = null, cards = [], hook = null, en
4629
4836
  `Style: End,Helvetica,${Math.round(H * 0.045)},&H00FFFFFF,&H00FFFFFF,&H20101010,&H00000000,-1,0,0,0,100,100,2,0,3,40,0,5,0,0,0,1`,
4630
4837
  ...(endLayers ? endCardStyles(endLayers.colors, H) : []), "",
4631
4838
  "[Events]", "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
4632
- ...captions.map((c) => `Dialogue: 1,${assTime(c.s)},${assTime(c.e)},Cap,,0,0,0,,{\\pos(${W / 2},${y})${c.colour ? `\\c${c.colour}${thick ? "" : `\\bord${CAPTION_COLOUR_MIN_OUTLINE}`}` : ""}}${c.text}`),
4633
- ...cards.filter((c) => c.label).map((c) => `Dialogue: 2,${assTime(c.in)},${assTime(c.out)},Card,,0,0,0,,{${box(c.box)}\\fs${Math.round(H * 0.036)}\\fad(60,0)}${assText(c.label)}`),
4634
- ...(hook?.text ? [`Dialogue: 3,${assTime(hook.in)},${assTime(hook.out)},Card,,0,0,0,,{${box(hook.box)}\\fs${Math.round(H * 0.026)}}${assText(hook.text)}`] : []),
4635
- ...(endCard ? [`Dialogue: 4,${assTime(endCard.in)},${assTime(endCard.out)},End,,0,0,0,,{\\pos(${W / 2},${H / 2})\\fad(120,0)}${assText(endCard.text)}`] : []),
4636
- ...(endLayers ? endCardDialogues(endLayers, W, H) : []),
4839
+ ...captions.map((c, k) => `Dialogue: 1,${csTime(starts[k])},${end(c, k)},Cap,,0,0,0,,{\\pos(${W / 2},${y})${c.colour ? `\\c${c.colour}${thick ? "" : `\\bord${CAPTION_COLOUR_MIN_OUTLINE}`}` : ""}}${c.text}`),
4840
+ ...cards.filter((c) => c.label).map((c) => `Dialogue: 2,${at(c.in)},${at(c.out)},Card,,0,0,0,,{${box(c.box)}\\fs${Math.round(H * 0.036)}\\fad(60,0)}${assText(c.label)}`),
4841
+ ...(hook?.text ? [`Dialogue: 3,${at(hook.in)},${at(hook.out)},Card,,0,0,0,,{${box(hook.box)}\\fs${Math.round(H * 0.026)}}${assText(hook.text)}`] : []),
4842
+ ...(endCard ? [`Dialogue: 4,${at(endCard.in)},${at(endCard.out)},End,,0,0,0,,{\\pos(${W / 2},${H / 2})\\fad(120,0)}${assText(endCard.text)}`] : []),
4843
+ ...(endLayers ? endCardDialogues(endLayers, W, H, at) : []),
4637
4844
  ].join("\n") + "\n";
4638
4845
  }
4639
4846
 
@@ -4730,40 +4937,45 @@ export function sourceAdPaceShots(sourceAd) {
4730
4937
  }
4731
4938
 
4732
4939
  /**
4733
- * endCardLayers and brandCheck (Plan 14): the manifest's `brand`, written by
4734
- * the worker beside `finishing`: the product's pack photo it downloaded
4735
- * (`packPhoto`, a file in the folder), the product's name, the scenes whose
4736
- * picture the pull's rule draws from that photo (`photoScenes`), the end
4737
- * card's length and the brand's colours (hex), each optional. Null when the
4738
- * manifest has none, so a cut without it is the one it always was.
4940
+ * How long the end card shows, the same for every brand: Daniel's ruling on COP-309 (2026-11-14, #4585), "the card
4941
+ * comes up just after the last spoken word and shows for about 2 seconds, so nothing said is covered".
4739
4942
  */
4740
- export const END_CARD_LAYERS_SEC = 6;
4741
- export const END_CARD_MIN_SEC = 5;
4742
- export const END_CARD_MAX_SEC = 8;
4943
+ export const END_CARD_LAYERS_SEC = 2;
4743
4944
  /** The end card's colours when the brand gives none: a near-black ground, white words, a white call-to-action box. */
4744
4945
  export const END_CARD_COLORS = { background: "111111", text: "FFFFFF", accent: "FFFFFF" };
4745
4946
  /** Where the pack photo sits on the end card, as shares of the frame, and how far it pushes in across the card. */
4746
4947
  export const END_CARD_PHOTO_BOX = [0.1, 0.1, 0.9, 0.56];
4747
4948
  export const END_CARD_PUSH_IN = 0.05;
4748
- /** The words build in one after another, this far apart, after the photo has faded in. */
4749
- const END_CARD_WORD_STEP_SEC = 0.6;
4750
- const END_CARD_PHOTO_FADE_SEC = 0.4;
4949
+ /**
4950
+ * #4585: the card dissolves in over the last picture in END_CARD_FADE_SEC, so its ground never shows alone before the
4951
+ * photo, and its words build in one after another, this far apart, each fading in over END_CARD_WORD_FADE_MS, as the
4952
+ * dissolve ends. On a 2 s card the headline is fully on screen for 1.65 s, the offer 1.5 s, the call to action 1.35 s.
4953
+ */
4954
+ const END_CARD_WORD_STEP_SEC = 0.15;
4955
+ const END_CARD_FADE_SEC = 0.2;
4956
+ const END_CARD_WORD_FADE_MS = 150;
4751
4957
  /** A spoken call to action longer than this many words is too long to letter; the card then shows none. */
4752
4958
  const END_CARD_CTA_MAX_WORDS = 8;
4753
4959
 
4754
4960
  const hexColour = (value) => (typeof value === "string" && /^#?[0-9a-f]{6}$/i.test(value.trim()) ? value.trim().replace(/^#/, "").toUpperCase() : null);
4755
4961
 
4962
+ /**
4963
+ * endCardLayers and brandCheck (Plan 14): the manifest's `brand`, written by
4964
+ * the worker beside `finishing`: the product's pack photo it downloaded
4965
+ * (`packPhoto`, a file in the folder), the product's name, the scenes whose
4966
+ * picture the pull's rule draws from that photo (`photoScenes`) and the
4967
+ * brand's colours (hex), each optional. Null when the manifest has none, so a
4968
+ * cut without it is the one it always was.
4969
+ */
4756
4970
  export function brandOf(manifest) {
4757
4971
  const b = manifest?.brand;
4758
4972
  if (!b || typeof b !== "object") return null;
4759
4973
  const text = (v) => (hasText(v) ? v.trim() : null);
4760
4974
  const colors = b.colors && typeof b.colors === "object" ? b.colors : {};
4761
- const seconds = Number.isFinite(b.endCardSec) ? Math.min(END_CARD_MAX_SEC, Math.max(END_CARD_MIN_SEC, b.endCardSec)) : END_CARD_LAYERS_SEC;
4762
4975
  return {
4763
4976
  packPhoto: text(b.packPhoto),
4764
4977
  productName: text(b.productName),
4765
4978
  photoScenes: Array.isArray(b.photoScenes) ? b.photoScenes.filter((n) => Number.isInteger(n)) : [],
4766
- endCardSec: seconds,
4767
4979
  colors: {
4768
4980
  background: hexColour(colors.background) ?? END_CARD_COLORS.background,
4769
4981
  text: hexColour(colors.text) ?? END_CARD_COLORS.text,
@@ -4796,28 +5008,81 @@ export function endCardWords(storyboard, productName = null) {
4796
5008
  };
4797
5009
  }
4798
5010
 
5011
+ /** #4585: the end card comes up this long after the last heard word ends. */
5012
+ export const END_CARD_AFTER_VOICE_SEC = 0.3;
5013
+
4799
5014
  /**
4800
- * endCardLayers: the ad's last `endCardSec` seconds of screen time (`speed`
5015
+ * endCardLayers: the ad's last END_CARD_LAYERS_SEC seconds of screen time (`speed`
4801
5016
  * is the cut's speed-up, applied after) become the end card: the brand's
4802
5017
  * ground colour, the pack photo pushing in slowly, and the words drawn by
4803
- * code over it. The sound runs on under it as cut, so the call to action is
4804
- * heard over the card. Never more than half the ad. Null without a pack photo.
5018
+ * code over it. Never more than half the ad. Null without a pack photo.
5019
+ * #4585: the card never covers a heard word. When the last word (`voiceEndSec`,
5020
+ * on the cut's clock before the speed-up) ends inside those seconds, the card
5021
+ * comes up just after it, and `holdSec` is how much longer the picture must run
5022
+ * under the card so the card keeps its length.
4805
5023
  */
4806
- export function endCardLayersOf(brand, storyboard, pictureSec, speed = 1) {
5024
+ export function endCardLayersOf(brand, storyboard, pictureSec, speed = 1, voiceEndSec = null) {
4807
5025
  if (!brand?.packPhoto) return null;
4808
- const seconds = Math.min(brand.endCardSec * speed, pictureSec / 2);
5026
+ const seconds = Math.min(END_CARD_LAYERS_SEC * speed, pictureSec / 2);
4809
5027
  if (!(seconds > 0)) return null;
4810
- const at = roundMs(Math.max(0, pictureSec - seconds));
5028
+ // Only a card that would cover a word moves; one that comes up after the last word stays where it was.
5029
+ const waits = Number.isFinite(voiceEndSec) && voiceEndSec > Math.max(0, pictureSec - seconds) + 1e-3;
5030
+ const afterVoice = waits ? voiceEndSec + END_CARD_AFTER_VOICE_SEC : 0;
5031
+ const at = roundMs(Math.max(0, waits ? afterVoice : pictureSec - seconds));
5032
+ // Whole frames, so the held picture ends on the cut's own frame clock.
5033
+ const holdSec = waits ? Math.max(0, Math.ceil((at + seconds - pictureSec) * FPS - 1e-6)) / FPS : 0;
5034
+ const end = pictureSec + holdSec;
4811
5035
  return {
4812
5036
  file: brand.packPhoto,
4813
5037
  in: at,
4814
- out: roundMs(pictureSec + 1),
4815
- seconds: roundMs(pictureSec - at),
5038
+ out: roundMs(end + 1),
5039
+ seconds: roundMs(end - at),
5040
+ ...(holdSec > 0 ? { holdSec } : {}),
4816
5041
  words: endCardWords(storyboard, brand.productName),
4817
5042
  colors: brand.colors,
4818
5043
  };
4819
5044
  }
4820
5045
 
5046
+ /**
5047
+ * #4585: the heard words the end card would cover, so they would play with no picture of their scene. Each is a word
5048
+ * row (the cut's clock before the speed-up). Empty with no card, or when every word ends before the card comes up.
5049
+ */
5050
+ export function voiceUnderEndCard(rows, endCard) {
5051
+ return endCard ? rows.filter((r) => r.end > endCard.in + 1e-3) : [];
5052
+ }
5053
+
5054
+ /**
5055
+ * #4585: the end card on the cut. It comes up after the last heard word, and the last scene's picture runs on under it
5056
+ * (its sound faded out where it ends, then silence), so the card keeps its length. A cut laid on its measured map
5057
+ * cannot run on past its picture, so its card keeps the ad's last seconds. A card that would cover a heard word refuses
5058
+ * the cut (VoiceUnderEndCardRefusal). What it did goes in `notes`.
5059
+ */
5060
+ export function placeEndCard(timeline, brand, storyboard, pictureSec, speed, notes) {
5061
+ const rows = wordRows(timeline);
5062
+ const voiceEndSec = timeline.mapped ? null : Math.max(...rows.map((r) => r.end));
5063
+ const card = endCardLayersOf(brand, storyboard, pictureSec, speed, voiceEndSec);
5064
+ if (card?.holdSec) {
5065
+ const last = timeline.spine.at(-1);
5066
+ last.endCardHoldSec = card.holdSec;
5067
+ last.holdSec = (last.holdSec ?? 0) + card.holdSec;
5068
+ last.seconds += card.holdSec;
5069
+ notes.push(`the end card waits for the last word, so the ad runs ${card.holdSec.toFixed(2)}s longer under it`);
5070
+ }
5071
+ const covered = voiceUnderEndCard(rows, card);
5072
+ if (covered.length > 0) throw new VoiceUnderEndCardRefusal(covered);
5073
+ if (card) timeline.endCard = { in: card.in, out: card.out };
5074
+ return card;
5075
+ }
5076
+
5077
+ /** The staff message of a cut refused because the end card would cover some of its voice (VoiceUnderEndCardRefusal). */
5078
+ export function voiceUnderEndCardMessage(words) {
5079
+ const scenes = [...new Set(words.map((r) => r.scene))].sort((a, b) => a - b);
5080
+ const named = scenes.length > 1 ? `scenes ${scenes.slice(0, -1).join(", ")} and ${scenes.at(-1)}` : `scene ${scenes[0]}`;
5081
+ const from = Math.min(...words.map((r) => r.start));
5082
+ const to = Math.max(...words.map((r) => r.end));
5083
+ return `The end card would cover the voice of ${named} from ${from.toFixed(2)}s to ${to.toFixed(2)}s, so the cut was not attached`;
5084
+ }
5085
+
4821
5086
  /** An ASS colour (&HAABBGGRR) from a hex RRGGBB. */
4822
5087
  const assColour = (hex, alpha = "00") => `&H${alpha}${hex.slice(4, 6)}${hex.slice(2, 4)}${hex.slice(0, 2)}`;
4823
5088
 
@@ -4832,16 +5097,16 @@ function endCardStyles(colors, H) {
4832
5097
  ];
4833
5098
  }
4834
5099
 
4835
- /** The end card's words, building in one after another after the photo. */
4836
- function endCardDialogues(e, W, H) {
5100
+ /** The end card's words, building in one after another as the card's dissolve ends. `at` writes a time of the cut's clock. */
5101
+ function endCardDialogues(e, W, H, at = assTime) {
4837
5102
  const rows = [
4838
5103
  ["EndHead", e.words.headline, 0.64],
4839
5104
  ["EndOffer", e.words.offer, 0.71],
4840
5105
  ["EndCta", e.words.cta, 0.82],
4841
5106
  ].filter(([, words]) => hasText(words));
4842
5107
  return rows.map(([style, words, y], k) => {
4843
- const from = roundMs(e.in + END_CARD_PHOTO_FADE_SEC + k * END_CARD_WORD_STEP_SEC);
4844
- return `Dialogue: 5,${assTime(from)},${assTime(e.out)},${style},,0,0,0,,{\\pos(${W / 2},${Math.round(H * y)})\\fad(250,0)}${assText(words)}`;
5108
+ const from = roundMs(e.in + END_CARD_FADE_SEC + k * END_CARD_WORD_STEP_SEC);
5109
+ return `Dialogue: 5,${at(from)},${at(e.out)},${style},,0,0,0,,{\\pos(${W / 2},${Math.round(H * y)})\\fad(${END_CARD_WORD_FADE_MS},0)}${assText(words)}`;
4845
5110
  });
4846
5111
  }
4847
5112
 
@@ -5152,11 +5417,12 @@ export function takesOf(timeline, plans, speed = 1) {
5152
5417
  const last = takes.at(-1);
5153
5418
  const endsOnReaction = Boolean(timeline.spine[i + 1]?.reaction);
5154
5419
  if (last && last.n === seg.sceneIndex && last.lastSeg === i - 1) {
5155
- Object.assign(last, { takeSec: last.takeSec + seg.seconds, lastSeg: i, endsOnReaction });
5420
+ Object.assign(last, { takeSec: last.takeSec + seg.seconds - (seg.endCardHoldSec ?? 0), lastSeg: i, endsOnReaction });
5156
5421
  return;
5157
5422
  }
5423
+ // #4585: the picture held under the end card is not the take's.
5158
5424
  takes.push({
5159
- n: seg.sceneIndex, start: seg.startSec, takeSec: seg.seconds, dialogue: seg.audio === "clip",
5425
+ n: seg.sceneIndex, start: seg.startSec, takeSec: seg.seconds - (seg.endCardHoldSec ?? 0), dialogue: seg.audio === "clip",
5160
5426
  planSec: plans.get(seg.sceneIndex)?.durationSec ?? 0, lastSeg: i, endsOnReaction,
5161
5427
  });
5162
5428
  });
@@ -5429,8 +5695,8 @@ const roleOf = (seg) => (seg.reaction || seg.audio === "clip" ? "a-roll" : seg.a
5429
5695
  * cutChecks: the finished cut against CHECK_BARS. `screens` are the caption
5430
5696
  * screens burned in (null for none), `rows` and `scenes` the cut's words and
5431
5697
  * shots as written beside it, `levels` the voice's and the bed's loudness from
5432
- * the render. Caption sync is not checked: it needs a transcription of the
5433
- * finished cut of its own, and the cut's words are the ones its captions came from.
5698
+ * the render. Caption sync is checked apart, with captionCheck (cutSync): it
5699
+ * needs where each word is heard in the finished cut, not the words the captions came from.
5434
5700
  * With blipCheck and freezeCheck in `finish`, the checks also name blips (each
5435
5701
  * shot's source length found through `shotOf`, the storyboard's sourceShot, in
5436
5702
  * `sourceAd`) and freezes; with them off, their keys are absent. The same holds
@@ -5543,11 +5809,9 @@ function ffmpegReason(res) {
5543
5809
  return res.signal ? `it was stopped by ${res.signal}.` : "it printed no reason.";
5544
5810
  }
5545
5811
 
5546
- /** Both passes on the mix, then the finished cut measured again. A receipt may
5547
- * retain that final observation without changing the legacy mastering result. */
5548
- export function finishLoudnessPass(mix, out, limiter = null, onMeasured = null) {
5549
- const measured = measureLoudness(mix);
5550
- const args = loudnessApplyArgs(mix, measured, out, limiter);
5812
+ /** The mix normalized with pass one's numbers into `out`, through the limiter at `limit` when one is given. */
5813
+ function applyLoudness(mix, measured, out, limit) {
5814
+ const args = loudnessApplyArgs(mix, measured, out, limit == null ? null : peakLimiter(limit));
5551
5815
  const res = spawnSync("ffmpeg", args, { stdio: ["inherit", "inherit", "pipe"], encoding: "utf8", maxBuffer: 1 << 26 });
5552
5816
  if (res.status !== 0) {
5553
5817
  // ffmpeg's words still reach the log, and its reason leads the error:
@@ -5556,11 +5820,32 @@ export function finishLoudnessPass(mix, out, limiter = null, onMeasured = null)
5556
5820
  const quoted = args.map((a) => (/[\s\[\];]/.test(a) ? `'${a}'` : a)).join(" ");
5557
5821
  throw new FirstCutError(1, `ffmpeg failed on the loudness pass: ${ffmpegReason(res)} The command it ran:\n ffmpeg ${quoted}`);
5558
5822
  }
5559
- const finished = measureLoudness(out);
5823
+ return measureLoudness(out);
5824
+ }
5825
+
5826
+ /** Both passes on the mix, then the finished cut measured again. A receipt may
5827
+ * retain that final observation without changing the legacy mastering result.
5828
+ * `limit` (limitPeaks) is the limiter's ceiling, PEAK_LIMIT; a limited cut over
5829
+ * the limit is limited again lower (LIMIT_AGAIN_MAX), one under it is left as it is. */
5830
+ export function finishLoudnessPass(mix, out, limit = null, onMeasured = null) {
5831
+ const measured = measureLoudness(mix);
5832
+ let ceiling = limit;
5833
+ let finished = applyLoudness(mix, measured, out, ceiling);
5834
+ let again = 0;
5835
+ while (ceiling != null && finished && finished.tp > TRUE_PEAK_MAX_DB && again < LIMIT_AGAIN_MAX) {
5836
+ const lower = lowerPeakLimit(ceiling, finished.tp);
5837
+ if (lower >= ceiling) break;
5838
+ ceiling = lower;
5839
+ finished = applyLoudness(mix, measured, out, ceiling);
5840
+ again++;
5841
+ }
5560
5842
  const refusal = truePeakRefusal(finished);
5561
5843
  if (refusal) throw new LoudnessRefusal(refusal, finished);
5562
5844
  onMeasured?.(finished);
5563
- return { lufs: round2(finished.i), truePeak: round2(finished.tp), passes: measured ? 2 : 1, ...(limiter ? { limited: true } : {}) };
5845
+ return {
5846
+ lufs: round2(finished.i), truePeak: round2(finished.tp), passes: measured ? 2 : 1,
5847
+ ...(limit != null ? { limited: true } : {}), ...(again > 0 ? { limitedAgain: again, limit: ceiling } : {}),
5848
+ };
5564
5849
  }
5565
5850
 
5566
5851
  /** The filters of `names` this ffmpeg does not have. */
@@ -5576,14 +5861,16 @@ function hasFilter(name) {
5576
5861
 
5577
5862
  /**
5578
5863
  * The files the finishing settings write beside the cut: the pace record, the
5579
- * mix before the loudness pass, and the voice and bed cutChecks measures.
5864
+ * mix before the loudness pass (a .mov, whose sound stays uncompressed until
5865
+ * that pass), the voice and bed cutChecks measures, and captionCheck's checks.
5580
5866
  */
5581
5867
  export function finishPaths(outPath) {
5582
5868
  const dir = path.dirname(outPath);
5583
5869
  const base = path.basename(outPath, path.extname(outPath));
5584
5870
  return {
5585
5871
  pace: path.join(dir, `${base}.pace.json`),
5586
- mix: path.join(dir, `${base}.mix${path.extname(outPath)}`),
5872
+ mix: path.join(dir, `${base}.mix.mov`),
5873
+ sync: path.join(dir, `${base}.sync.json`),
5587
5874
  sound: path.join(dir, `${base}.sound.json`),
5588
5875
  master: path.join(dir, `${base}.music-only${path.extname(outPath)}`),
5589
5876
  voice: path.join(dir, `${base}.voice.wav`),
@@ -5649,6 +5936,15 @@ function mediaReader(here, exists) {
5649
5936
  export const sourceMapPath = (outPath) =>
5650
5937
  path.join(path.dirname(outPath), `${path.basename(outPath, path.extname(outPath))}.source-map.json`);
5651
5938
 
5939
+ /** #4585: the end card would cover some of the cut's voice (voiceUnderEndCard), so the cut is not delivered. */
5940
+ export class VoiceUnderEndCardRefusal extends FirstCutError {
5941
+ constructor(words) {
5942
+ super(1, voiceUnderEndCardMessage(words));
5943
+ this.name = "VoiceUnderEndCardRefusal";
5944
+ this.words = words;
5945
+ }
5946
+ }
5947
+
5652
5948
  /** A required text/fulfillment obligation cannot be claimed as delivered. */
5653
5949
  export class TextFinishRefusal extends FirstCutError {
5654
5950
  constructor(holds) {
@@ -6600,7 +6896,7 @@ function cutFinishEvidence({ manifest, storyboard, timeline = null, skip = new S
6600
6896
  * sidecars, and throws FirstCutError where the CLI would exit. The CLI's report
6601
6897
  * is printed by main() from what this returns.
6602
6898
  */
6603
- export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn = true, stillFill = false, prepareText = false }) {
6899
+ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn = true, stillFill = false, prepareText = false, heardWords = null }) {
6604
6900
  for (const bin of ["ffmpeg", "ffprobe"]) {
6605
6901
  if (spawnSync(bin, ["-version"]).status !== 0) {
6606
6902
  throw new FirstCutError(2, `${bin} is not installed. Install ffmpeg (brew install ffmpeg / apt install ffmpeg).`);
@@ -6787,18 +7083,20 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
6787
7083
  const packPhoto = Boolean(brand?.packPhoto) && exists(brand.packPhoto);
6788
7084
  let endLayers = null;
6789
7085
  if (finish?.endCardLayers) {
6790
- endLayers = packPhoto ? endCardLayersOf(brand, storyboard, pictureSec, speed) : null;
7086
+ endLayers = packPhoto ? placeEndCard(timeline, brand, storyboard, pictureSec, speed, notes) : null;
6791
7087
  if (!endLayers) notes.push("the pull has no pack photo of the product, so the end card was not drawn");
6792
7088
  }
6793
7089
  if (finish && (finish.captions || finish.cards || endLayers) && !stagedText) {
6794
7090
  if (hasFilter("subtitles")) {
6795
7091
  ass = "edit.ass";
6796
- const cap = sourceAd?.captions ?? null;
7092
+ const cap = sourceAd?.captions ?? manifest.sheetCaptions ?? null;
7093
+ // COP-300: a cut made again after its caption check failed times its captions by the finished film's heard words.
7094
+ const timed = (words) => (heardWords?.length ? retimeWords(words, heardWords, speed) : words);
6797
7095
  const screens = captionsBeforeEndCard(!finish.captions
6798
7096
  ? []
6799
7097
  : finish.captionsByLine
6800
- ? lineCaptionScreens(lineWords(timeline, storyboard), cap)
6801
- : captionScreens(wordRows(timeline), cap), endLayers);
7098
+ ? lineCaptionScreens(timed(lineWords(timeline, storyboard)), cap)
7099
+ : captionScreens(timed(wordRows(timeline)), cap), endLayers);
6802
7100
  if (finish.captions) burned = screens;
6803
7101
  burnedCards = finish.cards ? (copied ? copied.cards : storyboardCards(storyboard, timeline)) : [];
6804
7102
  writeFileSync(here(ass), editAss({
@@ -6810,6 +7108,7 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
6810
7108
  // A copied ad has an end card only where its source does. The pack-photo end card takes the CTA words' place.
6811
7109
  endCard: !endLayers && finish.cards && (!sourceAd || sourceAd.endCard) ? endCardOf(storyboard, pictureSec) : null,
6812
7110
  endLayers,
7111
+ speed,
6813
7112
  }));
6814
7113
  } else {
6815
7114
  notes.push(
@@ -6827,9 +7126,9 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
6827
7126
  else if (missing.length > 0) notes.push(`this ffmpeg has no ${missing.join(", ")} filter, so the voice was not cleaned`);
6828
7127
  else clean = { voice: VOICE_CLEAN, under: UNDER_VOICE };
6829
7128
  }
6830
- let limiter = null;
7129
+ let peakLimit = null;
6831
7130
  if (finish?.limitPeaks) {
6832
- if (hasFilter("alimiter")) limiter = PEAK_LIMITER;
7131
+ if (hasFilter("alimiter")) peakLimit = PEAK_LIMIT;
6833
7132
  else notes.push("this ffmpeg has no alimiter filter, so the loudness pass ran without the limiter");
6834
7133
  }
6835
7134
  const paths = finishPaths(out);
@@ -6923,7 +7222,7 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
6923
7222
  ...(finish
6924
7223
  ? {
6925
7224
  finish: {
6926
- levelSegments: !finish.finishLoudness, ass, speed,
7225
+ levelSegments: !finish.finishLoudness, ass, speed, ...(finish.finishLoudness ? { pcmMix: true } : {}),
6927
7226
  ...(pictures.length ? { pictures } : {}), ...(clean ? { clean } : {}), ...(meters ? { meters } : {}),
6928
7227
  ...(endLayers ? { endCard: endLayers } : {}),
6929
7228
  },
@@ -6950,13 +7249,14 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
6950
7249
  let loudnessMeasurement = null;
6951
7250
  if (finish?.finishLoudness) {
6952
7251
  try {
6953
- loudness = finishLoudnessPass(rendered, out, limiter, template
7252
+ loudness = finishLoudnessPass(rendered, out, peakLimit, template
6954
7253
  ? (measured) => { loudnessMeasurement = measured; } : null);
6955
7254
  } catch (error) {
6956
- if (!template || !(error instanceof FirstCutError)) throw error;
6957
- // One local limiter pass on the same retained mix, never a provider call.
7255
+ // A limited pass already limited itself again (#4573); the same mix would only be refused the same way.
7256
+ if (!template || peakLimit != null || !(error instanceof FirstCutError)) throw error;
7257
+ // The limiter on the same retained mix, never a provider call, limited again lower as finishLoudnessPass does.
6958
7258
  // If it still clips or cannot be measured, the refusal holds the cut.
6959
- loudness = finishLoudnessPass(rendered, out, PEAK_LIMITER,
7259
+ loudness = finishLoudnessPass(rendered, out, PEAK_LIMIT,
6960
7260
  (measured) => { loudnessMeasurement = measured; });
6961
7261
  } finally {
6962
7262
  rmSync(rendered, { force: true });
@@ -6991,6 +7291,10 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
6991
7291
  rmSync(sidecars.srt, { force: true });
6992
7292
  }
6993
7293
  writeFileSync(sidecars.scenes, `${JSON.stringify(scenes, null, 2)}\n`);
7294
+ const sync = finish?.captionCheck
7295
+ ? cutSync({ out, speed, scenes, rows, screens: ass && burned ? burned : [], manifest, here, readJson })
7296
+ : null;
7297
+ if (sync) writeFileSync(paths.sync, `${JSON.stringify(sync, null, 2)}\n`);
6994
7298
 
6995
7299
  const duration = execFileSync("ffprobe", [
6996
7300
  "-v", "error", "-show_entries", "format=duration", "-of", "default=nw=1:nk=1", out,
@@ -7097,10 +7401,55 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
7097
7401
  ...(loudness ? { loudness } : {}),
7098
7402
  ...(checks ? { checks } : {}),
7099
7403
  ...(finish.brandCheck ? { brand: brandRecord({ brand, packPhoto, endLayers, rows }) } : {}),
7404
+ // COP-300: the caption file is timed on the finished, sped-up cut's clock, as it is burned after the speed step.
7405
+ ...(ass && speed !== 1 ? { captionClock: "final" } : {}),
7406
+ ...(sync ? { sync: syncRecord(sync) } : {}),
7100
7407
  ...(notes.length > 0 ? { notes } : {}),
7101
7408
  };
7102
7409
  writeFileSync(paths.pace, `${JSON.stringify(pace, null, 2)}\n`);
7103
- return withSound({ out, durationSec, manifest, timeline, music, rows, sidecars, pace });
7410
+ return withSound({ out, durationSec, manifest, timeline, music, rows, sidecars, pace, ...(sync ? { sync } : {}) });
7411
+ }
7412
+
7413
+ /**
7414
+ * COP-300, captionCheck: the finished cut checked against its own sound. Check A on its decoded sound and frames;
7415
+ * Check B on each burned caption, at the frame it is first seen, against its first word as the free listener
7416
+ * (placementHeard) finds it in the finished sound: each take's own word times, moved by where its sound sits there.
7417
+ * The sections are the cut's takes. The captions, sections and heard words come back with the verdicts, so the
7418
+ * worker can judge Check B again on a listen of its own, and cut again from the heard words.
7419
+ */
7420
+ function cutSync({ out, speed, scenes, rows, screens, manifest, here, readJson }) {
7421
+ const sections = [];
7422
+ for (const p of scenes) {
7423
+ const last = sections.at(-1);
7424
+ if (last && last.id === p.scene) last.endSec = roundMs(p.startSec + p.seconds);
7425
+ else sections.push({ id: p.scene, startSec: p.startSec, endSec: roundMs(p.startSec + p.seconds) });
7426
+ }
7427
+ const captions = screens.map((c) => ({ text: c.text, seenSec: roundMs(captionSeenSec(captionStartCs(c.s / speed))) }));
7428
+ const takes = (manifest.scenes ?? []).flatMap((scene) => {
7429
+ const file = scene.wordsFrom === "voice" ? scene.voice : scene.clip;
7430
+ const words = readJson(scene.words);
7431
+ const cutWords = rows.filter((r) => r.scene === scene.sceneIndex);
7432
+ if (!file || !Array.isArray(words) || cutWords.length === 0) return [];
7433
+ return [{
7434
+ file: here(file),
7435
+ heard: words.map((w) => ({ text: String(w.w ?? ""), start: w.s, end: w.e })),
7436
+ words: cutWords.map((r) => ({ text: r.text, start: r.start, end: r.end })),
7437
+ }];
7438
+ });
7439
+ const heard = captions.length ? placementHeard({ film: out, speed, takes }) : [];
7440
+ return {
7441
+ checkA: soundPictureCheck(out),
7442
+ checkB: captions.length ? captionSync({ captions, heard, sections }) : null,
7443
+ listener: captions.length ? "placement" : null,
7444
+ captionClock: "final",
7445
+ captions, sections, heard,
7446
+ };
7447
+ }
7448
+
7449
+ /** The checks' numbers the pace record keeps: the verdicts, without each caption's row. */
7450
+ export function syncRecord(sync) {
7451
+ const { rows, ...checkB } = sync.checkB ?? {};
7452
+ return { checkA: sync.checkA, checkB: sync.checkB ? checkB : null, listener: sync.listener };
7104
7453
  }
7105
7454
 
7106
7455
  function main() {