@softure-ai/marketing-kit 0.18.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.
@@ -12,7 +12,7 @@ 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
17
  import { composeFootage, getFootageFilmSeconds, getFootageSfxCues } from "./compose.js";
18
18
  import { findMissingCaptionGlyphs, getCaptionBounds, getFootageCaptionLayout } from "./captions.js";
@@ -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 };
@@ -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. */
package/src/index.ts CHANGED
@@ -464,10 +464,15 @@ export {
464
464
  buildClipSoundMeasureArgs,
465
465
  getAudioCodecArgs,
466
466
  getClipSoundPath,
467
+ describeSpeechPreGain,
467
468
  getPreGainDb,
469
+ getSpeechPreGain,
468
470
  prepareClipSounds,
469
471
  type ClipSound,
470
472
  type ClipSoundInput,
473
+ type MeasuredPreGain,
474
+ type SpeechPeaks,
475
+ type SpeechPreGain,
471
476
  } from "./footage/clip-sound.js";
472
477
  export {
473
478
  AUDIO_BITRATE_RANGE_KBPS,