@softure-ai/marketing-kit 0.13.1 → 0.14.0

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.
Files changed (41) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +27 -8
  3. package/dist/config/schema.d.ts +2 -0
  4. package/dist/config/schema.d.ts.map +1 -1
  5. package/dist/config/schema.js +10 -2
  6. package/dist/config/schema.js.map +1 -1
  7. package/dist/footage/compose.d.ts +13 -0
  8. package/dist/footage/compose.d.ts.map +1 -1
  9. package/dist/footage/compose.js +26 -14
  10. package/dist/footage/compose.js.map +1 -1
  11. package/dist/footage/film-mix.d.ts +27 -0
  12. package/dist/footage/film-mix.d.ts.map +1 -0
  13. package/dist/footage/film-mix.js +36 -0
  14. package/dist/footage/film-mix.js.map +1 -0
  15. package/dist/footage/loudness.d.ts +91 -27
  16. package/dist/footage/loudness.d.ts.map +1 -1
  17. package/dist/footage/loudness.js +143 -69
  18. package/dist/footage/loudness.js.map +1 -1
  19. package/dist/footage/pipeline.d.ts +38 -10
  20. package/dist/footage/pipeline.d.ts.map +1 -1
  21. package/dist/footage/pipeline.js +119 -63
  22. package/dist/footage/pipeline.js.map +1 -1
  23. package/dist/footage/publish.js +4 -4
  24. package/dist/footage/publish.js.map +1 -1
  25. package/dist/index.d.ts +4 -3
  26. package/dist/index.d.ts.map +1 -1
  27. package/dist/index.js +3 -2
  28. package/dist/index.js.map +1 -1
  29. package/dist/og/element.d.ts.map +1 -1
  30. package/dist/og/element.js +8 -2
  31. package/dist/og/element.js.map +1 -1
  32. package/package.json +2 -2
  33. package/schema/marketing.schema.json +13 -1
  34. package/src/config/schema.ts +14 -2
  35. package/src/footage/compose.ts +33 -12
  36. package/src/footage/film-mix.ts +57 -0
  37. package/src/footage/loudness.ts +166 -68
  38. package/src/footage/pipeline.ts +151 -72
  39. package/src/footage/publish.ts +4 -4
  40. package/src/index.ts +28 -7
  41. package/src/og/element.ts +9 -2
@@ -89,6 +89,38 @@ export function getSegmentZoomEases(edl: Edl, edit: Pick<FootageEdit, "zoomPerce
89
89
  });
90
90
  }
91
91
 
92
+ /** One sound effect the film plays: its file, when it starts, its linear volume and how long it plays, in seconds. */
93
+ export interface FootageSfxCue {
94
+ src: string;
95
+ t: number;
96
+ volume: number;
97
+ dur: number;
98
+ }
99
+
100
+ /**
101
+ * The film's sound effects in film time: a whoosh before every `whoosh` cut, and the end card's whoosh and pop with
102
+ * `isEndCardWhoosh`; an event without a file in `sfx` plays nothing. The composition and the film's mix
103
+ * (`buildFilmMixArgs`) both play these.
104
+ */
105
+ export function getFootageSfxCues(film: FootageFilm, edl: Edl, sfx: Partial<Record<SfxEvent, string>>): FootageSfxCue[] {
106
+ const starts = getSegmentStarts(edl);
107
+ const cutEnd = getEdlDuration(edl);
108
+ const edit = getFootageEdit(film);
109
+ const cues: FootageSfxCue[] = [];
110
+ const play = (event: SfxEvent, t: number, volume: number, dur: number) => {
111
+ const src = sfx[event];
112
+ if (src !== undefined) cues.push({ src, t: r3(Math.max(0, t)), volume, dur });
113
+ };
114
+ edl.segments.forEach((segment, index) => {
115
+ if (segment.transition === "whoosh" && index > 0) play("whoosh", (starts[index] as number) - 0.1, 0.45, 0.57);
116
+ });
117
+ if (film.endCard !== null && edit.isEndCardWhoosh) {
118
+ play("whoosh", cutEnd, 0.3, 0.57);
119
+ play("pop", r3(cutEnd + 0.9), 0.35, 0.72);
120
+ }
121
+ return cues;
122
+ }
123
+
92
124
  export function composeFootage(input: FootageComposeInput): string {
93
125
  const { film, edl, words, frame, colors: c, fonts, assets, caption: captionBox } = input;
94
126
  const starts = getSegmentStarts(edl);
@@ -161,18 +193,7 @@ export function composeFootage(input: FootageComposeInput): string {
161
193
  const captionFit = film.captions && film.captionMaxLines !== undefined ? getCaptionFitScript(film.captionMaxLines, Math.round(captionBox.fontSize * CAPTION_MIN_FONT_SCALE)) : "";
162
194
 
163
195
  // --- Sound ---
164
- const sfx: { src: string; t: number; volume: number; dur: number }[] = [];
165
- const play = (event: SfxEvent, t: number, volume: number, dur: number) => {
166
- const src = assets.sfx[event];
167
- if (src !== undefined) sfx.push({ src, t: r3(Math.max(0, t)), volume, dur });
168
- };
169
- edl.segments.forEach((segment, index) => {
170
- if (segment.transition === "whoosh" && index > 0) play("whoosh", (starts[index] as number) - 0.1, 0.45, 0.57);
171
- });
172
- if (film.endCard !== null && edit.isEndCardWhoosh) {
173
- play("whoosh", cutEnd, 0.3, 0.57);
174
- play("pop", r3(cutEnd + 0.9), 0.35, 0.72);
175
- }
196
+ const sfx = getFootageSfxCues(film, edl, assets.sfx);
176
197
  const audio = [
177
198
  `<audio id="speech" src="${escapeHtml(assets.speech)}" data-start="0" data-duration="${cutEnd}" data-volume="1"></audio>`,
178
199
  ...(assets.music === null ? [] : [`<audio id="music" src="${escapeHtml(assets.music)}" data-start="0" data-duration="${end}" data-volume="1"></audio>`]),
@@ -0,0 +1,57 @@
1
+ import type { FootageSfxCue } from "./compose.js";
2
+ import { FOOTAGE_SAMPLE_RATE } from "./normalize.js";
3
+
4
+ /**
5
+ * The film's sound mixed by ffmpeg as the composition plays it (every element from its start, at its volume, for its
6
+ * duration, summed without normalization), so the mix stage can bring it to the target and gate it before
7
+ * hyperframes captures a frame (issue #1124). The finished film carries this mix, not the render's own sound.
8
+ */
9
+
10
+ export interface FilmMixInput {
11
+ /** The speech track and how long it plays (the cut's length). */
12
+ speech: { file: string; seconds: number };
13
+ /** The ducked music track and how long it plays (the film's length); null for none. */
14
+ music: { file: string; seconds: number } | null;
15
+ /** The sound effects, their `src` a file ffmpeg can read. */
16
+ sfx: readonly FootageSfxCue[];
17
+ /** The film's length: the mix is padded with silence or cut to it. */
18
+ seconds: number;
19
+ /** A WAV file (32-bit float, 48 kHz stereo). */
20
+ output: string;
21
+ }
22
+
23
+ const r3 = (value: number): number => Math.round(value * 1000) / 1000 || 0;
24
+
25
+ /** The ffmpeg arguments that write the film's mix. */
26
+ export function buildFilmMixArgs(input: FilmMixInput): string[] {
27
+ const format = `aresample=${FOOTAGE_SAMPLE_RATE},aformat=sample_fmts=fltp:channel_layouts=stereo`;
28
+ const sources: { file: string; filter: string }[] = [
29
+ { file: input.speech.file, filter: `atrim=duration=${r3(input.speech.seconds)},${format}` },
30
+ ...(input.music === null ? [] : [{ file: input.music.file, filter: `atrim=duration=${r3(input.music.seconds)},${format}` }]),
31
+ ...input.sfx.map((cue) => ({
32
+ file: cue.src,
33
+ filter: `atrim=duration=${r3(cue.dur)},${format},volume=${cue.volume},adelay=delays=${Math.round(cue.t * 1000)}:all=1`,
34
+ })),
35
+ ];
36
+ const chains = sources.map((source, index) => `[${index}:a]${source.filter}[a${index}]`);
37
+ const labels = sources.map((_, index) => `[a${index}]`).join("");
38
+ const mixed = sources.length === 1 ? `[a0]anull` : `${labels}amix=inputs=${sources.length}:duration=longest:normalize=0`;
39
+ const graph = [...chains, `${mixed},apad,atrim=duration=${r3(input.seconds)}[mix]`].join(";");
40
+ return [
41
+ "-v",
42
+ "error",
43
+ "-y",
44
+ ...sources.flatMap((source) => ["-i", source.file]),
45
+ "-filter_complex",
46
+ graph,
47
+ "-map",
48
+ "[mix]",
49
+ "-c:a",
50
+ "pcm_f32le",
51
+ "-ar",
52
+ String(FOOTAGE_SAMPLE_RATE),
53
+ "-ac",
54
+ "2",
55
+ input.output,
56
+ ];
57
+ }
@@ -50,9 +50,13 @@ function getLoudnormFilter(target: LoudnessTarget): string {
50
50
  return `loudnorm=I=${target.target}:TP=${target.truePeak}:LRA=${LOUDNESS_RANGE}`;
51
51
  }
52
52
 
53
- /** The first pass: decodes the sound only (a film's picture is skipped), prints the measurement on stderr, writes nothing. */
54
- export function buildLoudnessMeasureArgs(input: string, target: LoudnessTarget): string[] {
55
- return ["-hide_banner", "-nostats", "-i", input, "-vn", "-af", `${getLoudnormFilter(target)}:print_format=json`, "-f", "null", "-"];
53
+ /**
54
+ * The first pass: decodes the sound only (a film's picture is skipped), prints the measurement on stderr, writes
55
+ * nothing. With `filter`, what is measured is the sound through it (the mix stage's uncompressed probes).
56
+ */
57
+ export function buildLoudnessMeasureArgs(input: string, target: LoudnessTarget, filter?: string): string[] {
58
+ const measure = `${getLoudnormFilter(target)}:print_format=json`;
59
+ return ["-hide_banner", "-nostats", "-i", input, "-vn", "-af", filter === undefined ? measure : `${filter},${measure}`, "-f", "null", "-"];
56
60
  }
57
61
 
58
62
  /** The measurement from the first pass's stderr (its last JSON block); null when there is none or it is incomplete. */
@@ -130,12 +134,12 @@ export function buildLoudnessArgs(options: { input: string; measurement: Loudnes
130
134
  export type LoudnessMeasureOutcome = { kind: "measured"; measurement: LoudnessMeasurement } | { kind: "silent" };
131
135
 
132
136
  /**
133
- * The first pass over `input`: its measurement, or silent when no gain can bring it to the target. Throws naming
137
+ * The first pass over `input` (through `filter` when given): its measurement, or silent when no gain can bring it to the target. Throws naming
134
138
  * `label` (what is measured) when ffmpeg fails, rejects with the signal's reason on abort.
135
139
  */
136
- export async function measureLoudness(input: string, target: LoudnessTarget, options: { label: string; signal?: AbortSignal }): Promise<LoudnessMeasureOutcome> {
140
+ export async function measureLoudness(input: string, target: LoudnessTarget, options: { label: string; signal?: AbortSignal; filter?: string }): Promise<LoudnessMeasureOutcome> {
137
141
  const step = `Measuring ${options.label}'s loudness`;
138
- const measured = await runProcess({ command: "ffmpeg", args: buildLoudnessMeasureArgs(input, target), ...(options.signal === undefined ? {} : { signal: options.signal }) });
142
+ const measured = await runProcess({ command: "ffmpeg", args: buildLoudnessMeasureArgs(input, target, options.filter), ...(options.signal === undefined ? {} : { signal: options.signal }) });
139
143
  if (measured.kind === "not-started") throw new Error(`${step}: ffmpeg did not start (${measured.error}).`);
140
144
  if (measured.code !== 0) throw new Error(`${step}: ffmpeg ended with code ${String(measured.code)}: ${measured.stderr.trim().split("\n").slice(-3).join(" | ")}.`);
141
145
  const measurement = readLoudnessMeasurement(measured.stderr);
@@ -185,24 +189,41 @@ export interface MixLoudnessTarget extends LoudnessTarget {
185
189
  tolerance?: number;
186
190
  /** What the mix's gain keeps: the mix at the target (absent, `"loudness"`) or the speech's level (`"speech"`). */
187
191
  keep?: "loudness" | "speech";
192
+ /** How many times the mix is encoded and measured before the film fails. Absent: `MIX_ATTEMPTS`. */
193
+ attempts?: number;
194
+ /**
195
+ * A near-miss band in LU, at least `tolerance`: a finished mix outside `target ± tolerance` but inside
196
+ * `target ± warnTolerance`, under the true peak limit, finishes with a warning instead of failing. Absent: none.
197
+ */
198
+ warnTolerance?: number;
188
199
  }
189
200
 
190
201
  /** A gain to the window's edge aims this far inside it (at most half the tolerance), so the encode's drift stays in. */
191
202
  const MIX_EDGE_MARGIN = 0.2;
192
- /** The limiter's first ceiling sits this far under the true peak limit: AAC adds inter-sample overshoot after it. */
203
+ /** The limiter's ceiling sits this far under the true peak limit: AAC adds inter-sample overshoot after it. */
193
204
  export const MIX_ENCODE_HEADROOM = 1;
194
- /** How many times the mix is encoded and measured before the film fails. */
205
+ /** How many times the mix is encoded and measured before the film fails, unless `MixLoudnessTarget.attempts` says. */
195
206
  export const MIX_ATTEMPTS = 4;
196
- /** What a retry lowers the ceiling by on top of the measured overshoot, in dB. */
207
+ /** What a retry lowers the ceiling by on top of the measured true peak excess, in dB. */
197
208
  const MIX_RETRY_MARGIN = 0.3;
198
- /** With `keep: "speech"`, a retry aims this far inside the window's edge (at most half the tolerance), in LU. */
199
- export const MIX_RETRY_EDGE_MARGIN = 0.3;
200
- /** The limiter's loudness cost per dB of drive (gain minus ceiling) until the tries measure it, in LU per dB. */
201
- export const MIX_LIMITER_SLOPE = 0.5;
202
- /** The steepest limiter cost a retry believes: near 1 a gain step would barely move the mix and the gain would run away. */
203
- export const MIX_LIMITER_SLOPE_MAX = 0.7;
204
- /** How far apart the tries' drives must spread (their variance, in dB²) before the slope is fitted from them. */
205
- const MIX_SLOPE_SPREAD = 0.09;
209
+ /** With `keep: "speech"`, a probe inside the window shrunk by this much needs no gain (the encode moves a mix about this much), in LU. */
210
+ const MIX_MET_MARGIN = 0.1;
211
+ /** With `keep: "speech"`, a mix that misses the window is aimed this far inside its edge (at most half the tolerance), in LU. */
212
+ export const MIX_AIM_EDGE_MARGIN = 0.45;
213
+ /** How close to its aim a probe must land, in LU: the plain target's window, and how far inside the edge keep speech aims. */
214
+ export const MIX_GAIN_PRECISION = 0.15;
215
+ /** How many uncompressed passes one solve of the gain may take. */
216
+ export const MIX_GAIN_PROBES = 6;
217
+ /** The largest gain a probe tries, either way, in dB. */
218
+ const MIX_GAIN_LIMIT = 30;
219
+ /** Below this loudness change per dB of gain the slope is not trusted (the limiter takes it back): a probe steps by its miss. */
220
+ const MIX_MIN_SLOPE = 0.2;
221
+ /**
222
+ * The mix is low-passed here after the limiter, and the AAC encoder cuts here too: the limiter's fast gain moves leave
223
+ * high frequencies on every transient that AAC turns into inter-sample overshoot (up to 3.4 dB on clicky speech,
224
+ * issue #1124); without them it stays within about 1 dB.
225
+ */
226
+ export const MIX_LOWPASS_HZ = 16000;
206
227
  /** `alimiter`'s lowest ceiling (its `limit` of 0.0625), in dB. */
207
228
  const LIMITER_FLOOR = -24;
208
229
  /** The limiter runs at 4x the film's rate, so it holds the true peak rather than the sample peak. */
@@ -214,7 +235,7 @@ export interface MixAttempt {
214
235
  ceilingDbtp: number;
215
236
  }
216
237
 
217
- /** One encode of the mix: the attempt and what the encoded file measured. */
238
+ /** One measurement of the mix through an attempt: uncompressed (a probe of the gain) or encoded (a try). */
218
239
  export interface MixTry {
219
240
  attempt: MixAttempt;
220
241
  measured: MixLoudness;
@@ -230,9 +251,15 @@ export function getMixTolerance(target: MixLoudnessTarget): number {
230
251
  return target.tolerance ?? MIX_LOUDNESS_TOLERANCE;
231
252
  }
232
253
 
254
+ /** How many encodes the mix stage may take. */
255
+ export function getMixAttempts(target: MixLoudnessTarget): number {
256
+ return target.attempts ?? MIX_ATTEMPTS;
257
+ }
258
+
233
259
  /**
234
- * The gain a mix measuring `integrated` LUFS needs: to the target in the default mode; with `keep: "speech"` none
235
- * inside `target ± tolerance`, else to the nearest edge (aimed a little inside, see `MIX_EDGE_MARGIN`).
260
+ * The gain a mix measuring `integrated` LUFS needs before any limiter: to the target in the default mode; with
261
+ * `keep: "speech"` none inside `target ± tolerance`, else to the nearest edge (aimed a little inside, see
262
+ * `MIX_EDGE_MARGIN`). The first probe of the gain starts here.
236
263
  */
237
264
  export function getMixGain(integrated: number, target: MixLoudnessTarget): number {
238
265
  if (target.keep !== "speech") return roundTo(target.target - integrated, 2);
@@ -243,78 +270,149 @@ export function getMixGain(integrated: number, target: MixLoudnessTarget): numbe
243
270
  return 0;
244
271
  }
245
272
 
246
- /** The first try: the gain the measured mix needs (`getMixGain`), the ceiling one encode's headroom under the limit. */
247
- export function getFirstMixAttempt(measurement: Pick<LoudnessMeasurement, "inputI">, target: MixLoudnessTarget): MixAttempt {
248
- return { gainDb: getMixGain(measurement.inputI, target), ceilingDbtp: Math.max(LIMITER_FLOOR, roundTo(target.truePeak - MIX_ENCODE_HEADROOM, 2)) };
273
+ /** The first ceiling: one encode's headroom under the true peak limit, never under the limiter's floor. */
274
+ export function getFirstMixCeiling(target: MixLoudnessTarget): number {
275
+ return Math.max(LIMITER_FLOOR, roundTo(target.truePeak - MIX_ENCODE_HEADROOM, 2));
276
+ }
277
+
278
+ /**
279
+ * The ceiling for the next encode: lowered by the encode's true peak excess plus a margin when it broke the limit,
280
+ * else kept. The excess is the codec's (the gain does not move it), so the ceiling never moves with the loudness.
281
+ */
282
+ export function getNextMixCeiling(ceilingDbtp: number, measured: MixLoudness, target: MixLoudnessTarget): number {
283
+ const excess = measured.truePeak - target.truePeak;
284
+ return excess > 0 ? Math.max(LIMITER_FLOOR, roundTo(ceilingDbtp - excess - MIX_RETRY_MARGIN, 2)) : ceilingDbtp;
249
285
  }
250
286
 
251
- /** One try as the limiter model sees it: how hard the limiter was driven (gain minus ceiling) and the loudness it took. */
252
- function getLimiterPoint(entry: MixTry, inputI: number): { drive: number; cost: number } {
253
- return { drive: entry.attempt.gainDb - entry.attempt.ceilingDbtp, cost: inputI + entry.attempt.gainDb - entry.measured.integrated };
287
+ /** Where a probe of the gain should land a mix that measures `integrated` LUFS, and whether it already does. */
288
+ export interface MixAim {
289
+ aim: number;
290
+ isMet: boolean;
254
291
  }
255
292
 
256
293
  /**
257
- * How much loudness the limiter takes per dB it is driven harder, fitted (least squares) from the tries once their
258
- * drives spread, else `MIX_LIMITER_SLOPE`; clamped to 0..`MIX_LIMITER_SLOPE_MAX`. `inputI` is the render's mix as measured.
294
+ * The gain's aim for a mix at `integrated` LUFS: in the default mode the target (met within `MIX_GAIN_PRECISION`);
295
+ * with `keep: "speech"` met (no gain moves it) inside the window shrunk by `MIX_MET_MARGIN`, else
296
+ * `MIX_AIM_EDGE_MARGIN` inside the edge it misses.
259
297
  */
260
- export function getLimiterSlope(tries: readonly MixTry[], inputI: number): number {
261
- const points = tries.map((entry) => getLimiterPoint(entry, inputI));
262
- const meanDrive = points.reduce((sum, point) => sum + point.drive, 0) / Math.max(1, points.length);
263
- const meanCost = points.reduce((sum, point) => sum + point.cost, 0) / Math.max(1, points.length);
264
- const spread = points.reduce((sum, point) => sum + (point.drive - meanDrive) ** 2, 0);
265
- const slope = points.length >= 2 && spread >= MIX_SLOPE_SPREAD ? points.reduce((sum, point) => sum + (point.drive - meanDrive) * (point.cost - meanCost), 0) / spread : MIX_LIMITER_SLOPE;
266
- return roundTo(Math.min(MIX_LIMITER_SLOPE_MAX, Math.max(0, slope)), 3);
298
+ export function getMixAim(integrated: number, target: MixLoudnessTarget): MixAim {
299
+ if (target.keep !== "speech") return { aim: target.target, isMet: Math.abs(integrated - target.target) <= MIX_GAIN_PRECISION };
300
+ const tolerance = getMixTolerance(target);
301
+ const met = tolerance - Math.min(MIX_MET_MARGIN, tolerance / 2);
302
+ const aim = tolerance - Math.min(MIX_AIM_EDGE_MARGIN, tolerance / 2);
303
+ if (integrated < target.target - met) return { aim: roundTo(target.target - aim, 2), isMet: false };
304
+ if (integrated > target.target + met) return { aim: roundTo(target.target + aim, 2), isMet: false };
305
+ return { aim: integrated, isMet: true };
267
306
  }
268
307
 
269
308
  /**
270
- * Where a retry aims the mix's integrated loudness when it would land at `predicted` LUFS with the gain kept: the
271
- * target in the default mode; with `keep: "speech"` nowhere (the gain stays) while `predicted` is inside the window
272
- * shrunk by `MIX_RETRY_EDGE_MARGIN`, else that margin inside the edge it would miss.
309
+ * The next gain to probe at a fixed ceiling, from the probes so far (oldest first) and `shift` (what the encode adds
310
+ * to a probe's loudness, 0 before the first encode): a secant step through the last two probes, or a step by the
311
+ * miss when there is one probe or the slope is flat or falling (the limiter takes back what the gain adds, so the
312
+ * loudness is not monotone in the gain on clicky speech). Null when the last probe meets its aim, or the step would
313
+ * repeat a gain already probed.
273
314
  */
274
- function getRetryAim(predicted: number, target: MixLoudnessTarget): number | null {
275
- if (target.keep !== "speech") return target.target;
276
- const tolerance = getMixTolerance(target);
277
- const inside = tolerance - Math.min(MIX_RETRY_EDGE_MARGIN, tolerance / 2);
278
- if (predicted < target.target - inside) return target.target - inside;
279
- if (predicted > target.target + inside) return target.target + inside;
280
- return null;
315
+ export function getNextGainProbe(probes: readonly MixTry[], target: MixLoudnessTarget, shift = 0): number | null {
316
+ const last = probes.at(-1);
317
+ if (last === undefined) throw new Error("getNextGainProbe: no probe of the mix to correct.");
318
+ const { aim, isMet } = getMixAim(last.measured.integrated + shift, target);
319
+ if (isMet) return null;
320
+ const miss = aim - shift - last.measured.integrated;
321
+ const before = probes.at(-2);
322
+ const slope = before === undefined || before.attempt.gainDb === last.attempt.gainDb ? 0 : (last.measured.integrated - before.measured.integrated) / (last.attempt.gainDb - before.attempt.gainDb);
323
+ const step = slope > MIX_MIN_SLOPE ? miss / slope : miss;
324
+ const gainDb = roundTo(Math.min(MIX_GAIN_LIMIT, Math.max(-MIX_GAIN_LIMIT, last.attempt.gainDb + step)), 2);
325
+ return probes.some((probe) => probe.attempt.gainDb === gainDb) ? null : gainDb;
326
+ }
327
+
328
+ /** The probe closest to its aim: the one the encode uses. */
329
+ export function getBestGainProbe(probes: readonly MixTry[], target: MixLoudnessTarget, shift = 0): MixTry {
330
+ const score = (probe: MixTry): number => {
331
+ const { aim, isMet } = getMixAim(probe.measured.integrated + shift, target);
332
+ return isMet ? 0 : Math.abs(aim - shift - probe.measured.integrated);
333
+ };
334
+ const first = probes[0];
335
+ if (first === undefined) throw new Error("getBestGainProbe: no probe of the mix.");
336
+ return probes.reduce((best, probe) => (score(probe) < score(best) ? probe : best), first);
281
337
  }
282
338
 
283
339
  /**
284
- * The next try after the encodes in `tries` (oldest first; the last one missed `target`). The ceiling is lowered by
285
- * the last overshoot plus a margin when its true peak is over (never under the limiter's floor). The gain comes from
286
- * a model of the limiter: the loudness it takes grows with how hard it is driven (gain minus ceiling) at the slope
287
- * `getLimiterSlope` measures, so the gain is solved for the loudness the mix will have at the new ceiling, not the
288
- * one it had at the old one. `inputI` is the render's mix as measured before any try.
340
+ * The gain at `ceilingDbtp` found by measuring the uncompressed chain (`measure`, one decode of the sound, no encode)
341
+ * from `startGainDb`, at most `MIX_GAIN_PROBES` times: the best probe, with every probe it took.
289
342
  */
290
- export function getNextMixAttempt(tries: readonly MixTry[], inputI: number, target: MixLoudnessTarget): MixAttempt {
291
- const last = tries.at(-1);
292
- if (last === undefined) throw new Error("getNextMixAttempt: no encode of the mix to correct.");
293
- const overshoot = last.measured.truePeak - target.truePeak;
294
- const ceilingDbtp = overshoot > 0 ? Math.max(LIMITER_FLOOR, roundTo(last.attempt.ceilingDbtp - overshoot - MIX_RETRY_MARGIN, 2)) : last.attempt.ceilingDbtp;
295
- const slope = getLimiterSlope(tries, inputI);
296
- const { drive, cost } = getLimiterPoint(last, inputI);
297
- // The limiter's cost at a gain, at the new ceiling: never below none.
298
- const getCost = (gainDb: number): number => Math.max(0, cost + slope * (gainDb - ceilingDbtp - drive));
299
- const aim = getRetryAim(inputI + last.attempt.gainDb - getCost(last.attempt.gainDb), target);
300
- if (aim === null) return { gainDb: last.attempt.gainDb, ceilingDbtp };
301
- const gainDb = (aim - inputI + cost - slope * (ceilingDbtp + drive)) / (1 - slope);
302
- // A gain so low that the limiter would take nothing: the mix moves by the gain alone.
303
- return { gainDb: roundTo(getCost(gainDb) > 0 ? gainDb : aim - inputI, 2), ceilingDbtp };
343
+ export async function solveMixGain(options: {
344
+ ceilingDbtp: number;
345
+ startGainDb: number;
346
+ target: MixLoudnessTarget;
347
+ shift: number;
348
+ measure: (attempt: MixAttempt) => Promise<MixLoudness>;
349
+ }): Promise<{ best: MixTry; probes: MixTry[] }> {
350
+ const probes: MixTry[] = [];
351
+ let gainDb: number | null = options.startGainDb;
352
+ while (gainDb !== null && probes.length < MIX_GAIN_PROBES) {
353
+ const attempt = { gainDb, ceilingDbtp: options.ceilingDbtp };
354
+ probes.push({ attempt, measured: await options.measure(attempt) });
355
+ gainDb = getNextGainProbe(probes, options.target, options.shift);
356
+ }
357
+ return { best: getBestGainProbe(probes, options.target, options.shift), probes };
304
358
  }
305
359
 
306
360
  /**
307
361
  * The mix's last stage: one linear gain, then a lookahead limiter at 4x the film's rate (its delay compensated, so
308
- * the sound stays in sync with the picture; no auto level), back to the film's rate.
362
+ * the sound stays in sync with the picture; no auto level), back to the film's rate, then a low-pass at
363
+ * `MIX_LOWPASS_HZ` that keeps AAC's overshoot small.
309
364
  */
310
365
  export function getMixFilter(attempt: MixAttempt): string {
311
366
  const limit = roundTo(10 ** (attempt.ceilingDbtp / 20), 5);
312
- return [`volume=${attempt.gainDb}dB`, `aresample=${LIMITER_RATE}`, `alimiter=limit=${limit}:level=false:latency=true`, `aresample=${FOOTAGE_SAMPLE_RATE}`].join(",");
367
+ return [`volume=${attempt.gainDb}dB`, `aresample=${LIMITER_RATE}`, `alimiter=limit=${limit}:level=false:latency=true`, `aresample=${FOOTAGE_SAMPLE_RATE}`, `lowpass=f=${MIX_LOWPASS_HZ}`].join(",");
313
368
  }
314
369
 
315
- /** The mix's sound on its own through `filter`, encoded as the finished film carries it (AAC 192k, 48 kHz, stereo). */
370
+ /** The mix's sound on its own through `filter`, encoded as the finished film carries it (AAC 192k cut at `MIX_LOWPASS_HZ`, 48 kHz, stereo). */
316
371
  export function buildMixArgs(options: { input: string; filter: string; output: string }): string[] {
317
- return ["-v", "error", "-y", "-i", options.input, "-vn", "-map", "0:a:0", "-af", options.filter, "-c:a", "aac", "-b:a", FINISHED_AUDIO_BITRATE, "-ar", String(FOOTAGE_SAMPLE_RATE), "-ac", "2", options.output];
372
+ return [
373
+ "-v",
374
+ "error",
375
+ "-y",
376
+ "-i",
377
+ options.input,
378
+ "-vn",
379
+ "-map",
380
+ "0:a:0",
381
+ "-af",
382
+ options.filter,
383
+ "-c:a",
384
+ "aac",
385
+ "-b:a",
386
+ FINISHED_AUDIO_BITRATE,
387
+ "-cutoff",
388
+ String(MIX_LOWPASS_HZ),
389
+ "-ar",
390
+ String(FOOTAGE_SAMPLE_RATE),
391
+ "-ac",
392
+ "2",
393
+ options.output,
394
+ ];
395
+ }
396
+
397
+ /** How a measured mix stands against its target: inside it, a near miss inside `warnTolerance`, or outside. */
398
+ export type LoudnessVerdict = { kind: "pass" } | { kind: "warn"; warning: string } | { kind: "fail"; problems: string[] };
399
+
400
+ /**
401
+ * The verdict on a measured mix: `pass` inside `target ± tolerance` and at most `truePeak`; `warn` (a sentence with
402
+ * both values) when only the integrated loudness misses, by at most `warnTolerance`; else `fail` with the problems.
403
+ * The true peak limit has no near-miss band.
404
+ */
405
+ export function getLoudnessVerdict(measured: MixLoudness, target: MixLoudnessTarget): LoudnessVerdict {
406
+ const problems = findLoudnessProblems(measured, target);
407
+ if (problems.length === 0) return { kind: "pass" };
408
+ const band = target.warnTolerance;
409
+ if (band !== undefined && measured.truePeak <= target.truePeak && Math.abs(measured.integrated - target.target) <= band) {
410
+ const warning =
411
+ `the mix measures ${formatDb(measured.integrated)} LUFS integrated, ${formatDb(measured.truePeak)} dBTP true peak: ` +
412
+ `outside ${formatDb(target.target)} ± ${getMixTolerance(target)} LUFS, inside the ± ${band} LU near-miss band.`;
413
+ return { kind: "warn", warning };
414
+ }
415
+ return { kind: "fail", problems };
318
416
  }
319
417
 
320
418
  /** What keeps a measured mix outside the target, as sentences with both values; empty when it meets it. */