@softure-ai/marketing-kit 0.17.0 → 0.19.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 +52 -0
  2. package/README.md +54 -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/clip-sound.d.ts +59 -4
  13. package/dist/footage/clip-sound.d.ts.map +1 -1
  14. package/dist/footage/clip-sound.js +58 -12
  15. package/dist/footage/clip-sound.js.map +1 -1
  16. package/dist/footage/compose.d.ts +17 -3
  17. package/dist/footage/compose.d.ts.map +1 -1
  18. package/dist/footage/compose.js +61 -17
  19. package/dist/footage/compose.js.map +1 -1
  20. package/dist/footage/declick.d.ts +49 -41
  21. package/dist/footage/declick.d.ts.map +1 -1
  22. package/dist/footage/declick.js +181 -92
  23. package/dist/footage/declick.js.map +1 -1
  24. package/dist/footage/film.d.ts +45 -2
  25. package/dist/footage/film.d.ts.map +1 -1
  26. package/dist/footage/film.js +23 -0
  27. package/dist/footage/film.js.map +1 -1
  28. package/dist/footage/isolate-ranges.d.ts +5 -0
  29. package/dist/footage/isolate-ranges.d.ts.map +1 -1
  30. package/dist/footage/isolate-ranges.js +4 -2
  31. package/dist/footage/isolate-ranges.js.map +1 -1
  32. package/dist/footage/paid.d.ts +1 -1
  33. package/dist/footage/paid.d.ts.map +1 -1
  34. package/dist/footage/paid.js +3 -2
  35. package/dist/footage/paid.js.map +1 -1
  36. package/dist/footage/pipeline.d.ts +11 -0
  37. package/dist/footage/pipeline.d.ts.map +1 -1
  38. package/dist/footage/pipeline.js +28 -17
  39. package/dist/footage/pipeline.js.map +1 -1
  40. package/dist/footage/render.d.ts +5 -1
  41. package/dist/footage/render.d.ts.map +1 -1
  42. package/dist/footage/render.js +6 -2
  43. package/dist/footage/render.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 +22 -0
  65. package/dist/og/photo-cover.d.ts.map +1 -1
  66. package/dist/og/photo-cover.js +27 -9
  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/clip-sound.ts +95 -15
  73. package/src/footage/compose.ts +72 -17
  74. package/src/footage/declick.ts +172 -97
  75. package/src/footage/film.ts +54 -2
  76. package/src/footage/isolate-ranges.ts +9 -3
  77. package/src/footage/paid.ts +3 -3
  78. package/src/footage/pipeline.ts +41 -17
  79. package/src/footage/render.ts +7 -3
  80. package/src/index.ts +31 -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 +14 -0
  85. package/src/og/photo-cover.ts +46 -11
@@ -5,7 +5,7 @@ import { setTimeout as sleep } from "node:timers/promises";
5
5
  import { describeProviderFailure, type ProviderFailure } from "../voice/provider-failure.js";
6
6
  import { err, ok } from "./failure.js";
7
7
  import { probeAudio } from "./audio.js";
8
- import { prepareClipSounds, type ClipSound } from "./clip-sound.js";
8
+ import { prepareClipSounds, type ClipSound, type SpeechPeaks, type SpeechPreGain } from "./clip-sound.js";
9
9
  import { isSilent, readLoudnessMeasurement } from "./loudness.js";
10
10
  import { writeCacheFile } from "./cache.js";
11
11
  import type { Edl } from "./edl.js";
@@ -81,6 +81,8 @@ export type IsolateSpeechRangesOptions = Pick<FootageRunOptions, "buildDir" | "c
81
81
  * An app that already holds paid ranges under its own keys points the block at them.
82
82
  */
83
83
  rangeCache?: SpeechRangeCacheResolver;
84
+ /** How the clip sound's pre-gain treats a true peak above the ceiling (`SpeechPeaks`, issue #1181); default `ceiling`. */
85
+ speechPeaks?: SpeechPeaks;
84
86
  log?: (line: string) => void;
85
87
  };
86
88
 
@@ -124,6 +126,8 @@ export interface IsolatedSpeech {
124
126
  speech: Record<string, string>;
125
127
  /** Each clip's pre-gain in dB (`prepareClipSounds`): the gain of the sound its speech file is made from (issue #1159). */
126
128
  speechGainDb: Record<string, number>;
129
+ /** What each clip's pre-gain reached (`ClipSound.preGain`, issue #1181): on target, or held by the peak ceiling. */
130
+ speechPreGain: Record<string, SpeechPreGain>;
127
131
  ranges: IsolatedSpeechRange[];
128
132
  }
129
133
 
@@ -188,7 +192,7 @@ async function runIsolateSpeechRanges(
188
192
  options.onProgress?.({ step: "isolate", item: range.clip, itemIndex: index + 1, itemCount: buying.length, done: Math.round(done * 1000) / 1000, total: Math.round(total * 1000) / 1000 });
189
193
  };
190
194
  // Every clip's sound, lossless and pre-gained (#1139): what the isolator hears and what the cleaned ranges are laid over.
191
- const sounds = await prepareClipSounds(clips, { buildDir, ...aborting });
195
+ const sounds = await prepareClipSounds(clips, { buildDir, log, ...aborting, ...(options.speechPeaks === undefined ? {} : { peaks: options.speechPeaks }) });
192
196
  const getSound = (clip: PreparedClip): string => sounds[clip.clip.id]?.file ?? clip.file;
193
197
  const workDir = join(buildDir, "audio", "ranges");
194
198
  for (const [index, range] of buying.entries()) {
@@ -247,11 +251,13 @@ async function runIsolateSpeechRanges(
247
251
  }
248
252
  const speech: Record<string, string> = {};
249
253
  const speechGainDb: Record<string, number> = {};
254
+ const speechPreGain: Record<string, SpeechPreGain> = {};
250
255
  for (const clip of clips) {
251
256
  const id = clip.clip.id;
252
257
  speech[id] = getSound(clip);
253
258
  const clipGainDb = sounds[id]?.gainDb ?? 0;
254
259
  speechGainDb[id] = clipGainDb;
260
+ speechPreGain[id] = sounds[id]?.preGain ?? { kind: "silent" };
255
261
  const laidRanges = ranges.filter((range) => range.clip === id && range.laid);
256
262
  if (laidRanges.length === 0) continue;
257
263
  const laid: LaidRange[] = [];
@@ -272,7 +278,7 @@ async function runIsolateSpeechRanges(
272
278
  await runFfmpeg(`Laying the cleaned voice over clip ${id}`, buildRangeLayArgs(getSound(clip), laid, output, { fadeMs: options.fadeMs ?? DEFAULT_SPEECH_RANGE_FADE_MS }), { ...aborting, output });
273
279
  speech[id] = output;
274
280
  }
275
- return ok({ speech, speechGainDb, ranges });
281
+ return ok({ speech, speechGainDb, speechPreGain, ranges });
276
282
  }
277
283
 
278
284
  /**
@@ -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) });
@@ -12,9 +12,9 @@ import { copyFonts } from "../render/render.js";
12
12
  import type { TtsResult } from "../voice/provider.js";
13
13
  import type { TimedWord } from "../voice/voiceover.js";
14
14
  import { checkMusicFileType, describeAudioProbe, probeAudio } from "./audio.js";
15
- import { prepareClipSounds } from "./clip-sound.js";
15
+ import { prepareClipSounds, type SpeechPeaks, type SpeechPreGain } 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 {
@@ -145,6 +145,11 @@ export interface FootageRunOptions {
145
145
  * person to run again. Every failure also gets one `log` line with the step and its full command.
146
146
  */
147
147
  onFfmpegFailure?: FfmpegFailureHook;
148
+ /**
149
+ * How the clip sound's pre-gain treats a true peak above `SPEECH_PRE_GAIN.peakCeiling` (issue #1181): `ceiling`
150
+ * (default) stops the gain there; `float` reaches the target and writes the clip sound as 32-bit float.
151
+ */
152
+ speechPeaks?: SpeechPeaks;
148
153
  }
149
154
 
150
155
  export interface PreparedClip {
@@ -173,6 +178,11 @@ export type TranscribeOutcome =
173
178
  * optional so an app's own `ready` outcome still compiles.
174
179
  */
175
180
  speechGainDb?: Record<string, number>;
181
+ /**
182
+ * What each clip's pre-gain reached (`ClipSound.preGain`, issue #1181): `held_by_peak_ceiling` names a clip the
183
+ * speech chain hears under the target. Always answered; optional so an app's own `ready` outcome still compiles.
184
+ */
185
+ speechPreGain?: Record<string, SpeechPreGain>;
176
186
  };
177
187
 
178
188
  export function getFrame(film: Pick<FootageFilm, "format">): Frame {
@@ -301,20 +311,29 @@ async function decodeIsolatedVoice(cached: string, clipId: string, buildDir: str
301
311
  return output;
302
312
  }
303
313
 
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])) };
314
+ /** Each clip's lossless, pre-gained sound (`prepareClipSounds`), its pre-gain in dB and what it reached, by clip id. */
315
+ async function getClipSoundFiles(
316
+ clips: PreparedClip[],
317
+ options: Pick<FootageRunOptions, "buildDir" | "signal" | "speechPeaks" | "log">,
318
+ ): Promise<{ speech: Record<string, string>; speechGainDb: Record<string, number>; speechPreGain: Record<string, SpeechPreGain> }> {
319
+ const { buildDir, signal, speechPeaks, log } = options;
320
+ const sounds = Object.entries(await prepareClipSounds(clips, { buildDir, log, ...(signal === undefined ? {} : { signal }), ...(speechPeaks === undefined ? {} : { peaks: speechPeaks }) }));
321
+ return {
322
+ speech: Object.fromEntries(sounds.map(([id, sound]) => [id, sound.file])),
323
+ speechGainDb: Object.fromEntries(sounds.map(([id, sound]) => [id, sound.gainDb])),
324
+ speechPreGain: Object.fromEntries(sounds.map(([id, sound]) => [id, sound.preGain])),
325
+ };
308
326
  }
309
327
 
310
328
  /** The free transcripts of `--placeholder`, written under `placeholder/` for a look; the speech is each clip's lossless sound. */
311
- async function transcribePlaceholder(clips: PreparedClip[], buildDir: string, signal: AbortSignal | undefined): Promise<TranscribeOutcome> {
329
+ async function transcribePlaceholder(clips: PreparedClip[], options: FootageRunOptions): Promise<TranscribeOutcome> {
330
+ const { buildDir } = options;
312
331
  const words: Record<string, TimedWord[]> = {};
313
332
  for (const clip of clips) {
314
333
  words[clip.clip.id] = clip.clip.role === "talk" ? makePlaceholderTranscript(clip.clip.script, clip.duration) : [];
315
334
  writeTranscript(join(buildDir, "placeholder", `${clip.clip.id}.transcript.json`), words[clip.clip.id] ?? []);
316
335
  }
317
- return { kind: "ready", words, ...(await getClipSoundFiles(clips, buildDir, signal)) };
336
+ return { kind: "ready", words, ...(await getClipSoundFiles(clips, options)) };
318
337
  }
319
338
 
320
339
  /** The paid music step, when the film's music still has to be bought; null when it is cached or free. */
@@ -337,7 +356,7 @@ export function transcribeFootage(film: FootageFilm, clips: PreparedClip[], opti
337
356
  /** The body of `transcribeFootage`, inside its ffmpeg failure reporting. */
338
357
  async function runTranscribeFootage(film: FootageFilm, clips: PreparedClip[], options: FootageRunOptions): Promise<FootageResult<TranscribeOutcome>> {
339
358
  const { buildDir, providers, log, signal } = options;
340
- if (options.isPlaceholder) return ok(await transcribePlaceholder(clips, buildDir, signal));
359
+ if (options.isPlaceholder) return ok(await transcribePlaceholder(clips, options));
341
360
  const keyTerms = getFilmKeyTerms(film);
342
361
  if (!keyTerms.ok) return err(`footage film ${film.id}: ${keyTerms.errors.join(" ")}`, { kind: "input" });
343
362
  const sttKeyTerms = keyTerms.terms.length === 0 ? {} : { keyTerms: keyTerms.terms };
@@ -353,7 +372,7 @@ async function runTranscribeFootage(film: FootageFilm, clips: PreparedClip[], op
353
372
  plan.push({ clip, isolated, transcript });
354
373
  }
355
374
  if (steps.length > 0 && !options.isCommit) {
356
- const total = clips.reduce((sum, clip) => sum + clip.duration, 0) + (film.endCard === null ? 0 : END_CARD_SECONDS);
375
+ const total = clips.reduce((sum, clip) => sum + clip.duration, 0) + getEndCardSeconds(film.endCard);
357
376
  const music = getMusicPaidStep(film, options, total);
358
377
  const all = music === null ? steps : [...steps, music];
359
378
  for (const line of describePaidSteps(all)) log(line);
@@ -363,7 +382,7 @@ async function runTranscribeFootage(film: FootageFilm, clips: PreparedClip[], op
363
382
  const words: Record<string, TimedWord[]> = {};
364
383
  for (const clip of clips) words[clip.clip.id] = [];
365
384
  // Every clip's sound, lossless and pre-gained: what the isolator, the speech to text and the speech track hear (#1139).
366
- const { speech, speechGainDb } = await getClipSoundFiles(clips, buildDir, signal);
385
+ const { speech, speechGainDb, speechPreGain } = await getClipSoundFiles(clips, options);
367
386
  const isolating = plan.filter(({ isolated }) => isolated !== null && !existsSync(isolated.path));
368
387
  const transcribing = plan.filter(({ transcript }) => !existsSync(transcript.path));
369
388
  const isolateProgress = createStageProgress(options.onProgress, "isolate", isolating.map(({ clip }) => ({ item: clip.clip.id, seconds: clip.duration })));
@@ -416,7 +435,7 @@ async function runTranscribeFootage(film: FootageFilm, clips: PreparedClip[], op
416
435
  transcribeProgress(index, clip.duration);
417
436
  words[id] = result.value.words;
418
437
  }
419
- return ok({ kind: "ready", words, speech, speechGainDb });
438
+ return ok({ kind: "ready", words, speech, speechGainDb, speechPreGain });
420
439
  }
421
440
 
422
441
  /** The talking clips' sentences with their ids (`s1`…), as `buildEdl` names them, for choosing what to keep. */
@@ -762,7 +781,9 @@ async function runRenderFootage(
762
781
  if (musicFile !== null) {
763
782
  const keyframes = duckingKeyframes(words, getDuckingOptions(film.music));
764
783
  const output = join(assetsDir, "music.mp3");
765
- tracks.push({ item: "music", seconds, run: ffmpegTrack("The music track", output, () => buildMusicArgs({ input: musicFile, seconds, keyframes, output })) });
784
+ // Under the logo card the music fades out over the card's whole length, to the film's end (issue #1173).
785
+ const fadeOutSeconds = film.endCard?.layout === "logo" ? { fadeOutSeconds: getEndCardSeconds(film.endCard) } : {};
786
+ tracks.push({ item: "music", seconds, run: ffmpegTrack("The music track", output, () => buildMusicArgs({ input: musicFile, seconds, keyframes, output, ...fadeOutSeconds })) });
766
787
  }
767
788
  const sfx: Partial<Record<SfxEvent, string>> = {};
768
789
  mkdirSync(join(assetsDir, "sfx"), { recursive: true });
@@ -812,7 +833,10 @@ async function runRenderFootage(
812
833
  if (!prepared.ok) return prepared;
813
834
  const musicAsset = musicFile === null ? null : "assets/music.mp3";
814
835
  const fonts = copyFonts(options.brand.fonts, join(assetsDir, "fonts"));
815
- if (options.brand.logo !== null) cpSync(options.brand.logo, join(assetsDir, "logo.svg"));
836
+ // The logo card's own logo wins over the brand's; it keeps its extension, so a PNG is drawn as a PNG.
837
+ const logoSource = (film.endCard?.layout === "logo" ? film.endCard.logo : undefined) ?? options.brand.logo;
838
+ const logoAsset = logoSource === null ? null : `assets/logo${extname(logoSource).toLowerCase() || ".svg"}`;
839
+ if (logoSource !== null && logoAsset !== null) cpSync(logoSource, join(buildDir, logoAsset));
816
840
  cpSync(require.resolve("gsap/dist/gsap.min.js"), join(assetsDir, "gsap.min.js"));
817
841
  const base = resolveLayout(film.format, options.layout ?? {});
818
842
  // A caption preset places the 9:16 box in a platform's safe zone; the project's own caption override still wins.
@@ -820,7 +844,7 @@ async function runRenderFootage(
820
844
  const missing = findMissingCaptionGlyphs({
821
845
  fonts: options.brand.fonts,
822
846
  captions: film.captions ? words.map((word) => word.text) : [],
823
- endCard: film.endCard,
847
+ endCard: getEndCardTexts(film.endCard),
824
848
  brandName: options.brand.name,
825
849
  });
826
850
  if (missing.length > 0) {
@@ -841,7 +865,7 @@ async function runRenderFootage(
841
865
  speech: "assets/speech.wav",
842
866
  music: musicAsset,
843
867
  lastFrame: "assets/last.jpg",
844
- logo: options.brand.logo === null ? null : "assets/logo.svg",
868
+ logo: logoAsset,
845
869
  sfx,
846
870
  },
847
871
  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
  }
package/src/index.ts CHANGED
@@ -165,11 +165,21 @@ export {
165
165
  OG_TEMPLATE_IDS,
166
166
  PHOTO_COVER_LAYOUTS,
167
167
  getOgPalette,
168
+ FONT_USES,
169
+ findMissingCharacters,
168
170
  loadOgFonts,
171
+ readFontFileInfo,
169
172
  renderConfiguredOgImage,
170
173
  renderOgImage,
174
+ isPointUnderCoverText,
171
175
  renderPhotoCover,
172
176
  type ConfiguredOgImageOptions,
177
+ type FontFileFormat,
178
+ type FontFileInfo,
179
+ type FontFileWeight,
180
+ type FontUnusableReason,
181
+ type FontUse,
182
+ type FontUseVerdict,
173
183
  type OgBrand,
174
184
  type OgImageInput,
175
185
  type OgResult,
@@ -210,8 +220,13 @@ export {
210
220
  CAPTION_PRESETS,
211
221
  CAPTION_STYLES,
212
222
  DEFAULT_EDIT,
223
+ DEFAULT_END_CARD_SECONDS,
224
+ DEFAULT_LOGO_END_CARD_FADE_SECONDS,
225
+ DEFAULT_LOGO_END_CARD_SECONDS,
213
226
  getDefaultFillers,
214
227
  getDeclickLevel,
228
+ getEndCardSeconds,
229
+ getEndCardTexts,
215
230
  getFootageEdit,
216
231
  type CaptionPreset,
217
232
  type CaptionStyle,
@@ -222,28 +237,33 @@ export {
222
237
  type CutTransition,
223
238
  type JumpTransition,
224
239
  type FootageClip,
240
+ type FootageEndCard,
225
241
  type FootageFilm,
226
242
  type FootageMusic,
243
+ type FullFootageEndCard,
244
+ type LogoFootageEndCard,
227
245
  type FootageSpeech,
228
246
  type FootageTransitions,
229
247
  type MusicSource,
230
248
  } from "./footage/film.js";
231
249
  export {
232
- DECLICK_GATE_FADE,
233
- DECLICK_IMPULSE_DB,
250
+ DECLICK_AR_CONTEXT,
251
+ DECLICK_AR_ORDER,
252
+ DECLICK_CROSSFADE,
234
253
  DECLICK_LEVELS,
235
254
  DECLICK_MAX_IMPULSE,
236
255
  DECLICK_SETTINGS,
237
- DECLICK_WORD_WINDOW,
256
+ DECLICK_WORD_GUARD,
238
257
  buildDeclickDecodeArgs,
239
258
  buildDeclickEncodeArgs,
240
259
  declickSamples,
241
260
  declickSpeech,
242
261
  describeDeclick,
243
262
  findImpulses,
244
- getDeclickGain,
245
- getGateWindows,
263
+ getArPolynomial,
264
+ getRepairZones,
246
265
  getRunningMedian,
266
+ repairSpan,
247
267
  type ActiveDeclickLevel,
248
268
  type DeclickLevel,
249
269
  type DeclickReport,
@@ -401,6 +421,7 @@ export {
401
421
  composeFootage,
402
422
  getFootageFilmSeconds,
403
423
  getFootageSfxCues,
424
+ getLogoCardBox,
404
425
  getSegmentScales,
405
426
  type FootageComposeAssets,
406
427
  type FootageComposeInput,
@@ -443,10 +464,15 @@ export {
443
464
  buildClipSoundMeasureArgs,
444
465
  getAudioCodecArgs,
445
466
  getClipSoundPath,
467
+ describeSpeechPreGain,
446
468
  getPreGainDb,
469
+ getSpeechPreGain,
447
470
  prepareClipSounds,
448
471
  type ClipSound,
449
472
  type ClipSoundInput,
473
+ type MeasuredPreGain,
474
+ type SpeechPeaks,
475
+ type SpeechPreGain,
450
476
  } from "./footage/clip-sound.js";
451
477
  export {
452
478
  AUDIO_BITRATE_RANGE_KBPS,
@@ -1,76 +1,23 @@
1
- import { inflateSync } from "node:zlib";
2
-
1
+ import { OutOfBounds, readFontTables, readInt16, readUint16, readUint32 } from "./font-tables.js";
3
2
  import { err, ok, type OgResult } from "./result.js";
4
3
 
5
4
  /**
6
5
  * The characters a font file maps to a glyph, read from its `cmap` table the way Satori's font
7
6
  * parser (opentype.js) reads it: the last Unicode subtable of the table (platform 0 encodings 0-4,
8
7
  * platform 3 encodings 0, 1 and 10), in format 4 or 12. Glyph 0 (`.notdef`) means "not in the font".
9
- * Every read is bounds-checked, so a broken file is an error value, never an exception.
8
+ * TrueType, OpenType, WOFF and WOFF2 files are read (`readFontTables`), though Satori itself draws no WOFF2. Every read
9
+ * is bounds-checked, so a broken file is an error value, never an exception.
10
10
  */
11
11
  export interface CharacterMap {
12
12
  has(codePoint: number): boolean;
13
13
  }
14
14
 
15
- const SFNT_SIGNATURES = new Set([0x00010000, 0x74727565 /* true */, 0x4f54544f /* OTTO */]);
16
- const WOFF_SIGNATURE = 0x774f4646; // wOFF
17
- const WOFF2_SIGNATURE = 0x774f4632; // wOF2
18
- const COLLECTION_SIGNATURE = 0x74746366; // ttcf
19
-
20
- class OutOfBounds extends Error {}
21
-
22
- function readUint16(data: Buffer, offset: number): number {
23
- if (offset < 0 || offset + 2 > data.length) throw new OutOfBounds();
24
- return data.readUInt16BE(offset);
25
- }
26
-
27
- function readInt16(data: Buffer, offset: number): number {
28
- if (offset < 0 || offset + 2 > data.length) throw new OutOfBounds();
29
- return data.readInt16BE(offset);
30
- }
31
-
32
- function readUint32(data: Buffer, offset: number): number {
33
- if (offset < 0 || offset + 4 > data.length) throw new OutOfBounds();
34
- return data.readUInt32BE(offset);
35
- }
36
-
37
- function slice(data: Buffer, offset: number, length: number): Buffer {
38
- if (offset < 0 || length < 0 || offset + length > data.length) throw new OutOfBounds();
39
- return data.subarray(offset, offset + length);
40
- }
41
-
42
- const CMAP_TAG = 0x636d6170; // cmap
43
-
44
- /** The raw `cmap` table of an sfnt (`.ttf`, `.otf`) or WOFF file, or a reason it has none. */
15
+ /** The raw `cmap` table of a font file, or a reason it has none. */
45
16
  function findCmapTable(data: Buffer): OgResult<Buffer> {
46
- const signature = readUint32(data, 0);
47
- if (SFNT_SIGNATURES.has(signature)) {
48
- const count = readUint16(data, 4);
49
- for (let index = 0; index < count; index++) {
50
- const record = 12 + index * 16;
51
- if (readUint32(data, record) === CMAP_TAG) return ok(slice(data, readUint32(data, record + 8), readUint32(data, record + 12)));
52
- }
53
- return err("the font has no cmap table");
54
- }
55
- if (signature === WOFF_SIGNATURE) {
56
- const count = readUint16(data, 12);
57
- for (let index = 0; index < count; index++) {
58
- const entry = 44 + index * 20;
59
- if (readUint32(data, entry) !== CMAP_TAG) continue;
60
- const stored = slice(data, readUint32(data, entry + 4), readUint32(data, entry + 8));
61
- const length = readUint32(data, entry + 12);
62
- if (stored.length >= length) return ok(stored);
63
- try {
64
- return ok(inflateSync(stored));
65
- } catch {
66
- return err("the font's cmap table does not decompress");
67
- }
68
- }
69
- return err("the font has no cmap table");
70
- }
71
- if (signature === WOFF2_SIGNATURE) return err("WOFF2 is not read");
72
- if (signature === COLLECTION_SIGNATURE) return err("font collections are not read");
73
- return err("the file is not a TrueType, OpenType or WOFF font");
17
+ const tables = readFontTables(data);
18
+ if (!tables.ok) return tables;
19
+ const table = tables.value.get("cmap");
20
+ return table === undefined ? err("the font has no cmap table") : ok(table);
74
21
  }
75
22
 
76
23
  function isUnicodeEncoding(platform: number, encoding: number): boolean {
@@ -0,0 +1,172 @@
1
+ import { readCharacterMap } from "./character-map.js";
2
+ import { OutOfBounds, readFontTables, readInt32, readUint16, slice, type FontFileFormat, type FontTables } from "./font-tables.js";
3
+ import { OG_FONT_WEIGHTS } from "./fonts.js";
4
+ import { err, ok, type OgResult } from "./result.js";
5
+
6
+ /**
7
+ * What an uploaded font file is and where the kit can use it, so an app stores it as a `BrandFont` file
8
+ * (`family`, `files[{ path, weight, style }]`) and refuses it at upload with a reason instead of at render:
9
+ * - `captions`: the film's captions, drawn by the browser render, which takes `.ttf`, `.otf`, `.woff` and `.woff2`;
10
+ * - `draft`: the footage draft's captions, drawn by libass (FreeType), which reads `.ttf` and `.otf` and matches the
11
+ * family the file names itself;
12
+ * - `cover`: OG images and the photo cover, drawn by Satori, which reads static `.ttf`, `.otf` and `.woff` files at
13
+ * weights 100-900 in steps of 100 (the rules `loadOgFonts` applies).
14
+ */
15
+
16
+ export const FONT_USES = ["captions", "draft", "cover"] as const;
17
+
18
+ export type FontUse = (typeof FONT_USES)[number];
19
+
20
+ /** Why a file does not work for a use; a code, so an app words it in its own language. */
21
+ export type FontUnusableReason = "format" | "variable" | "weight" | "character-map" | "family-name";
22
+
23
+ export type FontUseVerdict = { isUsable: true } | { isUsable: false; reason: FontUnusableReason; detail: string };
24
+
25
+ export type FontFileWeight = { kind: "static"; value: number } | { kind: "variable"; min: number; max: number; default: number };
26
+
27
+ export interface FontFileInfo {
28
+ /** The typographic family (name ID 16), else the family (name ID 1); null when the file names none. */
29
+ family: string | null;
30
+ format: FontFileFormat;
31
+ weight: FontFileWeight;
32
+ /** The weight as `BrandFont` files and CSS write it: `400`, or a variable range `100 900`. */
33
+ cssWeight: string;
34
+ style: "normal" | "italic";
35
+ usableFor: Record<FontUse, FontUseVerdict>;
36
+ }
37
+
38
+ const FAMILY_NAME_ID = 1;
39
+ const TYPOGRAPHIC_FAMILY_NAME_ID = 16;
40
+ /** `usWeightClass` when a file has no `OS/2` table: regular, as browsers assume. */
41
+ const DEFAULT_WEIGHT = 400;
42
+ const WEIGHT_AXIS = "wght";
43
+
44
+ const USABLE: FontUseVerdict = { isUsable: true };
45
+
46
+ function unusable(reason: FontUnusableReason, detail: string): FontUseVerdict {
47
+ return { isUsable: false, reason, detail };
48
+ }
49
+
50
+ function decodeName(bytes: Buffer, platform: number): string {
51
+ if (platform === 1) return bytes.toString("latin1");
52
+ let text = "";
53
+ for (let index = 0; index + 1 < bytes.length; index += 2) text += String.fromCharCode(bytes.readUInt16BE(index));
54
+ return text;
55
+ }
56
+
57
+ /** A name record's text: the Windows Unicode record first, US English first among those, else the Macintosh one. */
58
+ function findName(table: Buffer, nameId: number): string | null {
59
+ const count = readUint16(table, 2);
60
+ const strings = readUint16(table, 4);
61
+ let best: { rank: number; name: string } | null = null;
62
+ for (let index = 0; index < count; index++) {
63
+ const record = 6 + index * 12;
64
+ const platform = readUint16(table, record);
65
+ if (readUint16(table, record + 6) !== nameId || (platform !== 3 && platform !== 1)) continue;
66
+ const language = readUint16(table, record + 4);
67
+ const text = decodeName(slice(table, strings + readUint16(table, record + 10), readUint16(table, record + 8)), platform).trim();
68
+ const rank = platform === 3 ? (language === 0x0409 ? 0 : 1) : 2;
69
+ if (text.length > 0 && (best === null || rank < best.rank)) best = { rank, name: text };
70
+ }
71
+ return best?.name ?? null;
72
+ }
73
+
74
+ function readFamily(tables: FontTables): string | null {
75
+ const table = tables.get("name");
76
+ if (table === undefined) return null;
77
+ return findName(table, TYPOGRAPHIC_FAMILY_NAME_ID) ?? findName(table, FAMILY_NAME_ID);
78
+ }
79
+
80
+ /** A 16.16 fixed-point number, rounded to a whole weight. */
81
+ function readFixedWeight(table: Buffer, offset: number): number {
82
+ return Math.round(readInt32(table, offset) / 65536);
83
+ }
84
+
85
+ function readWeight(tables: FontTables): FontFileWeight {
86
+ const fvar = tables.get("fvar");
87
+ if (fvar !== undefined) {
88
+ const axesOffset = readUint16(fvar, 4);
89
+ const axisCount = readUint16(fvar, 8);
90
+ const axisSize = readUint16(fvar, 10);
91
+ for (let index = 0; index < axisCount; index++) {
92
+ const axis = axesOffset + index * axisSize;
93
+ if (slice(fvar, axis, 4).toString("latin1") !== WEIGHT_AXIS) continue;
94
+ return { kind: "variable", min: readFixedWeight(fvar, axis + 4), default: readFixedWeight(fvar, axis + 8), max: readFixedWeight(fvar, axis + 12) };
95
+ }
96
+ }
97
+ const os2 = tables.get("OS/2");
98
+ return { kind: "static", value: os2 === undefined ? DEFAULT_WEIGHT : readUint16(os2, 4) };
99
+ }
100
+
101
+ function readStyle(tables: FontTables): "normal" | "italic" {
102
+ const os2 = tables.get("OS/2");
103
+ if (os2 !== undefined && (readUint16(os2, 62) & 0x1) !== 0) return "italic";
104
+ const head = tables.get("head");
105
+ if (head !== undefined && (readUint16(head, 44) & 0x2) !== 0) return "italic";
106
+ return "normal";
107
+ }
108
+
109
+ function toCssWeight(weight: FontFileWeight): string {
110
+ return weight.kind === "static" ? String(weight.value) : `${weight.min} ${weight.max}`;
111
+ }
112
+
113
+ function judgeDraft(format: FontFileFormat, family: string | null): FontUseVerdict {
114
+ if (format !== "ttf" && format !== "otf") return unusable("format", `the footage draft (libass) reads .ttf and .otf files, not .${format}`);
115
+ // libass matches the family of name ID 1; a file that names a typographic family names a family too in practice.
116
+ return family === null ? unusable("family-name", "the font names no family, so the footage draft cannot match it") : USABLE;
117
+ }
118
+
119
+ function judgeCover(data: Buffer, format: FontFileFormat, weight: FontFileWeight): FontUseVerdict {
120
+ if (format === "woff2") return unusable("format", "OG images (Satori) read .ttf, .otf and .woff files, not .woff2");
121
+ if (weight.kind === "variable") return unusable("variable", `OG images (Satori) need a static file, and this one is variable (${weight.min}-${weight.max})`);
122
+ if (!OG_FONT_WEIGHTS.some((ogWeight) => ogWeight === weight.value)) {
123
+ return unusable("weight", `OG images (Satori) need a weight from 100 to 900 in steps of 100, and this file is ${weight.value}`);
124
+ }
125
+ const characters = readCharacterMap(data);
126
+ return characters.ok ? USABLE : unusable("character-map", `OG images (Satori) cannot read its character map: ${characters.error}`);
127
+ }
128
+
129
+ /**
130
+ * Reads an uploaded font file's family, weight, style and format, and whether captions, the footage draft and OG images
131
+ * (the photo cover included) can use it. A broken or unknown file is an error value, never an exception.
132
+ */
133
+ export function readFontFileInfo(data: Buffer): OgResult<FontFileInfo> {
134
+ const tables = readFontTables(data);
135
+ if (!tables.ok) return err(`Reading the font file: ${tables.error}.`);
136
+ try {
137
+ const { format } = tables.value;
138
+ const family = readFamily(tables.value);
139
+ const weight = readWeight(tables.value);
140
+ return ok({
141
+ family,
142
+ format,
143
+ weight,
144
+ cssWeight: toCssWeight(weight),
145
+ style: readStyle(tables.value),
146
+ usableFor: { captions: USABLE, draft: judgeDraft(format, family), cover: judgeCover(data, format, weight) },
147
+ });
148
+ } catch (error) {
149
+ if (error instanceof OutOfBounds) return err("Reading the font file: a table of the font is truncated or malformed.");
150
+ throw error;
151
+ }
152
+ }
153
+
154
+ /** Characters that need no glyph: whitespace, control and format characters, variation selectors. */
155
+ const INVISIBLE_PATTERN = /^[\p{White_Space}\p{Cc}\p{Cf}\u{FE00}-\u{FE0F}\u{E0100}-\u{E01EF}]$/u;
156
+
157
+ /**
158
+ * The characters of `characters` the font file maps to no glyph, unique and in order (whitespace and other invisible
159
+ * characters are skipped), e.g. the Polish letters an app requires of a brand font. An error value when the file's
160
+ * character map cannot be read.
161
+ */
162
+ export function findMissingCharacters(data: Buffer, characters: string): OgResult<string[]> {
163
+ const map = readCharacterMap(data);
164
+ if (!map.ok) return err(`Checking the font file's characters: ${map.error}.`);
165
+ const missing: string[] = [];
166
+ for (const character of characters) {
167
+ if (INVISIBLE_PATTERN.test(character) || missing.includes(character)) continue;
168
+ const codePoint = character.codePointAt(0);
169
+ if (codePoint !== undefined && !map.value.has(codePoint)) missing.push(character);
170
+ }
171
+ return ok(missing);
172
+ }