@aicopycoders/exodus 2026.11.1000-beta.2 → 2026.11.1100-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.
@@ -433,4 +433,12 @@ export function sentenceGapCuts(
433
433
  words: Array<{ w: string; s: number; e: number }>,
434
434
  lines: Array<{ text: string; asksPause: boolean; cuesBeat: boolean }>,
435
435
  levels?: { windowSec: number; db: number[] } | null,
436
- ): Array<{ s: number; e: number; after: string; gap: number; kept: number; sound: boolean }>;
436
+ lineGap?: { max: number; keep: number } | null,
437
+ jump?: JumpCut | null,
438
+ ): Array<{ s: number; e: number; after: string; gap: number; kept: number; sound: boolean; atLine?: number }>;
439
+
440
+ /** jumpCut: a pause over maxGap between two heard words keeps keepAfter after the earlier word and keepBefore before the later. */
441
+ export interface JumpCut { maxGap: number; keepAfter: number; keepBefore: number }
442
+ export const JUMP_CUT: JumpCut;
443
+ /** jumpCut on one pause: the span it takes out, or null when it keeps the pause whole. */
444
+ export function jumpCutSpan(endSec: number, startSec: number, jump?: JumpCut): { s: number; e: number } | null;
@@ -72,6 +72,14 @@ export const PUNCH_IN_SCALE = 1.15;
72
72
  const even = (n) => 2 * Math.round(n / 2);
73
73
  const PUNCH_IN =
74
74
  `scale=${even(WIDTH * PUNCH_IN_SCALE)}:${even(HEIGHT * PUNCH_IN_SCALE)},crop=${WIDTH}:${HEIGHT},setsar=1`;
75
+ /**
76
+ * pacePass: the finished cut plays at `speed`, picture and sound, and every
77
+ * second piece of the spine is a centre crop scaled up by `zoom`, a small zoom
78
+ * step at each cut.
79
+ */
80
+ export const PACE_PASS = { speed: 1.12, zoom: 1.07 };
81
+ const PACE_ZOOM =
82
+ `scale=${even(WIDTH * PACE_PASS.zoom)}:${even(HEIGHT * PACE_PASS.zoom)},crop=${WIDTH}:${HEIGHT},setsar=1`;
75
83
  const floorFrame = (t) => Math.floor(t * FPS + 1e-6) / FPS;
76
84
  const ceilFrame = (t) => Math.ceil(t * FPS - 1e-6) / FPS;
77
85
  const stereo = "aresample=48000,aformat=channel_layouts=stereo";
@@ -97,6 +105,11 @@ export const NARRATION_JOIN_AIR_SEC = 0.25;
97
105
  * it lands. A dialogue clip's own tail ran ~1.1 s of dead air (#3423).
98
106
  */
99
107
  export const END_AIR_SEC = 0.5;
108
+ /**
109
+ * talkTrim: the most air a talking clip keeps after its last word, the ad's
110
+ * last line included. A join keeps JOIN_TAIL_SEC already, which is less.
111
+ */
112
+ export const TALK_TRIM_SEC = 0.3;
100
113
  /** A continuous low bed under the whole ad, so the joins between clips do not read as dead air. */
101
114
  const ROOM_TONE =
102
115
  "anoisesrc=color=brown:amplitude=0.0035:r=48000,highpass=f=60,lowpass=f=900,aformat=channel_layouts=stereo";
@@ -169,6 +182,22 @@ export const TRUE_PEAK_MAX_DB = -1;
169
182
  * resample is pinned to stereo, as every one after loudnorm is (loudnessApplyArgs).
170
183
  */
171
184
  export const PEAK_LIMITER = "aresample=192000,aformat=channel_layouts=stereo,alimiter=limit=0.8:level=false:attack=2:release=60";
185
+ /**
186
+ * jumpCut: inside a talking clip, a pause over maxGap between two heard words
187
+ * is cut down, keeping keepAfter after the earlier word and keepBefore before
188
+ * the later one. It rides
189
+ * the sentence-gap cut, so a pause the script writes in, one a direction asks
190
+ * for and a reaction's beat stay whole there too.
191
+ */
192
+ export const JUMP_CUT = { maxGap: 0.8, keepAfter: 0.18, keepBefore: 0.12 };
193
+
194
+ /** jumpCut on one pause, from `endSec` to `startSec`: the span it takes out, or null when it keeps the pause whole. */
195
+ export function jumpCutSpan(endSec, startSec, jump = JUMP_CUT) {
196
+ if (!(startSec - endSec > jump.maxGap + 1e-6)) return null;
197
+ const s = endSec + jump.keepAfter;
198
+ const e = startSec - jump.keepBefore;
199
+ return e > s ? { s, e } : null;
200
+ }
172
201
 
173
202
  /** Plan 14's on/off cut checks, each read only with cutChecks; paceCheck also carries its numbers. */
174
203
  const PLAN_14_CHECKS = ["floorCheck", "flashCheck", "levelStepCheck", "voFitCheck", "dashGapCheck", "nameCheck"];
@@ -210,6 +239,10 @@ export function finishingOf(manifest) {
210
239
  // Plan 14: the end card from the pack photo, and the record of whether the brand reached the ad (brandOf).
211
240
  ...(f.endCardLayers === true ? { endCardLayers: true } : {}),
212
241
  ...(f.brandCheck === true ? { brandCheck: true } : {}),
242
+ ...(f.jumpCut === true ? { jumpCut: true } : {}),
243
+ ...(f.talkTrim === true ? { talkTrim: true } : {}),
244
+ ...(on.captions && f.captionsByLine === true && f.captionColours === true ? { captionColours: true } : {}),
245
+ ...(f.pacePass === true ? { pacePass: true } : {}),
213
246
  };
214
247
  if (!Object.values(on).some(Boolean) && Object.keys(added).length === 0) return null;
215
248
  const target = f.targetSeconds;
@@ -408,6 +441,17 @@ const SAME_WORD_SPELLINGS = new Map([
408
441
  ["too", "to"],
409
442
  ]);
410
443
 
444
+ /**
445
+ * A word as people say it, read as its written long form, as in scout
446
+ * scribe.ts SPOKEN_FORMS: "go get 'em" is "go get them", "gonna" is "going to".
447
+ */
448
+ const SPOKEN_FORMS = new Map([
449
+ ["em", ["them"]], ["gonna", ["going", "to"]], ["wanna", ["want", "to"]], ["gotta", ["got", "to"]],
450
+ ["kinda", ["kind", "of"]], ["sorta", ["sort", "of"]], ["lemme", ["let", "me"]], ["gimme", ["give", "me"]],
451
+ ["cause", ["because"]], ["cuz", ["because"]], ["til", ["until"]], ["till", ["until"]], ["ya", ["you"]],
452
+ ["yeah", ["yes"]], ["yep", ["yes"]],
453
+ ]);
454
+
411
455
  /**
412
456
  * #3433: the number reading of scout spokenNumbers.ts, so a script's "$29" and a
413
457
  * scribe's "twenty nine dollars" line up here as they do in the server's cut.
@@ -532,7 +576,7 @@ function spokenForms(word) {
532
576
 
533
577
  /** The spoken tokens of one written word; empty for pure punctuation. */
534
578
  function spokenWords(word) {
535
- return spokenForms(word).map((t) => SAME_WORD_SPELLINGS.get(t) ?? t);
579
+ return spokenForms(word).flatMap((t) => SPOKEN_FORMS.get(t) ?? [t]).map((t) => SAME_WORD_SPELLINGS.get(t) ?? t);
536
580
  }
537
581
 
538
582
  /** { tokens, sourceIndex }: tokens[i] came from written word sourceIndex[i]. */
@@ -747,8 +791,13 @@ export function asksPause(line) {
747
791
  * lineGap ({ max, keep }, cutPace): where one line ends and the next begins,
748
792
  * a silence over `max` is cut to `keep` instead, and that break's last span
749
793
  * carries `atLine`, the index of the line after it, where the take is split.
794
+ *
795
+ * jump (JUMP_CUT, the jumpCut setting): any pause over jump.maxGap between two
796
+ * script words, inside a sentence too, keeps jump.keepAfter after the earlier
797
+ * word and jump.keepBefore before the later one instead (jumpCutSpan), on
798
+ * whole frames. The pauses kept above stay kept.
750
799
  */
751
- export function sentenceGapCuts(words, lines, levels = null, lineGap = null) {
800
+ export function sentenceGapCuts(words, lines, levels = null, lineGap = null, jump = null) {
752
801
  const written = [];
753
802
  const pieces = [];
754
803
  let between = "";
@@ -779,7 +828,9 @@ export function sentenceGapCuts(words, lines, levels = null, lineGap = null) {
779
828
  const newLine = a.li !== b.li;
780
829
  // A name heard split in two (#2300) ends on its last heard word.
781
830
  const [earlier, later] = [words[spoken.findLast((w) => w < to)], words[to]];
782
- if (!newLine && !SENTENCE_END.test(b.before) && !heardSentenceEnd(earlier.w)) continue;
831
+ const sentenceBreak = newLine || SENTENCE_END.test(b.before) || heardSentenceEnd(earlier.w);
832
+ // Inside a sentence only jumpCut acts, and only on a pause over its longest.
833
+ if (!sentenceBreak && !(jump && jumpCutSpan(earlier.e, later.s, jump))) continue;
783
834
  if (WRITTEN_PAUSE.test(b.before) || lines[a.li].asksPause || lines[b.li].asksPause) continue;
784
835
  if (newLine && lines[a.li].cuesBeat) continue;
785
836
  const gap = later.s - earlier.e;
@@ -790,14 +841,17 @@ export function sentenceGapCuts(words, lines, levels = null, lineGap = null) {
790
841
  const spans = sound ? [sound] : [];
791
842
  const [gapMax, gapKeep] =
792
843
  lineGap && newLine ? [lineGap.max, lineGap.keep] : [SENTENCE_GAP_MAX_SEC, SENTENCE_GAP_KEEP_SEC];
793
- const paused = gap - removed > gapMax + 1e-6;
844
+ // jumpCut: a pause over its longest keeps its two edges, with a sound in it taken out whole.
845
+ const jumped = Boolean(jump) && gap - removed > jump.maxGap + 1e-6;
846
+ const paused = jumped || (sentenceBreak && gap - removed > gapMax + 1e-6);
794
847
  if (paused) {
795
848
  // Placed on the gap with the sound already out, then moved back past it.
796
849
  // Frame edges only ever widen what is kept, so the silence left stays
797
850
  // between the kept length and the longest allowed.
798
851
  const back = (t) => (sound && t > sound.s ? t + removed : t);
799
- const s = back(ceilFrame(earlier.e + gapKeep / 2));
800
- const e = back(floorFrame(later.s - removed - gapKeep / 2));
852
+ const [keepAfter, keepBefore] = jumped ? [jump.keepAfter, jump.keepBefore] : [gapKeep / 2, gapKeep / 2];
853
+ const s = back(ceilFrame(earlier.e + keepAfter));
854
+ const e = back(floorFrame(later.s - removed - keepBefore));
801
855
  if (e > s) spans.push({ s, e });
802
856
  }
803
857
  const merged = [];
@@ -893,7 +947,7 @@ function clipLevels(file, filter = null) {
893
947
  /** Decoded final-mix levels; callers must not attribute an event to these whole-mix windows. */
894
948
  export const measureCutAudio = (file) => clipLevels(file);
895
949
 
896
- function tightenSentenceGaps(spine, reactionCues, scriptLines, readLevels, lineGap = null) {
950
+ function tightenSentenceGaps(spine, reactionCues, scriptLines, readLevels, lineGap = null, jump = null) {
897
951
  for (const seg of spine) {
898
952
  if (seg.source !== "clip" || seg.audio !== "clip" || !seg.words?.length || seg.fixedLength) continue;
899
953
  const lines = seg.lineIds.map((id) => ({
@@ -901,7 +955,7 @@ function tightenSentenceGaps(spine, reactionCues, scriptLines, readLevels, lineG
901
955
  asksPause: asksPause(scriptLines.get(id)),
902
956
  cuesBeat: reactionCues.has(id),
903
957
  }));
904
- const heardCuts = sentenceGapCuts(seg.words, lines, readLevels(seg.file), lineGap);
958
+ const heardCuts = sentenceGapCuts(seg.words, lines, readLevels(seg.file), lineGap, jump);
905
959
  // The measured map: on whole slots of the clip's own picture, so both lose the same frames.
906
960
  const cuts = seg.map?.picture ? cutsOnSlots(heardCuts, seg.map.deltaSec) : heardCuts;
907
961
  if (cuts.length === 0) continue;
@@ -1212,8 +1266,11 @@ export function brollWindow(seg, counts, cueLineId, texts, broll) {
1212
1266
  * word, so the action it ends on (her setting the mat down, #3199) is seen, and
1213
1267
  * one marked with actionLeadSec keeps that long before its first word, so the
1214
1268
  * action it opens on (the dog stepping onto the mat, #3272) is seen.
1269
+ *
1270
+ * talkTrim: no talking clip keeps more than TALK_TRIM_SEC of air after its last
1271
+ * word, the ad's last one included; a scene's actionTailSec still holds.
1215
1272
  */
1216
- function trimJoins(spine, reactionCues, scriptLines, gapMax = null) {
1273
+ function trimJoins(spine, reactionCues, scriptLines, gapMax = null, talkTrim = false) {
1217
1274
  // cutPace: the beat before someone new answers shrinks so the join holds at most gapMax of air.
1218
1275
  const newSpeakerLead = gapMax === null
1219
1276
  ? JOIN_LEAD_NEW_SPEAKER_SEC
@@ -1235,7 +1292,8 @@ function trimJoins(spine, reactionCues, scriptLines, gapMax = null) {
1235
1292
  inSec = Math.max(inSec, Math.min(clear, floorFrame(firstWord)));
1236
1293
  }
1237
1294
  const endsAd = k === spine.length - 1 && !reactionCues.has(seg.lineIds.at(-1));
1238
- const tailSec = Math.max(endsAd ? END_AIR_SEC : JOIN_TAIL_SEC, seg.actionTailSec ?? 0);
1295
+ const airSec = endsAd ? END_AIR_SEC : JOIN_TAIL_SEC;
1296
+ const tailSec = Math.max(talkTrim ? Math.min(airSec, TALK_TRIM_SEC) : airSec, seg.actionTailSec ?? 0);
1239
1297
  let outSec = ceilFrame(lastWord + tailSec);
1240
1298
  if (after.length > 0) {
1241
1299
  const clear = floorFrame(Math.min(...after.map((w) => w.s)) - EXTRA_CLEARANCE_SEC);
@@ -1380,6 +1438,17 @@ function markPunchIns(spine, sameShot) {
1380
1438
 
1381
1439
  const sameSpeaker = (prev, seg) => Boolean(prev.lastSpeaker && seg.firstSpeaker === prev.lastSpeaker);
1382
1440
 
1441
+ /** pacePass: every second piece of the spine zooms, where no punch-in does already. Answers the cut's note. */
1442
+ export function paceZooms(spine) {
1443
+ let zoomed = 0;
1444
+ spine.forEach((seg, k) => {
1445
+ if (k % 2 === 0 || seg.punchIn) return;
1446
+ seg.paceZoom = true;
1447
+ zoomed += 1;
1448
+ });
1449
+ return `pacePass: the cut plays at ${PACE_PASS.speed}x and ${zoomed} piece${zoomed === 1 ? "" : "s"} zoom ${PACE_PASS.zoom}x`;
1450
+ }
1451
+
1383
1452
  /** cutPace: two pieces of one take, back to back. */
1384
1453
  const samePiece = (prev, seg) =>
1385
1454
  Boolean(prev.piece && seg.piece && prev.file === seg.file && prev.piece.take === seg.piece.take);
@@ -2611,8 +2680,10 @@ export function buildTimeline({
2611
2680
  }
2612
2681
  const pace = finish?.cutPace === true;
2613
2682
  const lineGap = pace ? { max: PACE_SPLIT_PAUSE_SEC, keep: PACE_GAP_MAX_SEC } : null;
2614
- tightenSentenceGaps(spine, reactionCues, scriptLines, readLevels, lineGap);
2615
- trimJoins(spine, reactionCues, scriptLines, pace ? PACE_GAP_MAX_SEC : null);
2683
+ // jumpCut stays off a template launch's cut, whose selected clocks and windows hold their real time.
2684
+ const jump = finish?.jumpCut && manifest?.templateMotion?.enabled !== true ? JUMP_CUT : null;
2685
+ tightenSentenceGaps(spine, reactionCues, scriptLines, readLevels, lineGap, jump);
2686
+ trimJoins(spine, reactionCues, scriptLines, pace ? PACE_GAP_MAX_SEC : null, finish?.talkTrim === true);
2616
2687
  if (pace) {
2617
2688
  // The pieces of one take alternate between the plain frame and the
2618
2689
  // punch-in, and a jump-cut run's alternation carries on across them.
@@ -3161,6 +3232,7 @@ export function buildFfmpegArgs(timeline, { resolve, music, out, finish = null,
3161
3232
  }
3162
3233
  if (seg.holdSec > 0.01) fit.push(`tpad=stop_mode=clone:stop_duration=${sec(seg.holdSec)}`);
3163
3234
  if (seg.punchIn) fit.push(PUNCH_IN);
3235
+ if (seg.paceZoom) fit.push(PACE_ZOOM);
3164
3236
  filters.push(`${norm(`${i}:v`)}${fit.length ? `,${fit.join(",")}` : ""}[v${i}]`);
3165
3237
  // A segment split around a reaction beat starts partway into its sound too.
3166
3238
  const skipIn = inSec > 0.001 ? `atrim=start=${sec(inSec)},asetpts=PTS-STARTPTS,` : "";
@@ -3730,6 +3802,29 @@ export const CAPTION_CLEAR_SEC = 0.02;
3730
3802
  export const CAPTION_MIN_SEC = 0.35;
3731
3803
  /** captionsByLine: the caption font is at most this share of the frame's height (69 px of 1920). */
3732
3804
  export const CAPTION_MAX_SHARE = 0.036;
3805
+ /** captionColours: the speakers' caption colours in the order they first speak (ASS, &HBBGGRR&): white, yellow, cyan. */
3806
+ export const CAPTION_COLOURS = ["&HFFFFFF&", "&H00FFFF&", "&HFFFF00&"];
3807
+ /** captionColours: a coloured screen's black edge, at least this thick, so yellow or cyan still reads on a light picture. */
3808
+ export const CAPTION_COLOUR_MIN_OUTLINE = 4;
3809
+
3810
+ /**
3811
+ * captionColours: each line caption screen (lineCaptionScreens) in its
3812
+ * speaker's colour, so a viewer follows who talks when one of them is off
3813
+ * screen. The speaker is the screen's script line's speakerId, a narrator's
3814
+ * line (no speakerId) one speaker of its own; the colours go in the order the
3815
+ * speakers first speak and start again after the last. A screen whose line
3816
+ * the script does not hold stays as it is.
3817
+ */
3818
+ export function colourScreens(screens, storyboard) {
3819
+ const speakerOf = new Map((storyboard?.script ?? []).map((line) => [line?.lineId, line?.speakerId ?? null]));
3820
+ const order = [];
3821
+ return screens.map((c) => {
3822
+ if (!speakerOf.has(c.line)) return c;
3823
+ const who = speakerOf.get(c.line);
3824
+ if (!order.includes(who)) order.push(who);
3825
+ return { ...c, colour: CAPTION_COLOURS[order.indexOf(who) % CAPTION_COLOURS.length] };
3826
+ });
3827
+ }
3733
3828
 
3734
3829
  export function lineCaptionScreens(words, cap = null) {
3735
3830
  const per = Math.max(1, Math.round(cap?.wordsPerLine?.median ?? 3));
@@ -3834,7 +3929,7 @@ export function editAss({ captions = [], cap = null, cards = [], hook = null, en
3834
3929
  `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`,
3835
3930
  ...(endLayers ? endCardStyles(endLayers.colors, H) : []), "",
3836
3931
  "[Events]", "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
3837
- ...captions.map((c) => `Dialogue: 1,${assTime(c.s)},${assTime(c.e)},Cap,,0,0,0,,{\\pos(${W / 2},${y})}${c.text}`),
3932
+ ...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}`),
3838
3933
  ...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)}`),
3839
3934
  ...(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)}`] : []),
3840
3935
  ...(endCard ? [`Dialogue: 4,${assTime(endCard.in)},${assTime(endCard.out)},End,,0,0,0,,{\\pos(${W / 2},${H / 2})\\fad(120,0)}${assText(endCard.text)}`] : []),
@@ -5526,10 +5621,18 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
5526
5621
  // The finishing settings' part of the render: the speed, the burned
5527
5622
  // captions and cards, and where the mix goes before its loudness pass.
5528
5623
  const notes = [];
5624
+ if (finish?.captionColours && stagedText) notes.push("captionColours: the text stage draws these captions, so they stay one colour");
5529
5625
  const pictureSec = timeline.spine.reduce((sum, seg) => sum + seg.seconds, 0);
5530
5626
  // A song and selected semantic action clocks are never globally accelerated.
5531
5627
  const protectedMotion = [...timeline.spine, ...timeline.cutaways].some((s) => s.motionProtection);
5532
- const speed = finish?.cutPace && !timeline.wholeVoice && !protectedMotion ? speedFor(pictureSec, finish.targetSeconds) : 1;
5628
+ // pacePass: its speed in place of cutPace's, on a cut no clock is held to (no song laid whole, no selected or mapped clock).
5629
+ const paced = finish?.pacePass === true && !timeline.wholeVoice && !protectedMotion && !timeline.mapped &&
5630
+ manifest.templateMotion?.enabled !== true;
5631
+ if (finish?.pacePass && !paced) notes.push("this cut keeps a real-time clock, so pacePass did not speed it up or zoom it");
5632
+ if (paced) notes.push(paceZooms(timeline.spine));
5633
+ const speed = paced
5634
+ ? PACE_PASS.speed
5635
+ : finish?.cutPace && !timeline.wholeVoice && !protectedMotion ? speedFor(pictureSec, finish.targetSeconds) : 1;
5533
5636
  if (finish?.cutPace && protectedMotion) notes.push("selected action/listening/ending obligations keep their real-time clock; cutPace does not accelerate the whole cut");
5534
5637
  if (timeline.sourceMap) {
5535
5638
  // The exact bytes every measured clock was read from, for whoever binds an approval to them.
@@ -5611,7 +5714,7 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
5611
5714
  if (finish.captions) burned = screens;
5612
5715
  burnedCards = finish.cards ? (copied ? copied.cards : storyboardCards(storyboard, timeline)) : [];
5613
5716
  writeFileSync(here(ass), editAss({
5614
- captions: screens,
5717
+ captions: finish.captionColours ? colourScreens(screens, storyboard) : screens,
5615
5718
  cap,
5616
5719
  ...(finish.captionsByLine ? { capMaxShare: CAPTION_MAX_SHARE } : {}),
5617
5720
  cards: burnedCards,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aicopycoders/exodus",
3
- "version": "2026.11.1000-beta.2",
3
+ "version": "2026.11.1100-beta.1",
4
4
  "description": "CLI + Claude Code skills for the Copycoders Exodus ad pipeline",
5
5
  "repository": {
6
6
  "type": "git",