@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
@@ -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
  /**
@@ -1,25 +1,31 @@
1
- import { existsSync, mkdirSync, rmSync } from "node:fs";
1
+ import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
2
2
  import { join } from "node:path";
3
3
  import { setTimeout as sleep } from "node:timers/promises";
4
4
 
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 } from "./clip-sound.js";
8
+ import { prepareClipSounds, type ClipSound } from "./clip-sound.js";
9
+ import { isSilent, readLoudnessMeasurement } from "./loudness.js";
9
10
  import { writeCacheFile } from "./cache.js";
10
11
  import type { Edl } from "./edl.js";
11
12
  import type { FootageFilm } from "./film.js";
12
13
  import { getClipCacheKey } from "./paid.js";
13
14
  import { getFfmpegReporting, type FootageResult, type FootageRunOptions, type PreparedClip } from "./pipeline.js";
14
- import { runFfmpeg, withFfmpegFailureReporting } from "./process.js";
15
+ import { runFfmpeg, runProcess, withFfmpegFailureReporting } from "./process.js";
15
16
  import { toPaidAudio, type IsolationProvider, type PaidAudio } from "./providers.js";
16
17
  import {
17
18
  buildRangeAudioArgs,
18
19
  buildRangeLayArgs,
20
+ buildRangeMeasureArgs,
21
+ formatSpeechRangeGain,
19
22
  getPlanOptions,
23
+ getRangeInputGainDb,
24
+ getSpeechRangeGainPath,
20
25
  getSpeechRangeCache,
21
26
  getSpeechRangeWindows,
22
27
  planSpeechRanges,
28
+ readSpeechRangeGain,
23
29
  DEFAULT_SPEECH_RANGE_FADE_MS,
24
30
  type LaidRange,
25
31
  type PlanSpeechRangesOptions,
@@ -36,7 +42,9 @@ import {
36
42
  * (issue #1127): only a cancel stops the call. The ranges reach the provider's minimum input (`minSeconds`, issue
37
43
  * #1140): near ranges of a clip are merged, a short one is widened with the clip's own context and only the part the
38
44
  * cut hears is laid; a range that still cannot pass is never sent. A refusal the provider marks not retryable
39
- * (`isRetryable: false`, e.g. a 400 `audio_too_short`) is not asked again (issue #1141).
45
+ * (`isRetryable: false`, e.g. a 400 `audio_too_short`) is not asked again (issue #1141). Every window lands at the
46
+ * level of the clip's pre-gained sound (issue #1159): a bought range records the gain it was cut at next to its cached
47
+ * file, and a cached range cut from the un-gained sound (bought before the pre-gain) is raised by the clip's pre-gain.
40
48
  */
41
49
 
42
50
  /**
@@ -104,11 +112,18 @@ export interface IsolatedSpeechRange extends SpeechRange {
104
112
  * sent, its window keeps the clip's own sound); `not_bought` without `isCommit`.
105
113
  */
106
114
  outcome: SpeechRangeOutcome;
115
+ /**
116
+ * The dB its cleaned voice was raised by when laid (issue #1159): the clip's pre-gain for a range cut from the
117
+ * clip's un-gained sound, else 0; 0 when it is not laid.
118
+ */
119
+ gainDb: number;
107
120
  }
108
121
 
109
122
  export interface IsolatedSpeech {
110
123
  /** Every clip's audio for the speech track: its laid file, or its lossless sound when none of its ranges is laid. */
111
124
  speech: Record<string, string>;
125
+ /** Each clip's pre-gain in dB (`prepareClipSounds`): the gain of the sound its speech file is made from (issue #1159). */
126
+ speechGainDb: Record<string, number>;
112
127
  ranges: IsolatedSpeechRange[];
113
128
  }
114
129
 
@@ -155,11 +170,11 @@ async function runIsolateSpeechRanges(
155
170
  }
156
171
  const cache = options.rangeCache?.(range, clipKey) ?? getSpeechRangeCache(film.id, clipKey, range, { cacheDir: options.cacheDir, provider: providers.isolation.id });
157
172
  if (range.skip !== undefined) {
158
- ranges.push({ ...range, cacheKey: cache.key, path: cache.path, cached: false, laid: false, outcome: { kind: "skipped", ...range.skip } });
173
+ ranges.push({ ...range, cacheKey: cache.key, path: cache.path, cached: false, laid: false, outcome: { kind: "skipped", ...range.skip }, gainDb: 0 });
159
174
  continue;
160
175
  }
161
176
  const cached = existsSync(cache.path);
162
- ranges.push({ ...range, cacheKey: cache.key, path: cache.path, cached, laid: cached, outcome: cached ? { kind: "cached" } : { kind: "not_bought" } });
177
+ ranges.push({ ...range, cacheKey: cache.key, path: cache.path, cached, laid: cached, outcome: cached ? { kind: "cached" } : { kind: "not_bought" }, gainDb: 0 });
163
178
  }
164
179
  const skipped = ranges.filter((range) => range.outcome.kind === "skipped");
165
180
  if (skipped.length > 0) {
@@ -206,6 +221,8 @@ async function runIsolateSpeechRanges(
206
221
  }
207
222
  const paid = answer.paid;
208
223
  writeCacheFile(range.path, paid.audio);
224
+ // The gain of the sound it was cut from, so a later call lays it at the level of the clip's sound then (#1159).
225
+ writeCacheFile(getSpeechRangeGainPath(range.path), formatSpeechRangeGain(sounds[clip.clip.id]?.gainDb ?? 0));
209
226
  range.laid = true;
210
227
  range.outcome = { kind: "bought", attempts: answer.attempts };
211
228
  options.onCharge?.({
@@ -229,25 +246,63 @@ async function runIsolateSpeechRanges(
229
246
  log(`voice isolation DRY RUN: ${String(missing.length)} range${missing.length === 1 ? "" : "s"} (${seconds.toFixed(1)} s) not cached, laid with the clip's own sound. Run with --commit to pay.`);
230
247
  }
231
248
  const speech: Record<string, string> = {};
249
+ const speechGainDb: Record<string, number> = {};
232
250
  for (const clip of clips) {
233
251
  const id = clip.clip.id;
234
252
  speech[id] = getSound(clip);
253
+ const clipGainDb = sounds[id]?.gainDb ?? 0;
254
+ speechGainDb[id] = clipGainDb;
235
255
  const laidRanges = ranges.filter((range) => range.clip === id && range.laid);
236
256
  if (laidRanges.length === 0) continue;
237
257
  const laid: LaidRange[] = [];
238
258
  for (const window of getSpeechRangeWindows(laidRanges)) {
239
- const file = laidRanges.find((range) => range === window.range)?.path;
240
- if (file === undefined) continue;
259
+ const range = laidRanges.find((candidate) => candidate === window.range);
260
+ if (range === undefined) continue;
261
+ const file = range.path;
241
262
  const probed = await probeAudio(file, aborting);
242
- if (!probed.ok) return err(`${describeRange(window.range)}: the cleaned voice at ${file} does not read (${probed.error}); delete it and run again.`);
243
- laid.push({ window, file, isMono: probed.probe.channels === 1 });
263
+ if (!probed.ok) return err(`${describeRange(range)}: the cleaned voice at ${file} does not read (${probed.error}); delete it and run again.`);
264
+ const inputGainDb = await getCachedInputGainDb(range, { sound: sounds[id], file, ...aborting });
265
+ const gainDb = Math.round((clipGainDb - inputGainDb) * 100) / 100 || 0;
266
+ range.gainDb = gainDb;
267
+ if (gainDb !== 0) log(`voice isolation: ${describeRange(range)} was cut from the clip's sound at ${String(inputGainDb)} dB, laid over it at ${String(clipGainDb)} dB: raised by ${String(gainDb)} dB.`);
268
+ laid.push({ window, file, isMono: probed.probe.channels === 1, gainDb });
244
269
  }
245
270
  const output = join(buildDir, "audio", `${id}.ranges.wav`);
246
271
  mkdirSync(join(buildDir, "audio"), { recursive: true });
247
272
  await runFfmpeg(`Laying the cleaned voice over clip ${id}`, buildRangeLayArgs(getSound(clip), laid, output, { fadeMs: options.fadeMs ?? DEFAULT_SPEECH_RANGE_FADE_MS }), { ...aborting, output });
248
273
  speech[id] = output;
249
274
  }
250
- return ok({ speech, ranges });
275
+ return ok({ speech, speechGainDb, ranges });
276
+ }
277
+
278
+ /**
279
+ * The gain of the sound a laid range's cleaned voice was cut from (issue #1159): the clip's pre-gain when it was bought
280
+ * in this call; its record (`getSpeechRangeGainPath`) when there is one; else told from its loudness against the same
281
+ * range of the clip's pre-gained sound (`getRangeInputGainDb`), for a range cached before the record existed.
282
+ */
283
+ async function getCachedInputGainDb(range: IsolatedSpeechRange, input: { sound: ClipSound | undefined; file: string; signal?: AbortSignal }): Promise<number> {
284
+ const clipGainDb = input.sound?.gainDb ?? 0;
285
+ if (range.outcome.kind === "bought" || input.sound === undefined) return clipGainDb;
286
+ const record = getSpeechRangeGainPath(input.file);
287
+ if (existsSync(record)) {
288
+ const recorded = readSpeechRangeGain(readFileSync(record, "utf8"));
289
+ if (recorded !== null) return recorded;
290
+ }
291
+ if (clipGainDb === 0) return 0;
292
+ const cleanedLufs = await measureRangeLoudness(`the cleaned voice of ${describeRange(range)}`, buildRangeMeasureArgs(input.file), input.signal);
293
+ const baseLufs = await measureRangeLoudness(`${describeRange(range)} of the clip's sound`, buildRangeMeasureArgs(input.sound.file, range), input.signal);
294
+ return getRangeInputGainDb({ clipGainDb, cleanedLufs, baseLufs });
295
+ }
296
+
297
+ /** Integrated loudness in LUFS of a measuring pass (`buildRangeMeasureArgs`); null for silence. Throws naming `label` when ffmpeg fails. */
298
+ async function measureRangeLoudness(label: string, args: string[], signal: AbortSignal | undefined): Promise<number | null> {
299
+ const step = `Measuring ${label}`;
300
+ const measured = await runProcess({ command: "ffmpeg", args, ...(signal === undefined ? {} : { signal }) });
301
+ if (measured.kind === "not-started") throw new Error(`${step}: ffmpeg did not start (${measured.error}).`);
302
+ if (measured.code !== 0) throw new Error(`${step}: ffmpeg ended with code ${String(measured.code)}: ${measured.stderr.trim().split("\n").slice(-3).join(" | ")}.`);
303
+ const measurement = readLoudnessMeasurement(measured.stderr);
304
+ if (measurement === null) throw new Error(`${step}: ffmpeg printed no loudnorm measurement.`);
305
+ return isSilent(measurement) ? null : measurement.inputI;
251
306
  }
252
307
 
253
308
  type IsolationAnswer = { ok: true; paid: PaidAudio; attempts: number } | { ok: false; error: string; attempts: number; providerFailure: ProviderFailure | null };
@@ -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 {
@@ -167,6 +167,12 @@ export type TranscribeOutcome =
167
167
  words: Record<string, TimedWord[]>;
168
168
  /** The audio each clip's speech is cut from (the cleaned voice when isolated). */
169
169
  speech: Record<string, string>;
170
+ /**
171
+ * Each clip's pre-gain in dB (`prepareClipSounds`, issue #1159): the gain of the sound `speech` is made from. An
172
+ * app that lays its own cached ranges raises one cut from the clip's un-gained sound by it. Always answered;
173
+ * optional so an app's own `ready` outcome still compiles.
174
+ */
175
+ speechGainDb?: Record<string, number>;
170
176
  };
171
177
 
172
178
  export function getFrame(film: Pick<FootageFilm, "format">): Frame {
@@ -295,10 +301,10 @@ async function decodeIsolatedVoice(cached: string, clipId: string, buildDir: str
295
301
  return output;
296
302
  }
297
303
 
298
- /** Each clip's lossless, pre-gained sound (`prepareClipSounds`), by clip id. */
299
- async function getClipSoundFiles(clips: PreparedClip[], buildDir: string, signal: AbortSignal | undefined): Promise<Record<string, string>> {
300
- const sounds = await prepareClipSounds(clips, { buildDir, ...(signal === undefined ? {} : { signal }) });
301
- return Object.fromEntries(Object.entries(sounds).map(([id, sound]) => [id, sound.file]));
304
+ /** Each clip's lossless, pre-gained sound (`prepareClipSounds`) and its pre-gain in dB, by clip id. */
305
+ async function getClipSoundFiles(clips: PreparedClip[], buildDir: string, signal: AbortSignal | undefined): Promise<{ speech: Record<string, string>; speechGainDb: Record<string, number> }> {
306
+ const sounds = Object.entries(await prepareClipSounds(clips, { buildDir, ...(signal === undefined ? {} : { signal }) }));
307
+ return { speech: Object.fromEntries(sounds.map(([id, sound]) => [id, sound.file])), speechGainDb: Object.fromEntries(sounds.map(([id, sound]) => [id, sound.gainDb])) };
302
308
  }
303
309
 
304
310
  /** The free transcripts of `--placeholder`, written under `placeholder/` for a look; the speech is each clip's lossless sound. */
@@ -308,7 +314,7 @@ async function transcribePlaceholder(clips: PreparedClip[], buildDir: string, si
308
314
  words[clip.clip.id] = clip.clip.role === "talk" ? makePlaceholderTranscript(clip.clip.script, clip.duration) : [];
309
315
  writeTranscript(join(buildDir, "placeholder", `${clip.clip.id}.transcript.json`), words[clip.clip.id] ?? []);
310
316
  }
311
- return { kind: "ready", words, speech: await getClipSoundFiles(clips, buildDir, signal) };
317
+ return { kind: "ready", words, ...(await getClipSoundFiles(clips, buildDir, signal)) };
312
318
  }
313
319
 
314
320
  /** The paid music step, when the film's music still has to be bought; null when it is cached or free. */
@@ -347,7 +353,7 @@ async function runTranscribeFootage(film: FootageFilm, clips: PreparedClip[], op
347
353
  plan.push({ clip, isolated, transcript });
348
354
  }
349
355
  if (steps.length > 0 && !options.isCommit) {
350
- 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);
351
357
  const music = getMusicPaidStep(film, options, total);
352
358
  const all = music === null ? steps : [...steps, music];
353
359
  for (const line of describePaidSteps(all)) log(line);
@@ -357,7 +363,7 @@ async function runTranscribeFootage(film: FootageFilm, clips: PreparedClip[], op
357
363
  const words: Record<string, TimedWord[]> = {};
358
364
  for (const clip of clips) words[clip.clip.id] = [];
359
365
  // Every clip's sound, lossless and pre-gained: what the isolator, the speech to text and the speech track hear (#1139).
360
- const speech = await getClipSoundFiles(clips, buildDir, signal);
366
+ const { speech, speechGainDb } = await getClipSoundFiles(clips, buildDir, signal);
361
367
  const isolating = plan.filter(({ isolated }) => isolated !== null && !existsSync(isolated.path));
362
368
  const transcribing = plan.filter(({ transcript }) => !existsSync(transcript.path));
363
369
  const isolateProgress = createStageProgress(options.onProgress, "isolate", isolating.map(({ clip }) => ({ item: clip.clip.id, seconds: clip.duration })));
@@ -410,7 +416,7 @@ async function runTranscribeFootage(film: FootageFilm, clips: PreparedClip[], op
410
416
  transcribeProgress(index, clip.duration);
411
417
  words[id] = result.value.words;
412
418
  }
413
- return ok({ kind: "ready", words, speech });
419
+ return ok({ kind: "ready", words, speech, speechGainDb });
414
420
  }
415
421
 
416
422
  /** The talking clips' sentences with their ids (`s1`…), as `buildEdl` names them, for choosing what to keep. */
@@ -756,7 +762,9 @@ async function runRenderFootage(
756
762
  if (musicFile !== null) {
757
763
  const keyframes = duckingKeyframes(words, getDuckingOptions(film.music));
758
764
  const output = join(assetsDir, "music.mp3");
759
- 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 })) });
760
768
  }
761
769
  const sfx: Partial<Record<SfxEvent, string>> = {};
762
770
  mkdirSync(join(assetsDir, "sfx"), { recursive: true });
@@ -806,7 +814,10 @@ async function runRenderFootage(
806
814
  if (!prepared.ok) return prepared;
807
815
  const musicAsset = musicFile === null ? null : "assets/music.mp3";
808
816
  const fonts = copyFonts(options.brand.fonts, join(assetsDir, "fonts"));
809
- 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));
810
821
  cpSync(require.resolve("gsap/dist/gsap.min.js"), join(assetsDir, "gsap.min.js"));
811
822
  const base = resolveLayout(film.format, options.layout ?? {});
812
823
  // A caption preset places the 9:16 box in a platform's safe zone; the project's own caption override still wins.
@@ -814,7 +825,7 @@ async function runRenderFootage(
814
825
  const missing = findMissingCaptionGlyphs({
815
826
  fonts: options.brand.fonts,
816
827
  captions: film.captions ? words.map((word) => word.text) : [],
817
- endCard: film.endCard,
828
+ endCard: getEndCardTexts(film.endCard),
818
829
  brandName: options.brand.name,
819
830
  });
820
831
  if (missing.length > 0) {
@@ -835,7 +846,7 @@ async function runRenderFootage(
835
846
  speech: "assets/speech.wav",
836
847
  music: musicAsset,
837
848
  lastFrame: "assets/last.jpg",
838
- logo: options.brand.logo === null ? null : "assets/logo.svg",
849
+ logo: logoAsset,
839
850
  sfx,
840
851
  },
841
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
  }
@@ -214,11 +214,62 @@ export function buildRangeAudioArgs(audio: string, range: Pick<SpeechRange, "sta
214
214
  return ["-v", "error", "-y", "-ss", seconds(range.startMs), "-t", seconds(range.endMs - range.startMs), "-i", audio, "-vn", ...codec, output];
215
215
  }
216
216
 
217
- /** A cleaned range laid back: its file, and whether it is mono (panned to both channels at full level). */
217
+ /**
218
+ * A cleaned range laid back: its file, whether it is mono (panned to both channels at full level), and the dB it is
219
+ * raised by before its fades (`gainDb`, issue #1159: a range cut from the clip's un-gained sound is raised by the
220
+ * clip's pre-gain; absent or 0 leaves it as it is).
221
+ */
218
222
  export interface LaidRange {
219
223
  window: SpeechRangeWindow;
220
224
  file: string;
221
225
  isMono: boolean;
226
+ gainDb?: number;
227
+ }
228
+
229
+ /**
230
+ * Where the gain of the sound a range's cleaned voice was cut from is recorded (issue #1159): next to its cached file,
231
+ * as `<path>.gain.json` holding `{ "inputGainDb": <dB> }`. Commit it with the cached file.
232
+ */
233
+ export function getSpeechRangeGainPath(path: string): string {
234
+ return `${path}.gain.json`;
235
+ }
236
+
237
+ /** The record of `getSpeechRangeGainPath`'s file. */
238
+ export function formatSpeechRangeGain(inputGainDb: number): string {
239
+ return `${JSON.stringify({ inputGainDb })}\n`;
240
+ }
241
+
242
+ /** The input gain in a record's text; null when the text is not such a record. */
243
+ export function readSpeechRangeGain(text: string): number | null {
244
+ let json: unknown;
245
+ try {
246
+ json = JSON.parse(text);
247
+ } catch {
248
+ return null;
249
+ }
250
+ if (typeof json !== "object" || json === null) return null;
251
+ const value = (json as Record<string, unknown>).inputGainDb;
252
+ return typeof value === "number" && Number.isFinite(value) ? value : null;
253
+ }
254
+
255
+ /** A measuring pass (`loudnorm`, nothing written) over `file`, or only over `range` of it, as 48 kHz stereo. */
256
+ export function buildRangeMeasureArgs(file: string, range?: Pick<SpeechRange, "startMs" | "endMs">): string[] {
257
+ const window = range === undefined ? [] : ["-ss", seconds(range.startMs), "-t", seconds(range.endMs - range.startMs)];
258
+ const format = `aformat=sample_rates=${String(FOOTAGE_SAMPLE_RATE)}:channel_layouts=stereo`;
259
+ return ["-hide_banner", "-nostats", ...window, "-i", file, "-map", "0:a:0", "-vn", "-af", `${format},loudnorm=I=-23:TP=-2:LRA=11:print_format=json`, "-f", "null", "-"];
260
+ }
261
+
262
+ /**
263
+ * The gain of the sound a cached cleaned range was cut from, told from its loudness (issue #1159): a range cut from
264
+ * the clip's un-gained sound sits about `clipGainDb` under the same range of the pre-gained sound, one cut from the
265
+ * pre-gained sound about level with it (the cleaning takes off a few dB at most). The nearer case wins: 0 (un-gained)
266
+ * or `clipGainDb`. Without a loudness on either side (null: silence) it is `clipGainDb`, so nothing is changed.
267
+ */
268
+ export function getRangeInputGainDb(options: { clipGainDb: number; cleanedLufs: number | null; baseLufs: number | null }): number {
269
+ const { clipGainDb, cleanedLufs, baseLufs } = options;
270
+ if (clipGainDb === 0 || cleanedLufs === null || baseLufs === null) return clipGainDb;
271
+ const difference = cleanedLufs - baseLufs;
272
+ return Math.abs(difference + clipGainDb) < Math.abs(difference) ? 0 : clipGainDb;
222
273
  }
223
274
 
224
275
  /** Milliseconds of the linear crossfade at every join between the clip's own sound and a cleaned window. */
@@ -281,17 +332,18 @@ export function buildRangeLayArgs(base: string, laid: readonly LaidRange[], outp
281
332
  const inputs = ["-i", base];
282
333
  const gains: string[] = [];
283
334
  const parts: string[] = [];
284
- laid.forEach(({ window, file, isMono }, index) => {
335
+ laid.forEach(({ window, file, isMono, gainDb }, index) => {
285
336
  const fade = byWindow.get(window);
286
337
  if (fade === undefined) return;
287
338
  inputs.push("-i", file);
288
339
  gains.push(buildGainExpression(fade));
289
340
  const channels = isMono ? "pan=stereo|c0=c0|c1=c0," : "";
341
+ const volume = gainDb === undefined || gainDb === 0 ? "" : `,volume=${String(gainDb)}dB`;
290
342
  const fadeIn = fade.inEndMs > fade.inStartMs ? `,afade=t=in:st=0:d=${seconds(fade.inEndMs - fade.inStartMs)}` : "";
291
343
  const fadeOut = fade.outEndMs > fade.outStartMs ? `,afade=t=out:st=${seconds(fade.outStartMs - fade.inStartMs)}:d=${seconds(fade.outEndMs - fade.outStartMs)}` : "";
292
344
  const delay = Math.round((fade.inStartMs * FOOTAGE_SAMPLE_RATE) / 1000);
293
345
  parts.push(
294
- `[${index + 1}:a]atrim=start=${seconds(fade.inStartMs - window.range.startMs)}:end=${seconds(fade.outEndMs - window.range.startMs)},asetpts=PTS-STARTPTS,${channels}${format}${fadeIn}${fadeOut},adelay=${String(delay)}S:all=1[w${String(index)}]`,
346
+ `[${index + 1}:a]atrim=start=${seconds(fade.inStartMs - window.range.startMs)}:end=${seconds(fade.outEndMs - window.range.startMs)},asetpts=PTS-STARTPTS,${channels}${format}${volume}${fadeIn}${fadeOut},adelay=${String(delay)}S:all=1[w${String(index)}]`,
295
347
  );
296
348
  });
297
349
  parts.unshift(`[0:a]${format},aeval='val(ch)*(1-(${gains.join("+")}))':c=same[base]`);
package/src/index.ts CHANGED
@@ -163,18 +163,31 @@ export {
163
163
  countOgSlides,
164
164
  getDefaultOgSize,
165
165
  OG_TEMPLATE_IDS,
166
+ PHOTO_COVER_LAYOUTS,
166
167
  getOgPalette,
168
+ FONT_USES,
169
+ findMissingCharacters,
167
170
  loadOgFonts,
171
+ readFontFileInfo,
168
172
  renderConfiguredOgImage,
169
173
  renderOgImage,
174
+ isPointUnderCoverText,
170
175
  renderPhotoCover,
171
176
  type ConfiguredOgImageOptions,
177
+ type FontFileFormat,
178
+ type FontFileInfo,
179
+ type FontFileWeight,
180
+ type FontUnusableReason,
181
+ type FontUse,
182
+ type FontUseVerdict,
172
183
  type OgBrand,
173
184
  type OgImageInput,
174
185
  type OgResult,
175
186
  type OgTemplateId,
176
187
  type PhotoCover,
177
188
  type PhotoCoverInput,
189
+ type PhotoCoverLayout,
190
+ type PhotoCoverTone,
178
191
  } from "./og/index.js";
179
192
  export { buildPosts, postsMarkdown, type PlatformPost, type PostsInput } from "./posts/posts.js";
180
193
  export { createActionScene, getLocator, runAction, type LocatorSource } from "./record/actions.js";
@@ -207,8 +220,13 @@ export {
207
220
  CAPTION_PRESETS,
208
221
  CAPTION_STYLES,
209
222
  DEFAULT_EDIT,
223
+ DEFAULT_END_CARD_SECONDS,
224
+ DEFAULT_LOGO_END_CARD_FADE_SECONDS,
225
+ DEFAULT_LOGO_END_CARD_SECONDS,
210
226
  getDefaultFillers,
211
227
  getDeclickLevel,
228
+ getEndCardSeconds,
229
+ getEndCardTexts,
212
230
  getFootageEdit,
213
231
  type CaptionPreset,
214
232
  type CaptionStyle,
@@ -219,28 +237,33 @@ export {
219
237
  type CutTransition,
220
238
  type JumpTransition,
221
239
  type FootageClip,
240
+ type FootageEndCard,
222
241
  type FootageFilm,
223
242
  type FootageMusic,
243
+ type FullFootageEndCard,
244
+ type LogoFootageEndCard,
224
245
  type FootageSpeech,
225
246
  type FootageTransitions,
226
247
  type MusicSource,
227
248
  } from "./footage/film.js";
228
249
  export {
229
- DECLICK_GATE_FADE,
230
- DECLICK_IMPULSE_DB,
250
+ DECLICK_AR_CONTEXT,
251
+ DECLICK_AR_ORDER,
252
+ DECLICK_CROSSFADE,
231
253
  DECLICK_LEVELS,
232
254
  DECLICK_MAX_IMPULSE,
233
255
  DECLICK_SETTINGS,
234
- DECLICK_WORD_WINDOW,
256
+ DECLICK_WORD_GUARD,
235
257
  buildDeclickDecodeArgs,
236
258
  buildDeclickEncodeArgs,
237
259
  declickSamples,
238
260
  declickSpeech,
239
261
  describeDeclick,
240
262
  findImpulses,
241
- getDeclickGain,
242
- getGateWindows,
263
+ getArPolynomial,
264
+ getRepairZones,
243
265
  getRunningMedian,
266
+ repairSpan,
244
267
  type ActiveDeclickLevel,
245
268
  type DeclickLevel,
246
269
  type DeclickReport,
@@ -398,6 +421,7 @@ export {
398
421
  composeFootage,
399
422
  getFootageFilmSeconds,
400
423
  getFootageSfxCues,
424
+ getLogoCardBox,
401
425
  getSegmentScales,
402
426
  type FootageComposeAssets,
403
427
  type FootageComposeInput,
@@ -535,10 +559,15 @@ export {
535
559
  DEFAULT_SPEECH_RANGE_MIN_PAD,
536
560
  buildRangeAudioArgs,
537
561
  buildRangeLayArgs,
562
+ buildRangeMeasureArgs,
563
+ formatSpeechRangeGain,
564
+ getRangeInputGainDb,
538
565
  getSpeechRangeCache,
539
566
  getSpeechRangeFades,
567
+ getSpeechRangeGainPath,
540
568
  getSpeechRangeWindows,
541
569
  planSpeechRanges,
570
+ readSpeechRangeGain,
542
571
  type LaidRange,
543
572
  type PlanSpeechRangesOptions,
544
573
  type SpeechRange,