@softure-ai/marketing-kit 0.18.0 → 0.20.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 (48) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +27 -0
  3. package/dist/config/schema.d.ts +1 -0
  4. package/dist/config/schema.d.ts.map +1 -1
  5. package/dist/config/schema.js +1 -1
  6. package/dist/config/schema.js.map +1 -1
  7. package/dist/footage/clip-sound.d.ts +59 -4
  8. package/dist/footage/clip-sound.d.ts.map +1 -1
  9. package/dist/footage/clip-sound.js +58 -12
  10. package/dist/footage/clip-sound.js.map +1 -1
  11. package/dist/footage/declick.d.ts +35 -9
  12. package/dist/footage/declick.d.ts.map +1 -1
  13. package/dist/footage/declick.js +57 -88
  14. package/dist/footage/declick.js.map +1 -1
  15. package/dist/footage/film.d.ts +5 -2
  16. package/dist/footage/film.d.ts.map +1 -1
  17. package/dist/footage/film.js.map +1 -1
  18. package/dist/footage/isolate-ranges.d.ts +5 -0
  19. package/dist/footage/isolate-ranges.d.ts.map +1 -1
  20. package/dist/footage/isolate-ranges.js +4 -2
  21. package/dist/footage/isolate-ranges.js.map +1 -1
  22. package/dist/footage/mouth-clicks.d.ts +85 -0
  23. package/dist/footage/mouth-clicks.d.ts.map +1 -0
  24. package/dist/footage/mouth-clicks.js +207 -0
  25. package/dist/footage/mouth-clicks.js.map +1 -0
  26. package/dist/footage/pipeline.d.ts +11 -0
  27. package/dist/footage/pipeline.d.ts.map +1 -1
  28. package/dist/footage/pipeline.js +15 -9
  29. package/dist/footage/pipeline.js.map +1 -1
  30. package/dist/footage/sound-analysis.d.ts +25 -0
  31. package/dist/footage/sound-analysis.d.ts.map +1 -0
  32. package/dist/footage/sound-analysis.js +95 -0
  33. package/dist/footage/sound-analysis.js.map +1 -0
  34. package/dist/index.d.ts +3 -2
  35. package/dist/index.d.ts.map +1 -1
  36. package/dist/index.js +3 -2
  37. package/dist/index.js.map +1 -1
  38. package/package.json +1 -1
  39. package/schema/marketing.schema.json +3 -2
  40. package/src/config/schema.ts +1 -1
  41. package/src/footage/clip-sound.ts +95 -15
  42. package/src/footage/declick.ts +64 -97
  43. package/src/footage/film.ts +5 -2
  44. package/src/footage/isolate-ranges.ts +9 -3
  45. package/src/footage/mouth-clicks.ts +224 -0
  46. package/src/footage/pipeline.ts +29 -10
  47. package/src/footage/sound-analysis.ts +104 -0
  48. package/src/index.ts +9 -0
@@ -10,7 +10,8 @@ import type { FootageProbe } from "./probe.js";
10
10
  /**
11
11
  * Each clip's sound for the speech chain (issue #1139): read from the clip's source with the normalize step's own seek
12
12
  * and length (so the EDL's times hold), brought to 48 kHz stereo, raised by one linear pre-gain to about
13
- * `SPEECH_PRE_GAIN.target` with its true peak kept under `SPEECH_PRE_GAIN.peakCeiling`, and written as 24-bit PCM WAV.
13
+ * `SPEECH_PRE_GAIN.target` with its true peak kept under `SPEECH_PRE_GAIN.peakCeiling`, and written as 24-bit PCM WAV
14
+ * (or, with `speechPeaks: "float"`, raised to the target and written as 32-bit float, issue #1181).
14
15
  * Quiet phone speech is then never encoded lossily at its quiet level: the voice isolator, the speech to text, the cut,
15
16
  * the declick and the loudness pass all work on lossless sound, and the film's final AAC is the only lossy encode.
16
17
  */
@@ -31,10 +32,41 @@ export interface ClipSoundInput {
31
32
  duration: number;
32
33
  }
33
34
 
34
- /** A clip's lossless, pre-gained sound and the gain it got in dB. */
35
+ /**
36
+ * How the pre-gain treats a talking clip's true peak (issue #1181): `ceiling` (the default) stops the gain where the
37
+ * peak reaches `SPEECH_PRE_GAIN.peakCeiling` and writes 24-bit PCM; `float` raises it to the target whatever its peaks
38
+ * and writes 32-bit float PCM, so a peak above the ceiling (or 0 dBFS) cannot clip. Both are one linear gain.
39
+ */
40
+ export type SpeechPeaks = "ceiling" | "float";
41
+
42
+ /** A measured talking clip's pre-gain: the measurement before it and what it reached. */
43
+ export interface MeasuredPreGain {
44
+ /** Integrated loudness and true peak of the clip's sound before the pre-gain. */
45
+ inputLufs: number;
46
+ inputTruePeakDbtp: number;
47
+ /** Integrated loudness and true peak after it (the input plus the gain). */
48
+ reachedLufs: number;
49
+ truePeakDbtp: number;
50
+ }
51
+
52
+ /**
53
+ * What the pre-gain did to a clip (issue #1181): `on_target` reached `SPEECH_PRE_GAIN.target`; `held_by_peak_ceiling`
54
+ * stopped at the peak ceiling, under the target; `peaks_over_ceiling` reached the target with `speechPeaks: "float"`,
55
+ * its true peak above the ceiling (kept by the float file); `silent` a clip without sound, or silence (0 dB);
56
+ * `shared` a clip that does not talk, gained by the talking clips' mean and not measured.
57
+ */
58
+ export type SpeechPreGain =
59
+ | ({ kind: "on_target" } & MeasuredPreGain)
60
+ | ({ kind: "held_by_peak_ceiling" } & MeasuredPreGain)
61
+ | ({ kind: "peaks_over_ceiling" } & MeasuredPreGain)
62
+ | { kind: "silent" }
63
+ | { kind: "shared" };
64
+
65
+ /** A clip's lossless, pre-gained sound, the gain it got in dB and what the gain reached. */
35
66
  export interface ClipSound {
36
67
  file: string;
37
68
  gainDb: number;
69
+ preGain: SpeechPreGain;
38
70
  }
39
71
 
40
72
  const toFormat = `aformat=sample_rates=${String(FOOTAGE_SAMPLE_RATE)}:channel_layouts=stereo`;
@@ -56,15 +88,53 @@ export function buildClipSoundMeasureArgs(input: ClipSoundInput): string[] {
56
88
  * its true peak at `SPEECH_PRE_GAIN.peakCeiling`; 0 for silence. Rounded to a hundredth of a dB.
57
89
  */
58
90
  export function getPreGainDb(measurement: LoudnessMeasurement | null): number {
59
- if (measurement === null || isSilent(measurement)) return 0;
91
+ return getSpeechPreGain(measurement).gainDb;
92
+ }
93
+
94
+ /** Rounds to a hundredth, without a negative zero. */
95
+ function roundDb(value: number): number {
96
+ return Math.round(value * 100) / 100 || 0;
97
+ }
98
+
99
+ /**
100
+ * A measured clip's pre-gain in dB and what it reaches (issue #1181). With `peaks: "ceiling"` (the default) the gain
101
+ * is `getPreGainDb`'s, and a clip whose true peak stops it under the target is `held_by_peak_ceiling`; with `"float"`
102
+ * the gain always goes to the target, and a clip whose true peak then passes the ceiling is `peaks_over_ceiling`.
103
+ */
104
+ export function getSpeechPreGain(measurement: LoudnessMeasurement | null, options: { peaks?: SpeechPeaks } = {}): { gainDb: number; preGain: SpeechPreGain } {
105
+ if (measurement === null || isSilent(measurement)) return { gainDb: 0, preGain: { kind: "silent" } };
60
106
  const toTarget = SPEECH_PRE_GAIN.target - measurement.inputI;
61
107
  const toCeiling = Number.isFinite(measurement.inputTp) ? SPEECH_PRE_GAIN.peakCeiling - measurement.inputTp : toTarget;
62
- return Math.round(Math.min(toTarget, toCeiling) * 100) / 100 || 0;
108
+ const isHeld = toCeiling < toTarget;
109
+ const gainDb = roundDb(options.peaks === "float" ? toTarget : Math.min(toTarget, toCeiling));
110
+ const measured: MeasuredPreGain = {
111
+ inputLufs: roundDb(measurement.inputI),
112
+ inputTruePeakDbtp: roundDb(measurement.inputTp),
113
+ reachedLufs: roundDb(measurement.inputI + gainDb),
114
+ truePeakDbtp: roundDb(measurement.inputTp + gainDb),
115
+ };
116
+ if (!isHeld) return { gainDb, preGain: { kind: "on_target", ...measured } };
117
+ return { gainDb, preGain: { kind: options.peaks === "float" ? "peaks_over_ceiling" : "held_by_peak_ceiling", ...measured } };
63
118
  }
64
119
 
65
- /** The trimmed clip's sound, gained by `gainDb`, as a 24-bit 48 kHz stereo WAV; silence as long as the clip when it has none. */
66
- export function buildClipSoundArgs(input: ClipSoundInput & { gainDb: number; output: string }): string[] {
67
- const codec = ["-ar", String(FOOTAGE_SAMPLE_RATE), "-ac", "2", "-c:a", "pcm_s24le", input.output];
120
+ /** The log line for a clip whose pre-gain did not simply reach the target; null when it did, or for silence. */
121
+ export function describeSpeechPreGain(clipId: string, sound: Pick<ClipSound, "gainDb" | "preGain">): string | null {
122
+ const { preGain } = sound;
123
+ if (preGain.kind !== "held_by_peak_ceiling" && preGain.kind !== "peaks_over_ceiling") return null;
124
+ const gain = `${sound.gainDb >= 0 ? "+" : ""}${String(sound.gainDb)} dB`;
125
+ const input = `input ${String(preGain.inputLufs)} LUFS, ${String(preGain.inputTruePeakDbtp)} dBTP`;
126
+ if (preGain.kind === "peaks_over_ceiling") {
127
+ return `speech pre-gain: clip ${clipId} raised by ${gain} to ${String(preGain.reachedLufs)} LUFS (${input}); its true peak ${String(preGain.truePeakDbtp)} dBTP is over the ${String(SPEECH_PRE_GAIN.peakCeiling)} dBTP ceiling, kept by the 32-bit float sound.`;
128
+ }
129
+ return `speech pre-gain: clip ${clipId} held by the ${String(SPEECH_PRE_GAIN.peakCeiling)} dBTP peak ceiling at ${gain}: it reaches ${String(preGain.reachedLufs)} LUFS, not ${String(SPEECH_PRE_GAIN.target)} (${input}). speechPeaks: "float" reaches the target without clipping.`;
130
+ }
131
+
132
+ /**
133
+ * The trimmed clip's sound, gained by `gainDb`, as a 48 kHz stereo WAV (24-bit PCM, or 32-bit float with
134
+ * `peaks: "float"`); silence as long as the clip when it has none.
135
+ */
136
+ export function buildClipSoundArgs(input: ClipSoundInput & { gainDb: number; output: string; peaks?: SpeechPeaks }): string[] {
137
+ const codec = ["-ar", String(FOOTAGE_SAMPLE_RATE), "-ac", "2", "-c:a", input.peaks === "float" ? "pcm_f32le" : "pcm_s24le", input.output];
68
138
  const { seek, length } = getTrimArgs(input);
69
139
  if (!input.probe.hasAudio) return ["-v", "error", "-y", "-f", "lavfi", "-i", `anullsrc=r=${String(FOOTAGE_SAMPLE_RATE)}:cl=stereo`, ...length, ...codec];
70
140
  return ["-v", "error", "-y", ...seek, "-i", input.source, ...length, "-map", "0:a:0", "-vn", "-af", `${toFormat},volume=${String(input.gainDb)}dB`, ...codec];
@@ -90,24 +160,34 @@ async function measureClipSound(input: ClipSoundInput, signal: AbortSignal | und
90
160
  /**
91
161
  * Every clip's lossless, pre-gained sound under `<buildDir>/audio/<id>.wav`, by clip id. A talking clip is gained by its
92
162
  * own measurement (`getPreGainDb`); any other clip by the mean of the talking clips' gains (0 dB without one), so a
93
- * b-roll's own sound under the speech keeps its relation to it. Throws naming the clip when ffmpeg fails.
163
+ * b-roll's own sound under the speech keeps its relation to it. Each answers its `preGain` (issue #1181), and `log` gets
164
+ * a line for every clip the peak ceiling held under the target (or, with `peaks: "float"`, whose peaks pass it).
165
+ * Throws naming the clip when ffmpeg fails.
94
166
  */
95
- export async function prepareClipSounds(clips: readonly ClipSoundInput[], options: { buildDir: string; signal?: AbortSignal }): Promise<Record<string, ClipSound>> {
167
+ export async function prepareClipSounds(
168
+ clips: readonly ClipSoundInput[],
169
+ options: { buildDir: string; signal?: AbortSignal; peaks?: SpeechPeaks; log?: (line: string) => void },
170
+ ): Promise<Record<string, ClipSound>> {
96
171
  const { signal } = options;
97
- const gains = new Map<string, number>();
172
+ const peaks = options.peaks ?? "ceiling";
173
+ const measured = new Map<string, { gainDb: number; preGain: SpeechPreGain }>();
98
174
  for (const clip of clips) {
99
175
  if (clip.clip.role !== "talk") continue;
100
- gains.set(clip.clip.id, getPreGainDb(await measureClipSound(clip, signal)));
176
+ measured.set(clip.clip.id, getSpeechPreGain(await measureClipSound(clip, signal), { peaks }));
101
177
  }
102
- const talking = [...gains.values()];
178
+ const talking = [...measured.values()].map((entry) => entry.gainDb);
103
179
  const sharedGain = talking.length === 0 ? 0 : Math.round((talking.reduce((sum, gain) => sum + gain, 0) / talking.length) * 100) / 100 || 0;
104
180
  const sounds: Record<string, ClipSound> = {};
105
181
  for (const clip of clips) {
106
- const gainDb = gains.get(clip.clip.id) ?? sharedGain;
182
+ const shared: { gainDb: number; preGain: SpeechPreGain } = { gainDb: sharedGain, preGain: { kind: "shared" } };
183
+ const { gainDb, preGain } = measured.get(clip.clip.id) ?? shared;
107
184
  const output = getClipSoundPath(options.buildDir, clip.clip.id);
108
185
  mkdirSync(dirname(output), { recursive: true });
109
- await runFfmpeg(`Extracting the sound of clip ${clip.clip.id}`, buildClipSoundArgs({ ...clip, gainDb, output }), { ...(signal === undefined ? {} : { signal }), output });
110
- sounds[clip.clip.id] = { file: output, gainDb };
186
+ await runFfmpeg(`Extracting the sound of clip ${clip.clip.id}`, buildClipSoundArgs({ ...clip, gainDb, output, peaks }), { ...(signal === undefined ? {} : { signal }), output });
187
+ const sound: ClipSound = { file: output, gainDb, preGain };
188
+ sounds[clip.clip.id] = sound;
189
+ const line = describeSpeechPreGain(clip.clip.id, sound);
190
+ if (line !== null) options.log?.(line);
111
191
  }
112
192
  return sounds;
113
193
  }
@@ -2,8 +2,12 @@ import { readFileSync, rmSync, writeFileSync } from "node:fs";
2
2
 
3
3
  import type { TimedWord } from "../voice/voiceover.js";
4
4
  import { getAudioCodecArgs } from "./clip-sound.js";
5
+ import { MOUTH_CLICK_RULES, analyzeMouthClicks } from "./mouth-clicks.js";
5
6
  import { FOOTAGE_SAMPLE_RATE } from "./normalize.js";
6
7
  import { runFfmpeg } from "./process.js";
8
+ import { getBand, getFrameEnergies, getRunningMedian, type TimeSpan } from "./sound-analysis.js";
9
+
10
+ export { getRunningMedian, type TimeSpan };
7
11
 
8
12
  /**
9
13
  * The speech track's declick stage (issues #1084, #1170), between the cut speech track and its loudness normalization:
@@ -17,22 +21,30 @@ import { runFfmpeg } from "./process.js";
17
21
  * samples are replaced by AR (LPC) interpolation from the sound on both sides, joined with a raised-cosine crossfade
18
22
  * of `DECLICK_CROSSFADE` on each side. Every other sample leaves the stage as it came in.
19
23
  *
24
+ * The `repair` level (issue #1183) uses the mouth-click detector shared with moving a cut (`MOUTH_CLICK_RULES`,
25
+ * issue #1182) instead: impulses of 1 to 25 ms, outside the speech protection zone (word bounds on the real sound
26
+ * ±80 ms, nothing above -45 dBFS), only in pauses at least 150 ms long after the guard, and within the limits of
27
+ * `DECLICK_REPAIR_RULES` (the impulses over a limit are left and counted).
28
+ *
20
29
  * Without words the stage repairs nothing: it cannot tell a click from a consonant.
21
30
  */
22
31
 
23
- export const DECLICK_LEVELS = ["off", "gentle", "strong"] as const;
32
+ export const DECLICK_LEVELS = ["off", "gentle", "strong", "repair"] as const;
24
33
 
25
34
  export type DeclickLevel = (typeof DECLICK_LEVELS)[number];
26
35
 
27
36
  /** A level that runs the stage. */
28
37
  export type ActiveDeclickLevel = Exclude<DeclickLevel, "off">;
29
38
 
39
+ /** A level that runs the 0.18.0 detector (`findImpulses`, `DECLICK_SETTINGS`). */
40
+ export type DetectorDeclickLevel = Exclude<ActiveDeclickLevel, "repair">;
41
+
30
42
  export interface DeclickSettings {
31
43
  /** How far a frame's 2-8 kHz energy must rise above the band's running median to count as an impulse, in dB. */
32
44
  jumpDb: number;
33
45
  }
34
46
 
35
- export const DECLICK_SETTINGS: Record<ActiveDeclickLevel, DeclickSettings> = {
47
+ export const DECLICK_SETTINGS: Record<DetectorDeclickLevel, DeclickSettings> = {
36
48
  gentle: { jumpDb: 15 },
37
49
  strong: { jumpDb: 9 },
38
50
  };
@@ -43,6 +55,17 @@ export const DECLICK_WORD_GUARD = 0.08;
43
55
  export const DECLICK_MAX_IMPULSE = 0.012;
44
56
  /** The raised-cosine crossfade between the original and the interpolation on each side of a repair. */
45
57
  export const DECLICK_CROSSFADE = 0.003;
58
+ /** The `repair` level's rules (issue #1183); its impulses are `MOUTH_CLICK_RULES`'. */
59
+ export const DECLICK_REPAIR_RULES = {
60
+ /** The shortest pause that holds a repair once the word guard is taken off both sides, seconds. */
61
+ minPauseSeconds: 0.15,
62
+ /** The longest repair, its crossfades included, seconds. */
63
+ maxRepairSeconds: 0.025,
64
+ /** The most repairs in any one second. */
65
+ maxPerSecond: 3,
66
+ /** The share of the track's length all repairs (crossfades included) may take. */
67
+ maxShare: 0.01,
68
+ } as const;
46
69
  /** The AR model's order. */
47
70
  export const DECLICK_AR_ORDER = 24;
48
71
  /** Seconds of sound on each side of a repair the AR model is fitted on. */
@@ -61,11 +84,6 @@ const BAND_FLOOR_DB = -90;
61
84
  /** Added to Burg's denominator, so a silent context gives a zero model instead of a division by zero. */
62
85
  const AR_RIDGE = 1e-9;
63
86
 
64
- export interface TimeSpan {
65
- start: number;
66
- end: number;
67
- }
68
-
69
87
  /** What the stage did, in the render's and the draft's ok value. */
70
88
  export interface DeclickReport {
71
89
  level: ActiveDeclickLevel;
@@ -73,6 +91,8 @@ export interface DeclickReport {
73
91
  impulses: number;
74
92
  /** Each repaired impulse in the speech track's time, seconds (without its crossfades). */
75
93
  repairs: TimeSpan[];
94
+ /** Impulses the `repair` level left because a limit of `DECLICK_REPAIR_RULES` was reached; 0 for the other levels. */
95
+ skippedLimit: number;
76
96
  }
77
97
 
78
98
  const sortSpans = (words: readonly TimeSpan[]): TimeSpan[] => [...words].filter((word) => word.end > word.start).sort((a, b) => a.start - b.start);
@@ -99,91 +119,6 @@ export function getRepairZones(words: readonly TimeSpan[], seconds: number): Tim
99
119
  return zones;
100
120
  }
101
121
 
102
- /** One second-order section (RBJ cookbook), run in place over the samples. */
103
- function runBiquad(samples: Float64Array, kind: "highpass" | "lowpass", frequency: number, sampleRate: number): void {
104
- const w0 = (2 * Math.PI * Math.min(frequency, sampleRate * 0.45)) / sampleRate;
105
- const cos = Math.cos(w0);
106
- const alpha = Math.sin(w0) / (2 * Math.SQRT1_2);
107
- const a0 = 1 + alpha;
108
- const b0 = (kind === "lowpass" ? (1 - cos) / 2 : (1 + cos) / 2) / a0;
109
- const b1 = (kind === "lowpass" ? 1 - cos : -(1 + cos)) / a0;
110
- const b2 = b0;
111
- const a1 = (-2 * cos) / a0;
112
- const a2 = (1 - alpha) / a0;
113
- let x1 = 0;
114
- let x2 = 0;
115
- let y1 = 0;
116
- let y2 = 0;
117
- for (let index = 0; index < samples.length; index++) {
118
- const x = samples[index] ?? 0;
119
- const y = b0 * x + b1 * x1 + b2 * x2 - a1 * y1 - a2 * y2;
120
- x2 = x1;
121
- x1 = x;
122
- y2 = y1;
123
- y1 = y;
124
- samples[index] = y;
125
- }
126
- }
127
-
128
- /** The 2-8 kHz band of the signal: two high-pass and two low-pass sections (fourth order on each side). */
129
- function getBand(mono: Float32Array, sampleRate: number): Float64Array {
130
- const band = Float64Array.from(mono);
131
- runBiquad(band, "highpass", BAND_LOW_HZ, sampleRate);
132
- runBiquad(band, "highpass", BAND_LOW_HZ, sampleRate);
133
- runBiquad(band, "lowpass", BAND_HIGH_HZ, sampleRate);
134
- runBiquad(band, "lowpass", BAND_HIGH_HZ, sampleRate);
135
- return band;
136
- }
137
-
138
- /** Each frame's mean square in dB, frames of `frameLength` samples every `hop` samples. */
139
- function getFrameEnergies(band: Float64Array, frameLength: number, hop: number): Float64Array {
140
- const sums = new Float64Array(band.length + 1);
141
- for (let index = 0; index < band.length; index++) {
142
- const value = band[index] ?? 0;
143
- sums[index + 1] = (sums[index] ?? 0) + value * value;
144
- }
145
- const count = band.length < frameLength ? 0 : Math.floor((band.length - frameLength) / hop) + 1;
146
- const energies = new Float64Array(count);
147
- for (let frame = 0; frame < count; frame++) {
148
- const from = frame * hop;
149
- const power = ((sums[from + frameLength] ?? 0) - (sums[from] ?? 0)) / frameLength;
150
- energies[frame] = 10 * Math.log10(Math.max(power, 1e-20));
151
- }
152
- return energies;
153
- }
154
-
155
- /** The index of the first entry of the sorted list not below `value`. */
156
- function findInsertIndex(sorted: number[], value: number): number {
157
- let low = 0;
158
- let high = sorted.length;
159
- while (low < high) {
160
- const middle = (low + high) >> 1;
161
- if ((sorted[middle] ?? 0) < value) low = middle + 1;
162
- else high = middle;
163
- }
164
- return low;
165
- }
166
-
167
- /** The running median of the values over `reach` entries on each side (fewer at the ends). */
168
- export function getRunningMedian(values: Float64Array, reach: number): Float64Array {
169
- const medians = new Float64Array(values.length);
170
- const window: number[] = [];
171
- let from = 0;
172
- let to = 0;
173
- for (let index = 0; index < values.length; index++) {
174
- const wantedTo = Math.min(values.length, index + reach + 1);
175
- for (; to < wantedTo; to++) {
176
- const value = values[to] ?? 0;
177
- window.splice(findInsertIndex(window, value), 0, value);
178
- }
179
- const wantedFrom = Math.max(0, index - reach);
180
- for (; from < wantedFrom; from++) window.splice(findInsertIndex(window, values[from] ?? 0), 1);
181
- const middle = window.length >> 1;
182
- medians[index] = window.length % 2 === 1 ? (window[middle] ?? 0) : ((window[middle - 1] ?? 0) + (window[middle] ?? 0)) / 2;
183
- }
184
- return medians;
185
- }
186
-
187
122
  /** True when the impulse with its crossfades lies inside one zone. */
188
123
  const isRepairable = (span: TimeSpan, zones: readonly TimeSpan[]): boolean =>
189
124
  zones.some((zone) => span.start - DECLICK_CROSSFADE >= zone.start && span.end + DECLICK_CROSSFADE <= zone.end);
@@ -193,14 +128,14 @@ const isRepairable = (span: TimeSpan, zones: readonly TimeSpan[]): boolean =>
193
128
  * the level's `jumpDb` above the band's running median (±100 ms), shorter than `DECLICK_MAX_IMPULSE`, that lie with
194
129
  * their crossfades inside a repair zone (`getRepairZones`). Times in seconds, widened by a millisecond on each side.
195
130
  */
196
- export function findImpulses(mono: Float32Array, sampleRate: number, words: readonly TimeSpan[], level: ActiveDeclickLevel): TimeSpan[] {
131
+ export function findImpulses(mono: Float32Array, sampleRate: number, words: readonly TimeSpan[], level: DetectorDeclickLevel): TimeSpan[] {
197
132
  const seconds = mono.length / sampleRate;
198
133
  const zones = getRepairZones(words, seconds);
199
134
  if (zones.length === 0) return [];
200
135
  const { jumpDb } = DECLICK_SETTINGS[level];
201
136
  const frameLength = Math.max(1, Math.round(FRAME_SECONDS * sampleRate));
202
137
  const hop = Math.max(1, Math.round(HOP_SECONDS * sampleRate));
203
- const energies = getFrameEnergies(getBand(mono, sampleRate), frameLength, hop);
138
+ const energies = getFrameEnergies(getBand({ mono, sampleRate, lowHz: BAND_LOW_HZ, highHz: BAND_HIGH_HZ }), frameLength, hop);
204
139
  const medians = getRunningMedian(energies, Math.round(MEDIAN_SECONDS / HOP_SECONDS));
205
140
  const impulses: TimeSpan[] = [];
206
141
  let runStart = -1;
@@ -222,6 +157,35 @@ export function findImpulses(mono: Float32Array, sampleRate: number, words: read
222
157
  return impulses;
223
158
  }
224
159
 
160
+ /**
161
+ * The impulses the `repair` level repairs (issue #1183): `MOUTH_CLICK_RULES` impulses whose repair (with its
162
+ * crossfades) lies inside a pause at least `minPauseSeconds` long between the words' bounds on the real sound after
163
+ * the guard, outside the speech protection zone, taken in time order while the limits allow; the others in such a
164
+ * pause are counted as `skippedLimit`.
165
+ */
166
+ export function findRepairs(mono: Float32Array, sampleRate: number, words: readonly TimeSpan[]): { repairs: TimeSpan[]; skippedLimit: number } {
167
+ const seconds = mono.length / sampleRate;
168
+ const analysis = analyzeMouthClicks(mono, sampleRate, words);
169
+ const zones = getRepairZones(analysis.bounds, seconds).filter((zone) => zone.end - zone.start >= DECLICK_REPAIR_RULES.minPauseSeconds);
170
+ const budget = DECLICK_REPAIR_RULES.maxShare * seconds;
171
+ const repairs: TimeSpan[] = [];
172
+ let used = 0;
173
+ let skippedLimit = 0;
174
+ for (const candidate of analysis.candidates) {
175
+ const span = { start: candidate.start - DECLICK_CROSSFADE, end: candidate.end + DECLICK_CROSSFADE };
176
+ if (!zones.some((zone) => span.start >= zone.start && span.end <= zone.end) || analysis.isProtected(span)) continue;
177
+ const length = span.end - span.start;
178
+ const inLastSecond = repairs.filter((repair) => repair.start > candidate.start - 1).length;
179
+ if (length > DECLICK_REPAIR_RULES.maxRepairSeconds || inLastSecond >= DECLICK_REPAIR_RULES.maxPerSecond || used + length > budget) {
180
+ skippedLimit++;
181
+ continue;
182
+ }
183
+ repairs.push(candidate);
184
+ used += length;
185
+ }
186
+ return { repairs, skippedLimit };
187
+ }
188
+
225
189
  /**
226
190
  * The AR polynomial of the context segments (Burg's method over all of them at once): `a[0] = 1` and
227
191
  * `Σ a[k]·x[n-k] ≈ 0`. Fewer coefficients when the segments are short; a silent context gives all zeros after `a[0]`.
@@ -340,7 +304,8 @@ export function declickSamples(options: { samples: Float32Array; channels: numbe
340
304
  for (let channel = 0; channel < channels; channel++) sum += samples[index * channels + channel] ?? 0;
341
305
  mono[index] = sum / channels;
342
306
  }
343
- const impulses = findImpulses(mono, sampleRate, words, level);
307
+ const found = level === "repair" ? findRepairs(mono, sampleRate, words) : { repairs: findImpulses(mono, sampleRate, words, level), skippedLimit: 0 };
308
+ const impulses = found.repairs;
344
309
  const output = Float32Array.from(samples);
345
310
  const crossfade = Math.round(DECLICK_CROSSFADE * sampleRate);
346
311
  const context = Math.round(DECLICK_AR_CONTEXT * sampleRate);
@@ -354,7 +319,7 @@ export function declickSamples(options: { samples: Float32Array; channels: numbe
354
319
  for (let index = Math.max(0, from); index < Math.min(length, to); index++) output[index * channels + channel] = track[index] ?? 0;
355
320
  }
356
321
  }
357
- return { samples: output, impulses, report: { level, impulses: impulses.length, repairs: impulses.map((impulse) => ({ ...impulse })) } };
322
+ return { samples: output, impulses, report: { level, impulses: impulses.length, repairs: impulses.map((impulse) => ({ ...impulse })), skippedLimit: found.skippedLimit } };
358
323
  }
359
324
 
360
325
  const CHANNELS = 2;
@@ -423,5 +388,7 @@ export function describeDeclick(report: DeclickReport): string {
423
388
  const times = report.repairs.slice(0, LOGGED_REPAIRS).map((repair) => `${repair.start.toFixed(3)} s`);
424
389
  const more = report.repairs.length > LOGGED_REPAIRS ? `, +${String(report.repairs.length - LOGGED_REPAIRS)} more` : "";
425
390
  const where = times.length === 0 ? "" : ` at ${times.join(", ")}${more}`;
426
- return `declick (${report.level}): ${String(report.impulses)} impulse${report.impulses === 1 ? "" : "s"} repaired${where}; no gain change, nothing within ${String(DECLICK_WORD_GUARD * 1000)} ms of a word touched.`;
391
+ const count = `${String(report.impulses)} impulse${report.impulses === 1 ? "" : "s"} repaired${where}`;
392
+ if (report.level !== "repair") return `declick (${report.level}): ${count}; no gain change, nothing within ${String(DECLICK_WORD_GUARD * 1000)} ms of a word touched.`;
393
+ return `declick (repair): ${count}, ${String(report.skippedLimit)} left over the limits; no gain change, nothing within ${String(DECLICK_WORD_GUARD * 1000)} ms of a word's sound or above ${String(MOUTH_CLICK_RULES.loudDbfs)} dBFS touched.`;
427
394
  }
@@ -216,8 +216,11 @@ export function getEndCardTexts(card: FootageEndCard | null): { headline: string
216
216
  /** Settings of the speech track itself. */
217
217
  export interface FootageSpeech {
218
218
  /**
219
- * Mouth clicks and lip smacks between words (issue #1084): `gentle` lowers the pauses by 15 dB and removes impulses
220
- * that jump 15 dB above the band's median, `strong` by 20 dB and 9 dB. Absent or `off`: no pass, the track unchanged.
219
+ * Mouth clicks and lip smacks between words (issues #1084, #1170, #1183): each single impulse in a pause is repaired
220
+ * by AR interpolation and no gain changes. `gentle` and `strong` repair impulses that jump 15 or 9 dB above the band's
221
+ * median, nothing within 80 ms of a transcript word; `repair` uses the shared mouth-click rules (`MOUTH_CLICK_RULES`):
222
+ * word bounds on the real sound, nothing above -45 dBFS, pauses of 150 ms or more, at most 3 repairs a second and
223
+ * 1 % of the track. Absent or `off`: no pass, the track unchanged.
221
224
  */
222
225
  declick?: DeclickLevel;
223
226
  }
@@ -5,7 +5,7 @@ import { setTimeout as sleep } from "node:timers/promises";
5
5
  import { describeProviderFailure, type ProviderFailure } from "../voice/provider-failure.js";
6
6
  import { err, ok } from "./failure.js";
7
7
  import { probeAudio } from "./audio.js";
8
- import { prepareClipSounds, type ClipSound } from "./clip-sound.js";
8
+ import { prepareClipSounds, type ClipSound, type SpeechPeaks, type SpeechPreGain } from "./clip-sound.js";
9
9
  import { isSilent, readLoudnessMeasurement } from "./loudness.js";
10
10
  import { writeCacheFile } from "./cache.js";
11
11
  import type { Edl } from "./edl.js";
@@ -81,6 +81,8 @@ export type IsolateSpeechRangesOptions = Pick<FootageRunOptions, "buildDir" | "c
81
81
  * An app that already holds paid ranges under its own keys points the block at them.
82
82
  */
83
83
  rangeCache?: SpeechRangeCacheResolver;
84
+ /** How the clip sound's pre-gain treats a true peak above the ceiling (`SpeechPeaks`, issue #1181); default `ceiling`. */
85
+ speechPeaks?: SpeechPeaks;
84
86
  log?: (line: string) => void;
85
87
  };
86
88
 
@@ -124,6 +126,8 @@ export interface IsolatedSpeech {
124
126
  speech: Record<string, string>;
125
127
  /** Each clip's pre-gain in dB (`prepareClipSounds`): the gain of the sound its speech file is made from (issue #1159). */
126
128
  speechGainDb: Record<string, number>;
129
+ /** What each clip's pre-gain reached (`ClipSound.preGain`, issue #1181): on target, or held by the peak ceiling. */
130
+ speechPreGain: Record<string, SpeechPreGain>;
127
131
  ranges: IsolatedSpeechRange[];
128
132
  }
129
133
 
@@ -188,7 +192,7 @@ async function runIsolateSpeechRanges(
188
192
  options.onProgress?.({ step: "isolate", item: range.clip, itemIndex: index + 1, itemCount: buying.length, done: Math.round(done * 1000) / 1000, total: Math.round(total * 1000) / 1000 });
189
193
  };
190
194
  // Every clip's sound, lossless and pre-gained (#1139): what the isolator hears and what the cleaned ranges are laid over.
191
- const sounds = await prepareClipSounds(clips, { buildDir, ...aborting });
195
+ const sounds = await prepareClipSounds(clips, { buildDir, log, ...aborting, ...(options.speechPeaks === undefined ? {} : { peaks: options.speechPeaks }) });
192
196
  const getSound = (clip: PreparedClip): string => sounds[clip.clip.id]?.file ?? clip.file;
193
197
  const workDir = join(buildDir, "audio", "ranges");
194
198
  for (const [index, range] of buying.entries()) {
@@ -247,11 +251,13 @@ async function runIsolateSpeechRanges(
247
251
  }
248
252
  const speech: Record<string, string> = {};
249
253
  const speechGainDb: Record<string, number> = {};
254
+ const speechPreGain: Record<string, SpeechPreGain> = {};
250
255
  for (const clip of clips) {
251
256
  const id = clip.clip.id;
252
257
  speech[id] = getSound(clip);
253
258
  const clipGainDb = sounds[id]?.gainDb ?? 0;
254
259
  speechGainDb[id] = clipGainDb;
260
+ speechPreGain[id] = sounds[id]?.preGain ?? { kind: "silent" };
255
261
  const laidRanges = ranges.filter((range) => range.clip === id && range.laid);
256
262
  if (laidRanges.length === 0) continue;
257
263
  const laid: LaidRange[] = [];
@@ -272,7 +278,7 @@ async function runIsolateSpeechRanges(
272
278
  await runFfmpeg(`Laying the cleaned voice over clip ${id}`, buildRangeLayArgs(getSound(clip), laid, output, { fadeMs: options.fadeMs ?? DEFAULT_SPEECH_RANGE_FADE_MS }), { ...aborting, output });
273
279
  speech[id] = output;
274
280
  }
275
- return ok({ speech, speechGainDb, ranges });
281
+ return ok({ speech, speechGainDb, speechPreGain, ranges });
276
282
  }
277
283
 
278
284
  /**