@softure-ai/marketing-kit 0.17.0 → 0.18.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 (74) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/README.md +45 -11
  3. package/dist/config/actions-schema.d.ts +14 -14
  4. package/dist/config/config.d.ts.map +1 -1
  5. package/dist/config/config.js +11 -1
  6. package/dist/config/config.js.map +1 -1
  7. package/dist/config/schema.d.ts +78 -70
  8. package/dist/config/schema.d.ts.map +1 -1
  9. package/dist/config/schema.js +25 -8
  10. package/dist/config/schema.js.map +1 -1
  11. package/dist/config/shot-steps.d.ts +16 -16
  12. package/dist/footage/compose.d.ts +17 -3
  13. package/dist/footage/compose.d.ts.map +1 -1
  14. package/dist/footage/compose.js +61 -17
  15. package/dist/footage/compose.js.map +1 -1
  16. package/dist/footage/declick.d.ts +49 -41
  17. package/dist/footage/declick.d.ts.map +1 -1
  18. package/dist/footage/declick.js +181 -92
  19. package/dist/footage/declick.js.map +1 -1
  20. package/dist/footage/film.d.ts +45 -2
  21. package/dist/footage/film.d.ts.map +1 -1
  22. package/dist/footage/film.js +23 -0
  23. package/dist/footage/film.js.map +1 -1
  24. package/dist/footage/paid.d.ts +1 -1
  25. package/dist/footage/paid.d.ts.map +1 -1
  26. package/dist/footage/paid.js +3 -2
  27. package/dist/footage/paid.js.map +1 -1
  28. package/dist/footage/pipeline.d.ts.map +1 -1
  29. package/dist/footage/pipeline.js +13 -8
  30. package/dist/footage/pipeline.js.map +1 -1
  31. package/dist/footage/render.d.ts +5 -1
  32. package/dist/footage/render.d.ts.map +1 -1
  33. package/dist/footage/render.js +6 -2
  34. package/dist/footage/render.js.map +1 -1
  35. package/dist/index.d.ts +4 -4
  36. package/dist/index.d.ts.map +1 -1
  37. package/dist/index.js +4 -4
  38. package/dist/index.js.map +1 -1
  39. package/dist/og/character-map.d.ts +2 -1
  40. package/dist/og/character-map.d.ts.map +1 -1
  41. package/dist/og/character-map.js +7 -63
  42. package/dist/og/character-map.js.map +1 -1
  43. package/dist/og/font-file.d.ts +53 -0
  44. package/dist/og/font-file.d.ts.map +1 -0
  45. package/dist/og/font-file.js +153 -0
  46. package/dist/og/font-file.js.map +1 -0
  47. package/dist/og/font-tables.d.ts +25 -0
  48. package/dist/og/font-tables.d.ts.map +1 -0
  49. package/dist/og/font-tables.js +212 -0
  50. package/dist/og/font-tables.js.map +1 -0
  51. package/dist/og/index.d.ts +3 -1
  52. package/dist/og/index.d.ts.map +1 -1
  53. package/dist/og/index.js +2 -1
  54. package/dist/og/index.js.map +1 -1
  55. package/dist/og/photo-cover.d.ts +22 -0
  56. package/dist/og/photo-cover.d.ts.map +1 -1
  57. package/dist/og/photo-cover.js +27 -9
  58. package/dist/og/photo-cover.js.map +1 -1
  59. package/package.json +1 -1
  60. package/schema/marketing.schema.json +76 -23
  61. package/src/config/config.ts +10 -2
  62. package/src/config/schema.ts +24 -5
  63. package/src/footage/compose.ts +72 -17
  64. package/src/footage/declick.ts +172 -97
  65. package/src/footage/film.ts +54 -2
  66. package/src/footage/paid.ts +3 -3
  67. package/src/footage/pipeline.ts +12 -7
  68. package/src/footage/render.ts +7 -3
  69. package/src/index.ts +26 -5
  70. package/src/og/character-map.ts +8 -61
  71. package/src/og/font-file.ts +172 -0
  72. package/src/og/font-tables.ts +221 -0
  73. package/src/og/index.ts +14 -0
  74. package/src/og/photo-cover.ts +46 -11
@@ -6,17 +6,18 @@ import { FOOTAGE_SAMPLE_RATE } from "./normalize.js";
6
6
  import { runFfmpeg } from "./process.js";
7
7
 
8
8
  /**
9
- * The speech track's declick stage (issue #1084), between the cut speech track and its loudness normalization: mouth
10
- * clicks and lip smacks between words are short broadband bursts well below the speech peaks, which ffmpeg's
11
- * `adeclick` does not see. Two steps over the cut speech, both from the words' film times:
9
+ * The speech track's declick stage (issues #1084, #1170), between the cut speech track and its loudness normalization:
10
+ * mouth clicks and lip smacks in the pauses are short broadband bursts well below the speech peaks, which ffmpeg's
11
+ * `adeclick` does not see. The stage repairs single impulses and changes no gain:
12
12
  *
13
- * - a gate: outside each word's window (start and end ± 40 ms) the speech is lowered, with a 20 ms linear fade that
14
- * sits outside the window, so no word onset or tail is touched;
15
- * - impulse removal: outside the words' own spans, bursts under 30 ms that jump above the 2-8 kHz band's running median
16
- * are lowered by 30 dB with a short crossfade on both sides.
13
+ * - it touches nothing within ±80 ms of a transcript word (`DECLICK_WORD_GUARD`): the speech-to-text boundaries are 20
14
+ * to 60 ms off the real sound, so a gate on them lowered decays and onsets and was heard as hoarseness and pumping
15
+ * (#1170). Only the pauses beyond that guard are searched, so a pause must be longer than 160 ms to hold a repair;
16
+ * - an impulse is a burst under `DECLICK_MAX_IMPULSE` whose 2-8 kHz energy jumps above the band's running median; its
17
+ * samples are replaced by AR (LPC) interpolation from the sound on both sides, joined with a raised-cosine crossfade
18
+ * of `DECLICK_CROSSFADE` on each side. Every other sample leaves the stage as it came in.
17
19
  *
18
- * The gain is applied per sample to the decoded PCM (a `volume` expression is evaluated only once per audio frame,
19
- * about 21 ms, coarser than the crossfades).
20
+ * Without words the stage repairs nothing: it cannot tell a click from a consonant.
20
21
  */
21
22
 
22
23
  export const DECLICK_LEVELS = ["off", "gentle", "strong"] as const;
@@ -27,27 +28,25 @@ export type DeclickLevel = (typeof DECLICK_LEVELS)[number];
27
28
  export type ActiveDeclickLevel = Exclude<DeclickLevel, "off">;
28
29
 
29
30
  export interface DeclickSettings {
30
- /** How far the speech is lowered outside the words' windows, in dB (negative). */
31
- gateDb: number;
32
31
  /** How far a frame's 2-8 kHz energy must rise above the band's running median to count as an impulse, in dB. */
33
32
  jumpDb: number;
34
- /** The crossfade on both sides of a lowered impulse, in seconds. */
35
- crossfadeSeconds: number;
36
33
  }
37
34
 
38
35
  export const DECLICK_SETTINGS: Record<ActiveDeclickLevel, DeclickSettings> = {
39
- gentle: { gateDb: -15, jumpDb: 15, crossfadeSeconds: 0.005 },
40
- strong: { gateDb: -20, jumpDb: 9, crossfadeSeconds: 0.008 },
36
+ gentle: { jumpDb: 15 },
37
+ strong: { jumpDb: 9 },
41
38
  };
42
39
 
43
- /** Seconds a word's window reaches past its start and end; the gate leaves the window untouched. */
44
- export const DECLICK_WORD_WINDOW = 0.04;
45
- /** The gate's fade, outside the window. */
46
- export const DECLICK_GATE_FADE = 0.02;
40
+ /** Seconds around each word's start and end that the stage never touches. */
41
+ export const DECLICK_WORD_GUARD = 0.08;
47
42
  /** The longest burst that counts as an impulse. */
48
- export const DECLICK_MAX_IMPULSE = 0.03;
49
- /** How far an impulse is lowered, in dB. */
50
- export const DECLICK_IMPULSE_DB = -30;
43
+ export const DECLICK_MAX_IMPULSE = 0.012;
44
+ /** The raised-cosine crossfade between the original and the interpolation on each side of a repair. */
45
+ export const DECLICK_CROSSFADE = 0.003;
46
+ /** The AR model's order. */
47
+ export const DECLICK_AR_ORDER = 24;
48
+ /** Seconds of sound on each side of a repair the AR model is fitted on. */
49
+ export const DECLICK_AR_CONTEXT = 0.01;
51
50
 
52
51
  const BAND_LOW_HZ = 2000;
53
52
  const BAND_HIGH_HZ = 8000;
@@ -55,10 +54,12 @@ const FRAME_SECONDS = 0.002;
55
54
  const HOP_SECONDS = 0.001;
56
55
  /** The running median's reach on each side of a frame. */
57
56
  const MEDIAN_SECONDS = 0.1;
58
- /** A lowered impulse reaches this far past its detected frames, for the band filter's delay and the frames' edges. */
57
+ /** A repaired impulse reaches this far past its detected frames, for the band filter's delay and the frames' edges. */
59
58
  const IMPULSE_MARGIN = 0.001;
60
59
  /** A frame quieter than this (mean square, dB) is never an impulse: digital silence with a stray bit is not a click. */
61
60
  const BAND_FLOOR_DB = -90;
61
+ /** Added to Burg's denominator, so a silent context gives a zero model instead of a division by zero. */
62
+ const AR_RIDGE = 1e-9;
62
63
 
63
64
  export interface TimeSpan {
64
65
  start: number;
@@ -68,30 +69,34 @@ export interface TimeSpan {
68
69
  /** What the stage did, in the render's and the draft's ok value. */
69
70
  export interface DeclickReport {
70
71
  level: ActiveDeclickLevel;
71
- /** Impulses lowered. */
72
+ /** Impulses repaired. */
72
73
  impulses: number;
73
- /** The gate between words in dB; null when the track has no words to tell speech from pauses (no gate). */
74
- gateDb: number | null;
74
+ /** Each repaired impulse in the speech track's time, seconds (without its crossfades). */
75
+ repairs: TimeSpan[];
75
76
  }
76
77
 
77
- const fromDb = (db: number): number => 10 ** (db / 20);
78
-
79
78
  const sortSpans = (words: readonly TimeSpan[]): TimeSpan[] => [...words].filter((word) => word.end > word.start).sort((a, b) => a.start - b.start);
80
79
 
81
80
  /**
82
- * The windows the gate leaves open: each word's start and end ± `DECLICK_WORD_WINDOW`, merged when two windows (with
83
- * their fades) would touch, so the gain never dips between two close words.
81
+ * The stretches the stage may change: the pauses before the first word, between words and after the last, each shrunk
82
+ * by `DECLICK_WORD_GUARD` on every side that meets a word. None without words.
84
83
  */
85
- export function getGateWindows(words: readonly TimeSpan[]): TimeSpan[] {
86
- const windows: TimeSpan[] = [];
87
- for (const word of sortSpans(words)) {
88
- const start = Math.max(0, word.start - DECLICK_WORD_WINDOW);
89
- const end = word.end + DECLICK_WORD_WINDOW;
90
- const last = windows.at(-1);
91
- if (last !== undefined && start - last.end < 2 * DECLICK_GATE_FADE) last.end = Math.max(last.end, end);
92
- else windows.push({ start, end });
84
+ export function getRepairZones(words: readonly TimeSpan[], seconds: number): TimeSpan[] {
85
+ const spoken = sortSpans(words);
86
+ if (spoken.length === 0) return [];
87
+ const zones: TimeSpan[] = [];
88
+ let from = 0;
89
+ let isAfterWord = false;
90
+ for (const word of spoken) {
91
+ const start = isAfterWord ? from + DECLICK_WORD_GUARD : from;
92
+ const end = word.start - DECLICK_WORD_GUARD;
93
+ if (end > start) zones.push({ start, end });
94
+ from = Math.max(from, word.end);
95
+ isAfterWord = true;
93
96
  }
94
- return windows;
97
+ const start = from + DECLICK_WORD_GUARD;
98
+ if (seconds > start) zones.push({ start, end: seconds });
99
+ return zones;
95
100
  }
96
101
 
97
102
  /** One second-order section (RBJ cookbook), run in place over the samples. */
@@ -179,22 +184,24 @@ export function getRunningMedian(values: Float64Array, reach: number): Float64Ar
179
184
  return medians;
180
185
  }
181
186
 
182
- /** True when the span overlaps a word's own span. */
183
- const isInsideWord = (span: TimeSpan, words: readonly TimeSpan[]): boolean => words.some((word) => span.start < word.end && span.end > word.start);
187
+ /** True when the impulse with its crossfades lies inside one zone. */
188
+ const isRepairable = (span: TimeSpan, zones: readonly TimeSpan[]): boolean =>
189
+ zones.some((zone) => span.start - DECLICK_CROSSFADE >= zone.start && span.end + DECLICK_CROSSFADE <= zone.end);
184
190
 
185
191
  /**
186
- * The impulses of a mono signal: runs of 2 ms frames (1 ms hop) whose 2-8 kHz energy jumps more than the level's
187
- * `jumpDb` above the band's running median (±100 ms), shorter than `DECLICK_MAX_IMPULSE`, overlapping no word's own
188
- * span. Times in seconds, widened by a millisecond on each side.
192
+ * The impulses of a mono signal the stage repairs: runs of 2 ms frames (1 ms hop) whose 2-8 kHz energy jumps more than
193
+ * the level's `jumpDb` above the band's running median (±100 ms), shorter than `DECLICK_MAX_IMPULSE`, that lie with
194
+ * their crossfades inside a repair zone (`getRepairZones`). Times in seconds, widened by a millisecond on each side.
189
195
  */
190
196
  export function findImpulses(mono: Float32Array, sampleRate: number, words: readonly TimeSpan[], level: ActiveDeclickLevel): TimeSpan[] {
197
+ const seconds = mono.length / sampleRate;
198
+ const zones = getRepairZones(words, seconds);
199
+ if (zones.length === 0) return [];
191
200
  const { jumpDb } = DECLICK_SETTINGS[level];
192
201
  const frameLength = Math.max(1, Math.round(FRAME_SECONDS * sampleRate));
193
202
  const hop = Math.max(1, Math.round(HOP_SECONDS * sampleRate));
194
203
  const energies = getFrameEnergies(getBand(mono, sampleRate), frameLength, hop);
195
204
  const medians = getRunningMedian(energies, Math.round(MEDIAN_SECONDS / HOP_SECONDS));
196
- const spoken = sortSpans(words);
197
- const seconds = mono.length / sampleRate;
198
205
  const impulses: TimeSpan[] = [];
199
206
  let runStart = -1;
200
207
  const closeRun = (lastFrame: number): void => {
@@ -203,7 +210,7 @@ export function findImpulses(mono: Float32Array, sampleRate: number, words: read
203
210
  runStart = -1;
204
211
  if (end - start >= DECLICK_MAX_IMPULSE) return;
205
212
  const span = { start: Math.max(0, start - IMPULSE_MARGIN), end: Math.min(seconds, end + IMPULSE_MARGIN) };
206
- if (!isInsideWord(span, spoken)) impulses.push(span);
213
+ if (isRepairable(span, zones)) impulses.push(span);
207
214
  };
208
215
  for (let frame = 0; frame < energies.length; frame++) {
209
216
  const energy = energies[frame] ?? 0;
@@ -215,57 +222,111 @@ export function findImpulses(mono: Float32Array, sampleRate: number, words: read
215
222
  return impulses;
216
223
  }
217
224
 
218
- /** Sets the gain to `value` from sample `from` up to (not including) `to`, multiplying what is there. */
219
- function scaleRange(gain: Float32Array, from: number, to: number, value: (index: number) => number): void {
220
- for (let index = Math.max(0, from); index < Math.min(gain.length, to); index++) gain[index] = (gain[index] ?? 1) * value(index);
225
+ /**
226
+ * The AR polynomial of the context segments (Burg's method over all of them at once): `a[0] = 1` and
227
+ * `Σ a[k]·x[n-k] ≈ 0`. Fewer coefficients when the segments are short; a silent context gives all zeros after `a[0]`.
228
+ */
229
+ export function getArPolynomial(segments: readonly Float64Array[], order: number): Float64Array {
230
+ const longest = Math.max(0, ...segments.map((segment) => segment.length));
231
+ const usable = Math.min(order, Math.floor(longest / 2));
232
+ const forward = segments.map((segment) => Float64Array.from(segment));
233
+ const backward = segments.map((segment) => Float64Array.from(segment));
234
+ let polynomial = new Float64Array(usable + 1);
235
+ polynomial[0] = 1;
236
+ for (let step = 1; step <= usable; step++) {
237
+ let numerator = 0;
238
+ let denominator = AR_RIDGE;
239
+ forward.forEach((f, segment) => {
240
+ const b = backward[segment] ?? f;
241
+ for (let index = step; index < f.length; index++) {
242
+ numerator += (f[index] ?? 0) * (b[index - 1] ?? 0);
243
+ denominator += (f[index] ?? 0) ** 2 + (b[index - 1] ?? 0) ** 2;
244
+ }
245
+ });
246
+ const reflection = (-2 * numerator) / denominator;
247
+ forward.forEach((f, segment) => {
248
+ const b = backward[segment] ?? f;
249
+ for (let index = f.length - 1; index >= step; index--) {
250
+ const fValue = f[index] ?? 0;
251
+ const bValue = b[index - 1] ?? 0;
252
+ f[index] = fValue + reflection * bValue;
253
+ b[index] = bValue + reflection * fValue;
254
+ }
255
+ });
256
+ const next = Float64Array.from(polynomial);
257
+ for (let k = 1; k <= step; k++) next[k] = (polynomial[k] ?? 0) + reflection * (polynomial[step - k] ?? 0);
258
+ polynomial = next;
259
+ }
260
+ return polynomial;
221
261
  }
222
262
 
223
- /** A linear ramp from `fromValue` at sample `from` to `toValue` at sample `to`. */
224
- const ramp = (from: number, to: number, fromValue: number, toValue: number) => (index: number) => (to <= from ? toValue : fromValue + ((toValue - fromValue) * (index - from)) / (to - from));
225
-
226
263
  /**
227
- * The stage's gain per sample: the gate (1 inside the windows, a linear fade outside them, the gate's level beyond)
228
- * times a dip for every impulse (its crossfades clamped to the neighbouring words, so no word is touched). With no
229
- * words, no gate.
264
+ * Solves `B·x = rhs` for a symmetric positive definite banded Toeplitz `B` (`B[i][j] = band[|i-j|]`, zero beyond the
265
+ * band) by a banded Cholesky factorization.
230
266
  */
231
- export function getDeclickGain(options: { length: number; sampleRate: number; words: readonly TimeSpan[]; impulses: readonly TimeSpan[]; level: ActiveDeclickLevel }): Float32Array {
232
- const { length, sampleRate, level } = options;
233
- const settings = DECLICK_SETTINGS[level];
234
- const at = (seconds: number): number => Math.round(seconds * sampleRate);
235
- const windows = getGateWindows(options.words);
236
- const gate = windows.length === 0 ? 1 : fromDb(settings.gateDb);
237
- const gain = new Float32Array(length).fill(1);
238
- if (gate < 1) {
239
- const fade = at(DECLICK_GATE_FADE);
240
- const open = new Float32Array(length).fill(gate);
241
- for (const window of windows) {
242
- const start = at(window.start);
243
- const end = at(window.end);
244
- for (let index = Math.max(0, start - fade); index < Math.min(length, end + fade); index++) {
245
- const value = index < start ? gate + ((1 - gate) * (index - (start - fade))) / fade : index >= end ? 1 - ((1 - gate) * (index - end)) / fade : 1;
246
- open[index] = Math.max(open[index] ?? gate, value);
247
- }
267
+ function solveBandedToeplitz(band: Float64Array, rhs: Float64Array): Float64Array {
268
+ const size = rhs.length;
269
+ const width = band.length - 1;
270
+ // lower[i * (width + 1) + d] holds L(i, i - d).
271
+ const lower = new Float64Array(size * (width + 1));
272
+ const at = (row: number, column: number): number => lower[row * (width + 1) + (row - column)] ?? 0;
273
+ for (let row = 0; row < size; row++) {
274
+ for (let column = Math.max(0, row - width); column <= row; column++) {
275
+ let sum = band[row - column] ?? 0;
276
+ for (let k = Math.max(0, row - width); k < column; k++) sum -= at(row, k) * at(column, k);
277
+ lower[row * (width + 1) + (row - column)] = row === column ? Math.sqrt(Math.max(sum, 1e-30)) : sum / at(column, column);
248
278
  }
249
- gain.set(open);
250
279
  }
251
- const spoken = sortSpans(options.words);
252
- const dip = fromDb(DECLICK_IMPULSE_DB);
253
- const crossfade = settings.crossfadeSeconds;
254
- for (const impulse of options.impulses) {
255
- const before = spoken.filter((word) => word.end <= impulse.start).reduce((latest, word) => Math.max(latest, word.end), 0);
256
- const after = spoken.filter((word) => word.start >= impulse.end).reduce((earliest, word) => Math.min(earliest, word.start), Infinity);
257
- const start = at(impulse.start);
258
- const end = at(impulse.end);
259
- const fadeIn = at(Math.max(before, impulse.start - crossfade));
260
- const fadeOut = at(Math.min(after, impulse.end + crossfade));
261
- scaleRange(gain, fadeIn, start, ramp(fadeIn, start, 1, dip));
262
- scaleRange(gain, start, end, () => dip);
263
- scaleRange(gain, end, fadeOut, ramp(end, fadeOut, dip, 1));
280
+ const middle = new Float64Array(size);
281
+ for (let row = 0; row < size; row++) {
282
+ let sum = rhs[row] ?? 0;
283
+ for (let k = Math.max(0, row - width); k < row; k++) sum -= at(row, k) * (middle[k] ?? 0);
284
+ middle[row] = sum / at(row, row);
285
+ }
286
+ const solution = new Float64Array(size);
287
+ for (let row = size - 1; row >= 0; row--) {
288
+ let sum = middle[row] ?? 0;
289
+ for (let k = row + 1; k <= Math.min(size - 1, row + width); k++) sum -= at(k, row) * (solution[k] ?? 0);
290
+ solution[row] = sum / at(row, row);
291
+ }
292
+ return solution;
293
+ }
294
+
295
+ /**
296
+ * Repairs samples `from` to `to` (exclusive) of one channel in place by least-squares AR interpolation: an AR model
297
+ * fitted on `context` samples on both sides, and the samples that minimize the model's residual energy given the
298
+ * sound around them (samples beyond the track count as zero). A raised-cosine crossfade of `crossfade` samples at each
299
+ * end joins the interpolation to the original.
300
+ */
301
+ export function repairSpan(options: { channel: Float64Array; from: number; to: number; crossfade: number; context: number }): void {
302
+ const { channel, crossfade, context } = options;
303
+ const from = Math.max(0, options.from);
304
+ const to = Math.min(channel.length, options.to);
305
+ const count = to - from;
306
+ if (count <= 0) return;
307
+ const polynomial = getArPolynomial([channel.slice(Math.max(0, from - context), from), channel.slice(to, Math.min(channel.length, to + context))], DECLICK_AR_ORDER);
308
+ const order = polynomial.length - 1;
309
+ const band = new Float64Array(order + 1);
310
+ for (let lag = 0; lag <= order; lag++) for (let k = 0; k + lag <= order; k++) band[lag] = (band[lag] ?? 0) + (polynomial[k] ?? 0) * (polynomial[k + lag] ?? 0);
311
+ const known = (index: number): number => (index < 0 || index >= channel.length || (index >= from && index < to) ? 0 : (channel[index] ?? 0));
312
+ const rhs = new Float64Array(count);
313
+ for (let row = from; row < to + order; row++) {
314
+ let residual = 0;
315
+ for (let k = 0; k <= order; k++) residual += (polynomial[k] ?? 0) * known(row - k);
316
+ for (let index = Math.max(from, row - order); index <= Math.min(to - 1, row); index++) rhs[index - from] = (rhs[index - from] ?? 0) - (polynomial[row - index] ?? 0) * residual;
317
+ }
318
+ const interpolated = solveBandedToeplitz(band, rhs);
319
+ for (let offset = 0; offset < count; offset++) {
320
+ const edge = Math.min(offset + 0.5, count - offset - 0.5);
321
+ const mix = crossfade <= 0 || edge >= crossfade ? 1 : 0.5 - 0.5 * Math.cos((Math.PI * edge) / crossfade);
322
+ channel[from + offset] = mix * (interpolated[offset] ?? 0) + (1 - mix) * (channel[from + offset] ?? 0);
264
323
  }
265
- return gain;
266
324
  }
267
325
 
268
- /** The stage over interleaved samples: the impulses found on the channels' average, then the gain on every channel. */
326
+ /**
327
+ * The stage over interleaved samples: the impulses found on the channels' average, then each one repaired on every
328
+ * channel (with its crossfades). Every sample outside the repairs is returned as it came in.
329
+ */
269
330
  export function declickSamples(options: { samples: Float32Array; channels: number; sampleRate: number; words: readonly TimeSpan[]; level: ActiveDeclickLevel }): {
270
331
  samples: Float32Array;
271
332
  impulses: TimeSpan[];
@@ -280,11 +341,20 @@ export function declickSamples(options: { samples: Float32Array; channels: numbe
280
341
  mono[index] = sum / channels;
281
342
  }
282
343
  const impulses = findImpulses(mono, sampleRate, words, level);
283
- const gain = getDeclickGain({ length, sampleRate, words, impulses, level });
284
- const output = new Float32Array(samples.length);
285
- for (let index = 0; index < samples.length; index++) output[index] = (samples[index] ?? 0) * (gain[Math.floor(index / channels)] ?? 1);
286
- const hasGate = getGateWindows(words).length > 0;
287
- return { samples: output, impulses, report: { level, impulses: impulses.length, gateDb: hasGate ? DECLICK_SETTINGS[level].gateDb : null } };
344
+ const output = Float32Array.from(samples);
345
+ const crossfade = Math.round(DECLICK_CROSSFADE * sampleRate);
346
+ const context = Math.round(DECLICK_AR_CONTEXT * sampleRate);
347
+ for (let channel = 0; channel < channels && impulses.length > 0; channel++) {
348
+ const track = new Float64Array(length);
349
+ for (let index = 0; index < length; index++) track[index] = samples[index * channels + channel] ?? 0;
350
+ for (const impulse of impulses) {
351
+ const from = Math.round(impulse.start * sampleRate) - crossfade;
352
+ const to = Math.round(impulse.end * sampleRate) + crossfade;
353
+ repairSpan({ channel: track, from, to, crossfade, context });
354
+ for (let index = Math.max(0, from); index < Math.min(length, to); index++) output[index * channels + channel] = track[index] ?? 0;
355
+ }
356
+ }
357
+ return { samples: output, impulses, report: { level, impulses: impulses.length, repairs: impulses.map((impulse) => ({ ...impulse })) } };
288
358
  }
289
359
 
290
360
  const CHANNELS = 2;
@@ -328,7 +398,7 @@ export interface DeclickSpeechOptions {
328
398
  onSeconds?: (done: number) => void;
329
399
  }
330
400
 
331
- /** Runs the stage on a speech track file: decode, find and lower, encode. The raw PCM next to the output is removed. */
401
+ /** Runs the stage on a speech track file: decode, find and repair, encode. The raw PCM next to the output is removed. */
332
402
  export async function declickSpeech(options: DeclickSpeechOptions): Promise<DeclickReport> {
333
403
  const { input, output, seconds } = options;
334
404
  const aborting = options.signal === undefined ? {} : { signal: options.signal };
@@ -345,8 +415,13 @@ export async function declickSpeech(options: DeclickSpeechOptions): Promise<Decl
345
415
  }
346
416
  }
347
417
 
418
+ /** How many repair times the log line lists. */
419
+ const LOGGED_REPAIRS = 8;
420
+
348
421
  /** The stage's log line. */
349
422
  export function describeDeclick(report: DeclickReport): string {
350
- const gate = report.gateDb === null ? "no words, so no gate" : `the pauses lowered by ${String(-report.gateDb)} dB`;
351
- return `declick (${report.level}): ${String(report.impulses)} impulse${report.impulses === 1 ? "" : "s"} removed, ${gate}.`;
423
+ const times = report.repairs.slice(0, LOGGED_REPAIRS).map((repair) => `${repair.start.toFixed(3)} s`);
424
+ const more = report.repairs.length > LOGGED_REPAIRS ? `, +${String(report.repairs.length - LOGGED_REPAIRS)} more` : "";
425
+ 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.`;
352
427
  }
@@ -140,8 +140,8 @@ export interface FootageFilm {
140
140
  captionKeepWithNext?: string[];
141
141
  /** The cut's look: zoom size, fade length, Ken Burns, the end card's whoosh. Absent fields take `DEFAULT_EDIT`. */
142
142
  edit?: Partial<FootageEdit>;
143
- /** The closing card after the last segment; null: the film ends with its last segment. */
144
- endCard: EndCard | null;
143
+ /** The closing card after the last segment (`FootageEndCard`); null: the film ends with its last segment. */
144
+ endCard: FootageEndCard | null;
145
145
  /** The speech track's cleanup before its loudness normalization. Absent: none. */
146
146
  speech?: FootageSpeech;
147
147
  /** The speech track's loudness, normalized before the music is mixed under it. Absent: −14 LUFS, −1 dBTP; null: left as filmed. */
@@ -161,6 +161,58 @@ export interface FootageFilm {
161
161
  cover?: { at?: number } | null;
162
162
  }
163
163
 
164
+ /**
165
+ * The closing card after a footage film's last segment, over the cut's last frame. No speech plays under it; the
166
+ * music plays on. `layout` tells the two shapes apart (`"full"` when absent).
167
+ */
168
+ export type FootageEndCard = FullFootageEndCard | LogoFootageEndCard;
169
+
170
+ /** The brand row, the headline, the link pill and the note (`layout` absent or `"full"`). */
171
+ export interface FullFootageEndCard extends EndCard {
172
+ layout?: "full";
173
+ /** The card's length in seconds (1-3); absent: `DEFAULT_END_CARD_SECONDS`. The entrances keep pace with it. */
174
+ seconds?: number;
175
+ }
176
+
177
+ /**
178
+ * A short brand card (issue #1173): the logo and one optional line on the brand's background, fading in, inside the
179
+ * 9:16 platform safe zone; the music fades out under it to the film's end.
180
+ */
181
+ export interface LogoFootageEndCard {
182
+ layout: "logo";
183
+ /** One short line under the logo ("Follow for more"), in the heading font; empty: the logo alone. */
184
+ line: string;
185
+ /** The card's logo, a PNG (with alpha) or an SVG file; absent: the brand's logo, or the brand name without one. */
186
+ logo?: string;
187
+ /** The card's length in seconds (1-3); absent: `DEFAULT_LOGO_END_CARD_SECONDS`. */
188
+ seconds?: number;
189
+ /** How long the card fades in over the last frame, in seconds; absent: `DEFAULT_LOGO_END_CARD_FADE_SECONDS`. */
190
+ fadeSeconds?: number;
191
+ }
192
+
193
+ /** The full end card's length when it sets none. */
194
+ export const DEFAULT_END_CARD_SECONDS = 3;
195
+ /** The logo card's length when it sets none. */
196
+ export const DEFAULT_LOGO_END_CARD_SECONDS = 1.5;
197
+ /** The logo card's fade in when it sets none. */
198
+ export const DEFAULT_LOGO_END_CARD_FADE_SECONDS = 0.2;
199
+
200
+ /** The end card's length in seconds: 0 without a card, else its `seconds` or its layout's default. */
201
+ export function getEndCardSeconds(card: FootageEndCard | null): number {
202
+ if (card === null) return 0;
203
+ return card.seconds ?? (card.layout === "logo" ? DEFAULT_LOGO_END_CARD_SECONDS : DEFAULT_END_CARD_SECONDS);
204
+ }
205
+
206
+ /**
207
+ * The end card's texts in the shape the glyph check reads (`findMissingCaptionGlyphs`): the logo card's line is drawn
208
+ * in the heading font, like the full card's headline; it has no url or note.
209
+ */
210
+ export function getEndCardTexts(card: FootageEndCard | null): { headline: string; url: string; note: string } | null {
211
+ if (card === null) return null;
212
+ if (card.layout !== "logo") return { headline: card.headline, url: card.url, note: card.note };
213
+ return { headline: card.line, url: "", note: "" };
214
+ }
215
+
164
216
  /** Settings of the speech track itself. */
165
217
  export interface FootageSpeech {
166
218
  /**
@@ -4,10 +4,10 @@ import { extname, join } from "node:path";
4
4
 
5
5
  import { err, ok, type TtsResult } from "../voice/provider.js";
6
6
  import { footageCacheKey, getFootageCachePath, hashFile } from "./cache.js";
7
- import { END_CARD_SECONDS, getFootageFilmSeconds } from "./compose.js";
7
+ import { getFootageFilmSeconds } from "./compose.js";
8
8
  import { readEdl, type Edl } from "./edl.js";
9
9
  import { getFilmKeyTerms } from "./keyterms.js";
10
- import type { FootageClip, FootageFilm } from "./film.js";
10
+ import { getEndCardSeconds, type FootageClip, type FootageFilm } from "./film.js";
11
11
  import { getTrimmedDuration, probeFootage } from "./probe.js";
12
12
  import type { FootageProviders, FootageRates, PaidStepKind } from "./providers.js";
13
13
  import {
@@ -266,7 +266,7 @@ export async function estimateFootageFilm(film: FootageFilm, options: EstimateFo
266
266
  }
267
267
  const music = film.music.source;
268
268
  if (music.kind === "prompt" || music.kind === "video") {
269
- const seconds = edl === null ? clipSeconds + (film.endCard === null ? 0 : END_CARD_SECONDS) : getFootageFilmSeconds(film, edl);
269
+ const seconds = edl === null ? clipSeconds + getEndCardSeconds(film.endCard) : getFootageFilmSeconds(film, edl);
270
270
  add("music", "film", options.providers.music.id, seconds, await isMusicCached(film, options));
271
271
  }
272
272
  return ok({ items, totalCredits: round(items.reduce((sum, item) => sum + item.credits, 0), 2) });
@@ -14,7 +14,7 @@ import type { TimedWord } from "../voice/voiceover.js";
14
14
  import { checkMusicFileType, describeAudioProbe, probeAudio } from "./audio.js";
15
15
  import { prepareClipSounds } from "./clip-sound.js";
16
16
  import { readCachedTranscript, writeCacheFile, writeTranscript } from "./cache.js";
17
- import { composeFootage, END_CARD_SECONDS, getFootageFilmSeconds, getFootageSfxCues } from "./compose.js";
17
+ import { composeFootage, getFootageFilmSeconds, getFootageSfxCues } from "./compose.js";
18
18
  import { findMissingCaptionGlyphs, getCaptionBounds, getFootageCaptionLayout } from "./captions.js";
19
19
  import { err, getProviderFootageFailure, ok, type FootageResult } from "./failure.js";
20
20
  import { findLowDiskProblems, getFreeBytes, getRenderTempDir, type FreeBytesReader } from "./disk.js";
@@ -22,7 +22,7 @@ import { buildEdl, getEdlDuration, readEdl, remapWords, validateEdl, type Edl }
22
22
  import { makePlaceholderTranscript } from "./fake.js";
23
23
  import { chooseCutTransitions, type CutMeasure } from "./cuts.js";
24
24
  import { declickSpeech, describeDeclick, type DeclickReport } from "./declick.js";
25
- import { DEFAULT_AUTO_THRESHOLD, getDeclickLevel, getFootageEdit, type FootageClip, type FootageFilm, type MusicSource } from "./film.js";
25
+ import { DEFAULT_AUTO_THRESHOLD, getDeclickLevel, getEndCardSeconds, getEndCardTexts, getFootageEdit, type FootageClip, type FootageFilm, type MusicSource } from "./film.js";
26
26
  import { getFilmKeyTerms } from "./keyterms.js";
27
27
  import { buildFilmMixArgs } from "./film-mix.js";
28
28
  import {
@@ -353,7 +353,7 @@ async function runTranscribeFootage(film: FootageFilm, clips: PreparedClip[], op
353
353
  plan.push({ clip, isolated, transcript });
354
354
  }
355
355
  if (steps.length > 0 && !options.isCommit) {
356
- const total = clips.reduce((sum, clip) => sum + clip.duration, 0) + (film.endCard === null ? 0 : END_CARD_SECONDS);
356
+ const total = clips.reduce((sum, clip) => sum + clip.duration, 0) + getEndCardSeconds(film.endCard);
357
357
  const music = getMusicPaidStep(film, options, total);
358
358
  const all = music === null ? steps : [...steps, music];
359
359
  for (const line of describePaidSteps(all)) log(line);
@@ -762,7 +762,9 @@ async function runRenderFootage(
762
762
  if (musicFile !== null) {
763
763
  const keyframes = duckingKeyframes(words, getDuckingOptions(film.music));
764
764
  const output = join(assetsDir, "music.mp3");
765
- tracks.push({ item: "music", seconds, run: ffmpegTrack("The music track", output, () => buildMusicArgs({ input: musicFile, seconds, keyframes, output })) });
765
+ // Under the logo card the music fades out over the card's whole length, to the film's end (issue #1173).
766
+ const fadeOutSeconds = film.endCard?.layout === "logo" ? { fadeOutSeconds: getEndCardSeconds(film.endCard) } : {};
767
+ tracks.push({ item: "music", seconds, run: ffmpegTrack("The music track", output, () => buildMusicArgs({ input: musicFile, seconds, keyframes, output, ...fadeOutSeconds })) });
766
768
  }
767
769
  const sfx: Partial<Record<SfxEvent, string>> = {};
768
770
  mkdirSync(join(assetsDir, "sfx"), { recursive: true });
@@ -812,7 +814,10 @@ async function runRenderFootage(
812
814
  if (!prepared.ok) return prepared;
813
815
  const musicAsset = musicFile === null ? null : "assets/music.mp3";
814
816
  const fonts = copyFonts(options.brand.fonts, join(assetsDir, "fonts"));
815
- if (options.brand.logo !== null) cpSync(options.brand.logo, join(assetsDir, "logo.svg"));
817
+ // The logo card's own logo wins over the brand's; it keeps its extension, so a PNG is drawn as a PNG.
818
+ const logoSource = (film.endCard?.layout === "logo" ? film.endCard.logo : undefined) ?? options.brand.logo;
819
+ const logoAsset = logoSource === null ? null : `assets/logo${extname(logoSource).toLowerCase() || ".svg"}`;
820
+ if (logoSource !== null && logoAsset !== null) cpSync(logoSource, join(buildDir, logoAsset));
816
821
  cpSync(require.resolve("gsap/dist/gsap.min.js"), join(assetsDir, "gsap.min.js"));
817
822
  const base = resolveLayout(film.format, options.layout ?? {});
818
823
  // A caption preset places the 9:16 box in a platform's safe zone; the project's own caption override still wins.
@@ -820,7 +825,7 @@ async function runRenderFootage(
820
825
  const missing = findMissingCaptionGlyphs({
821
826
  fonts: options.brand.fonts,
822
827
  captions: film.captions ? words.map((word) => word.text) : [],
823
- endCard: film.endCard,
828
+ endCard: getEndCardTexts(film.endCard),
824
829
  brandName: options.brand.name,
825
830
  });
826
831
  if (missing.length > 0) {
@@ -841,7 +846,7 @@ async function runRenderFootage(
841
846
  speech: "assets/speech.wav",
842
847
  music: musicAsset,
843
848
  lastFrame: "assets/last.jpg",
844
- logo: options.brand.logo === null ? null : "assets/logo.svg",
849
+ logo: logoAsset,
845
850
  sfx,
846
851
  },
847
852
  brandName: options.brand.name,
@@ -109,14 +109,18 @@ export function buildSpeechArgs(edl: Edl, sources: Record<string, string>, outpu
109
109
  return ["-v", "error", "-y", ...inputs, "-filter_complex", parts.join(";"), "-map", "[speech]", ...getAudioCodecArgs(output), output];
110
110
  }
111
111
 
112
- /** The music track: looped to the film's length, ducked by the keyframes, faded in and out. */
113
- export function buildMusicArgs(options: { input: string; seconds: number; keyframes: VolumeKeyframe[]; output: string }): string[] {
112
+ /**
113
+ * The music track: looped to the film's length, ducked by the keyframes, faded in and faded out to the film's end over
114
+ * `fadeOutSeconds` (default 1.5 s; the logo end card fades it over the card's whole length).
115
+ */
116
+ export function buildMusicArgs(options: { input: string; seconds: number; keyframes: VolumeKeyframe[]; output: string; fadeOutSeconds?: number }): string[] {
114
117
  const { seconds } = options;
118
+ const fadeOut = r3(Math.min(seconds, options.fadeOutSeconds ?? MUSIC_FADE_OUT));
115
119
  const filters = [
116
120
  `aformat=sample_rates=${FOOTAGE_SAMPLE_RATE}:channel_layouts=stereo`,
117
121
  `volume=eval=frame:volume='${volumeExpression(options.keyframes)}'`,
118
122
  `afade=t=in:d=${MUSIC_FADE_IN}`,
119
- `afade=t=out:st=${r3(Math.max(0, seconds - MUSIC_FADE_OUT))}:d=${MUSIC_FADE_OUT}`,
123
+ `afade=t=out:st=${r3(Math.max(0, seconds - fadeOut))}:d=${fadeOut}`,
120
124
  ];
121
125
  return ["-v", "error", "-y", "-stream_loop", "-1", "-i", options.input, "-t", String(seconds), "-af", filters.join(","), "-c:a", "libmp3lame", "-q:a", "2", options.output];
122
126
  }