@aicopycoders/exodus 2026.11.1200-beta.12 → 2026.11.1200-beta.13

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.
@@ -83,6 +83,9 @@ export class FirstCutError extends Error {
83
83
  readonly code: 1 | 2;
84
84
  }
85
85
 
86
+ /** Why a finished cut is refused for its loudness (LoudnessRefusal's message), or null when its true peak is at or under -1 dBTP. */
87
+ export function truePeakRefusal(measured: { i: number; tp: number } | null): string | null;
88
+
86
89
  /** The finished cut's true peak is over -1 dBTP, or could not be measured, after the loudness pass. */
87
90
  export class LoudnessRefusal extends FirstCutError {
88
91
  constructor(message: string, measured: { i: number; tp: number } | null);
@@ -269,8 +272,11 @@ export interface CutPace {
269
272
  /** COP-300: the finished cut was checked against its own sound (cutSync). */
270
273
  captionCheck?: true;
271
274
  };
272
- /** `limited`: limitPeaks' limiter ran after the loudness pass. */
273
- loudness?: { lufs: number; truePeak: number; passes: 1 | 2; limited?: true };
275
+ /**
276
+ * `limited`: limitPeaks' limiter ran after the loudness pass. #4573: `limitedAgain` times it ran again lower, from
277
+ * the same mix, because the finished file was over -1 dBTP; `limit` is the ceiling the kept cut was made at.
278
+ */
279
+ loudness?: { lufs: number; truePeak: number; passes: 1 | 2; limited?: true; limitedAgain?: number; limit?: number };
274
280
  /** Present only with cutChecks. */
275
281
  checks?: CutChecks;
276
282
  /** COP-300: present when a sped-up cut burned its captions: the caption file is on the finished cut's clock. */
@@ -199,11 +199,32 @@ export const FINISH_LRA = 11;
199
199
  export const TRUE_PEAK_MAX_DB = -1;
200
200
  /**
201
201
  * limitPeaks: after the loudness pass, the sound oversampled 4x through a
202
- * limiter at 0.8 (about -1.9 dB), so a peak between two samples is caught too.
202
+ * limiter at PEAK_LIMIT (about -1.9 dB), so a peak between two samples is caught too.
203
203
  * The cut is still measured after and refused over TRUE_PEAK_MAX_DB. Its
204
204
  * resample is pinned to stereo, as every one after loudnorm is (loudnessApplyArgs).
205
205
  */
206
- export const PEAK_LIMITER = "aresample=192000,aformat=channel_layouts=stereo,alimiter=limit=0.8:level=false:attack=2:release=60";
206
+ export const PEAK_LIMIT = 0.8;
207
+ /** The limiter at `limit`, a linear level alimiter takes from 0.0625 to 1. */
208
+ export function peakLimiter(limit = PEAK_LIMIT) {
209
+ return `aresample=192000,aformat=channel_layouts=stereo,alimiter=limit=${limit}:level=false:attack=2:release=60`;
210
+ }
211
+ export const PEAK_LIMITER = peakLimiter();
212
+ /**
213
+ * #4573: the AAC encode after the limiter can put a peak back over
214
+ * TRUE_PEAK_MAX_DB, by a different amount on each cut of the same takes (the
215
+ * room tone is fresh noise every time). A limited cut that lands over is
216
+ * limited again from the same mix, this many times at most, each time lower by
217
+ * what the last one landed over FINISH_TRUE_PEAK; still over, it is refused.
218
+ */
219
+ export const LIMIT_AGAIN_MAX = 2;
220
+ /** The lowest ceiling a limit again goes to (about -6 dB): a cut that needs lower is refused, not squashed. */
221
+ const PEAK_LIMIT_MIN = 0.5;
222
+
223
+ /** The next ceiling down after a limited pass measured `tp` dBTP. */
224
+ export function lowerPeakLimit(limit, tp) {
225
+ const lower = limit * 10 ** (-(tp - FINISH_TRUE_PEAK) / 20);
226
+ return Math.max(PEAK_LIMIT_MIN, Math.round(lower * 10_000) / 10_000);
227
+ }
207
228
  /**
208
229
  * jumpCut: inside a talking clip, a pause over maxGap between two heard words
209
230
  * is cut down, keeping keepAfter after the earlier word and keepBefore before
@@ -5571,11 +5592,9 @@ function ffmpegReason(res) {
5571
5592
  return res.signal ? `it was stopped by ${res.signal}.` : "it printed no reason.";
5572
5593
  }
5573
5594
 
5574
- /** Both passes on the mix, then the finished cut measured again. A receipt may
5575
- * retain that final observation without changing the legacy mastering result. */
5576
- export function finishLoudnessPass(mix, out, limiter = null, onMeasured = null) {
5577
- const measured = measureLoudness(mix);
5578
- const args = loudnessApplyArgs(mix, measured, out, limiter);
5595
+ /** The mix normalized with pass one's numbers into `out`, through the limiter at `limit` when one is given. */
5596
+ function applyLoudness(mix, measured, out, limit) {
5597
+ const args = loudnessApplyArgs(mix, measured, out, limit == null ? null : peakLimiter(limit));
5579
5598
  const res = spawnSync("ffmpeg", args, { stdio: ["inherit", "inherit", "pipe"], encoding: "utf8", maxBuffer: 1 << 26 });
5580
5599
  if (res.status !== 0) {
5581
5600
  // ffmpeg's words still reach the log, and its reason leads the error:
@@ -5584,11 +5603,32 @@ export function finishLoudnessPass(mix, out, limiter = null, onMeasured = null)
5584
5603
  const quoted = args.map((a) => (/[\s\[\];]/.test(a) ? `'${a}'` : a)).join(" ");
5585
5604
  throw new FirstCutError(1, `ffmpeg failed on the loudness pass: ${ffmpegReason(res)} The command it ran:\n ffmpeg ${quoted}`);
5586
5605
  }
5587
- const finished = measureLoudness(out);
5606
+ return measureLoudness(out);
5607
+ }
5608
+
5609
+ /** Both passes on the mix, then the finished cut measured again. A receipt may
5610
+ * retain that final observation without changing the legacy mastering result.
5611
+ * `limit` (limitPeaks) is the limiter's ceiling, PEAK_LIMIT; a limited cut over
5612
+ * the limit is limited again lower (LIMIT_AGAIN_MAX), one under it is left as it is. */
5613
+ export function finishLoudnessPass(mix, out, limit = null, onMeasured = null) {
5614
+ const measured = measureLoudness(mix);
5615
+ let ceiling = limit;
5616
+ let finished = applyLoudness(mix, measured, out, ceiling);
5617
+ let again = 0;
5618
+ while (ceiling != null && finished && finished.tp > TRUE_PEAK_MAX_DB && again < LIMIT_AGAIN_MAX) {
5619
+ const lower = lowerPeakLimit(ceiling, finished.tp);
5620
+ if (lower >= ceiling) break;
5621
+ ceiling = lower;
5622
+ finished = applyLoudness(mix, measured, out, ceiling);
5623
+ again++;
5624
+ }
5588
5625
  const refusal = truePeakRefusal(finished);
5589
5626
  if (refusal) throw new LoudnessRefusal(refusal, finished);
5590
5627
  onMeasured?.(finished);
5591
- return { lufs: round2(finished.i), truePeak: round2(finished.tp), passes: measured ? 2 : 1, ...(limiter ? { limited: true } : {}) };
5628
+ return {
5629
+ lufs: round2(finished.i), truePeak: round2(finished.tp), passes: measured ? 2 : 1,
5630
+ ...(limit != null ? { limited: true } : {}), ...(again > 0 ? { limitedAgain: again, limit: ceiling } : {}),
5631
+ };
5592
5632
  }
5593
5633
 
5594
5634
  /** The filters of `names` this ffmpeg does not have. */
@@ -6860,9 +6900,9 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
6860
6900
  else if (missing.length > 0) notes.push(`this ffmpeg has no ${missing.join(", ")} filter, so the voice was not cleaned`);
6861
6901
  else clean = { voice: VOICE_CLEAN, under: UNDER_VOICE };
6862
6902
  }
6863
- let limiter = null;
6903
+ let peakLimit = null;
6864
6904
  if (finish?.limitPeaks) {
6865
- if (hasFilter("alimiter")) limiter = PEAK_LIMITER;
6905
+ if (hasFilter("alimiter")) peakLimit = PEAK_LIMIT;
6866
6906
  else notes.push("this ffmpeg has no alimiter filter, so the loudness pass ran without the limiter");
6867
6907
  }
6868
6908
  const paths = finishPaths(out);
@@ -6983,13 +7023,14 @@ export function firstCut({ dir, out: outOpt, skip = new Set(), music: musicOn =
6983
7023
  let loudnessMeasurement = null;
6984
7024
  if (finish?.finishLoudness) {
6985
7025
  try {
6986
- loudness = finishLoudnessPass(rendered, out, limiter, template
7026
+ loudness = finishLoudnessPass(rendered, out, peakLimit, template
6987
7027
  ? (measured) => { loudnessMeasurement = measured; } : null);
6988
7028
  } catch (error) {
6989
- if (!template || !(error instanceof FirstCutError)) throw error;
6990
- // One local limiter pass on the same retained mix, never a provider call.
7029
+ // A limited pass already limited itself again (#4573); the same mix would only be refused the same way.
7030
+ if (!template || peakLimit != null || !(error instanceof FirstCutError)) throw error;
7031
+ // The limiter on the same retained mix, never a provider call, limited again lower as finishLoudnessPass does.
6991
7032
  // If it still clips or cannot be measured, the refusal holds the cut.
6992
- loudness = finishLoudnessPass(rendered, out, PEAK_LIMITER,
7033
+ loudness = finishLoudnessPass(rendered, out, PEAK_LIMIT,
6993
7034
  (measured) => { loudnessMeasurement = measured; });
6994
7035
  } finally {
6995
7036
  rmSync(rendered, { force: true });
@@ -74,6 +74,10 @@ export interface CustomerRun {
74
74
  notes?: string[];
75
75
  } | null;
76
76
  canRetry: boolean;
77
+ canCutAgain?: boolean;
78
+ cutFailure?: {
79
+ sentence: string;
80
+ };
77
81
  stopReason: CustomerStopReason | null;
78
82
  detailsPath: string | null;
79
83
  cutHolds?: string[];
@@ -100,6 +100,13 @@ function stoppedLines(run, page) {
100
100
  run.canRetry ? `Try again from the video's page: ${page}` : "Start a new one from the Video page.",
101
101
  ];
102
102
  }
103
+ if (run.cutFailure && run.canCutAgain) {
104
+ return [
105
+ "The final cut didn't work.",
106
+ run.cutFailure.sentence,
107
+ `All your clips are done. Cut again from the video's page; it makes no new clips and costs nothing: ${page}`,
108
+ ];
109
+ }
103
110
  return run.canRetry
104
111
  ? ["Something went wrong making this video.", `Try again from the video's page: ${page}`]
105
112
  : ["Something went wrong making this video. Start a new one from the Video page."];
@@ -225,6 +225,9 @@ export interface VideoRun {
225
225
  };
226
226
  workflowId?: string;
227
227
  cutHeldScenes?: number[];
228
+ cutFailure?: {
229
+ sentence: string;
230
+ };
228
231
  cutCheck?: string[];
229
232
  moduleOwned?: boolean;
230
233
  director?: RunDirector;
@@ -330,6 +333,7 @@ export type RunStop = {
330
333
  framesNodeId?: string;
331
334
  heldScenes?: number[];
332
335
  heldTakes?: HeldTake[];
336
+ cutFailure?: string;
333
337
  } | {
334
338
  at: "pilot";
335
339
  nodeId?: string;
@@ -916,6 +916,7 @@ export function classifyRun(run) {
916
916
  ...(missingScenes.length > 0 ? { missingScenes } : {}),
917
917
  ...(missingScenes.length > 0 && framesNodeId ? { framesNodeId } : {}),
918
918
  ...(run.cutHeldScenes?.length ? { heldScenes: run.cutHeldScenes } : {}),
919
+ ...(run.cutFailure?.sentence ? { cutFailure: run.cutFailure.sentence } : {}),
919
920
  };
920
921
  }
921
922
  return { at: "paused", nodeId: run.pausedNodeId, reason: run.pauseReason };
@@ -1141,6 +1142,16 @@ export function stopLines(stop, runId, runUrl, videoPage) {
1141
1142
  }
1142
1143
  if (stop.heldScenes?.length)
1143
1144
  return heldSceneLines(stop.heldScenes, runId, videoPage, stop.heldTakes);
1145
+ if (stop.cutFailure) {
1146
+ return [
1147
+ "Parked: every piece is made, but the app's cut of them didn't work.",
1148
+ stop.cutFailure,
1149
+ `Cut it again on the video's page. It makes no new clips and costs nothing: ${videoPage}`,
1150
+ `Or cut it yourself: exodus video pull ${runId} --out ./ad-${runId}`,
1151
+ `Then upload: exodus video upload ${runId} --file cut.mp4`,
1152
+ `Watch it here: ${runUrl}`,
1153
+ ];
1154
+ }
1144
1155
  if (stop.cutAttached === null) {
1145
1156
  return [
1146
1157
  "Parked: every piece is made.",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aicopycoders/exodus",
3
- "version": "2026.11.1200-beta.12",
3
+ "version": "2026.11.1200-beta.13",
4
4
  "description": "CLI + Claude Code skills for the Copycoders Exodus ad pipeline",
5
5
  "repository": {
6
6
  "type": "git",