@aicopycoders/exodus 2026.10.2400-beta.3 → 2026.11.500-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.
@@ -32,6 +32,12 @@
32
32
  // After the render it writes the whole ad's word times beside the MP4, as
33
33
  // <out>.words.json and <out>.srt, for captioning in post, and where each scene
34
34
  // plays in the cut as <out>.scenes.json (#3300).
35
+ //
36
+ // A kind can turn on finishing settings, which reach this file as the
37
+ // manifest's `finishing` (see finishingOf). Without it the cut is the one
38
+ // described above, byte for byte. The same holds for its sound settings, which
39
+ // reach this file as the manifest's `sound` (see soundOf), and for a voice
40
+ // that is one song laid whole, the manifest's `wholeVoice` (see wholeVoiceOf).
35
41
  import { execFileSync, spawnSync } from "node:child_process";
36
42
  import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
37
43
  import path from "node:path";
@@ -125,6 +131,204 @@ export const BROLL_LEAD_SEC = 0.5;
125
131
  export const BROLL_MIN_HOLD_SEC = 0.8;
126
132
  export const BROLL_MAX_HOLD_SEC = 4;
127
133
 
134
+ /**
135
+ * The finishing settings (a kind's cutPace, captions, cards, finishLoudness).
136
+ * cutPace: at most PACE_GAP_MAX_SEC of air where a new speaker answers; a pause
137
+ * over PACE_SPLIT_PAUSE_SEC where one line ends and the next begins is cut to
138
+ * PACE_GAP_MAX_SEC and the take is split there, every other piece punched in;
139
+ * the cut sped up, at most SPEED_MAX, when it runs past the kind's
140
+ * targetSeconds; and a pace report. A speed under SPEED_FLOOR is not worth
141
+ * the change and is left at 1.
142
+ */
143
+ export const PACE_GAP_MAX_SEC = 0.35;
144
+ export const PACE_SPLIT_PAUSE_SEC = 0.45;
145
+ export const SPEED_MAX = 1.15;
146
+ const SPEED_FLOOR = 1.02;
147
+ /** A shot longer than this counts as long in the pace report. */
148
+ export const LONG_SHOT_SEC = 4;
149
+ /** A pause in the voice at least this long is one the pace report reads. */
150
+ const PACE_PAUSE_SEC = 0.2;
151
+ /** A card lands this long before the first word of the line it is cued to. */
152
+ export const CARD_LEAD_SEC = 0.07;
153
+ /** finishLoudness: the whole mix's target, and the true peak a cut may not pass after it. */
154
+ export const FINISH_LUFS = -14;
155
+ export const FINISH_TRUE_PEAK = -1.5;
156
+ export const FINISH_LRA = 11;
157
+ export const TRUE_PEAK_MAX_DB = -1;
158
+ /**
159
+ * limitPeaks: after the loudness pass, the sound oversampled 4x through a
160
+ * limiter at 0.8 (about -1.9 dB), so a peak between two samples is caught too.
161
+ * The cut is still measured after and refused over TRUE_PEAK_MAX_DB.
162
+ */
163
+ export const PEAK_LIMITER = "aresample=192000,alimiter=limit=0.8:level=false:attack=2:release=60";
164
+
165
+ /**
166
+ * The manifest's finishing settings, or null when none is on. The worker
167
+ * writes them from the run's frozen kind settings, so a redo of the run cuts
168
+ * with the same ones. A setting added after the first four is present only
169
+ * when it is on and can act (captionsByLine needs captions).
170
+ */
171
+ export function finishingOf(manifest) {
172
+ const f = manifest?.finishing;
173
+ if (!f || typeof f !== "object") return null;
174
+ const on = {
175
+ cutPace: f.cutPace === true,
176
+ captions: f.captions === true,
177
+ cards: f.cards === true,
178
+ finishLoudness: f.finishLoudness === true,
179
+ };
180
+ const added = {
181
+ ...(on.captions && f.captionsByLine === true ? { captionsByLine: true } : {}),
182
+ ...(f.cleanVoice === true ? { cleanVoice: true } : {}),
183
+ ...(on.finishLoudness && f.limitPeaks === true ? { limitPeaks: true } : {}),
184
+ ...(Number.isFinite(f.brollMinSec) && f.brollMinSec > 0 ? { brollMinSec: f.brollMinSec } : {}),
185
+ ...(f.speedUpSlowBroll === true ? { speedUpSlowBroll: true } : {}),
186
+ ...(f.cutChecks === true ? { cutChecks: true } : {}),
187
+ };
188
+ if (!Object.values(on).some(Boolean) && Object.keys(added).length === 0) return null;
189
+ const target = f.targetSeconds;
190
+ return on.cutPace && Number.isFinite(target) && target > 0 ? { ...on, targetSeconds: target, ...added } : { ...on, ...added };
191
+ }
192
+
193
+ /**
194
+ * The sound settings (a kind's soundEffects, roomTone, music "suno" and
195
+ * musicOnlyMaster), as the manifest's `sound`: the files the worker made for
196
+ * this run. A sound lands SOUND_LEAD_SEC before the first word of the line it
197
+ * is cued to, SOUND_UNDER_DB under the voice there. A room-tone bed runs from
198
+ * its set's first scene (the first bed from the start) to the next bed, looped,
199
+ * BED_UNDER_DB under the voice, in place of the brown-noise room tone; a bed
200
+ * quieter than BED_FLOOR_LUFS, or with no loudness to measure, is left out and
201
+ * noted. With `duck` the music sits MUSIC_UNDER_DB under the voice and a
202
+ * sidechain compressor keyed on the voice ducks it (DUCK). With
203
+ * musicOnlyMaster a second file beside the cut carries the cut's picture and
204
+ * the music alone, at FINISH_LUFS. The voice's level is SEGMENT_LUFS where
205
+ * every segment is levelled to it, else each segment's file is measured.
206
+ */
207
+ export const SOUND_UNDER_DB = 10;
208
+ export const SOUND_LEAD_SEC = 0.03;
209
+ const SOUND_FALLBACK_DB = -22;
210
+ export const BED_UNDER_DB = 24;
211
+ export const BED_FLOOR_LUFS = -70;
212
+ const BED_FADE_SEC = 0.15;
213
+ export const MUSIC_UNDER_DB = 16.8;
214
+ const MUSIC_FALLBACK_DB = -20;
215
+ export const DUCK = { threshold: 0.05, ratio: 2.5, attack: 20, release: 350 };
216
+ /**
217
+ * cleanVoice: the voice's chain (rumble cut, light noise reduction, de-essing,
218
+ * gentle compression), and what happens to the room, sounds and music under
219
+ * it: down UNDER_VOICE.db, trimmed under `highpass` and over `lowpass` Hz, and
220
+ * ducked by a compressor keyed on the cleaned voice. It is the one duck: the
221
+ * music's own (DUCK) is left out. A reaction's tail is a voice, so it is
222
+ * neither cleaned nor ducked.
223
+ */
224
+ export const VOICE_CLEAN =
225
+ "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";
226
+ export const UNDER_VOICE = { db: -6, highpass: 60, lowpass: 9000, duck: { threshold: 0.03, ratio: 5, attack: 15, release: 300 } };
227
+ const CLEAN_FILTERS = ["highpass", "lowpass", "afftdn", "deesser", "acompressor", "sidechaincompress"];
228
+ const SEGMENT_LUFS = -16;
229
+ /** A voice at or under this is no level to set a sound against. */
230
+ const VOICE_FLOOR_LUFS = -60;
231
+
232
+ /** The manifest's sound settings, or null when it names none. */
233
+ export function soundOf(manifest) {
234
+ const s = manifest?.sound;
235
+ if (!s || typeof s !== "object") return null;
236
+ const listed = (xs, ok) => (Array.isArray(xs) ? xs.filter((x) => typeof x?.file === "string" && ok(x)) : []);
237
+ const sound = {
238
+ effects: listed(s.effects, (x) => typeof x.cueLineId === "string"),
239
+ beds: listed(s.beds, (x) => Number.isFinite(x.fromScene)),
240
+ duck: s.duck === true,
241
+ musicOnlyMaster: s.musicOnlyMaster === true,
242
+ };
243
+ return sound.effects.length || sound.beds.length || sound.duck || sound.musicOnlyMaster ? sound : null;
244
+ }
245
+
246
+ /** The voice's level over segments [{ seconds, lufs }], added by power and weighted by length. */
247
+ export function voiceLufsOf(levels) {
248
+ const heard = levels.filter((l) => Number.isFinite(l.lufs) && l.seconds > 0);
249
+ const total = heard.reduce((t, l) => t + l.seconds, 0);
250
+ if (total <= 0) return null;
251
+ return round2(10 * Math.log10(heard.reduce((t, l) => t + l.seconds * 10 ** (l.lufs / 10), 0) / total));
252
+ }
253
+
254
+ const heardVoice = (lufs) => Number.isFinite(lufs) && lufs > VOICE_FLOOR_LUFS;
255
+
256
+ /** The gain (dB) that puts a sound `underDb` under the voice; `fallback` when either level is unknown. */
257
+ export function gainUnder(voiceLufs, underDb, soundLufs, fallback) {
258
+ return heardVoice(voiceLufs) && Number.isFinite(soundLufs) ? round2(voiceLufs - underDb - soundLufs) : fallback;
259
+ }
260
+
261
+ /**
262
+ * Where each sound and bed plays and how loud, from the cut's timeline.
263
+ * `measure(file)` is a file's loudness in LUFS, or null.
264
+ */
265
+ export function soundPlan(sound, timeline, storyboard, { levelled, measure }) {
266
+ const notes = [];
267
+ const spine = timeline.spine;
268
+ const pictureSec = spine.reduce((t, seg) => t + seg.seconds, 0);
269
+ const segLufs = spine.map((seg) => {
270
+ if (seg.audio !== "narration" && seg.audio !== "clip") return null;
271
+ return levelled ? SEGMENT_LUFS : measure(seg.audio === "narration" ? seg.voice : seg.file);
272
+ });
273
+ const voiceLufs = voiceLufsOf(spine.map((seg, k) => ({ seconds: seg.seconds, lufs: segLufs[k] })));
274
+ const counts = lineWordCounts(storyboard);
275
+ const effects = [];
276
+ for (const e of sound.effects) {
277
+ const cue = cueOffsetOnSpine(spine, counts, e.cueLineId);
278
+ if (!cue) {
279
+ notes.push(`the sound cued to ${e.cueLineId} is left out: the cut does not speak that line`);
280
+ continue;
281
+ }
282
+ const k = spine.findIndex((seg) => cue.startSec < seg.startSec + seg.seconds);
283
+ const under = Number.isFinite(e.underDb) ? e.underDb : SOUND_UNDER_DB;
284
+ effects.push({
285
+ file: e.file, cueLineId: e.cueLineId, atSec: roundMs(Math.max(0, cue.startSec - SOUND_LEAD_SEC)),
286
+ gainDb: gainUnder(segLufs[k] ?? voiceLufs, under, measure(e.file), SOUND_FALLBACK_DB),
287
+ });
288
+ }
289
+ const bedRef = heardVoice(voiceLufs) ? voiceLufs : FINISH_LUFS;
290
+ const heard = [];
291
+ for (const b of sound.beds) {
292
+ const seg = spine.find((x) => x.sceneIndex === b.fromScene);
293
+ const lufs = measure(b.file);
294
+ if (!seg) notes.push(`the bed for scene ${b.fromScene} is left out: that scene is not in the cut`);
295
+ else if (!Number.isFinite(lufs) || lufs < BED_FLOOR_LUFS) {
296
+ notes.push(`the bed ${b.file} is left out: ${Number.isFinite(lufs) ? `${lufs} LUFS is under ${BED_FLOOR_LUFS}` : "it has no loudness to measure"}`);
297
+ } else {
298
+ const under = Number.isFinite(b.underDb) ? b.underDb : BED_UNDER_DB;
299
+ heard.push({ file: b.file, fromScene: b.fromScene, from: seg.startSec, gainDb: round2(bedRef - under - lufs) });
300
+ }
301
+ }
302
+ heard.sort((a, b) => a.from - b.from);
303
+ const beds = heard.map((b, k) => {
304
+ const startSec = k === 0 ? 0 : roundMs(b.from);
305
+ const end = k + 1 < heard.length ? heard[k + 1].from : pictureSec;
306
+ return { file: b.file, fromScene: b.fromScene, startSec, seconds: roundMs(Math.max(0.1, end - startSec)), gainDb: b.gainDb };
307
+ });
308
+ return { voiceLufs, effects, beds, notes };
309
+ }
310
+
311
+ /** The music's gain under the voice when it is ducked. */
312
+ export function duckedMusicGain(voiceLufs, musicLufs) {
313
+ return gainUnder(voiceLufs, MUSIC_UNDER_DB, musicLufs, MUSIC_FALLBACK_DB);
314
+ }
315
+
316
+ /** musicOnlyMaster: the cut's picture as it is, with the music alone in place of the mix. */
317
+ export function musicOnlyMasterArgs(cut, music, seconds, gainDb, out) {
318
+ return [
319
+ "-y", "-hide_banner", "-loglevel", "error", "-i", cut, "-stream_loop", "-1", "-i", music,
320
+ "-filter_complex", `[1:a]${stereo},atrim=0:${sec(seconds)},asetpts=PTS-STARTPTS,volume=${gainDb}dB[music]`,
321
+ "-map", "0:v:0", "-map", "[music]", "-c:v", "copy", "-c:a", "aac", "-b:a", "192k", "-movflags", "+faststart", out,
322
+ ];
323
+ }
324
+
325
+ /** How much a cut of `seconds` is sped up to come near the kind's target length: 1 when it is not. */
326
+ export function speedFor(seconds, targetSeconds) {
327
+ if (!(targetSeconds > 0) || !(seconds > 0)) return 1;
328
+ const want = Math.min(SPEED_MAX, seconds / targetSeconds);
329
+ return want > SPEED_FLOOR ? roundMs(want) : 1;
330
+ }
331
+
128
332
  /** The word rule the planner sized every line with (scout models.ts wordCount). */
129
333
  export function wordCount(text) {
130
334
  const trimmed = (text ?? "").trim();
@@ -491,8 +695,12 @@ export function asksPause(line) {
491
695
  * break's gap, the silence it keeps, and whether a sound went.
492
696
  *
493
697
  * lines: [{ text, asksPause, cuesBeat }] in the order the clip speaks them.
698
+ *
699
+ * lineGap ({ max, keep }, cutPace): where one line ends and the next begins,
700
+ * a silence over `max` is cut to `keep` instead, and that break's last span
701
+ * carries `atLine`, the index of the line after it, where the take is split.
494
702
  */
495
- export function sentenceGapCuts(words, lines, levels = null) {
703
+ export function sentenceGapCuts(words, lines, levels = null, lineGap = null) {
496
704
  const written = [];
497
705
  const pieces = [];
498
706
  let between = "";
@@ -532,13 +740,16 @@ export function sentenceGapCuts(words, lines, levels = null) {
532
740
  const sound = heard && { s: Math.max(floorFrame(heard.s), ceilFrame(earlier.e)), e: ceilFrame(heard.e) };
533
741
  const removed = sound ? sound.e - sound.s : 0;
534
742
  const spans = sound ? [sound] : [];
535
- if (gap - removed > SENTENCE_GAP_MAX_SEC + 1e-6) {
743
+ const [gapMax, gapKeep] =
744
+ lineGap && newLine ? [lineGap.max, lineGap.keep] : [SENTENCE_GAP_MAX_SEC, SENTENCE_GAP_KEEP_SEC];
745
+ const paused = gap - removed > gapMax + 1e-6;
746
+ if (paused) {
536
747
  // Placed on the gap with the sound already out, then moved back past it.
537
748
  // Frame edges only ever widen what is kept, so the silence left stays
538
749
  // between the kept length and the longest allowed.
539
750
  const back = (t) => (sound && t > sound.s ? t + removed : t);
540
- const s = back(ceilFrame(earlier.e + SENTENCE_GAP_KEEP_SEC / 2));
541
- const e = back(floorFrame(later.s - removed - SENTENCE_GAP_KEEP_SEC / 2));
751
+ const s = back(ceilFrame(earlier.e + gapKeep / 2));
752
+ const e = back(floorFrame(later.s - removed - gapKeep / 2));
542
753
  if (e > s) spans.push({ s, e });
543
754
  }
544
755
  const merged = [];
@@ -548,7 +759,11 @@ export function sentenceGapCuts(words, lines, levels = null) {
548
759
  else merged.push({ ...span });
549
760
  }
550
761
  const kept = gap - merged.reduce((sum, c) => sum + c.e - c.s, 0);
551
- for (const { s, e } of merged) cuts.push({ s, e, after: earlier.w, gap, kept, sound: Boolean(sound) });
762
+ const split = lineGap && newLine && paused ? b.li : null;
763
+ merged.forEach(({ s, e }, m) => {
764
+ const cut = { s, e, after: earlier.w, gap, kept, sound: Boolean(sound) };
765
+ cuts.push(split !== null && m === merged.length - 1 ? { ...cut, atLine: split } : cut);
766
+ });
552
767
  }
553
768
  return cuts;
554
769
  }
@@ -627,7 +842,7 @@ function clipLevels(file, filter = null) {
627
842
  * trims, reaction splits, cue times, captions) works in cut time. The renderer
628
843
  * removes seg.cuts from the picture and the sound before anything else.
629
844
  */
630
- function tightenSentenceGaps(spine, reactionCues, scriptLines, readLevels) {
845
+ function tightenSentenceGaps(spine, reactionCues, scriptLines, readLevels, lineGap = null) {
631
846
  for (const seg of spine) {
632
847
  if (seg.source !== "clip" || seg.audio !== "clip" || !seg.words?.length) continue;
633
848
  const lines = seg.lineIds.map((id) => ({
@@ -635,11 +850,14 @@ function tightenSentenceGaps(spine, reactionCues, scriptLines, readLevels) {
635
850
  asksPause: asksPause(scriptLines.get(id)),
636
851
  cuesBeat: reactionCues.has(id),
637
852
  }));
638
- const cuts = sentenceGapCuts(seg.words, lines, readLevels(seg.file));
853
+ const cuts = sentenceGapCuts(seg.words, lines, readLevels(seg.file), lineGap);
639
854
  if (cuts.length === 0) continue;
640
855
  const removedBefore = (t) => cuts.reduce((sum, c) => sum + (c.e <= t ? c.e - c.s : 0), 0);
641
856
  const removed = removedBefore(Infinity);
642
857
  seg.cuts = cuts.map(({ s, e }) => ({ s, e }));
858
+ // cutPace: where the take is split, in its time once the gaps are out.
859
+ const splits = cuts.filter((c) => c.atLine !== undefined).map((c) => ({ at: c.s - removedBefore(c.s), line: c.atLine }));
860
+ if (splits.length > 0) seg.splits = splits;
643
861
  seg.words = seg.words.map((w) => ({ ...w, s: w.s - removedBefore(w.s), e: w.e - removedBefore(w.s) }));
644
862
  seg.seconds -= removed;
645
863
  seg.clipSeconds -= removed;
@@ -699,6 +917,7 @@ export function scenePlans(storyboard) {
699
917
  durationSec: typeof scene.durationSec === "number" ? scene.durationSec : null,
700
918
  actionTailSec: typeof scene.actionTailSec === "number" && scene.actionTailSec > 0 ? scene.actionTailSec : 0,
701
919
  actionLeadSec: typeof scene.actionLeadSec === "number" && scene.actionLeadSec > 0 ? scene.actionLeadSec : 0,
920
+ sourceShot: Number.isInteger(scene.sourceShot) && scene.sourceShot > 0 ? scene.sourceShot : null,
702
921
  broll:
703
922
  hasText(scene.broll?.covers) && Number.isFinite(scene.broll?.plannedSec) && scene.broll.plannedSec > 0
704
923
  ? { covers: scene.broll.covers, plannedSec: scene.broll.plannedSec }
@@ -877,12 +1096,16 @@ export function brollWindow(seg, counts, cueLineId, texts, broll) {
877
1096
  * one marked with actionLeadSec keeps that long before its first word, so the
878
1097
  * action it opens on (the dog stepping onto the mat, #3272) is seen.
879
1098
  */
880
- function trimJoins(spine, reactionCues, scriptLines) {
1099
+ function trimJoins(spine, reactionCues, scriptLines, gapMax = null) {
1100
+ // cutPace: the beat before someone new answers shrinks so the join holds at most gapMax of air.
1101
+ const newSpeakerLead = gapMax === null
1102
+ ? JOIN_LEAD_NEW_SPEAKER_SEC
1103
+ : Math.min(JOIN_LEAD_NEW_SPEAKER_SEC, roundMs(gapMax - JOIN_TAIL_SEC));
881
1104
  spine.forEach((seg, k) => {
882
1105
  if (seg.source !== "clip" || seg.audio !== "clip" || !seg.words?.length) return;
883
1106
  const prev = spine[k - 1];
884
1107
  const sameSpeaker = Boolean(prev?.lastSpeaker) && prev.lastSpeaker === seg.firstSpeaker;
885
- const lead = sameSpeaker || !prev ? JOIN_LEAD_SAME_SPEAKER_SEC : JOIN_LEAD_NEW_SPEAKER_SEC;
1108
+ const lead = sameSpeaker || !prev ? JOIN_LEAD_SAME_SPEAKER_SEC : newSpeakerLead;
886
1109
  const span = scriptedSpan(seg.words, seg.lineIds.map((id) => scriptLines.get(id)?.text));
887
1110
  const line = span ? seg.words.slice(span.first, span.last + 1) : seg.words;
888
1111
  const before = span ? seg.words.slice(0, span.first) : [];
@@ -1022,6 +1245,47 @@ function markPunchIns(spine, sameShot) {
1022
1245
 
1023
1246
  const sameSpeaker = (prev, seg) => Boolean(prev.lastSpeaker && seg.firstSpeaker === prev.lastSpeaker);
1024
1247
 
1248
+ /** cutPace: two pieces of one take, back to back. */
1249
+ const samePiece = (prev, seg) =>
1250
+ Boolean(prev.piece && seg.piece && prev.file === seg.file && prev.piece.take === seg.piece.take);
1251
+
1252
+ /**
1253
+ * cutPace: split each take at the pauses tightenSentenceGaps marked, where one
1254
+ * line ends and the next begins, so the pieces join as a jump cut. Each piece
1255
+ * plays its own lines, on whole frames, from the same file.
1256
+ */
1257
+ function splitAtPauses(spine) {
1258
+ for (let k = spine.length - 1; k >= 0; k--) {
1259
+ const seg = spine[k];
1260
+ const marks = seg.splits ?? [];
1261
+ delete seg.splits;
1262
+ const at = marks
1263
+ .map((m) => ({ t: Math.round((m.at - seg.inSec) * FPS) / FPS, line: m.line }))
1264
+ .filter((m) => m.t > 0 && m.t < seg.seconds);
1265
+ if (at.length === 0) continue;
1266
+ const edges = [0, ...at.map((m) => m.t), seg.seconds];
1267
+ const lineEdges = [0, ...at.map((m) => m.line), seg.lineIds.length];
1268
+ const of = edges.length - 1;
1269
+ const pieces = edges.slice(0, -1).map((from, j) => {
1270
+ const to = edges[j + 1];
1271
+ const piece = {
1272
+ ...seg,
1273
+ inSec: seg.inSec + from,
1274
+ seconds: to - from,
1275
+ lineIds: seg.lineIds.slice(lineEdges[j], lineEdges[j + 1]),
1276
+ words: seg.words
1277
+ ? seg.words.filter((w) => w.s >= from && w.s < to).map((w) => ({ ...w, s: w.s - from, e: w.e - from }))
1278
+ : null,
1279
+ piece: { take: seg.sceneIndex, n: j + 1, of },
1280
+ note: `${seg.note}, piece ${j + 1} of ${of}`,
1281
+ };
1282
+ piece.holdSec = holdFor(piece);
1283
+ return piece;
1284
+ });
1285
+ spine.splice(k, 1, ...pieces);
1286
+ }
1287
+ }
1288
+
1025
1289
  /**
1026
1290
  * The pacings whose edit punches in, each with when a scene plays on in the
1027
1291
  * shot of the one before it. Jump cuts film every scene in one framing. A
@@ -1051,8 +1315,129 @@ export function scenesWithNoClip({ manifest, storyboard, skip, exists = Boolean
1051
1315
  .sort((a, b) => a - b);
1052
1316
  }
1053
1317
 
1318
+ /**
1319
+ * A kind's songAsVoice: the voice is one track, a song, laid whole under the
1320
+ * picture and never cut, and each narrated scene lasts its own stretch of it
1321
+ * (the pulled narration.json's cuts, which run on from one another to the
1322
+ * song's end). Null, and the cut is today's, without the manifest's
1323
+ * `wholeVoice` or without the pulled narration.
1324
+ */
1325
+ export function wholeVoiceOf(manifest, readJson, exists) {
1326
+ if (manifest?.wholeVoice !== true || !exists(manifest.narration?.file)) return null;
1327
+ const cuts = readJson(manifest.narration.timing)?.cuts;
1328
+ if (!Array.isArray(cuts) || cuts.length === 0) return null;
1329
+ return {
1330
+ file: manifest.narration.file,
1331
+ seconds: Math.max(...cuts.map((c) => c.startSec + c.durationSec)),
1332
+ starts: new Map(cuts.map((c) => [c.sceneIndex, c.startSec])),
1333
+ };
1334
+ }
1335
+
1336
+ const roundFrame = (t) => Math.round(t * FPS) / FPS;
1337
+
1338
+ /**
1339
+ * Lays the spine on the whole voice. Each scene with a stretch of the voice
1340
+ * runs from its stretch's start to the next one's, the last to the voice's
1341
+ * end, on whole frames, its clip trimmed or its last frame held to fit. A
1342
+ * scene with no stretch (no line) between two that have one keeps its clip
1343
+ * but takes its time from the scene before it, never past that scene's last
1344
+ * word, so every later line still lands on its words; one with no room left
1345
+ * is dropped. Scenes before the first stretch play first and the voice starts
1346
+ * after them. Returns where the voice starts and what was dropped.
1347
+ */
1348
+ export function fitWholeVoice(spine, whole) {
1349
+ const on = spine.flatMap((seg, k) => (whole.starts.has(seg.sceneIndex) ? [k] : []));
1350
+ if (on.length === 0) return null;
1351
+ const startSec = spine.slice(0, on[0]).reduce((t, seg) => t + seg.seconds, 0);
1352
+ const gone = new Set();
1353
+ on.forEach((k, j) => {
1354
+ const seg = spine[k];
1355
+ const next = on[j + 1];
1356
+ const from = j === 0 ? 0 : roundFrame(whole.starts.get(seg.sceneIndex));
1357
+ const to = next === undefined ? ceilFrame(whole.seconds) : roundFrame(whole.starts.get(spine[next].sceneIndex));
1358
+ const spoken = Math.max(1 / FPS, ceilFrame(Math.max(0, ...(seg.words ?? []).map((w) => w.e))));
1359
+ let room = Math.max(0, to - from - spoken);
1360
+ let given = 0;
1361
+ for (const b of next === undefined ? [] : spine.slice(k + 1, next)) {
1362
+ const seconds = Math.min(b.seconds, floorFrame(room));
1363
+ if (seconds < 1 / FPS) {
1364
+ gone.add(b);
1365
+ continue;
1366
+ }
1367
+ if (seconds < b.seconds) b.note = withHow(b.note, [`cut to ${seconds.toFixed(2)}s to keep the voice on its lines`]);
1368
+ b.seconds = seconds;
1369
+ b.holdSec = holdFor(b);
1370
+ room -= seconds;
1371
+ given += seconds;
1372
+ }
1373
+ seg.seconds = to - from - given;
1374
+ seg.holdSec = holdFor(seg);
1375
+ seg.wholeVoice = true;
1376
+ seg.note = withHow(seg.note, [`on the whole voice from ${from.toFixed(2)}s to ${to.toFixed(2)}s`]);
1377
+ });
1378
+ const dropped = spine
1379
+ .filter((seg) => gone.has(seg))
1380
+ .map((seg) => ({ n: seg.sceneIndex, reason: `scene ${seg.sceneIndex}: no room left between two lines of the voice` }));
1381
+ for (let k = spine.length - 1; k >= 0; k--) if (gone.has(spine[k])) spine.splice(k, 1);
1382
+ return { startSec, dropped };
1383
+ }
1384
+
1385
+ /**
1386
+ * The manifest's `sourceAd` (a kind's shotCopy with a source record), or null:
1387
+ * the record's shot times, its caption style, hook box and card boxes. The
1388
+ * worker writes it; a member's own pull has none, so their cut is today's.
1389
+ */
1390
+ export function sourceAdOf(manifest) {
1391
+ const a = manifest?.sourceAd;
1392
+ if (!a || typeof a !== "object" || !(a.seconds > 0) || !Array.isArray(a.shots) || a.shots.length === 0) return null;
1393
+ return {
1394
+ ...a,
1395
+ cards: Array.isArray(a.cards) ? a.cards : [],
1396
+ pictures: Array.isArray(a.pictures) ? a.pictures : [],
1397
+ };
1398
+ }
1399
+
1400
+ /**
1401
+ * The copied shots laid on the cut. Each scene names the shot it copies (the
1402
+ * storyboard's sourceShot). A spine scene and the shots after it that no spine
1403
+ * scene copies (its cutaways) make one group, the source's voice running over
1404
+ * them as ours does; shots before the first spine scene join its group. Each
1405
+ * group's stretch of the source maps evenly onto its stretch of the cut, so a
1406
+ * cutaway lands at its shot's own place in the group. Returns
1407
+ * [{ shots: [n...], src: [t0, t1], cut: [c0, c1] }], in order.
1408
+ */
1409
+ export function sourceGroups(spine, sourceAd, shotOf) {
1410
+ const entries = [...sourceAd.shots].sort((a, b) => a.n - b.n);
1411
+ const onSpine = new Map();
1412
+ for (const seg of spine) {
1413
+ const n = shotOf(seg.sceneIndex);
1414
+ if (n === null || !entries.some((e) => e.n === n)) continue;
1415
+ const at = onSpine.get(n) ?? { c0: Infinity, c1: -Infinity };
1416
+ onSpine.set(n, { c0: Math.min(at.c0, seg.startSec), c1: Math.max(at.c1, seg.startSec + seg.seconds) });
1417
+ }
1418
+ const heads = entries.filter((e) => onSpine.has(e.n));
1419
+ return heads.map((head, i) => {
1420
+ const next = heads[i + 1];
1421
+ const shots = entries.filter((e) => (i === 0 || e.n >= head.n) && (!next || e.n < next.n));
1422
+ const src0 = i === 0 ? Math.min(head.t0, shots[0].t0) : head.t0;
1423
+ const src1 = next ? next.t0 : Math.max(...shots.map((e) => e.t1));
1424
+ const cut1 = next ? onSpine.get(next.n).c0 : onSpine.get(head.n).c1;
1425
+ return { shots: shots.map((e) => e.n), src: [src0, src1], cut: [roundMs(onSpine.get(head.n).c0), roundMs(cut1)] };
1426
+ });
1427
+ }
1428
+
1429
+ /** A time of the source ad on the cut, through its group (the first or last group's ends past them). */
1430
+ export function mapSourceTime(groups, t) {
1431
+ if (groups.length === 0) return t;
1432
+ const g = groups.find((x) => t < x.src[1]) ?? groups.at(-1);
1433
+ const span = g.src[1] - g.src[0];
1434
+ const k = span > 0 ? (g.cut[1] - g.cut[0]) / span : 1;
1435
+ return Math.min(g.cut[1], Math.max(g.cut[0], g.cut[0] + (t - g.src[0]) * k));
1436
+ }
1437
+
1054
1438
  export function buildTimeline({
1055
- manifest, storyboard, skip, probe, exists, readWords, readLevels = () => null, stillFill = false,
1439
+ manifest, storyboard, skip, probe, exists, readWords, readLevels = () => null, stillFill = false, finish = null,
1440
+ wholeVoice = null, sourceAd = null,
1056
1441
  }) {
1057
1442
  const plans = scenePlans(storyboard);
1058
1443
  const counts = lineWordCounts(storyboard);
@@ -1193,6 +1578,9 @@ export function buildTimeline({
1193
1578
  })));
1194
1579
  }
1195
1580
 
1581
+ const whole = wholeVoice ? fitWholeVoice(spine, wholeVoice) : null;
1582
+ if (whole) dropped.push(...whole.dropped);
1583
+
1196
1584
  const sameShot = PUNCH_IN_RUNS.get(manifest?.shots?.pacing);
1197
1585
  if (sameShot) markPunchIns(spine, sameShot);
1198
1586
 
@@ -1205,10 +1593,23 @@ export function buildTimeline({
1205
1593
  const scriptLines = new Map((storyboard?.script ?? []).map((line) => [line?.lineId, line]));
1206
1594
  const reactionCues = new Set(waiting.filter((w) => w.reaction).map((w) => w.cueLineId));
1207
1595
  const last = spine.at(-1);
1208
- if (refits.has(last) && !reactionCues.has(last.lineIds.at(-1))) Object.assign(last, refits.get(last)(true));
1209
- tightenSentenceGaps(spine, reactionCues, scriptLines, readLevels);
1210
- trimJoins(spine, reactionCues, scriptLines);
1596
+ if (!whole && refits.has(last) && !reactionCues.has(last.lineIds.at(-1))) Object.assign(last, refits.get(last)(true));
1597
+ const pace = finish?.cutPace === true;
1598
+ const lineGap = pace ? { max: PACE_SPLIT_PAUSE_SEC, keep: PACE_GAP_MAX_SEC } : null;
1599
+ tightenSentenceGaps(spine, reactionCues, scriptLines, readLevels, lineGap);
1600
+ trimJoins(spine, reactionCues, scriptLines, pace ? PACE_GAP_MAX_SEC : null);
1601
+ if (pace) {
1602
+ // The pieces of one take alternate between the plain frame and the
1603
+ // punch-in, and a jump-cut run's alternation carries on across them.
1604
+ splitAtPauses(spine);
1605
+ for (const seg of spine) delete seg.punchIn;
1606
+ markPunchIns(spine, (prev, seg) => samePiece(prev, seg) || Boolean(sameShot?.(prev, seg)));
1607
+ }
1211
1608
  for (const c of waiting.filter((w) => w.reaction)) {
1609
+ if (whole) {
1610
+ dropped.push({ n: c.sceneIndex, reason: `cutaway ${c.sceneIndex}: a reaction beat would stop the voice laid whole` });
1611
+ continue;
1612
+ }
1212
1613
  if (!c.cueLineId || placeReaction(spine, counts, c) === null) {
1213
1614
  dropped.push({ n: c.sceneIndex, reason: `cutaway ${c.sceneIndex}: ${noCue(c)}` });
1214
1615
  }
@@ -1220,6 +1621,21 @@ export function buildTimeline({
1220
1621
  else seg.fadeOutSec = Math.min(REACTION_FADE_OUT_SEC, seg.seconds);
1221
1622
  seg.fadeInSec = quietStart(readLevels(seg.file), seg.seconds);
1222
1623
  });
1624
+ // A copied shot no voice runs in lasts its shot's length, its clip trimmed or its last frame held.
1625
+ const shotOf = (n) => plans.get(n)?.sourceShot ?? null;
1626
+ const shotSec = (n) => {
1627
+ const e = sourceAd?.shots.find((x) => x.n === shotOf(n));
1628
+ return e ? e.t1 - e.t0 : null;
1629
+ };
1630
+ if (sourceAd) {
1631
+ for (const seg of spine) {
1632
+ const len = seg.audio === "silence" && !seg.reaction ? shotSec(seg.sceneIndex) : null;
1633
+ if (len === null) continue;
1634
+ seg.seconds = ceilFrame(len);
1635
+ seg.holdSec = holdFor(seg);
1636
+ seg.note = withHow(seg.note, [`its source shot's ${len.toFixed(2)}s`]);
1637
+ }
1638
+ }
1223
1639
  let total = 0;
1224
1640
  for (const seg of spine) {
1225
1641
  seg.startSec = total;
@@ -1228,10 +1644,22 @@ export function buildTimeline({
1228
1644
  spine.forEach((seg, k) => {
1229
1645
  if (seg.reaction?.tail) seg.reaction.tail.atSec = spine[k + 1].startSec;
1230
1646
  });
1647
+ const groups = sourceAd ? sourceGroups(spine, sourceAd, shotOf) : null;
1231
1648
 
1232
1649
  const lineTexts = new Map([...scriptLines].map(([id, line]) => [id, line?.text]));
1233
1650
  const beats = spine.filter((seg) => seg.reaction);
1234
1651
  for (const c of waiting.filter((w) => !w.reaction)) {
1652
+ // A copied shot lands where its shot sits in the source, through its group.
1653
+ const copied = groups?.length ? sourceAd.shots.find((e) => e.n === shotOf(c.sceneIndex)) : null;
1654
+ if (copied) {
1655
+ const startSec = roundMs(mapSourceTime(groups, copied.t0));
1656
+ const span = roundMs(mapSourceTime(groups, copied.t1) - startSec);
1657
+ cutaways.push({
1658
+ ...c, startSec, method: "source", sourceShot: copied.n,
1659
+ seconds: c.source === "clip" ? Math.min(span, c.seconds) : span,
1660
+ });
1661
+ continue;
1662
+ }
1235
1663
  const cue = c.cueLineId ? cueOffsetOnSpine(spine, counts, c.cueLineId) : null;
1236
1664
  if (!cue) {
1237
1665
  dropped.push({ n: c.sceneIndex, reason: `cutaway ${c.sceneIndex}: ${noCue(c)}` });
@@ -1272,9 +1700,79 @@ export function buildTimeline({
1272
1700
  spine,
1273
1701
  cutaways,
1274
1702
  left: dropped.sort((a, b) => a.n - b.n).map((d) => d.reason),
1703
+ ...(whole ? { wholeVoice: { file: wholeVoice.file, startSec: whole.startSec } } : {}),
1704
+ ...(groups ? { sourceGroups: groups } : {}),
1275
1705
  };
1276
1706
  }
1277
1707
 
1708
+ /**
1709
+ * brollMinSec: a cutaway on screen for less than `minSec` of the finished ad
1710
+ * (its time in the cut over `speed`) is left out, and the shot before it plays
1711
+ * on over its time: the cutaway that ends where it starts, its last frame held
1712
+ * if its clip runs out, else the scene under it. `clipSeconds(file)` is a
1713
+ * clip's length. Returns a line for each cutaway left out.
1714
+ */
1715
+ export function holdBroll(timeline, minSec, speed, clipSeconds) {
1716
+ const kept = [];
1717
+ const left = [];
1718
+ for (const c of timeline.cutaways) {
1719
+ const shown = c.seconds / speed;
1720
+ if (shown >= minSec - 1e-6) {
1721
+ kept.push(c);
1722
+ continue;
1723
+ }
1724
+ const why = `cutaway ${c.sceneIndex}: ${shown.toFixed(2)}s on screen, under the ${minSec}s B-roll minimum, so it is left out and`;
1725
+ const before = kept.at(-1);
1726
+ if (before && Math.abs(before.startSec + before.seconds - c.startSec) < 0.5 / FPS) {
1727
+ before.seconds = roundMs(c.startSec + c.seconds - before.startSec);
1728
+ if (c.cutShortBy) before.cutShortBy = c.cutShortBy;
1729
+ else delete before.cutShortBy;
1730
+ const hold = before.source === "clip" ? roundMs(before.seconds - clipSeconds(before.file)) : 0;
1731
+ if (hold > 0) before.holdSec = hold;
1732
+ left.push(`${why} cutaway ${before.sceneIndex} plays on over it`);
1733
+ } else {
1734
+ left.push(`${why} the scene under it plays on`);
1735
+ }
1736
+ }
1737
+ timeline.cutaways = kept;
1738
+ return left;
1739
+ }
1740
+
1741
+ /** speedUpSlowBroll: the most a slow cutaway is sped up. */
1742
+ export const SLOW_SHOT_SPEED_MAX = 1.6;
1743
+
1744
+ /**
1745
+ * speedUpSlowBroll: every shot's motion is read off its clip before the render
1746
+ * (`motionOf(file, fromSec, seconds)`), and a cutaway that slowShots finds slow
1747
+ * plays its clip faster, at most SLOW_SHOT_SPEED_MAX, so it shows more of its
1748
+ * clip in the same time on screen. A cutaway whose clip is no longer than its
1749
+ * time on screen cannot be, and is noted. Returns a line for each slow cutaway.
1750
+ */
1751
+ export function speedUpSlowBroll(timeline, motionOf, clipSeconds) {
1752
+ const shots = [
1753
+ ...timeline.spine
1754
+ .filter((seg) => seg.source === "clip")
1755
+ .map((seg) => ({ n: seg.sceneIndex, role: roleOf(seg), file: seg.file, from: seg.inSec ?? 0, sec: seg.seconds - (seg.holdSec ?? 0) })),
1756
+ ...timeline.cutaways
1757
+ .filter((c) => c.source === "clip")
1758
+ .map((c) => ({ n: c.sceneIndex, role: "b-roll", file: c.file, from: 0, sec: c.seconds, cutaway: c })),
1759
+ ].filter((s) => s.sec > 0);
1760
+ const measured = shots.map((s) => ({ ...s, motion: motionOf(s.file, s.from, s.sec) }));
1761
+ const notes = [];
1762
+ for (const slow of slowShots(measured)) {
1763
+ const c = slow.cutaway;
1764
+ if (!c) continue;
1765
+ const have = clipSeconds(c.file);
1766
+ if (!(have > c.seconds + 0.05)) {
1767
+ 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`);
1768
+ continue;
1769
+ }
1770
+ c.speed = roundMs(Math.min(have / c.seconds, SLOW_SHOT_SPEED_MAX));
1771
+ 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`);
1772
+ }
1773
+ return notes;
1774
+ }
1775
+
1278
1776
  /** #3365: why the cut stopped on scenes with no clip, and the person's three ways on. */
1279
1777
  function noClipRefusal(missing) {
1280
1778
  const scenes = missing.map((m) => `scene ${m.n} (${m.status})`).join(", ");
@@ -1293,7 +1791,17 @@ function sec(n) {
1293
1791
  return (Number.isFinite(n) ? Math.max(0, n) : 0).toFixed(3);
1294
1792
  }
1295
1793
 
1296
- export function buildFfmpegArgs(timeline, { resolve, music, out }) {
1794
+ /**
1795
+ * The render. `finish` (null: today's render) carries the finishing settings'
1796
+ * part of it: levelSegments false leaves each segment's sound as it is for the
1797
+ * whole mix's loudness pass, `ass` names the captions and cards file burned in
1798
+ * (read from the folder ffmpeg runs in), `speed` over 1 speeds the whole
1799
+ * cut, picture and sound, after the burn, `clean` (cleanVoice) is the voice's
1800
+ * chain and the duck under it, and `meters` (cutChecks) names the two files
1801
+ * the voice and everything under it are also written to.
1802
+ */
1803
+ export function buildFfmpegArgs(timeline, { resolve, music, out, finish = null, sound = null }) {
1804
+ const level = finish && finish.levelSegments === false ? "anull" : LOUDNORM;
1297
1805
  const inputs = [];
1298
1806
  let count = 0;
1299
1807
  const addInput = (...args) => {
@@ -1350,8 +1858,10 @@ export function buildFfmpegArgs(timeline, { resolve, music, out }) {
1350
1858
  const fitLength =
1351
1859
  `apad,atrim=0:${sec(seg.seconds)},afade=t=in:d=${sec(fadeIn)}${rise},` +
1352
1860
  `afade=t=out:st=${sec(seg.seconds - fadeOut)}:d=${sec(fadeOut)}`;
1353
- const fitSound = `${LOUDNORM},${fitLength}`;
1354
- if (seg.audio === "narration") {
1861
+ const fitSound = `${level},${fitLength}`;
1862
+ if (seg.wholeVoice) {
1863
+ filters.push(`anullsrc=r=48000:cl=stereo,atrim=0:${sec(seg.seconds)}[a${i}]`);
1864
+ } else if (seg.audio === "narration") {
1355
1865
  const v = addInput("-i", resolve(seg.voice));
1356
1866
  filters.push(`[${v}:a]${stereo},${skipIn}${fitSound}[a${i}]`);
1357
1867
  } else if (seg.audio === "clip" && seg.reaction?.tail) {
@@ -1359,7 +1869,7 @@ export function buildFfmpegArgs(timeline, { resolve, music, out }) {
1359
1869
  // ducked, faded out, and laid in at the join; the next line's own sound
1360
1870
  // plays at full level over it (#2406).
1361
1871
  const t = seg.reaction.tail;
1362
- filters.push(`${heard}${skipIn}${LOUDNORM},asplit=2[as${i}][at${i}]`);
1872
+ filters.push(`${heard}${skipIn}${level},asplit=2[as${i}][at${i}]`);
1363
1873
  filters.push(`[as${i}]${fitLength}[a${i}]`);
1364
1874
  filters.push(
1365
1875
  `[at${i}]atrim=start=${sec(t.fromSec - inSec)}:duration=${sec(t.seconds)},asetpts=PTS-STARTPTS,` +
@@ -1380,7 +1890,18 @@ export function buildFfmpegArgs(timeline, { resolve, music, out }) {
1380
1890
  // ends on its own. No -shortest: ffmpeg 8 held the whole ad's frames for it,
1381
1891
  // and Debian's ffmpeg 5.1 (the worker's) never ended at all (#2988).
1382
1892
  const pictureSec = timeline.spine.reduce((sum, seg) => sum + seg.seconds, 0);
1383
- filters.push(`[voicecat]apad,atrim=end=${pictureSec.toFixed(6)}[voice]`);
1893
+ if (timeline.wholeVoice) {
1894
+ // The voice laid whole from where its first scene starts, under the spine's own sound.
1895
+ const k = addInput("-i", resolve(timeline.wholeVoice.file));
1896
+ filters.push(`[voicecat]apad,atrim=end=${pictureSec.toFixed(6)}[spoken]`);
1897
+ filters.push(
1898
+ `[${k}:a]${stereo},${level},adelay=delays=${Math.round(timeline.wholeVoice.startSec * 1000)}:all=1,` +
1899
+ `apad,atrim=end=${pictureSec.toFixed(6)}[whole]`,
1900
+ );
1901
+ filters.push("[spoken][whole]amix=inputs=2:duration=first:dropout_transition=0:normalize=0[voice]");
1902
+ } else {
1903
+ filters.push(`[voicecat]apad,atrim=end=${pictureSec.toFixed(6)}[voice]`);
1904
+ }
1384
1905
 
1385
1906
  let videoLabel = "vcat";
1386
1907
  timeline.cutaways.forEach((c, j) => {
@@ -1389,8 +1910,11 @@ export function buildFfmpegArgs(timeline, { resolve, music, out }) {
1389
1910
  ? addInput("-i", resolve(c.file))
1390
1911
  : addInput("-loop", "1", "-t", String(c.seconds), "-i", resolve(c.file));
1391
1912
  const end = c.startSec + c.seconds;
1913
+ // speedUpSlowBroll: a slow cutaway plays faster; brollMinSec: one that plays on past its clip holds its last frame.
1914
+ const faster = c.speed > 1 ? `,setpts=PTS/${c.speed}` : "";
1915
+ const hold = c.holdSec > 0 ? `,tpad=stop_mode=clone:stop_duration=${sec(c.holdSec)}` : "";
1392
1916
  filters.push(
1393
- `${norm(`${i}:v`)},trim=0:${sec(c.seconds)},setpts=PTS-STARTPTS+${sec(c.startSec)}/TB[cv${j}]`,
1917
+ `${norm(`${i}:v`)}${faster}${hold},trim=0:${sec(c.seconds)},setpts=PTS-STARTPTS+${sec(c.startSec)}/TB[cv${j}]`,
1394
1918
  );
1395
1919
  // eof_action=pass keeps the spine showing once the cutaway's frames end.
1396
1920
  filters.push(
@@ -1399,17 +1923,103 @@ export function buildFfmpegArgs(timeline, { resolve, music, out }) {
1399
1923
  videoLabel = `ov${j}`;
1400
1924
  });
1401
1925
 
1402
- filters.push(`${ROOM_TONE}[room]`);
1403
- const beds = ["[room]", ...tails];
1926
+ // A copied ad's product cards: the product sheet picture fitted into each source box, for its time.
1927
+ (finish?.pictures ?? []).forEach((p, j) => {
1928
+ const k = addInput("-loop", "1", "-t", sec(p.endSec), "-i", resolve(p.file));
1929
+ const w = Math.round((p.box[2] - p.box[0]) * WIDTH);
1930
+ const h = Math.round((p.box[3] - p.box[1]) * HEIGHT);
1931
+ filters.push(`[${k}:v]scale=${w}:${h}:force_original_aspect_ratio=decrease,format=rgba[pic${j}]`);
1932
+ filters.push(
1933
+ `[${videoLabel}][pic${j}]overlay=x=${Math.round(p.box[0] * WIDTH)}+(${w}-overlay_w)/2:y=${Math.round(p.box[1] * HEIGHT)}+(${h}-overlay_h)/2` +
1934
+ `:enable=between(t\\,${sec(p.startSec)}\\,${sec(p.endSec)}):eof_action=pass[pin${j}]`,
1935
+ );
1936
+ videoLabel = `pin${j}`;
1937
+ });
1938
+ if (finish?.ass) {
1939
+ filters.push(`[${videoLabel}]subtitles=filename=${finish.ass}[burned]`);
1940
+ videoLabel = "burned";
1941
+ }
1942
+ const speed = finish?.speed > 1 ? finish.speed : null;
1943
+ if (speed) {
1944
+ filters.push(`[${videoLabel}]setpts=PTS/${speed}[faster]`);
1945
+ videoLabel = "faster";
1946
+ }
1947
+
1948
+ const beds = [];
1949
+ if (sound?.beds?.length) {
1950
+ sound.beds.forEach((b, j) => {
1951
+ const k = addInput("-stream_loop", "-1", "-i", resolve(b.file));
1952
+ filters.push(
1953
+ `[${k}:a]${stereo},atrim=0:${sec(b.seconds)},asetpts=PTS-STARTPTS,volume=${b.gainDb}dB,` +
1954
+ `afade=t=in:d=${BED_FADE_SEC},afade=t=out:st=${sec(Math.max(0, b.seconds - BED_FADE_SEC))}:d=${BED_FADE_SEC},` +
1955
+ `adelay=delays=${Math.round(b.startSec * 1000)}:all=1[set${j}]`,
1956
+ );
1957
+ beds.push(`[set${j}]`);
1958
+ });
1959
+ } else {
1960
+ filters.push(`${ROOM_TONE}[room]`);
1961
+ beds.push("[room]");
1962
+ }
1963
+ beds.push(...tails);
1964
+ (sound?.effects ?? []).forEach((e, j) => {
1965
+ const k = addInput("-i", resolve(e.file));
1966
+ filters.push(`[${k}:a]${stereo},volume=${e.gainDb}dB,adelay=delays=${Math.round(e.atSec * 1000)}:all=1[sfx${j}]`);
1967
+ beds.push(`[sfx${j}]`);
1968
+ });
1969
+ let voice = "[voice]";
1970
+ const clean = finish?.clean ?? null;
1404
1971
  if (music) {
1405
1972
  const m = addInput("-stream_loop", "-1", "-i", music);
1406
- filters.push(`[${m}:a]${stereo},volume=${MUSIC_VOLUME}[bed]`);
1973
+ const duck = clean ? null : sound?.music?.duck;
1974
+ if (duck) {
1975
+ filters.push("[voice]asplit=2[voiced][duckkey]");
1976
+ filters.push(`[${m}:a]${stereo},atrim=0:${pictureSec.toFixed(6)},asetpts=PTS-STARTPTS,volume=${sound.music.gainDb}dB[bedraw]`);
1977
+ filters.push(
1978
+ `[bedraw][duckkey]sidechaincompress=threshold=${duck.threshold}:ratio=${duck.ratio}:attack=${duck.attack}:release=${duck.release}[bed]`,
1979
+ );
1980
+ voice = "[voiced]";
1981
+ } else if (clean && sound?.music) {
1982
+ filters.push(`[${m}:a]${stereo},atrim=0:${pictureSec.toFixed(6)},asetpts=PTS-STARTPTS,volume=${sound.music.gainDb}dB[bed]`);
1983
+ } else {
1984
+ filters.push(`[${m}:a]${stereo},volume=${MUSIC_VOLUME}[bed]`);
1985
+ }
1407
1986
  beds.push("[bed]");
1408
1987
  }
1988
+ let under = beds;
1989
+ if (clean) {
1990
+ // Each bed is trimmed to the picture, then ducked on its own by the same key, which ducks their sum the same.
1991
+ const ducked = beds.filter((label) => !tails.includes(label));
1992
+ const u = clean.under;
1993
+ filters.push(`[voice]${clean.voice},asplit=${ducked.length + 1}[voiced]${ducked.map((_, j) => `[vkey${j}]`).join("")}`);
1994
+ ducked.forEach((label, j) => {
1995
+ filters.push(`${label}atrim=end=${pictureSec.toFixed(6)},highpass=f=${u.highpass},lowpass=f=${u.lowpass},volume=${u.db}dB[uc${j}]`);
1996
+ filters.push(
1997
+ `[uc${j}][vkey${j}]sidechaincompress=threshold=${u.duck.threshold}:ratio=${u.duck.ratio}:attack=${u.duck.attack}:release=${u.duck.release}[ud${j}]`,
1998
+ );
1999
+ });
2000
+ voice = "[voiced]";
2001
+ under = [...ducked.map((_, j) => `[ud${j}]`), ...tails];
2002
+ }
2003
+ if (finish?.meters) {
2004
+ // cutChecks: the voice, and everything under it mixed, each also written alone to be measured.
2005
+ filters.push(`${voice}asplit=2[metered][vmeter]`);
2006
+ voice = "[metered]";
2007
+ under = under.map((label, j) => {
2008
+ filters.push(`${label}asplit=2[mu${j}][mb${j}]`, `[mb${j}]atrim=end=${pictureSec.toFixed(6)}[mt${j}]`);
2009
+ return `[mu${j}]`;
2010
+ });
2011
+ filters.push(
2012
+ `${under.map((_, j) => `[mt${j}]`).join("")}amix=inputs=${under.length}:duration=longest:dropout_transition=0:normalize=0[bedmeter]`,
2013
+ );
2014
+ }
1409
2015
  filters.push(
1410
- `[voice]${beds.join("")}amix=inputs=${beds.length + 1}:duration=first:dropout_transition=0:normalize=0[mix]`,
2016
+ `${voice}${under.join("")}amix=inputs=${under.length + 1}:duration=first:dropout_transition=0:normalize=0[mix]`,
1411
2017
  );
1412
- const audioLabel = "mix";
2018
+ let audioLabel = "mix";
2019
+ if (speed) {
2020
+ filters.push(`[mix]atempo=${speed}[mixfaster]`);
2021
+ audioLabel = "mixfaster";
2022
+ }
1413
2023
 
1414
2024
  return [
1415
2025
  "-y", "-hide_banner", "-loglevel", "error",
@@ -1420,6 +2030,9 @@ export function buildFfmpegArgs(timeline, { resolve, music, out }) {
1420
2030
  "-c:a", "aac", "-b:a", "192k",
1421
2031
  "-movflags", "+faststart",
1422
2032
  out,
2033
+ ...(finish?.meters
2034
+ ? ["-map", "[vmeter]", "-c:a", "pcm_s16le", finish.meters.voice, "-map", "[bedmeter]", "-c:a", "pcm_s16le", finish.meters.bed]
2035
+ : []),
1423
2036
  ];
1424
2037
  }
1425
2038
 
@@ -1673,6 +2286,551 @@ export function noWordTimes(timeline) {
1673
2286
  return rows;
1674
2287
  }
1675
2288
 
2289
+ // ---- finishing: captions and cards drawn by code, the pace report, the loudness pass ----
2290
+
2291
+ const pad2 = (n) => String(n).padStart(2, "0");
2292
+ const round2 = (n) => Math.round(n * 100) / 100;
2293
+ const assTime = (t) => {
2294
+ const cs = Math.round(Math.max(0, t) * 100);
2295
+ return `${Math.floor(cs / 360000)}:${pad2(Math.floor(cs / 6000) % 60)}:${pad2(Math.floor(cs / 100) % 60)}.${pad2(cs % 100)}`;
2296
+ };
2297
+ const assText = (s) => String(s).replace(/[{}\\]/g, "").replace(/\s*[\r\n]+\s*/g, " ").trim();
2298
+
2299
+ /** A caption screen never holds words across a pause longer than this, so a silent beat shows none. */
2300
+ export const CAPTION_BREAK_SEC = 0.8;
2301
+
2302
+ /**
2303
+ * Caption screens from the cut's words: a few words a screen (`cap`, a source
2304
+ * record's caption style, else 3), never across a pause, each up until 0.25 s
2305
+ * after its last word or the next screen. `words`: [{ text, start, end }].
2306
+ */
2307
+ export function captionScreens(words, cap = null) {
2308
+ const per = Math.max(1, Math.round(cap?.wordsPerLine?.median ?? 3));
2309
+ const caps = /all-caps|capitals|upper/i.test(cap?.style ?? "");
2310
+ const chunks = [];
2311
+ let cur = [];
2312
+ for (const w of words) {
2313
+ if (cur.length && (cur.length >= per || w.start - cur.at(-1).end > CAPTION_BREAK_SEC)) {
2314
+ chunks.push(cur);
2315
+ cur = [];
2316
+ }
2317
+ cur.push(w);
2318
+ }
2319
+ if (cur.length) chunks.push(cur);
2320
+ return chunks.map((ws, k) => {
2321
+ const next = chunks[k + 1]?.[0];
2322
+ const text = ws.map((w) => assText(w.text)).join(" ").replace(/[.,;:]+$/, "");
2323
+ return {
2324
+ text: caps ? text.toUpperCase() : text,
2325
+ s: ws[0].start,
2326
+ e: roundMs(Math.min(ws.at(-1).end + 0.25, next?.start ?? Infinity)),
2327
+ };
2328
+ });
2329
+ }
2330
+
2331
+ /**
2332
+ * captionsByLine: a caption screen holds the words of one script line only, a
2333
+ * few a screen (`cap`, a source record's caption style, else 3), breaks on a
2334
+ * pause over CAPTION_LINE_GAP_SEC, stays up CAPTION_TAIL_SEC after its last
2335
+ * word at most and goes off CAPTION_CLEAR_SEC before the next comes on. A
2336
+ * screen shorter than CAPTION_MIN_SEC joins the next one of its line, else the
2337
+ * one before, one word over the few at most. `words`: [{ text, start, end, line }].
2338
+ */
2339
+ export const CAPTION_LINE_GAP_SEC = 0.5;
2340
+ export const CAPTION_TAIL_SEC = 0.15;
2341
+ export const CAPTION_CLEAR_SEC = 0.02;
2342
+ export const CAPTION_MIN_SEC = 0.35;
2343
+ /** captionsByLine: the caption font is at most this share of the frame's height (69 px of 1920). */
2344
+ export const CAPTION_MAX_SHARE = 0.036;
2345
+
2346
+ export function lineCaptionScreens(words, cap = null) {
2347
+ const per = Math.max(1, Math.round(cap?.wordsPerLine?.median ?? 3));
2348
+ const caps = /all-caps|capitals|upper/i.test(cap?.style ?? "");
2349
+ let chunks = [];
2350
+ let cur = [];
2351
+ for (const w of words) {
2352
+ const last = cur.at(-1);
2353
+ // Script words timed by one heard word ("twenty five" for "25") stay on one screen.
2354
+ const oneHeard = last && w.line === last.line && w.start === last.start && w.end === last.end;
2355
+ if (last && !oneHeard && (cur.length >= per || w.line !== last.line || w.start - last.end > CAPTION_LINE_GAP_SEC)) {
2356
+ chunks.push(cur);
2357
+ cur = [];
2358
+ }
2359
+ cur.push(w);
2360
+ }
2361
+ if (cur.length) chunks.push(cur);
2362
+ for (let k = 0; k < chunks.length; k++) {
2363
+ const c = chunks[k];
2364
+ if (c.at(-1).end - c[0].start >= CAPTION_MIN_SEC) continue;
2365
+ const next = chunks[k + 1];
2366
+ const prev = chunks[k - 1];
2367
+ 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;
2368
+ if (joins(c, next)) {
2369
+ chunks[k + 1] = [...c, ...next];
2370
+ chunks[k] = null;
2371
+ } else if (joins(prev, c)) {
2372
+ chunks[k - 1] = [...prev, ...c];
2373
+ chunks[k] = null;
2374
+ }
2375
+ }
2376
+ chunks = chunks.filter(Boolean);
2377
+ return chunks.map((ws, k) => {
2378
+ const next = chunks[k + 1]?.[0];
2379
+ const text = ws.map((w) => assText(w.text)).join(" ").replace(/[.,;:]+$/, "");
2380
+ const off = next ? next.start - CAPTION_CLEAR_SEC : Infinity;
2381
+ const e = Math.min(Math.max(ws[0].start + 0.12, ws.at(-1).end + CAPTION_TAIL_SEC), off);
2382
+ return { text: caps ? text.toUpperCase() : text, s: roundMs(ws[0].start), e: roundMs(e), line: ws[0].line };
2383
+ });
2384
+ }
2385
+
2386
+ /**
2387
+ * captionsByLine: the cut's words in its own time, each with the script line
2388
+ * it belongs to. Where a segment's script is heard in order (alignScript),
2389
+ * they are the script's words as written, each timed by the heard words that
2390
+ * say it; elsewhere they are the heard words, each on the line its place among
2391
+ * the script's words gives it, the way a cue line is found (lineInSegment).
2392
+ */
2393
+ export function lineWords(timeline, storyboard) {
2394
+ const texts = new Map((storyboard?.script ?? []).map((line) => [line?.lineId, line?.text]));
2395
+ const counts = lineWordCounts(storyboard);
2396
+ const rows = [];
2397
+ for (const seg of timeline.spine) {
2398
+ const heard = seg.words ?? [];
2399
+ if (heard.length === 0) continue;
2400
+ const at = (t) => roundMs(seg.startSec + t);
2401
+ const lines = seg.lineIds.map((id) => scriptWords(texts.get(id)));
2402
+ const aligned = lines.some((l) => l.length > 0) ? alignScript(heard, lines.flat()) : null;
2403
+ if (aligned) {
2404
+ const lineOf = lines.flatMap((ws, j) => ws.map(() => seg.lineIds[j]));
2405
+ const { expected, heard: tokens, heardTokenOf } = aligned;
2406
+ lines.flat().forEach((text, i) => {
2407
+ const said = heardTokenOf.filter((_, e) => expected.sourceIndex[e] <= i && i <= expected.lastSourceIndex[e]);
2408
+ if (said.length === 0) return;
2409
+ const start = at(heard[tokens.sourceIndex[said[0]]].s);
2410
+ const end = at(heard[tokens.lastSourceIndex[said.at(-1)]].e);
2411
+ if (end > start) rows.push({ text, start, end, line: lineOf[i] });
2412
+ });
2413
+ continue;
2414
+ }
2415
+ const ends = [];
2416
+ let n = 0;
2417
+ for (const id of seg.lineIds) ends.push((n += counts.get(id) ?? 0));
2418
+ heard.forEach((w, i) => {
2419
+ const text = (w.w ?? "").trim();
2420
+ const start = at(w.s);
2421
+ const end = at(w.e);
2422
+ if (!text || end <= start) return;
2423
+ const j = ends.findIndex((last) => Math.min(i, n - 1) < last);
2424
+ rows.push({ text, start, end, line: seg.lineIds[j] ?? seg.lineIds.at(-1) ?? `scene ${seg.sceneIndex}` });
2425
+ });
2426
+ }
2427
+ return rows;
2428
+ }
2429
+
2430
+ /**
2431
+ * One ASS file for the burn: the caption screens in their band, the cards in
2432
+ * their boxes, the hook box and the end card. Boxes are [x0, y0, x1, y1] as
2433
+ * shares of the frame. Every word on screen is the script's or the storyboard's.
2434
+ */
2435
+ export function editAss({ captions = [], cap = null, cards = [], hook = null, endCard = null, capMaxShare = null }, W = WIDTH, H = HEIGHT) {
2436
+ const thick = /thick black outline/i.test(cap?.style ?? "");
2437
+ const y = cap?.place ? Math.round(((cap.place[0] + cap.place[1]) / 2) * H) : Math.round(H * 0.7);
2438
+ const capSize = Math.min(Math.round(H * (thick ? 0.05 : 0.034)), capMaxShare ? Math.round(H * capMaxShare) : Infinity);
2439
+ const box = (b) => `\\pos(${Math.round(((b[0] + b[2]) / 2) * W)},${Math.round(((b[1] + b[3]) / 2) * H)})`;
2440
+ return [
2441
+ "[Script Info]", "ScriptType: v4.00+", `PlayResX: ${W}`, `PlayResY: ${H}`, "WrapStyle: 0", "ScaledBorderAndShadow: yes", "",
2442
+ "[V4+ Styles]",
2443
+ "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding",
2444
+ `Style: Cap,Helvetica,${capSize},&H00FFFFFF,&H00FFFFFF,&H00000000,&H90000000,-1,0,0,0,100,100,0,0,1,${thick ? 7 : 1.5},${thick ? 4 : 2},5,60,60,0,1`,
2445
+ "Style: Card,Helvetica,60,&H00141414,&H00141414,&H00FFFFFF,&H50000000,-1,0,0,0,100,100,0,0,3,18,4,5,0,0,0,1",
2446
+ `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`, "",
2447
+ "[Events]", "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
2448
+ ...captions.map((c) => `Dialogue: 1,${assTime(c.s)},${assTime(c.e)},Cap,,0,0,0,,{\\pos(${W / 2},${y})}${c.text}`),
2449
+ ...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)}`),
2450
+ ...(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)}`] : []),
2451
+ ...(endCard ? [`Dialogue: 4,${assTime(endCard.in)},${assTime(endCard.out)},End,,0,0,0,,{\\pos(${W / 2},${H / 2})\\fad(120,0)}${assText(endCard.text)}`] : []),
2452
+ ].join("\n") + "\n";
2453
+ }
2454
+
2455
+ /**
2456
+ * Where a card sits when the storyboard says it only in words (`placement`).
2457
+ * A source record's own boxes take their place once a run can carry one.
2458
+ */
2459
+ const CARD_BOXES = [
2460
+ [/full|centre|center|middle/i, [0.08, 0.44, 0.92, 0.56]],
2461
+ [/lower|bottom/i, [0.08, 0.56, 0.92, 0.64]],
2462
+ ];
2463
+ const CARD_BOX_TOP = [0.08, 0.14, 0.92, 0.24];
2464
+ export const cardBox = (placement) => CARD_BOXES.find(([words]) => words.test(placement ?? ""))?.[1] ?? CARD_BOX_TOP;
2465
+ /** Overlays that are pictures, not words: no file for them reaches the cut, so none is drawn. */
2466
+ const PICTURE_OVERLAY = /screenshot|chart/i;
2467
+ /** The end card holds the ad's last this many seconds. */
2468
+ export const END_CARD_SEC = 2;
2469
+
2470
+ /**
2471
+ * The storyboard's on-screen words (its overlays) as cards: each lands
2472
+ * CARD_LEAD_SEC before the first word of the line it is cued to and holds
2473
+ * through that line, at least BROLL_MIN_HOLD_SEC. The CTA's own overlay is
2474
+ * the end card instead (endCardOf). An overlay cued to a line no segment
2475
+ * speaks is left out.
2476
+ */
2477
+ export function storyboardCards(storyboard, timeline) {
2478
+ const counts = lineWordCounts(storyboard);
2479
+ const ctaId = storyboard?.cta?.overlayId;
2480
+ const cards = [];
2481
+ for (const o of storyboard?.overlays ?? []) {
2482
+ if (!hasText(o?.text) || !hasText(o?.cueLineId) || o.overlayId === ctaId || PICTURE_OVERLAY.test(o.type ?? "")) continue;
2483
+ const seg = timeline.spine.find((s) => !s.reaction && s.lineIds.includes(o.cueLineId));
2484
+ const cue = seg ? cueOffsetOnSpine(timeline.spine, counts, o.cueLineId) : null;
2485
+ if (!cue) continue;
2486
+ const at = roundMs(Math.max(0, cue.startSec - CARD_LEAD_SEC));
2487
+ const lineEnd = seg.startSec + (cueEndInSegment(seg, counts, o.cueLineId) ?? seg.seconds);
2488
+ cards.push({
2489
+ n: cards.length + 1, label: o.text.trim(), box: cardBox(o.placement),
2490
+ in: at, out: roundMs(Math.max(lineEnd, at + BROLL_MIN_HOLD_SEC)), on: `line ${o.cueLineId}`,
2491
+ });
2492
+ }
2493
+ return cards;
2494
+ }
2495
+
2496
+ /**
2497
+ * A copied ad's on-screen words in the source's own places: the storyboard's
2498
+ * overlays, in script order, land in the record's card boxes one for one, at
2499
+ * the card's times on the cut; the overlay placed "hook" goes in the record's
2500
+ * hook box. Cards with no overlay of ours, and overlays with no card, are
2501
+ * left out and noted.
2502
+ */
2503
+ export function sourceAdEdit(storyboard, sourceAd, groups) {
2504
+ const at = (t) => roundMs(mapSourceTime(groups, t));
2505
+ const order = new Map((storyboard?.script ?? []).map((line, i) => [line?.lineId, i]));
2506
+ const ctaId = storyboard?.cta?.overlayId;
2507
+ const words = (storyboard?.overlays ?? []).filter(
2508
+ (o) => hasText(o?.text) && o.overlayId !== ctaId && !PICTURE_OVERLAY.test(o.type ?? ""),
2509
+ );
2510
+ const hookOverlay = words.find((o) => /hook/i.test(o.placement ?? "")) ?? null;
2511
+ const texts = words
2512
+ .filter((o) => o !== hookOverlay)
2513
+ .sort((a, b) => (order.get(a.cueLineId) ?? Infinity) - (order.get(b.cueLineId) ?? Infinity));
2514
+ const cards = sourceAd.cards.flatMap((c, k) => {
2515
+ const o = texts[k];
2516
+ if (!o) return [];
2517
+ const from = at(c.tIn);
2518
+ return [{ n: k + 1, label: o.text.trim(), box: c.box, in: from, out: Math.max(at(c.tOut), roundMs(from + BROLL_MIN_HOLD_SEC)), on: `source card ${c.n}` }];
2519
+ });
2520
+ const notes = [];
2521
+ if (sourceAd.cards.length > texts.length) notes.push(`${sourceAd.cards.length - texts.length} of the source's cards had no overlay of ours, so they were not drawn`);
2522
+ if (texts.length > sourceAd.cards.length) notes.push(`${texts.length - sourceAd.cards.length} overlays had no source card to land in, so they were not drawn`);
2523
+ const hook = sourceAd.hook && hookOverlay
2524
+ ? { text: hookOverlay.text.trim(), box: sourceAd.hook.box, in: at(sourceAd.hook.tIn), out: at(sourceAd.hook.tOut) }
2525
+ : null;
2526
+ if (sourceAd.hook && !hookOverlay) notes.push("the source has a hook box and the storyboard no overlay placed \"hook\", so none was drawn");
2527
+ return { cards, hook, notes };
2528
+ }
2529
+
2530
+ /** The CTA overlay's words over the ad's last END_CARD_SEC, or null when the storyboard has none. */
2531
+ export function endCardOf(storyboard, seconds) {
2532
+ const ctaId = storyboard?.cta?.overlayId;
2533
+ const overlay = ctaId ? (storyboard?.overlays ?? []).find((o) => o?.overlayId === ctaId) : null;
2534
+ if (!hasText(overlay?.text)) return null;
2535
+ return { text: overlay.text.trim(), in: roundMs(Math.max(0, seconds - END_CARD_SEC)), out: roundMs(seconds + 1) };
2536
+ }
2537
+
2538
+ /**
2539
+ * The pace report: cuts a minute, mean and longest shot, shots over
2540
+ * LONG_SHOT_SEC, words a minute and pauses over 0.3 s, against a source ad's
2541
+ * when there is one (each source figure null when not). Shots are
2542
+ * [{ start, end }] or [{ t0, t1 }]; silences [{ s, e }].
2543
+ */
2544
+ export function paceReport({ ourShots, srcShots = null, ourSec, srcSec = null, ourWords = 0, srcWords = 0, ourSilences = [], speed = 1 }) {
2545
+ const lens = (xs) => xs.map((s) => round2((s.end ?? s.t1) - (s.start ?? s.t0)));
2546
+ const o = lens(ourShots);
2547
+ const sr = srcShots && srcSec ? lens(srcShots) : null;
2548
+ const mean = (a) => (a.length ? round2(a.reduce((x, y) => x + y, 0) / a.length) : null);
2549
+ const long = (a) => a.filter((x) => x > LONG_SHOT_SEC + 0.05).length;
2550
+ return {
2551
+ seconds: { ours: round2(ourSec), source: sr ? round2(srcSec) : null, ratio: sr ? roundMs(ourSec / srcSec) : null },
2552
+ speed,
2553
+ cutsPerMin: { ours: round2(((ourShots.length - 1) / ourSec) * 60), source: sr ? round2(((srcShots.length - 1) / srcSec) * 60) : null },
2554
+ meanShotSec: { ours: mean(o), source: sr ? mean(sr) : null },
2555
+ longestShotSec: { ours: Math.max(0, ...o), source: sr ? Math.max(0, ...sr) : null },
2556
+ over4s: { ours: long(o), source: sr ? long(sr) : null },
2557
+ wordsPerMin: { ours: ourWords ? round2((ourWords / ourSec) * 60) : null, source: srcWords && srcSec ? round2((srcWords / srcSec) * 60) : null },
2558
+ deadAir: {
2559
+ over03s: ourSilences.filter((x) => x.e - x.s > 0.3).length,
2560
+ longestSec: round2(Math.max(0, ...ourSilences.map((x) => x.e - x.s))),
2561
+ },
2562
+ };
2563
+ }
2564
+
2565
+ /** The pauses in the cut's voice, from its word times: every gap of PACE_PAUSE_SEC or more between two words. */
2566
+ export function voicePauses(rows) {
2567
+ const pauses = [];
2568
+ for (let i = 1; i < rows.length; i++) {
2569
+ if (rows[i].start - rows[i - 1].end >= PACE_PAUSE_SEC) pauses.push({ s: rows[i - 1].end, e: rows[i].start });
2570
+ }
2571
+ return pauses;
2572
+ }
2573
+
2574
+ // ---- cutChecks: the finished cut checked before anyone grades it ----
2575
+
2576
+ /**
2577
+ * The bars a checked cut is held to. voiceOverBedDb and the slow-shot ratio
2578
+ * are guesses, to be tuned against the graders' notes on the cuts they mark.
2579
+ */
2580
+ export const CHECK_BARS = { voiceOverBedDb: 10, minBrollSec: 1.2, truePeak: -1.0, lufs: -14 };
2581
+ /** A shot is slow when it moves under this share of the cut's median motion, or under SLOW_SHOT_FLOOR. */
2582
+ const SLOW_SHOT_RATIO = 0.35;
2583
+ const SLOW_SHOT_FLOOR = 0.6;
2584
+ /** A phrase of this many words said again within REPEAT_WITHIN words is a repeat. */
2585
+ const REPEAT_WORDS = 3;
2586
+ const REPEAT_WITHIN = 14;
2587
+ 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" };
2588
+ /** A heard word as the checks compare it: lower case, no punctuation, a number word as its digits. */
2589
+ export const checkWord = (s) => {
2590
+ const t = String(s).toLowerCase().replace(/[’']/g, "").replace(/[^a-z0-9%$]/g, "");
2591
+ return NUMBER_WORDS_AS_DIGITS[t] ?? t;
2592
+ };
2593
+
2594
+ /** Caption screens that hold words of two script lines. `words` carry their line (lineWords). */
2595
+ export function lineMixes(screens, words) {
2596
+ return screens
2597
+ .filter((c) => new Set(words.filter((w) => w.start >= c.s - 0.01 && w.start < c.e).map((w) => w.line)).size > 1)
2598
+ .map((c) => ({ s: c.s, text: c.text }));
2599
+ }
2600
+
2601
+ /** A phrase of REPEAT_WORDS or more words said again within REPEAT_WITHIN words. `heard`: [{ w, s }]. */
2602
+ export function repeats(heard) {
2603
+ const t = heard.map((h) => checkWord(h.w));
2604
+ const out = [];
2605
+ for (let i = 0; i + REPEAT_WORDS <= t.length; i++) {
2606
+ const phrase = t.slice(i, i + REPEAT_WORDS).join(" ");
2607
+ for (let j = i + REPEAT_WORDS; j + REPEAT_WORDS <= Math.min(t.length, i + REPEAT_WORDS + REPEAT_WITHIN); j++) {
2608
+ if (t.slice(j, j + REPEAT_WORDS).join(" ") === phrase) {
2609
+ out.push({ phrase, firstAt: roundMs(heard[i].s), againAt: roundMs(heard[j].s) });
2610
+ i += REPEAT_WORDS - 1;
2611
+ break;
2612
+ }
2613
+ }
2614
+ }
2615
+ return out;
2616
+ }
2617
+
2618
+ /** B-roll and narrated shots on screen for less than CHECK_BARS.minBrollSec. `shots`: [{ n, role, start, end }]. */
2619
+ export function shortShots(shots, minSec = CHECK_BARS.minBrollSec) {
2620
+ return shots
2621
+ .filter((s) => ["b-roll", "overlay", "vo-enactment"].includes(s.role) && s.end - s.start < minSec)
2622
+ .map((s) => ({ n: s.n, role: s.role, at: s.start, sec: roundMs(s.end - s.start) }));
2623
+ }
2624
+
2625
+ /**
2626
+ * Shots whose motion is far under the cut's median. A shot of someone talking
2627
+ * to camera (a-roll) sits still at natural speed, so it is never slow here.
2628
+ * `motion`: [{ n, role, sec, motion }].
2629
+ */
2630
+ export function slowShots(motion) {
2631
+ const values = motion.map((m) => m.motion).filter((x) => x != null).sort((a, b) => a - b);
2632
+ if (!values.length) return [];
2633
+ const median = values[Math.floor(values.length / 2)];
2634
+ return motion
2635
+ .filter((m) => m.role !== "a-roll" && m.motion != null && m.sec >= 1 && (m.motion < median * SLOW_SHOT_RATIO || m.motion < SLOW_SHOT_FLOOR))
2636
+ .map((m) => ({ ...m, median: roundMs(median) }));
2637
+ }
2638
+
2639
+ /** The voice's loudness over the rest's, in dB; null when the voice is silent, 60 when the rest is. */
2640
+ export const voiceOverBed = (voiceLufs, bedLufs) =>
2641
+ voiceLufs == null || bedLufs == null || voiceLufs < -60 ? null : bedLufs < -60 ? 60 : roundMs(voiceLufs - bedLufs);
2642
+
2643
+ /** What fails the bars, in words; the cut passes when nothing does. */
2644
+ export function checkVerdict(c, bars = CHECK_BARS) {
2645
+ const fails = [];
2646
+ if (c.lineMixes?.length) fails.push(`${c.lineMixes.length} caption screens mix two lines`);
2647
+ if (c.voiceOverBedDb != null && c.voiceOverBedDb < bars.voiceOverBedDb) fails.push(`voice ${c.voiceOverBedDb} dB over the bed (bar ${bars.voiceOverBedDb})`);
2648
+ if (c.repeats?.length) fails.push(`${c.repeats.length} phrase(s) said twice`);
2649
+ if (c.shortShots?.length) fails.push(`${c.shortShots.length} b-roll shot(s) under ${bars.minBrollSec} s`);
2650
+ if (c.slowShots === null) fails.push("shot motion could not be measured");
2651
+ else if (c.slowShots?.length) fails.push(`${c.slowShots.length} slow shot(s)`);
2652
+ if (c.truePeak != null && c.truePeak > bars.truePeak) fails.push(`true peak ${c.truePeak} dBTP (bar ${bars.truePeak})`);
2653
+ if (c.lufs != null && Math.abs(c.lufs - bars.lufs) > 1) fails.push(`loudness ${c.lufs} LUFS (bar ${bars.lufs} ± 1)`);
2654
+ return { pass: !fails.length, fails };
2655
+ }
2656
+
2657
+ /** Frame-to-frame change of a file's picture, on a 90 px wide copy, printed per frame. `from`/`seconds` read a stretch. */
2658
+ export function motionArgs(file, from = null, seconds = null) {
2659
+ return [
2660
+ "-hide_banner", "-nostats",
2661
+ ...(from !== null ? ["-ss", sec(from)] : []), ...(seconds !== null ? ["-t", sec(seconds)] : []),
2662
+ "-i", file, "-an",
2663
+ "-vf", "scale=90:-2,tblend=all_mode=difference,signalstats,metadata=print:key=lavfi.signalstats.YAVG:file=-",
2664
+ "-f", "null", "-",
2665
+ ];
2666
+ }
2667
+
2668
+ /** motionArgs' printout as [{ t, y }]: each frame's time and its mean change. */
2669
+ export function readMotion(stdout) {
2670
+ const rows = [];
2671
+ let t = null;
2672
+ for (const line of String(stdout ?? "").split("\n")) {
2673
+ const time = line.match(/pts_time:([\d.]+)/);
2674
+ if (time) {
2675
+ t = Number(time[1]);
2676
+ continue;
2677
+ }
2678
+ const y = line.match(/YAVG=([\d.]+)/);
2679
+ if (y && t !== null) rows.push({ t, y: Number(y[1]) });
2680
+ }
2681
+ return rows;
2682
+ }
2683
+
2684
+ /** Each shot's mean motion, its first and last 0.1 s left out so a cut is not counted as motion. */
2685
+ export function motionByShot(rows, shots) {
2686
+ return shots.map((s) => {
2687
+ const v = rows.filter((r) => r.t > s.start + 0.1 && r.t < s.end - 0.1).map((r) => r.y);
2688
+ 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 };
2689
+ });
2690
+ }
2691
+
2692
+ /** 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. */
2693
+ const roleOf = (seg) => (seg.reaction || seg.audio === "clip" ? "a-roll" : seg.audio === "narration" ? "vo-enactment" : "b-roll");
2694
+
2695
+ /**
2696
+ * cutChecks: the finished cut against CHECK_BARS. `screens` are the caption
2697
+ * screens burned in (null for none), `rows` and `scenes` the cut's words and
2698
+ * shots as written beside it, `levels` the voice's and the bed's loudness from
2699
+ * the render. Caption sync is not checked: it needs a transcription of the
2700
+ * finished cut of its own, and the cut's words are the ones its captions came from.
2701
+ */
2702
+ function checkCut({ timeline, storyboard, screens, rows, scenes, out, loudness, levels }) {
2703
+ const roles = new Map(timeline.spine.map((seg) => [seg.sceneIndex, roleOf(seg)]));
2704
+ for (const c of timeline.cutaways) roles.set(c.sceneIndex, "b-roll");
2705
+ const shots = scenes.map((p) => ({ n: p.scene, role: roles.get(p.scene) ?? "b-roll", start: p.startSec, end: roundMs(p.startSec + p.seconds) }));
2706
+ const read = spawnSync("ffmpeg", motionArgs(out), { encoding: "utf8", maxBuffer: 1 << 28 });
2707
+ const motion = read.status === 0 ? readMotion(read.stdout) : [];
2708
+ const finished = loudness ? { i: loudness.lufs, tp: loudness.truePeak } : measureLoudness(out);
2709
+ const checks = {
2710
+ lineMixes: screens ? lineMixes(screens, lineWords(timeline, storyboard)) : null,
2711
+ // A song laid whole is the voice and the music at once, so it has no level over a bed.
2712
+ voiceOverBedDb: timeline.wholeVoice ? null : voiceOverBed(levels.voiceLufs, levels.bedLufs),
2713
+ voiceLufs: levels.voiceLufs,
2714
+ bedLufs: levels.bedLufs,
2715
+ repeats: repeats(rows.map((r) => ({ w: r.text, s: r.start }))),
2716
+ shortShots: shortShots(shots),
2717
+ // null: ffmpeg could not read the motion, so no shot was checked.
2718
+ slowShots: motion.length ? slowShots(motionByShot(motion, shots)) : null,
2719
+ lufs: finished ? round2(finished.i) : null,
2720
+ truePeak: finished ? round2(finished.tp) : null,
2721
+ };
2722
+ return { ...checks, verdict: checkVerdict(checks) };
2723
+ }
2724
+
2725
+ const LOUDNORM_TARGET = `I=${FINISH_LUFS}:TP=${FINISH_TRUE_PEAK}:LRA=${FINISH_LRA}`;
2726
+
2727
+ /** finishLoudness, pass one: measure a file's sound. Its numbers come back on stderr as JSON. */
2728
+ export function loudnessMeasureArgs(file) {
2729
+ return ["-hide_banner", "-nostats", "-i", file, "-map", "0:a:0", "-af", `loudnorm=${LOUDNORM_TARGET}:print_format=json`, "-f", "null", "-"];
2730
+ }
2731
+
2732
+ /** loudnorm's measured numbers out of its printed JSON, or null when any is missing or not a number (a silent file). */
2733
+ export function readLoudness(stderr) {
2734
+ const block = String(stderr ?? "").match(/\{[^{}]*"input_i"[^{}]*\}/);
2735
+ if (!block) return null;
2736
+ let raw;
2737
+ try {
2738
+ raw = JSON.parse(block[0]);
2739
+ } catch {
2740
+ return null;
2741
+ }
2742
+ const measured = {
2743
+ i: Number(raw.input_i), tp: Number(raw.input_tp), lra: Number(raw.input_lra),
2744
+ thresh: Number(raw.input_thresh), offset: Number(raw.target_offset),
2745
+ };
2746
+ return Object.values(measured).every(Number.isFinite) ? measured : null;
2747
+ }
2748
+
2749
+ /**
2750
+ * finishLoudness, pass two: the whole mix normalized with pass one's numbers,
2751
+ * the picture copied as it is. Without them (pass one could not read the
2752
+ * sound) loudnorm runs on its own, in one pass. `limiter` (limitPeaks) runs
2753
+ * after it.
2754
+ */
2755
+ export function loudnessApplyArgs(mix, measured, out, limiter = null) {
2756
+ const second = measured
2757
+ ? `:measured_I=${measured.i}:measured_TP=${measured.tp}:measured_LRA=${measured.lra}` +
2758
+ `:measured_thresh=${measured.thresh}:offset=${measured.offset}:linear=true`
2759
+ : "";
2760
+ return [
2761
+ "-y", "-hide_banner", "-loglevel", "error", "-i", mix,
2762
+ "-map", "0:v:0", "-map", "0:a:0", "-c:v", "copy",
2763
+ "-af", `loudnorm=${LOUDNORM_TARGET}${second}${limiter ? `,${limiter}` : ""},aresample=48000`,
2764
+ "-c:a", "aac", "-b:a", "192k", "-movflags", "+faststart", out,
2765
+ ];
2766
+ }
2767
+
2768
+ /** Why a finished cut is refused for its loudness, or null when its true peak is at or under TRUE_PEAK_MAX_DB. */
2769
+ export function truePeakRefusal(measured) {
2770
+ if (!measured) return "The cut's loudness could not be measured after the loudness pass, so it was not attached";
2771
+ if (measured.tp <= TRUE_PEAK_MAX_DB) return null;
2772
+ return `The cut's true peak is ${measured.tp.toFixed(2)} dBTP after the loudness pass, over the ${TRUE_PEAK_MAX_DB} dBTP limit, so it was not attached`;
2773
+ }
2774
+
2775
+ function measureLoudness(file) {
2776
+ const res = spawnSync("ffmpeg", loudnessMeasureArgs(file), { encoding: "utf8", maxBuffer: 1 << 26 });
2777
+ return res.status === 0 ? readLoudness(res.stderr) : null;
2778
+ }
2779
+
2780
+ /** A sound file's loudness pass one, padded to 3 s as LOUDNORM is, so a short sound still measures. */
2781
+ export function soundLevelArgs(file) {
2782
+ return ["-hide_banner", "-nostats", "-i", file, "-map", "0:a:0", "-af", `apad=whole_dur=3,loudnorm=${LOUDNORM_TARGET}:print_format=json`, "-f", "null", "-"];
2783
+ }
2784
+
2785
+ function measureLufs(file) {
2786
+ const res = spawnSync("ffmpeg", soundLevelArgs(file), { encoding: "utf8", maxBuffer: 1 << 26 });
2787
+ const measured = res.status === 0 ? readLoudness(res.stderr) : null;
2788
+ return measured ? round2(measured.i) : null;
2789
+ }
2790
+
2791
+ /** Both passes on the rendered mix, then the finished cut measured again; throws LoudnessRefusal over the limit. */
2792
+ export function finishLoudnessPass(mix, out, limiter = null) {
2793
+ const measured = measureLoudness(mix);
2794
+ const args = loudnessApplyArgs(mix, measured, out, limiter);
2795
+ const res = spawnSync("ffmpeg", args, { stdio: "inherit" });
2796
+ if (res.status !== 0) {
2797
+ const quoted = args.map((a) => (/[\s\[\];]/.test(a) ? `'${a}'` : a)).join(" ");
2798
+ throw new FirstCutError(1, `ffmpeg failed on the loudness pass. The command it ran:\n ffmpeg ${quoted}`);
2799
+ }
2800
+ const finished = measureLoudness(out);
2801
+ const refusal = truePeakRefusal(finished);
2802
+ if (refusal) throw new LoudnessRefusal(refusal, finished);
2803
+ return { lufs: round2(finished.i), truePeak: round2(finished.tp), passes: measured ? 2 : 1, ...(limiter ? { limited: true } : {}) };
2804
+ }
2805
+
2806
+ /** The filters of `names` this ffmpeg does not have. */
2807
+ function missingFilters(names) {
2808
+ const listed = spawnSync("ffmpeg", ["-hide_banner", "-filters"]).stdout?.toString() ?? "";
2809
+ return names.filter((name) => !new RegExp(`^\\s*\\S+\\s+${name}\\s`, "m").test(listed));
2810
+ }
2811
+
2812
+ /** Whether this ffmpeg has a filter (the captions and cards need `subtitles`, which needs libass). */
2813
+ function hasFilter(name) {
2814
+ return missingFilters([name]).length === 0;
2815
+ }
2816
+
2817
+ /**
2818
+ * The files the finishing settings write beside the cut: the pace record, the
2819
+ * mix before the loudness pass, and the voice and bed cutChecks measures.
2820
+ */
2821
+ export function finishPaths(outPath) {
2822
+ const dir = path.dirname(outPath);
2823
+ const base = path.basename(outPath, path.extname(outPath));
2824
+ return {
2825
+ pace: path.join(dir, `${base}.pace.json`),
2826
+ mix: path.join(dir, `${base}.mix${path.extname(outPath)}`),
2827
+ sound: path.join(dir, `${base}.sound.json`),
2828
+ master: path.join(dir, `${base}.music-only${path.extname(outPath)}`),
2829
+ voice: path.join(dir, `${base}.voice.wav`),
2830
+ bed: path.join(dir, `${base}.bed.wav`),
2831
+ };
2832
+ }
2833
+
1676
2834
  function fail(code, message) {
1677
2835
  console.error(message);
1678
2836
  process.exit(code);
@@ -1687,6 +2845,15 @@ export class FirstCutError extends Error {
1687
2845
  }
1688
2846
  }
1689
2847
 
2848
+ /** finishLoudness: the finished cut's true peak is over TRUE_PEAK_MAX_DB, or could not be measured. */
2849
+ export class LoudnessRefusal extends FirstCutError {
2850
+ constructor(message, measured) {
2851
+ super(1, message);
2852
+ this.name = "LoudnessRefusal";
2853
+ this.measured = measured ?? null;
2854
+ }
2855
+ }
2856
+
1690
2857
  function parseArgs(argv) {
1691
2858
  const opts = { dir: undefined, out: undefined, skip: new Set(), music: true, stillFill: false };
1692
2859
  for (let i = 0; i < argv.length; i++) {
@@ -1755,6 +2922,12 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
1755
2922
  if (!storyboard) {
1756
2923
  console.error(`Warning: ${manifest.storyboard ?? "storyboard.json"} is missing or unreadable, so every scene is cut as A-roll and no cutaway is placed.`);
1757
2924
  }
2925
+ const finish = finishingOf(manifest);
2926
+ const sourceAd = sourceAdOf(manifest);
2927
+ const wholeVoice = wholeVoiceOf(manifest, readJson, exists);
2928
+ if (manifest.wholeVoice === true && !wholeVoice) {
2929
+ console.error("Warning: the manifest asks for the voice laid whole, but the narration track or its narration.json is missing, so each scene's voice is laid on its own.");
2930
+ }
1758
2931
  const timeline = buildTimeline({
1759
2932
  manifest,
1760
2933
  storyboard,
@@ -1767,24 +2940,153 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
1767
2940
  return Array.isArray(rows) && rows.length > 0 ? rows : null;
1768
2941
  },
1769
2942
  readLevels: (file) => clipLevels(here(file)),
2943
+ ...(finish ? { finish } : {}),
2944
+ ...(wholeVoice ? { wholeVoice } : {}),
2945
+ ...(sourceAd ? { sourceAd } : {}),
1770
2946
  });
1771
2947
  if (timeline.spine.length === 0) {
1772
2948
  throw new FirstCutError(1, `No scene has a clip or a keyframe. Check: exodus video status ${manifest.runId}`);
1773
2949
  }
1774
2950
 
2951
+ // The finishing settings' part of the render: the speed, the burned
2952
+ // captions and cards, and where the mix goes before its loudness pass.
2953
+ const notes = [];
2954
+ const pictureSec = timeline.spine.reduce((sum, seg) => sum + seg.seconds, 0);
2955
+ // A voice laid whole is a song: it is never sped up.
2956
+ const speed = finish?.cutPace && !timeline.wholeVoice ? speedFor(pictureSec, finish.targetSeconds) : 1;
2957
+ if (finish?.brollMinSec) {
2958
+ const held = holdBroll(timeline, finish.brollMinSec, speed, (file) => probe(file).seconds);
2959
+ timeline.left.push(...held);
2960
+ notes.push(...held);
2961
+ }
2962
+ if (finish?.speedUpSlowBroll && timeline.cutaways.length > 0) {
2963
+ const motionOf = (file, from, seconds) => {
2964
+ const res = spawnSync("ffmpeg", motionArgs(here(file), from, seconds), { encoding: "utf8", maxBuffer: 1 << 28 });
2965
+ if (res.status !== 0) return null;
2966
+ return motionByShot(readMotion(res.stdout), [{ n: 0, role: null, start: 0, end: seconds }])[0].motion;
2967
+ };
2968
+ notes.push(...speedUpSlowBroll(timeline, motionOf, (file) => probe(file).seconds));
2969
+ }
2970
+ let ass = null;
2971
+ // The caption screens burned in, which cutChecks reads.
2972
+ let burned = null;
2973
+ // A copied ad: its words in the record's boxes and its product photos from the product sheet.
2974
+ const copied = sourceAd && finish?.cards ? sourceAdEdit(storyboard, sourceAd, timeline.sourceGroups ?? []) : null;
2975
+ if (copied) notes.push(...copied.notes);
2976
+ let pictures = [];
2977
+ if (sourceAd && finish?.cards && sourceAd.pictures.length > 0) {
2978
+ if (exists(manifest.productSheet)) {
2979
+ pictures = sourceAd.pictures.map((p) => ({
2980
+ file: manifest.productSheet, box: p.box,
2981
+ startSec: roundMs(mapSourceTime(timeline.sourceGroups ?? [], p.tIn)),
2982
+ endSec: roundMs(mapSourceTime(timeline.sourceGroups ?? [], p.tOut)),
2983
+ }));
2984
+ } else {
2985
+ notes.push(`the pull has no product sheet picture, so the source's ${sourceAd.pictures.length} product card(s) were not drawn`);
2986
+ }
2987
+ }
2988
+ if (finish && (finish.captions || finish.cards)) {
2989
+ if (hasFilter("subtitles")) {
2990
+ ass = "edit.ass";
2991
+ const cap = sourceAd?.captions ?? null;
2992
+ const screens = !finish.captions
2993
+ ? []
2994
+ : finish.captionsByLine
2995
+ ? lineCaptionScreens(lineWords(timeline, storyboard), cap)
2996
+ : captionScreens(wordRows(timeline), cap);
2997
+ if (finish.captions) burned = screens;
2998
+ writeFileSync(here(ass), editAss({
2999
+ captions: screens,
3000
+ cap,
3001
+ ...(finish.captionsByLine ? { capMaxShare: CAPTION_MAX_SHARE } : {}),
3002
+ cards: finish.cards ? (copied ? copied.cards : storyboardCards(storyboard, timeline)) : [],
3003
+ hook: copied?.hook ?? null,
3004
+ // A copied ad has an end card only where its source does.
3005
+ endCard: finish.cards && (!sourceAd || sourceAd.endCard) ? endCardOf(storyboard, pictureSec) : null,
3006
+ }));
3007
+ } else {
3008
+ notes.push("this ffmpeg has no subtitles filter (libass), so the captions and cards were not burned in");
3009
+ }
3010
+ }
3011
+ // cleanVoice, where this ffmpeg has the filters. A voice laid whole is a song, kept as it is.
3012
+ let clean = null;
3013
+ if (finish?.cleanVoice) {
3014
+ const missing = timeline.wholeVoice ? [] : missingFilters(CLEAN_FILTERS);
3015
+ if (timeline.wholeVoice) notes.push("the voice is a song laid whole, so it was kept as it is, not cleaned");
3016
+ else if (missing.length > 0) notes.push(`this ffmpeg has no ${missing.join(", ")} filter, so the voice was not cleaned`);
3017
+ else clean = { voice: VOICE_CLEAN, under: UNDER_VOICE };
3018
+ }
3019
+ let limiter = null;
3020
+ if (finish?.limitPeaks) {
3021
+ if (hasFilter("alimiter")) limiter = PEAK_LIMITER;
3022
+ else notes.push("this ffmpeg has no alimiter filter, so the loudness pass ran without the limiter");
3023
+ }
3024
+ const paths = finishPaths(out);
3025
+ const rendered = finish?.finishLoudness ? paths.mix : out;
3026
+ const meters = finish?.cutChecks ? { voice: paths.voice, bed: paths.bed } : null;
3027
+ // The burn reads its file from the folder ffmpeg runs in, so every path is absolute then.
3028
+ const at = ass ? (file) => path.resolve(dir, file) : here;
3029
+
1775
3030
  const music = musicOn && exists(manifest.music) ? manifest.music : null;
3031
+ const sound = soundOf(manifest);
3032
+ let mixSound = null;
3033
+ const levels = new Map();
3034
+ const measure = (file) => {
3035
+ if (!levels.has(file)) levels.set(file, exists(file) ? measureLufs(here(file)) : null);
3036
+ return levels.get(file);
3037
+ };
3038
+ if (sound) {
3039
+ const missing = [...sound.effects, ...sound.beds].filter((x) => !exists(x.file)).map((x) => x.file);
3040
+ const plan = soundPlan(
3041
+ { ...sound, effects: sound.effects.filter((x) => exists(x.file)), beds: sound.beds.filter((x) => exists(x.file)) },
3042
+ timeline, storyboard, { levelled: !finish?.finishLoudness, measure },
3043
+ );
3044
+ const ducked = sound.duck && music ? { gainDb: duckedMusicGain(plan.voiceLufs, measure(music)), duck: DUCK } : null;
3045
+ mixSound = {
3046
+ ...plan, music: ducked,
3047
+ notes: [...missing.map((f) => `${f} is not in the folder, so it is left out`), ...plan.notes],
3048
+ };
3049
+ }
1776
3050
  const ffmpegArgs = buildFfmpegArgs(timeline, {
1777
- resolve: here,
1778
- music: music ? here(music) : null,
1779
- out,
3051
+ resolve: at,
3052
+ music: music ? at(music) : null,
3053
+ out: rendered,
3054
+ ...(finish
3055
+ ? {
3056
+ finish: {
3057
+ levelSegments: !finish.finishLoudness, ass, speed,
3058
+ ...(pictures.length ? { pictures } : {}), ...(clean ? { clean } : {}), ...(meters ? { meters } : {}),
3059
+ },
3060
+ }
3061
+ : {}),
3062
+ ...(mixSound ? { sound: mixSound } : {}),
1780
3063
  });
1781
- const res = spawnSync("ffmpeg", ffmpegArgs, { stdio: "inherit" });
3064
+ const res = spawnSync("ffmpeg", ffmpegArgs, { stdio: "inherit", ...(ass ? { cwd: path.resolve(dir) } : {}) });
1782
3065
  if (res.status !== 0) {
1783
3066
  const quoted = ffmpegArgs.map((a) => (/[\s\[\];]/.test(a) ? `'${a}'` : a)).join(" ");
1784
3067
  throw new FirstCutError(1, `ffmpeg failed. The command it ran:\n ffmpeg ${quoted}`);
1785
3068
  }
3069
+ let meterLevels = null;
3070
+ if (meters) {
3071
+ meterLevels = { voiceLufs: measureLufs(meters.voice), bedLufs: measureLufs(meters.bed) };
3072
+ rmSync(meters.voice, { force: true });
3073
+ rmSync(meters.bed, { force: true });
3074
+ }
3075
+ let loudness = null;
3076
+ if (finish?.finishLoudness) {
3077
+ try {
3078
+ loudness = finishLoudnessPass(rendered, out, limiter);
3079
+ } finally {
3080
+ rmSync(rendered, { force: true });
3081
+ }
3082
+ }
1786
3083
 
1787
- const rows = wordRows(timeline);
3084
+ // With the cut sped up, the times written beside it are the sped-up ones.
3085
+ const faster = (t) => (speed === 1 ? t : roundMs(t / speed));
3086
+ const rows = wordRows(timeline).map((r) => (speed === 1 ? r : { ...r, start: faster(r.start), end: faster(r.end) }));
3087
+ const scenes = sceneTimes(timeline).map((p) =>
3088
+ speed === 1 ? p : { ...p, startSec: faster(p.startSec), seconds: faster(p.seconds) },
3089
+ );
1788
3090
  const sidecars = sidecarPaths(out);
1789
3091
  if (rows.length > 0) {
1790
3092
  writeFileSync(sidecars.words, `${JSON.stringify(rows, null, 2)}\n`);
@@ -1793,12 +3095,61 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
1793
3095
  rmSync(sidecars.words, { force: true });
1794
3096
  rmSync(sidecars.srt, { force: true });
1795
3097
  }
1796
- writeFileSync(sidecars.scenes, `${JSON.stringify(sceneTimes(timeline), null, 2)}\n`);
3098
+ writeFileSync(sidecars.scenes, `${JSON.stringify(scenes, null, 2)}\n`);
1797
3099
 
1798
3100
  const duration = execFileSync("ffprobe", [
1799
3101
  "-v", "error", "-show_entries", "format=duration", "-of", "default=nw=1:nk=1", out,
1800
3102
  ]).toString().trim();
1801
- return { out, durationSec: Number(duration), manifest, timeline, music, rows, sidecars };
3103
+ const durationSec = Number(duration);
3104
+
3105
+ // The sound record beside the cut, and the music-only master the kind asked for.
3106
+ let soundRecord;
3107
+ if (mixSound) {
3108
+ let master = null;
3109
+ if (sound.musicOnlyMaster) {
3110
+ const lufs = music ? measure(music) : null;
3111
+ if (!music) mixSound.notes.push("the cut has no music, so no music-only master was made");
3112
+ else if (!Number.isFinite(lufs)) mixSound.notes.push("the music has no loudness to measure, so no music-only master was made");
3113
+ else {
3114
+ const args = musicOnlyMasterArgs(out, here(music), durationSec, round2(FINISH_LUFS - lufs), paths.master);
3115
+ if (spawnSync("ffmpeg", args, { stdio: "inherit" }).status === 0) master = paths.master;
3116
+ else mixSound.notes.push("ffmpeg could not make the music-only master");
3117
+ }
3118
+ }
3119
+ soundRecord = {
3120
+ voiceLufs: mixSound.voiceLufs,
3121
+ effects: mixSound.effects,
3122
+ beds: mixSound.beds,
3123
+ ...(mixSound.music ? { music: mixSound.music } : {}),
3124
+ ...(master ? { master: path.basename(master) } : {}),
3125
+ notes: mixSound.notes,
3126
+ };
3127
+ writeFileSync(paths.sound, `${JSON.stringify(soundRecord, null, 2)}\n`);
3128
+ }
3129
+ const withSound = (cut) => (soundRecord ? { ...cut, sound: soundRecord, ...(soundRecord.master ? { musicOnlyMaster: paths.master } : {}) } : cut);
3130
+ if (!finish) return withSound({ out, durationSec, manifest, timeline, music, rows, sidecars });
3131
+
3132
+ const checks = finish.cutChecks
3133
+ ? checkCut({ timeline, storyboard, screens: burned, rows, scenes, out, loudness, levels: meterLevels })
3134
+ : null;
3135
+ // The pace record: the cut's own numbers, the settings it was cut with (so
3136
+ // a redo of the run matches), its loudness once the pass ran, and its checks.
3137
+ const pace = {
3138
+ ...paceReport({
3139
+ ourShots: scenes.map((p) => ({ start: p.startSec, end: roundMs(p.startSec + p.seconds) })),
3140
+ ...(sourceAd ? { srcShots: sourceAd.shots, srcSec: sourceAd.seconds } : {}),
3141
+ ourSec: durationSec,
3142
+ ourWords: rows.length,
3143
+ ourSilences: voicePauses(rows).filter((x) => x.s > 0.3 && x.e < durationSec - 0.3),
3144
+ speed,
3145
+ }),
3146
+ finishing: finish,
3147
+ ...(loudness ? { loudness } : {}),
3148
+ ...(checks ? { checks } : {}),
3149
+ ...(notes.length > 0 ? { notes } : {}),
3150
+ };
3151
+ writeFileSync(paths.pace, `${JSON.stringify(pace, null, 2)}\n`);
3152
+ return withSound({ out, durationSec, manifest, timeline, music, rows, sidecars, pace });
1802
3153
  }
1803
3154
 
1804
3155
  function main() {
@@ -1840,6 +3191,15 @@ function main() {
1840
3191
  for (const line of edges) console.log(" " + line);
1841
3192
  }
1842
3193
  console.log(`Room tone: under the whole ad. Music bed: ${music ?? "none"}`);
3194
+ if (cut.pace) {
3195
+ const { pace } = cut;
3196
+ const loud = pace.loudness ? `, ${pace.loudness.lufs} LUFS, true peak ${pace.loudness.truePeak} dBTP` : "";
3197
+ console.log(
3198
+ `Pace: ${pace.cutsPerMin.ours} cuts a minute, ${pace.over4s.ours} shots over ${LONG_SHOT_SEC}s, ` +
3199
+ `${pace.deadAir.over03s} pauses over 0.3s, speed ${pace.speed}${loud} -> ${path.basename(finishPaths(out).pace)}`,
3200
+ );
3201
+ for (const note of pace.notes ?? []) console.log(` ${note}`);
3202
+ }
1843
3203
  console.log(`Upload it: exodus video upload ${manifest.runId} --file ${out}`);
1844
3204
  }
1845
3205