@softure-ai/marketing-kit 0.16.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 (85) hide show
  1. package/CHANGELOG.md +65 -0
  2. package/README.md +72 -19
  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/isolate-ranges.d.ts +10 -1
  25. package/dist/footage/isolate-ranges.d.ts.map +1 -1
  26. package/dist/footage/isolate-ranges.js +56 -10
  27. package/dist/footage/isolate-ranges.js.map +1 -1
  28. package/dist/footage/paid.d.ts +1 -1
  29. package/dist/footage/paid.d.ts.map +1 -1
  30. package/dist/footage/paid.js +3 -2
  31. package/dist/footage/paid.js.map +1 -1
  32. package/dist/footage/pipeline.d.ts +6 -0
  33. package/dist/footage/pipeline.d.ts.map +1 -1
  34. package/dist/footage/pipeline.js +19 -14
  35. package/dist/footage/pipeline.js.map +1 -1
  36. package/dist/footage/render.d.ts +5 -1
  37. package/dist/footage/render.d.ts.map +1 -1
  38. package/dist/footage/render.js +6 -2
  39. package/dist/footage/render.js.map +1 -1
  40. package/dist/footage/speech-ranges.d.ts +28 -1
  41. package/dist/footage/speech-ranges.d.ts.map +1 -1
  42. package/dist/footage/speech-ranges.js +47 -2
  43. package/dist/footage/speech-ranges.js.map +1 -1
  44. package/dist/index.d.ts +5 -5
  45. package/dist/index.d.ts.map +1 -1
  46. package/dist/index.js +5 -5
  47. package/dist/index.js.map +1 -1
  48. package/dist/og/character-map.d.ts +2 -1
  49. package/dist/og/character-map.d.ts.map +1 -1
  50. package/dist/og/character-map.js +7 -63
  51. package/dist/og/character-map.js.map +1 -1
  52. package/dist/og/font-file.d.ts +53 -0
  53. package/dist/og/font-file.d.ts.map +1 -0
  54. package/dist/og/font-file.js +153 -0
  55. package/dist/og/font-file.js.map +1 -0
  56. package/dist/og/font-tables.d.ts +25 -0
  57. package/dist/og/font-tables.d.ts.map +1 -0
  58. package/dist/og/font-tables.js +212 -0
  59. package/dist/og/font-tables.js.map +1 -0
  60. package/dist/og/index.d.ts +3 -1
  61. package/dist/og/index.d.ts.map +1 -1
  62. package/dist/og/index.js +2 -1
  63. package/dist/og/index.js.map +1 -1
  64. package/dist/og/photo-cover.d.ts +49 -8
  65. package/dist/og/photo-cover.d.ts.map +1 -1
  66. package/dist/og/photo-cover.js +213 -53
  67. package/dist/og/photo-cover.js.map +1 -1
  68. package/package.json +1 -1
  69. package/schema/marketing.schema.json +76 -23
  70. package/src/config/config.ts +10 -2
  71. package/src/config/schema.ts +24 -5
  72. package/src/footage/compose.ts +72 -17
  73. package/src/footage/declick.ts +172 -97
  74. package/src/footage/film.ts +54 -2
  75. package/src/footage/isolate-ranges.ts +66 -11
  76. package/src/footage/paid.ts +3 -3
  77. package/src/footage/pipeline.ts +25 -14
  78. package/src/footage/render.ts +7 -3
  79. package/src/footage/speech-ranges.ts +55 -3
  80. package/src/index.ts +34 -5
  81. package/src/og/character-map.ts +8 -61
  82. package/src/og/font-file.ts +172 -0
  83. package/src/og/font-tables.ts +221 -0
  84. package/src/og/index.ts +19 -0
  85. package/src/og/photo-cover.ts +259 -62
@@ -453,12 +453,29 @@ const videoSchema = z
453
453
  });
454
454
  });
455
455
 
456
- const endCardSchema = z
457
- .strictObject({
456
+ const endCardSeconds = (fallback: number) =>
457
+ z.number().min(1).max(3).optional().describe(`The card's length in seconds after the cut (1-3). Default ${fallback}.`);
458
+
459
+ /** A footage film's end card: the full card (`layout` absent or "full") or the short logo card (issue #1173). */
460
+ const footageEndCardSchema = z.discriminatedUnion("layout", [
461
+ z.strictObject({
462
+ layout: z.literal("full").optional().describe('"full" (the default): the brand row, headline, link pill and note.'),
458
463
  headline: nonEmpty.describe("The end card's headline."),
459
464
  url: nonEmpty.describe("The address shown in the end card's link pill, as written (e.g. example.com)."),
460
465
  note: z.string().default("").describe("A small line under the link; empty: none."),
461
- });
466
+ seconds: endCardSeconds(3),
467
+ }),
468
+ z.strictObject({
469
+ layout: z.literal("logo").describe('"logo": a short brand card, the logo and one line on the brand background, the music fading out under it.'),
470
+ line: z.string().max(80).default("").describe('One short line under the logo, e.g. "Follow for more"; empty: the logo alone.'),
471
+ logo: relativePath
472
+ .regex(/\.(svg|png)$/i, "must be an .svg or a .png file")
473
+ .optional()
474
+ .describe("The card's logo, an .svg or a .png with alpha, relative to the folder of marketing.json; without it brand.logo, or the brand name."),
475
+ seconds: endCardSeconds(1.5),
476
+ fadeSeconds: z.number().min(0).max(1).optional().describe("How long the card fades in over the last frame, in seconds (0-1). Default 0.2."),
477
+ }),
478
+ ]);
462
479
 
463
480
  const clipSource = z
464
481
  .string()
@@ -601,14 +618,16 @@ const footageSchema = z
601
618
  })
602
619
  .prefault({})
603
620
  .describe("The cut's look; the defaults read as an ordinary phone video."),
604
- endCard: endCardSchema.optional().describe("The closing card after the last segment; without it, the film ends with its last segment."),
621
+ endCard: footageEndCardSchema
622
+ .optional()
623
+ .describe('The closing card after the last segment ("full", the default, or the short "logo" card); without it, the film ends with its last segment.'),
605
624
  speech: z
606
625
  .strictObject({
607
626
  declick: z
608
627
  .enum(DECLICK_LEVELS)
609
628
  .default("off")
610
629
  .describe(
611
- "Mouth clicks and lip smacks between words, cleaned before the loudness pass: gentle lowers the pauses by 15 dB and removes short clicks, strong by 20 dB with a more sensitive detection; off (the default) leaves the speech track as cut.",
630
+ "Mouth clicks and lip smacks in the pauses, repaired before the loudness pass: each single impulse in a pause is replaced by AR interpolation with a 3 ms crossfade, nothing within 80 ms of a word is touched and no gain changes; gentle detects strong impulses only, strong is more sensitive; off (the default) leaves the speech track as cut.",
612
631
  ),
613
632
  })
614
633
  .prefault({})
@@ -4,9 +4,19 @@ import type { ComposeFont } from "../compose/compose.js";
4
4
  import { escapeHtml, fontFaces, fontStack } from "../compose/html.js";
5
5
  import { CAPTION_LINE_HEIGHT, getCaptionPillCss, getCaptionPositionCss, type CaptionLayout } from "../compose/timeline.js";
6
6
  import type { TimedWord } from "../voice/voiceover.js";
7
- import { getCaptionChunkLayouts, getCaptionSpans, getFootageCaptionChunks, isSameCaptionPlace, type CaptionSpan } from "./captions.js";
7
+ import { CAPTION_SAFE_ZONES, getCaptionChunkLayouts, getCaptionSpans, getFootageCaptionChunks, isSameCaptionPlace, type CaptionSpan } from "./captions.js";
8
8
  import { getEdlDuration, getSegmentStarts, type Edl } from "./edl.js";
9
- import { CAPTION_MIN_FONT_SCALE, DEFAULT_EDIT, getFootageEdit, type FootageEdit, type FootageFilm } from "./film.js";
9
+ import {
10
+ CAPTION_MIN_FONT_SCALE,
11
+ DEFAULT_EDIT,
12
+ DEFAULT_END_CARD_SECONDS,
13
+ DEFAULT_LOGO_END_CARD_FADE_SECONDS,
14
+ getEndCardSeconds,
15
+ getFootageEdit,
16
+ type FootageEdit,
17
+ type FootageFilm,
18
+ type LogoFootageEndCard,
19
+ } from "./film.js";
10
20
  import { FOOTAGE_FPS } from "./normalize.js";
11
21
 
12
22
  const r3 = (value: number): number => Math.round(value * 1000) / 1000 || 0;
@@ -16,7 +26,8 @@ const r3 = (value: number): number => Math.round(value * 1000) / 1000 || 0;
16
26
  * EDL segment over the normalized clip with its media start, the transitions (`fade` cross-fades from the segment
17
27
  * before over `fadeFrames`, `zoom` punches in by `zoomPercent` on alternate jump cuts, eased over `zoomEaseFrames`, `whoosh` plays the whoosh
18
28
  * sound), a slow zoom on `kenburns` segments, the captions (plain phrases, or the word-highlight pill), the end card
19
- * over the cut's last frame (its whoosh only with `isEndCardWhoosh`), the cut speech track and the ducked music.
29
+ * over the cut's last frame (the full card, or the short logo card; its whoosh only with `isEndCardWhoosh`), the cut
30
+ * speech track and the ducked music.
20
31
  */
21
32
 
22
33
  const COMPOSITION_ID = "film";
@@ -24,8 +35,12 @@ const COMPOSITION_ID = "film";
24
35
  export const FADE_SECONDS = r3(DEFAULT_EDIT.fadeFrames / FOOTAGE_FPS);
25
36
  /** How far a segment marked `kenburns` zooms when the film's `kenBurnsPercent` is 0 (a hand edit asked for it). */
26
37
  const HAND_KEN_BURNS_PERCENT = 4;
27
- /** The end card's length after the cut. */
28
- export const END_CARD_SECONDS = 3;
38
+ /** The full end card's length after the cut when it sets no `seconds` (`DEFAULT_END_CARD_SECONDS`). */
39
+ export const END_CARD_SECONDS = DEFAULT_END_CARD_SECONDS;
40
+ /** The logo card's line, in px. */
41
+ const LOGO_CARD_LINE_SIZE = 64;
42
+ /** The largest box the logo card's logo is drawn in, in px: an SVG fills it, a PNG is never drawn past its own pixels. */
43
+ const LOGO_CARD_MARK = { width: 720, height: 480 };
29
44
 
30
45
  export interface FootageComposeAssets {
31
46
  /** The normalized clips by id (read when there is no `picture`). */
@@ -42,6 +57,7 @@ export interface FootageComposeAssets {
42
57
  music: string | null;
43
58
  /** The cut's last frame, under the end card. */
44
59
  lastFrame: string;
60
+ /** The end card's logo (the logo card's own, else the brand's), an SVG or a PNG; null for the brand name alone. */
45
61
  logo: string | null;
46
62
  sfx: Partial<Record<SfxEvent, string>>;
47
63
  }
@@ -62,9 +78,9 @@ export interface FootageComposeInput {
62
78
  locale: string;
63
79
  }
64
80
 
65
- /** The film's length: the cut plus the end card. */
81
+ /** The film's length: the cut plus the end card (`getEndCardSeconds`). */
66
82
  export function getFootageFilmSeconds(film: Pick<FootageFilm, "endCard">, edl: Edl): number {
67
- return r3(getEdlDuration(edl) + (film.endCard === null ? 0 : END_CARD_SECONDS));
83
+ return r3(getEdlDuration(edl) + getEndCardSeconds(film.endCard));
68
84
  }
69
85
 
70
86
  /** The picture scale each segment starts at: `zoom` cuts alternate between punched in (`zoomPercent`) and back out. */
@@ -99,7 +115,7 @@ export interface FootageSfxCue {
99
115
 
100
116
  /**
101
117
  * 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
118
+ * `isEndCardWhoosh` (the pop only when it starts before the film's end); an event without a file in `sfx` plays nothing. The composition and the film's mix
103
119
  * (`buildFilmMixArgs`) both play these.
104
120
  */
105
121
  export function getFootageSfxCues(film: FootageFilm, edl: Edl, sfx: Partial<Record<SfxEvent, string>>): FootageSfxCue[] {
@@ -116,7 +132,8 @@ export function getFootageSfxCues(film: FootageFilm, edl: Edl, sfx: Partial<Reco
116
132
  });
117
133
  if (film.endCard !== null && edit.isEndCardWhoosh) {
118
134
  play("whoosh", cutEnd, 0.3, 0.57);
119
- play("pop", r3(cutEnd + 0.9), 0.35, 0.72);
135
+ const pop = r3(cutEnd + 0.9);
136
+ if (pop < getFootageFilmSeconds(film, edl)) play("pop", pop, 0.35, 0.72);
120
137
  }
121
138
  return cues;
122
139
  }
@@ -202,10 +219,17 @@ export function composeFootage(input: FootageComposeInput): string {
202
219
 
203
220
  const tail = r3(end - cutEnd);
204
221
  const endCard = film.endCard;
222
+ const lastFrameHtml = `<img id="last" class="clip shot" src="${escapeHtml(assets.lastFrame)}" data-start="${cutEnd}" data-duration="${tail}" />`;
223
+ // The full card's entrances were timed for 3 s; a shorter card plays them faster, so the last one ends on screen.
224
+ const pace = endCard === null ? 1 : Math.min(1, getEndCardSeconds(endCard) / DEFAULT_END_CARD_SECONDS);
225
+ const paced = (seconds: number): number => r3(seconds * pace);
205
226
  const endCardHtml =
206
227
  endCard === null
207
228
  ? ""
208
- : `<img id="last" class="clip shot" src="${escapeHtml(assets.lastFrame)}" data-start="${cutEnd}" data-duration="${tail}" />
229
+ : endCard.layout === "logo"
230
+ ? `${lastFrameHtml}
231
+ ${getLogoCardHtml(endCard, assets.logo, input.brandName)}`
232
+ : `${lastFrameHtml}
209
233
  <div class="shade" id="shade"></div>
210
234
  <div class="endcard">
211
235
  <div class="brand" id="ec-brand">${assets.logo === null ? "" : `<img class="logo" src="${escapeHtml(assets.logo)}" alt="" />`}<span>${escapeHtml(input.brandName)}</span></div>
@@ -216,13 +240,16 @@ export function composeFootage(input: FootageComposeInput): string {
216
240
  const endCardTweens =
217
241
  endCard === null
218
242
  ? []
219
- : [
220
- `tl.fromTo("#shade", { opacity: 0 }, { opacity: 0.82, duration: 0.45, ease: "power2.out" }, ${cutEnd});`,
221
- `tl.fromTo("#ec-brand", { y: 30, opacity: 0 }, { y: 0, opacity: 1, duration: 0.5, ease: "power3.out" }, ${r3(cutEnd + 0.3)});`,
222
- `tl.fromTo("#ec-headline", { y: 40, opacity: 0 }, { y: 0, opacity: 1, duration: 0.6, ease: "power3.out" }, ${r3(cutEnd + 0.45)});`,
223
- `tl.fromTo("#ec-url", { y: 30, opacity: 0, scale: 0.94 }, { y: 0, opacity: 1, scale: 1, duration: 0.55, ease: "power3.out" }, ${r3(cutEnd + 0.9)});`,
224
- ...(endCard.note.length > 0 ? [`tl.fromTo("#ec-note", { opacity: 0 }, { opacity: 1, duration: 0.5, ease: "power2.out" }, ${r3(cutEnd + 1.3)});`] : []),
225
- ];
243
+ : endCard.layout === "logo"
244
+ ? [`tl.fromTo("#ec-logo-card", { opacity: 0 }, { opacity: 1, duration: ${r3(endCard.fadeSeconds ?? DEFAULT_LOGO_END_CARD_FADE_SECONDS)}, ease: "none" }, ${cutEnd});`]
245
+ : [
246
+ `tl.fromTo("#shade", { opacity: 0 }, { opacity: 0.82, duration: ${paced(0.45)}, ease: "power2.out" }, ${cutEnd});`,
247
+ `tl.fromTo("#ec-brand", { y: 30, opacity: 0 }, { y: 0, opacity: 1, duration: ${paced(0.5)}, ease: "power3.out" }, ${r3(cutEnd + paced(0.3))});`,
248
+ `tl.fromTo("#ec-headline", { y: 40, opacity: 0 }, { y: 0, opacity: 1, duration: ${paced(0.6)}, ease: "power3.out" }, ${r3(cutEnd + paced(0.45))});`,
249
+ `tl.fromTo("#ec-url", { y: 30, opacity: 0, scale: 0.94 }, { y: 0, opacity: 1, scale: 1, duration: ${paced(0.55)}, ease: "power3.out" }, ${r3(cutEnd + paced(0.9))});`,
250
+ ...(endCard.note.length > 0 ? [`tl.fromTo("#ec-note", { opacity: 0 }, { opacity: 1, duration: ${paced(0.5)}, ease: "power2.out" }, ${r3(cutEnd + paced(1.3))});`] : []),
251
+ ];
252
+ const logoBox = getLogoCardBox(film, frame);
226
253
 
227
254
  const bodyFont = fontStack(fonts.body, "sans-serif");
228
255
  const headingFont = fonts.heading === null ? bodyFont : fontStack(fonts.heading, "sans-serif");
@@ -252,6 +279,12 @@ html,body{width:${frame.width}px;height:${frame.height}px;overflow:hidden;backgr
252
279
  .headline{font-family:${headingFont};font-weight:500;font-size:${input.headlineSize}px;letter-spacing:-.025em;line-height:1.02;margin-top:44px}
253
280
  .url{display:inline-block;margin-top:40px;padding:20px 38px;border-radius:999px;font-size:44px;font-weight:600;color:${c.onCta};background:${c.cta}}
254
281
  .note{margin-top:26px;font-size:30px;color:${c.muted}}
282
+ .logocard{position:absolute;inset:0;background:${c.background};opacity:0}
283
+ .logobox{position:absolute;top:${logoBox.top}px;bottom:${logoBox.bottom}px;left:${logoBox.left}px;right:${logoBox.right}px;display:flex;flex-direction:column;justify-content:center;align-items:center;gap:48px;text-align:center}
284
+ .mark{display:block;max-width:min(100%,${LOGO_CARD_MARK.width}px);max-height:${LOGO_CARD_MARK.height}px;width:auto;height:auto}
285
+ .mark.vector{width:min(100%,${LOGO_CARD_MARK.width}px);height:${LOGO_CARD_MARK.height}px;object-fit:contain}
286
+ .markname{font-family:${headingFont};font-weight:600;font-size:96px;letter-spacing:-.02em}
287
+ .logoline{font-family:${headingFont};font-weight:600;font-size:${LOGO_CARD_LINE_SIZE}px;line-height:1.15;letter-spacing:-.01em}
255
288
  </style>
256
289
  </head>
257
290
  <body>
@@ -279,6 +312,28 @@ window.__timelines["${COMPOSITION_ID}"] = tl;
279
312
  `;
280
313
  }
281
314
 
315
+ /**
316
+ * The logo card (`layout: "logo"`): the brand's background over the whole frame, the logo (an SVG drawn as a vector to
317
+ * fill its box, a PNG at most at its own size, so neither is drawn soft) or the brand name, and the optional line.
318
+ */
319
+ function getLogoCardHtml(card: LogoFootageEndCard, logo: string | null, brandName: string): string {
320
+ const isVector = logo !== null && /\.svg$/i.test(logo);
321
+ const mark = logo === null ? `<span class="markname">${escapeHtml(brandName)}</span>` : `<img class="mark${isVector ? " vector" : ""}" src="${escapeHtml(logo)}" alt="" />`;
322
+ const line = card.line.trim().length > 0 ? `<p class="logoline">${escapeHtml(card.line)}</p>` : "";
323
+ return `<div class="logocard" id="ec-logo-card"><div class="logobox">${mark}${line}</div></div>`;
324
+ }
325
+
326
+ /**
327
+ * Where the logo card's content sits, in px from the frame's edges: a 9:16 film keeps it inside its caption preset's
328
+ * safe zone (`CAPTION_SAFE_ZONES`, `all` without a preset), centred between equal sides; other frames keep 80 px.
329
+ */
330
+ export function getLogoCardBox(film: Pick<FootageFilm, "format" | "captionPreset">, frame: { width: number; height: number }): { top: number; bottom: number; left: number; right: number } {
331
+ if (film.format !== "9:16" || frame.height !== 1920) return { top: 80, bottom: 80, left: 80, right: 80 };
332
+ const zone = CAPTION_SAFE_ZONES[film.captionPreset ?? "all"];
333
+ const side = Math.max(zone.left, zone.right);
334
+ return { top: zone.top, bottom: zone.bottom, left: side, right: side };
335
+ }
336
+
282
337
  /**
283
338
  * A page script that shrinks each caption's font in 1 px steps until its text takes at most `maxLines` lines, or the
284
339
  * font reaches `minFontSize`. Only the browser knows how the font wraps, so it measures there: once at load and again
@@ -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
  }