@softure-ai/marketing-kit 0.14.0 → 0.15.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 (41) hide show
  1. package/CHANGELOG.md +29 -0
  2. package/README.md +22 -1
  3. package/dist/footage/draft.js +2 -2
  4. package/dist/footage/draft.js.map +1 -1
  5. package/dist/footage/failure.d.ts +42 -0
  6. package/dist/footage/failure.d.ts.map +1 -0
  7. package/dist/footage/failure.js +14 -0
  8. package/dist/footage/failure.js.map +1 -0
  9. package/dist/footage/film-mix.d.ts +5 -1
  10. package/dist/footage/film-mix.d.ts.map +1 -1
  11. package/dist/footage/film-mix.js +11 -2
  12. package/dist/footage/film-mix.js.map +1 -1
  13. package/dist/footage/isolate-ranges.d.ts +47 -4
  14. package/dist/footage/isolate-ranges.d.ts.map +1 -1
  15. package/dist/footage/isolate-ranges.js +64 -14
  16. package/dist/footage/isolate-ranges.js.map +1 -1
  17. package/dist/footage/paid.d.ts +3 -0
  18. package/dist/footage/paid.d.ts.map +1 -1
  19. package/dist/footage/paid.js +2 -1
  20. package/dist/footage/paid.js.map +1 -1
  21. package/dist/footage/pipeline.d.ts +2 -2
  22. package/dist/footage/pipeline.d.ts.map +1 -1
  23. package/dist/footage/pipeline.js +21 -20
  24. package/dist/footage/pipeline.js.map +1 -1
  25. package/dist/footage/speech-ranges.d.ts +29 -4
  26. package/dist/footage/speech-ranges.d.ts.map +1 -1
  27. package/dist/footage/speech-ranges.js +56 -11
  28. package/dist/footage/speech-ranges.js.map +1 -1
  29. package/dist/index.d.ts +3 -2
  30. package/dist/index.d.ts.map +1 -1
  31. package/dist/index.js +3 -2
  32. package/dist/index.js.map +1 -1
  33. package/package.json +1 -1
  34. package/src/footage/draft.ts +2 -2
  35. package/src/footage/failure.ts +44 -0
  36. package/src/footage/film-mix.ts +10 -2
  37. package/src/footage/isolate-ranges.ts +110 -14
  38. package/src/footage/paid.ts +5 -2
  39. package/src/footage/pipeline.ts +25 -21
  40. package/src/footage/speech-ranges.ts +68 -11
  41. package/src/index.ts +15 -1
@@ -1,7 +1,8 @@
1
1
  import { existsSync, mkdirSync } from "node:fs";
2
2
  import { join } from "node:path";
3
+ import { setTimeout as sleep } from "node:timers/promises";
3
4
 
4
- import { err, ok } from "../voice/provider.js";
5
+ import { err, ok } from "./failure.js";
5
6
  import { probeAudio } from "./audio.js";
6
7
  import { writeCacheFile } from "./cache.js";
7
8
  import type { Edl } from "./edl.js";
@@ -9,30 +10,65 @@ import type { FootageFilm } from "./film.js";
9
10
  import { getClipCacheKey } from "./paid.js";
10
11
  import { getFfmpegReporting, type FootageResult, type FootageRunOptions, type PreparedClip } from "./pipeline.js";
11
12
  import { runFfmpeg, withFfmpegFailureReporting } from "./process.js";
12
- import { toPaidAudio } from "./providers.js";
13
+ import { toPaidAudio, type IsolationProvider, type PaidAudio } from "./providers.js";
13
14
  import {
14
15
  buildRangeAudioArgs,
15
16
  buildRangeLayArgs,
16
17
  getSpeechRangeCache,
17
18
  getSpeechRangeWindows,
18
19
  planSpeechRanges,
20
+ DEFAULT_SPEECH_RANGE_FADE_MS,
19
21
  type LaidRange,
20
22
  type SpeechRange,
23
+ type SpeechRangeCacheResolver,
21
24
  } from "./speech-ranges.js";
22
25
 
23
26
  /**
24
27
  * Voice isolation of only what the cut hears (issue #1087): each talking clip's sound ranges (`planSpeechRanges`) are
25
28
  * cleaned one by one and cached by the clip's identity, the range in milliseconds and the provider, so an unchanged
26
29
  * segment is never paid twice and a changed cut pays only its new ranges. The cleaned ranges are laid back over the
27
- * clip's own sound into one file as long as the clip: the speech map `renderFootage` takes.
30
+ * clip's own sound into one file as long as the clip: the speech map `renderFootage` takes. A range the provider refuses
31
+ * is asked again, and one refused on every attempt keeps the clip's own sound in its window while the others are laid
32
+ * (issue #1127): only a cancel stops the call.
28
33
  */
29
34
 
35
+ /** How often a refused range is asked again: `attempts` in all (default 3), waiting `delaysMs[n]` before attempt n + 2. */
36
+ export interface SpeechRangeRetry {
37
+ /** Attempts per range, at least 1; default `DEFAULT_SPEECH_RANGE_ATTEMPTS` (3). */
38
+ attempts?: number;
39
+ /** Milliseconds before each retry (the last repeats); default `DEFAULT_SPEECH_RANGE_RETRY_DELAYS_MS` (1 s, 2 s). */
40
+ delaysMs?: readonly number[];
41
+ /** Waits `ms`, rejecting when `signal` aborts; default a timer. Injected by tests. */
42
+ wait?: (ms: number, signal?: AbortSignal) => Promise<void>;
43
+ }
44
+
45
+ export const DEFAULT_SPEECH_RANGE_ATTEMPTS = 3;
46
+ export const DEFAULT_SPEECH_RANGE_RETRY_DELAYS_MS: readonly number[] = [1000, 2000];
47
+
30
48
  export type IsolateSpeechRangesOptions = Pick<FootageRunOptions, "buildDir" | "cacheDir" | "providers" | "isCommit" | "signal" | "onCharge" | "onProgress" | "onFfmpegFailure"> & {
31
49
  /** Seconds added on each side of a sound span; default `DEFAULT_SPEECH_RANGE_MARGIN` (0.25). */
32
50
  margin?: number;
51
+ /** Retries of a refused range. */
52
+ retry?: SpeechRangeRetry;
53
+ /** Milliseconds of the linear crossfade at every join; default `DEFAULT_SPEECH_RANGE_FADE_MS` (15), 0 switches at once. */
54
+ fadeMs?: number;
55
+ /** The `item` of a range's charge (e.g. the app's segment id); default the clip id. */
56
+ chargeItem?: (range: SpeechRange) => string;
57
+ /**
58
+ * Where a range's cleaned voice is cached; default `getSpeechRangeCache` (`<cacheDir>/<film>/<key>.isolated.mp3`).
59
+ * An app that already holds paid ranges under its own keys points the block at them.
60
+ */
61
+ rangeCache?: SpeechRangeCacheResolver;
33
62
  log?: (line: string) => void;
34
63
  };
35
64
 
65
+ /** What happened to a range in this call. */
66
+ export type SpeechRangeOutcome =
67
+ | { kind: "cached" }
68
+ | { kind: "bought"; attempts: number }
69
+ | { kind: "failed"; error: string; attempts: number }
70
+ | { kind: "not_bought" };
71
+
36
72
  export interface IsolatedSpeechRange extends SpeechRange {
37
73
  /** The paid cache's key and file of the range's cleaned voice. */
38
74
  cacheKey: string;
@@ -41,6 +77,11 @@ export interface IsolatedSpeechRange extends SpeechRange {
41
77
  cached: boolean;
42
78
  /** Whether it is laid in the clip's speech file (cached, or bought with `isCommit`). */
43
79
  laid: boolean;
80
+ /**
81
+ * `cached`; `bought` in this call; `failed` when the provider refused it on every attempt (its window keeps the
82
+ * clip's own sound); `not_bought` without `isCommit`.
83
+ */
84
+ outcome: SpeechRangeOutcome;
44
85
  }
45
86
 
46
87
  export interface IsolatedSpeech {
@@ -52,8 +93,9 @@ export interface IsolatedSpeech {
52
93
  /**
53
94
  * Cleans the voice of the ranges the cut hears and answers the speech map the render takes (`TranscribeOutcome.speech`).
54
95
  * With `isCommit` every uncached range is bought (`onCharge` step `isolate`, item the clip id, with its `range`);
55
- * without it only cached ranges are laid, a free draft, and `ranges` names what is still missing. Each clip with a laid
56
- * range gets `<buildDir>/audio/<id>.ranges.mp3`.
96
+ * without it only cached ranges are laid, a free draft, and `ranges` names what is still missing. A refused range is
97
+ * retried (`retry`); one refused on every attempt is answered `failed` and the call still succeeds. Each clip with a
98
+ * laid range gets `<buildDir>/audio/<id>.ranges.mp3`, crossfaded at every join (`fadeMs`).
57
99
  */
58
100
  export function isolateSpeechRanges(film: FootageFilm, clips: PreparedClip[], edl: Edl, options: IsolateSpeechRangesOptions): Promise<FootageResult<IsolatedSpeech>> {
59
101
  const log = options.log ?? ((): void => undefined);
@@ -88,9 +130,9 @@ async function runIsolateSpeechRanges(
88
130
  clipKey = await getClipCacheKey(clip.source, clip.clip);
89
131
  clipKeys.set(range.clip, clipKey);
90
132
  }
91
- const cache = getSpeechRangeCache(film.id, clipKey, range, { cacheDir: options.cacheDir, provider: providers.isolation.id });
133
+ const cache = options.rangeCache?.(range, clipKey) ?? getSpeechRangeCache(film.id, clipKey, range, { cacheDir: options.cacheDir, provider: providers.isolation.id });
92
134
  const cached = existsSync(cache.path);
93
- ranges.push({ ...range, cacheKey: cache.key, path: cache.path, cached, laid: cached });
135
+ ranges.push({ ...range, cacheKey: cache.key, path: cache.path, cached, laid: cached, outcome: cached ? { kind: "cached" } : { kind: "not_bought" } });
94
136
  }
95
137
  const buying = options.isCommit ? ranges.filter((range) => !range.cached) : [];
96
138
  const total = buying.reduce((sum, range) => sum + (range.endMs - range.startMs) / 1000, 0);
@@ -110,15 +152,28 @@ async function runIsolateSpeechRanges(
110
152
  await runFfmpeg(`Cutting ${describeRange(range)} for voice isolation`, buildRangeAudioArgs(clip.file, range, input), { ...aborting, output: input });
111
153
  signal?.throwIfAborted();
112
154
  log(`voice isolation (${providers.isolation.id}): ${describeRange(range)}, ${units.toFixed(1)} s.`);
113
- const cleaned = await providers.isolation.isolate({ audio: input, ...aborting });
114
- signal?.throwIfAborted();
115
- if (!cleaned.ok) return err(`${describeRange(range)}: ${cleaned.error}`);
116
- const paid = toPaidAudio(cleaned.value);
155
+ const answer = await isolateWithRetries({
156
+ audio: input,
157
+ isolation: providers.isolation,
158
+ retry: options.retry ?? {},
159
+ ...aborting,
160
+ onRefused: (error, attempt) => {
161
+ log(`voice isolation: ${describeRange(range)} refused (attempt ${String(attempt)}): ${error}`);
162
+ },
163
+ });
164
+ if (!answer.ok) {
165
+ range.outcome = { kind: "failed", error: answer.error, attempts: answer.attempts };
166
+ done += units;
167
+ report(range, index);
168
+ continue;
169
+ }
170
+ const paid = answer.paid;
117
171
  writeCacheFile(range.path, paid.audio);
118
172
  range.laid = true;
173
+ range.outcome = { kind: "bought", attempts: answer.attempts };
119
174
  options.onCharge?.({
120
175
  step: "isolate",
121
- item: range.clip,
176
+ item: options.chargeItem?.(range) ?? range.clip,
122
177
  provider: providers.isolation.id,
123
178
  units,
124
179
  ...(paid.credits === undefined ? {} : { credits: paid.credits }),
@@ -129,7 +184,9 @@ async function runIsolateSpeechRanges(
129
184
  done += units;
130
185
  report(range, index);
131
186
  }
132
- const missing = ranges.filter((range) => !range.laid);
187
+ const failed = ranges.filter((range) => range.outcome.kind === "failed");
188
+ if (failed.length > 0) log(`voice isolation: ${String(failed.length)} range${failed.length === 1 ? "" : "s"} refused, laid with the clip's own sound: ${failed.map(describeRange).join("; ")}.`);
189
+ const missing = ranges.filter((range) => range.outcome.kind === "not_bought");
133
190
  if (missing.length > 0) {
134
191
  const seconds = missing.reduce((sum, range) => sum + (range.endMs - range.startMs) / 1000, 0);
135
192
  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.`);
@@ -150,12 +207,51 @@ async function runIsolateSpeechRanges(
150
207
  }
151
208
  const output = join(buildDir, "audio", `${id}.ranges.mp3`);
152
209
  mkdirSync(join(buildDir, "audio"), { recursive: true });
153
- await runFfmpeg(`Laying the cleaned voice over clip ${id}`, buildRangeLayArgs(clip.file, laid, output), { ...aborting, output });
210
+ await runFfmpeg(`Laying the cleaned voice over clip ${id}`, buildRangeLayArgs(clip.file, laid, output, { fadeMs: options.fadeMs ?? DEFAULT_SPEECH_RANGE_FADE_MS }), { ...aborting, output });
154
211
  speech[id] = output;
155
212
  }
156
213
  return ok({ speech, ranges });
157
214
  }
158
215
 
216
+ type IsolationAnswer = { ok: true; paid: PaidAudio; attempts: number } | { ok: false; error: string; attempts: number };
217
+
218
+ /** Asks the provider for one range's cleaned voice, again after each refusal up to `retry.attempts`; a cancel throws. */
219
+ async function isolateWithRetries(input: {
220
+ audio: string;
221
+ isolation: IsolationProvider;
222
+ retry: SpeechRangeRetry;
223
+ signal?: AbortSignal;
224
+ onRefused: (error: string, attempt: number) => void;
225
+ }): Promise<IsolationAnswer> {
226
+ const { audio, isolation, retry, signal, onRefused } = input;
227
+ const attempts = Math.max(1, Math.floor(retry.attempts ?? DEFAULT_SPEECH_RANGE_ATTEMPTS));
228
+ const delays = retry.delaysMs ?? DEFAULT_SPEECH_RANGE_RETRY_DELAYS_MS;
229
+ const wait = retry.wait ?? waitFor;
230
+ let error = "";
231
+ for (let attempt = 1; attempt <= attempts; attempt += 1) {
232
+ if (attempt > 1) {
233
+ await wait(delays[Math.min(attempt - 2, delays.length - 1)] ?? 0, signal);
234
+ signal?.throwIfAborted();
235
+ }
236
+ const cleaned = await isolation.isolate({ audio, ...(signal === undefined ? {} : { signal }) });
237
+ signal?.throwIfAborted();
238
+ if (cleaned.ok) return { ok: true, paid: toPaidAudio(cleaned.value), attempts: attempt };
239
+ error = cleaned.error;
240
+ onRefused(error, attempt);
241
+ }
242
+ return { ok: false, error, attempts };
243
+ }
244
+
245
+ /** Resolves after `ms`, or rejects with the signal's reason when it aborts first. */
246
+ async function waitFor(ms: number, signal?: AbortSignal): Promise<void> {
247
+ try {
248
+ await sleep(ms, undefined, signal === undefined ? {} : { signal });
249
+ } catch (error) {
250
+ signal?.throwIfAborted();
251
+ throw error;
252
+ }
253
+ }
254
+
159
255
  function describeRange(range: SpeechRange): string {
160
256
  return `clip ${range.clip} ${(range.startMs / 1000).toFixed(3)}-${(range.endMs / 1000).toFixed(3)} s`;
161
257
  }
@@ -10,7 +10,7 @@ import { getFilmKeyTerms } from "./keyterms.js";
10
10
  import type { FootageClip, FootageFilm } from "./film.js";
11
11
  import { getTrimmedDuration, probeFootage } from "./probe.js";
12
12
  import type { FootageProviders, FootageRates, PaidStepKind } from "./providers.js";
13
- import { getSpeechRangeCache, planSpeechRanges, type SpeechRangeClip } from "./speech-ranges.js";
13
+ import { getSpeechRangeCache, planSpeechRanges, type SpeechRangeCacheResolver, type SpeechRangeClip } from "./speech-ranges.js";
14
14
 
15
15
  /**
16
16
  * Where each paid result of a footage film is cached, shared by the pipeline and by the questions an app asks before
@@ -179,6 +179,8 @@ export interface EstimateFootageOptions extends FootageCacheOptions {
179
179
  isolate?: "clips" | "segments";
180
180
  /** Seconds around each sound span with `isolate: "segments"`; default `DEFAULT_SPEECH_RANGE_MARGIN`. */
181
181
  margin?: number;
182
+ /** Where a range's cleaned voice is cached with `isolate: "segments"`, as `isolateSpeechRanges` takes it; default `getSpeechRangeCache`. */
183
+ rangeCache?: SpeechRangeCacheResolver;
182
184
  }
183
185
 
184
186
  const round = (value: number, digits: number): number => {
@@ -234,7 +236,8 @@ export async function estimateFootageFilm(film: FootageFilm, options: EstimateFo
234
236
  const provider = options.providers.isolation.id;
235
237
  for (const range of planSpeechRanges(edl, rangeClips, options.margin === undefined ? {} : { margin: options.margin })) {
236
238
  const clipKey = clipKeys[range.clip] ?? null;
237
- const cached = clipKey !== null && existsSync(getSpeechRangeCache(film.id, clipKey, range, { cacheDir: options.cacheDir, provider }).path);
239
+ const cache = clipKey === null ? null : (options.rangeCache?.(range, clipKey) ?? getSpeechRangeCache(film.id, clipKey, range, { cacheDir: options.cacheDir, provider }));
240
+ const cached = cache !== null && existsSync(cache.path);
238
241
  add("isolate", range.clip, provider, (range.endMs - range.startMs) / 1000, cached);
239
242
  const item = items.at(-1);
240
243
  if (item !== undefined) item.range = { start: range.startMs / 1000, end: range.endMs / 1000 };
@@ -8,12 +8,13 @@ import type { BrandFont } from "../config/config.js";
8
8
  import type { SfxEvent } from "../config/schema.js";
9
9
  import { getHyperframesBin, getHyperframesEnv } from "../render/hyperframes.js";
10
10
  import { copyFonts } from "../render/render.js";
11
- import { err, ok, type TtsResult } from "../voice/provider.js";
11
+ import type { TtsResult } from "../voice/provider.js";
12
12
  import type { TimedWord } from "../voice/voiceover.js";
13
13
  import { checkMusicFileType, describeAudioProbe, probeAudio } from "./audio.js";
14
14
  import { readCachedTranscript, writeCacheFile, writeTranscript } from "./cache.js";
15
15
  import { composeFootage, END_CARD_SECONDS, getFootageFilmSeconds, getFootageSfxCues } from "./compose.js";
16
16
  import { findMissingCaptionGlyphs, getCaptionBounds, getFootageCaptionLayout } from "./captions.js";
17
+ import { err, ok, type FootageResult } from "./failure.js";
17
18
  import { findLowDiskProblems, getFreeBytes, getRenderTempDir, type FreeBytesReader } from "./disk.js";
18
19
  import { buildEdl, getEdlDuration, readEdl, remapWords, validateEdl, type Edl } from "./edl.js";
19
20
  import { makePlaceholderTranscript } from "./fake.js";
@@ -101,6 +102,8 @@ const require = createRequire(import.meta.url);
101
102
  /** Bumped when the normalized format changes, so older normalized clips are made again. */
102
103
  const NORMALIZE_VERSION = 2;
103
104
 
105
+ export type { FootageResult } from "./failure.js";
106
+
104
107
  export interface FootageBrand {
105
108
  name: string;
106
109
  /** BCP 47, e.g. `en-US`. */
@@ -151,7 +154,6 @@ export interface PreparedClip {
151
154
  duration: number;
152
155
  }
153
156
 
154
- export type FootageResult<T> = TtsResult<T>;
155
157
 
156
158
  export type TranscribeOutcome =
157
159
  | { kind: "dry-run"; steps: PaidStep[] }
@@ -229,23 +231,23 @@ async function runPrepareFootage(
229
231
  options: Pick<FootageRunOptions, "buildDir" | "log" | "fetch" | "signal" | "onProgress" | "normalize">,
230
232
  ): Promise<FootageResult<PreparedClip[]>> {
231
233
  const { buildDir, log, signal } = options;
232
- if (film.clips.length === 0) return err(`footage film ${film.id} has no clips.`);
234
+ if (film.clips.length === 0) return err(`footage film ${film.id} has no clips.`, { kind: "input" });
233
235
  const sources: Record<string, string> = {};
234
236
  for (const clip of film.clips) {
235
237
  if (!isUrl(clip.source)) {
236
- if (!existsSync(clip.source)) return err(`clip "${clip.id}": no file at ${clip.source}`);
238
+ if (!existsSync(clip.source)) return err(`clip "${clip.id}": no file at ${clip.source}`, { kind: "input" });
237
239
  sources[clip.id] = clip.source;
238
240
  continue;
239
241
  }
240
242
  const downloaded = await download(clip.source, join(buildDir, "sources"), options);
241
- if (!downloaded.ok) return err(`clip "${clip.id}": ${downloaded.error}`);
243
+ if (!downloaded.ok) return err(`clip "${clip.id}": ${downloaded.error}`, downloaded.failure);
242
244
  sources[clip.id] = downloaded.value;
243
245
  }
244
246
  const probed = await probeFootage(film.clips, sources, signal === undefined ? {} : { signal });
245
247
  if (!probed.ok) return err(probed.errors.join("\n"));
246
248
  if (film.music.source.kind === "file") {
247
249
  const music = await checkMusicFile(film.music.source, options);
248
- if (!music.ok) return err(music.error);
250
+ if (!music.ok) return music;
249
251
  }
250
252
  const frame = getFrame(film);
251
253
  const clipsDir = join(buildDir, "clips");
@@ -322,7 +324,7 @@ async function runTranscribeFootage(film: FootageFilm, clips: PreparedClip[], op
322
324
  const { buildDir, providers, log, signal } = options;
323
325
  if (options.isPlaceholder) return ok(transcribePlaceholder(film, clips, buildDir));
324
326
  const keyTerms = getFilmKeyTerms(film);
325
- if (!keyTerms.ok) return err(`footage film ${film.id}: ${keyTerms.errors.join(" ")}`);
327
+ if (!keyTerms.ok) return err(`footage film ${film.id}: ${keyTerms.errors.join(" ")}`, { kind: "input" });
326
328
  const sttKeyTerms = keyTerms.terms.length === 0 ? {} : { keyTerms: keyTerms.terms };
327
329
  const plan: { clip: PreparedClip; isolated: CacheEntry | null; transcript: CacheEntry }[] = [];
328
330
  const steps: PaidStep[] = [];
@@ -502,13 +504,13 @@ export function readEdlFile(film: FootageFilm, clips: PreparedClip[], edlPath: s
502
504
  try {
503
505
  json = JSON.parse(readFileSync(edlPath, "utf8")) as unknown;
504
506
  } catch (error) {
505
- return err(`${edlPath}: not JSON (${String(error)})`);
507
+ return err(`${edlPath}: not JSON (${String(error)})`, { kind: "input" });
506
508
  }
507
509
  const read = readEdl(json);
508
- if (!read.ok) return err(`${edlPath}: ${read.error}`);
510
+ if (!read.ok) return err(`${edlPath}: ${read.error}`, { kind: "input" });
509
511
  const bounds = getCaptionBounds(getFrame(film).height, getFootageCaptionLayout(film, layout));
510
512
  const problems = validateEdl(read.edl, clips.map((clip) => ({ id: clip.clip.id, duration: clip.duration })), film.id, bounds);
511
- return problems.length > 0 ? err(`${edlPath}: ${problems.join("; ")}`) : ok(read.edl);
513
+ return problems.length > 0 ? err(`${edlPath}: ${problems.join("; ")}`, { kind: "input" }) : ok(read.edl);
512
514
  }
513
515
 
514
516
  /**
@@ -518,16 +520,16 @@ export function readEdlFile(film: FootageFilm, clips: PreparedClip[], edlPath: s
518
520
  */
519
521
  async function checkMusicFile(source: Extract<MusicSource, { kind: "file" }>, options: Pick<FootageRunOptions, "log" | "signal">): Promise<FootageResult<string>> {
520
522
  const { path, fileName, contentType } = source;
521
- if (!existsSync(path)) return err(`music: no file at ${path}`);
523
+ if (!existsSync(path)) return err(`music: no file at ${path}`, { kind: "input" });
522
524
  const name = fileName ?? path;
523
525
  if (extname(name) === "" && contentType === undefined) {
524
526
  options.log(`music: ${path} has no extension and no declared name or content type; the probe checks it.`);
525
527
  } else {
526
528
  const type = checkMusicFileType(contentType === undefined ? { fileName: name } : { fileName: name, contentType });
527
- if (!type.ok) return err(`music: ${type.error}`);
529
+ if (!type.ok) return err(`music: ${type.error}`, { kind: "input" });
528
530
  }
529
531
  const probe = await probeAudio(path, options.signal === undefined ? {} : { signal: options.signal });
530
- if (!probe.ok) return err(`music: ${probe.error}`);
532
+ if (!probe.ok) return err(`music: ${probe.error}`, { kind: "input" });
531
533
  options.log(`music: ${path} (${describeAudioProbe(probe.probe)}).`);
532
534
  return ok(path);
533
535
  }
@@ -552,7 +554,7 @@ export async function findFootageMusic(
552
554
  ): Promise<FootageResult<FootageMusicLookup>> {
553
555
  const source = film.music.source;
554
556
  if (source.kind === "none") return ok({ kind: "none" });
555
- if (source.kind === "file") return existsSync(source.path) ? ok({ kind: "file", path: source.path }) : err(`music: no file at ${source.path}`);
557
+ if (source.kind === "file") return existsSync(source.path) ? ok({ kind: "file", path: source.path }) : err(`music: no file at ${source.path}`, { kind: "input" });
556
558
  let cache: CacheEntry;
557
559
  if (source.kind === "prompt") {
558
560
  cache = getPromptMusicCache(film, options);
@@ -695,7 +697,7 @@ async function runRenderFootage(
695
697
  ): Promise<FootageResult<RenderedFootage>> {
696
698
  const { buildDir, log, signal } = options;
697
699
  const finishVideoProblems = options.finishVideo === undefined ? [] : findFinishVideoProblems(options.finishVideo);
698
- if (finishVideoProblems.length > 0) return err(finishVideoProblems.join(" "));
700
+ if (finishVideoProblems.length > 0) return err(finishVideoProblems.join(" "), { kind: "input" });
699
701
  const lowDisk = findLowDiskProblems({ temp: getRenderTempDir(process.env, options.tempDir), build: buildDir }, options.readFreeBytes ?? getFreeBytes);
700
702
  if (lowDisk.length > 0) return err(`not enough disk space to render: ${lowDisk.join(" ")}`);
701
703
  const seconds = getFootageFilmSeconds(film, edl);
@@ -759,7 +761,8 @@ async function runRenderFootage(
759
761
  }
760
762
  // The film's mix, brought to `mixLoudness` and gated before hyperframes captures a frame (issue #1124).
761
763
  const mixLoudness = getMixLoudnessTarget(film);
762
- let mixed: FootageResult<PreparedMix | null> = ok(null);
764
+ // Widened: the mix track assigns it inside a closure, which narrowing does not see.
765
+ let mixed = ok(null) as FootageResult<PreparedMix | null>;
763
766
  if (mixLoudness !== null) {
764
767
  const mixSource = join(buildDir, "mix.wav");
765
768
  const musicTrack = musicFile === null ? null : { file: join(assetsDir, "music.mp3"), seconds };
@@ -809,7 +812,7 @@ async function runRenderFootage(
809
812
  brandName: options.brand.name,
810
813
  });
811
814
  if (missing.length > 0) {
812
- return err(`the brand fonts cannot draw every letter of the film: ${missing.map((entry) => `${entry.font} lacks ${entry.characters.join(" ")}`).join("; ")}. Add a font file that covers them (brand.fonts).`);
815
+ return err(`the brand fonts cannot draw every letter of the film: ${missing.map((entry) => `${entry.font} lacks ${entry.characters.join(" ")}`).join("; ")}. Add a font file that covers them (brand.fonts).`, { kind: "input" });
813
816
  }
814
817
  const html = composeFootage({
815
818
  film,
@@ -964,7 +967,7 @@ export async function finishFootage(
964
967
  const finished = await probeFilmFacts(output, aborting);
965
968
  if (!finished.ok) return err(`the finished film: ${finished.error}`);
966
969
  const problems = findFinishProblems(finished.facts, readTopLevelBoxes(output));
967
- if (problems.length > 0) return err(`the finished film ${output} is not publishable: ${problems.join("; ")}.`);
970
+ if (problems.length > 0) return err(`the finished film ${output} is not publishable: ${problems.join("; ")}.`, { kind: "publishable", problems });
968
971
  let loudness: FinishedLoudness | null = null;
969
972
  if (finished.facts.audio !== null) {
970
973
  const measured = await measureLoudness(output, mixLoudness ?? DEFAULT_LOUDNESS, { label: "the finished film", ...aborting });
@@ -972,7 +975,7 @@ export async function finishFootage(
972
975
  const sound = { integrated: measured.measurement.inputI, truePeak: measured.measurement.inputTp };
973
976
  // A mix left as rendered (`mixLoudness: null`) or silent is reported, not held to a target it was not brought to.
974
977
  const verdict = mixLoudness === null || audioFile === undefined ? { kind: "pass" as const } : getLoudnessVerdict(sound, mixLoudness);
975
- if (verdict.kind === "fail") return err(`the finished film ${output} measures ${describeMixLoudness(sound)}: ${verdict.problems.join("; ")}.`);
978
+ if (verdict.kind === "fail") return err(`the finished film ${output} measures ${describeMixLoudness(sound)}: ${verdict.problems.join("; ")}.`, { kind: "loudness", loudness: sound });
976
979
  loudness = { ...sound, warning: verdict.kind === "warn" ? `the finished film ${output}: ${verdict.warning}` : null };
977
980
  log(`loudness: the finished film measures ${formatDb(sound.integrated)} LUFS, true peak ${formatDb(sound.truePeak)} dBTP.`);
978
981
  if (loudness.warning !== null) log(`loudness warning: ${loudness.warning}`);
@@ -1024,7 +1027,7 @@ async function finishMix(input: {
1024
1027
  const attempt = solved.best.attempt;
1025
1028
  await runFfmpeg("The film's mix", buildMixArgs({ input: input.input, filter: getMixFilter(attempt), output: input.output }), { ...aborting, output: input.output });
1026
1029
  const encoded = await measureLoudness(input.output, input.target, { label: "the film's encoded mix", ...aborting });
1027
- if (encoded.kind === "silent") return err("the film's mix measures silent after its gain and limiter.");
1030
+ if (encoded.kind === "silent") return err("the film's mix measures silent after its gain and limiter.", { kind: "loudness", loudness: null });
1028
1031
  const measured = { integrated: encoded.measurement.inputI, truePeak: encoded.measurement.inputTp };
1029
1032
  const verdict = getLoudnessVerdict(measured, input.target);
1030
1033
  if (verdict.kind === "pass" || (verdict.kind === "warn" && tries === attempts)) return ok({ attempt, tries, probes, measured });
@@ -1032,13 +1035,14 @@ async function finishMix(input: {
1032
1035
  return err(
1033
1036
  `the film's mix still measures ${describeMixLoudness(measured)} after ${attempts} encodes (last: gain ${formatDb(attempt.gainDb)} dB, ` +
1034
1037
  `limiter at ${formatDb(attempt.ceilingDbtp)} dBTP): ${verdict.kind === "fail" ? verdict.problems.join("; ") : ""}.`,
1038
+ { kind: "loudness", loudness: measured },
1035
1039
  );
1036
1040
  }
1037
1041
  shift = Number.isFinite(solved.best.measured.integrated) ? measured.integrated - solved.best.measured.integrated : 0;
1038
1042
  ceilingDbtp = getNextMixCeiling(attempt.ceilingDbtp, measured, input.target);
1039
1043
  startGainDb = attempt.gainDb;
1040
1044
  }
1041
- return err(`the film's mix was not encoded: mixLoudness.attempts is ${attempts}.`);
1045
+ return err(`the film's mix was not encoded: mixLoudness.attempts is ${attempts}.`, { kind: "input" });
1042
1046
  }
1043
1047
 
1044
1048
  /** Both measurements of a mix, as an error names them. */
@@ -91,6 +91,9 @@ export function getSpeechRangeCache(filmId: string, clipKey: string, range: Spee
91
91
  return { key, path: getFootageCachePath(options.cacheDir, filmId, "isolated", key) };
92
92
  }
93
93
 
94
+ /** A range's paid cache entry, the app's own: its key (reported on the charge) and file. `clipKey` is the clip's identity. */
95
+ export type SpeechRangeCacheResolver = (range: SpeechRange, clipKey: string) => { key: string; path: string };
96
+
94
97
  const seconds = (ms: number): string => (ms / 1000).toFixed(3);
95
98
 
96
99
  /** One range of a clip's sound (`audio`, read from its start) as mp3, for the isolation provider. */
@@ -105,27 +108,81 @@ export interface LaidRange {
105
108
  isMono: boolean;
106
109
  }
107
110
 
111
+ /** Milliseconds of the linear crossfade at every join between the clip's own sound and a cleaned window. */
112
+ export const DEFAULT_SPEECH_RANGE_FADE_MS = 15;
113
+
114
+ /** Where a window's cleaned sound fades in and out, in milliseconds of the clip: `inStart ≤ inEnd ≤ outStart ≤ outEnd`. */
115
+ export interface SpeechRangeFade {
116
+ inStartMs: number;
117
+ inEndMs: number;
118
+ outStartMs: number;
119
+ outEndMs: number;
120
+ }
121
+
122
+ /**
123
+ * The crossfades of one clip's windows (as `getSpeechRangeWindows` answers them). At a switch between two overlapping
124
+ * neighbours both ranges have sound, so the fade is centred on the switch, widened by half the fade on each side (at
125
+ * most half the overlap) and shared by both windows, whose gains then sum to one. At a range's own edge the range has
126
+ * no sound outside it, so the fade lies inside the window. No fade is longer than half its window.
127
+ */
128
+ export function getSpeechRangeFades(windows: readonly SpeechRangeWindow[], fadeMs: number): SpeechRangeFade[] {
129
+ const fade = Math.max(0, fadeMs);
130
+ const sorted = [...windows].sort((a, b) => a.startMs - b.startMs);
131
+ const halfWindow = (window: SpeechRangeWindow): number => (window.endMs - window.startMs) / 2;
132
+ /** Half the shared fade at the switch between `before` and `after`; null when they do not overlap. */
133
+ const getSwitchHalf = (before: SpeechRangeWindow | undefined, after: SpeechRangeWindow | undefined): number | null => {
134
+ if (before === undefined || after === undefined || before.range.endMs <= after.range.startMs || before.endMs !== after.startMs) return null;
135
+ const room = Math.min(before.range.endMs - before.endMs, after.startMs - after.range.startMs);
136
+ return Math.floor(Math.min(fade / 2, room, halfWindow(before) / 2, halfWindow(after) / 2));
137
+ };
138
+ return sorted.map((window, index) => {
139
+ const edge = Math.floor(Math.min(fade, halfWindow(window)));
140
+ const startHalf = getSwitchHalf(sorted[index - 1], window);
141
+ const endHalf = getSwitchHalf(window, sorted[index + 1]);
142
+ const [inStartMs, inEndMs] = startHalf === null ? [window.startMs, window.startMs + edge] : [window.startMs - startHalf, window.startMs + startHalf];
143
+ const [outStartMs, outEndMs] = endHalf === null ? [window.endMs - edge, window.endMs] : [window.endMs - endHalf, window.endMs + endHalf];
144
+ return { inStartMs, inEndMs, outStartMs, outEndMs };
145
+ });
146
+ }
147
+
148
+ /** The gain of a window with `fade` at time `t`, as an ffmpeg expression: 0 outside, 1 inside, linear in the fades. */
149
+ function buildGainExpression(fade: SpeechRangeFade): string {
150
+ const rise = fade.inEndMs > fade.inStartMs ? `clip((t-${seconds(fade.inStartMs)})/${seconds(fade.inEndMs - fade.inStartMs)},0,1)` : `gte(t,${seconds(fade.inStartMs)})`;
151
+ const fall = fade.outEndMs > fade.outStartMs ? `clip((${seconds(fade.outEndMs)}-t)/${seconds(fade.outEndMs - fade.outStartMs)},0,1)` : `lt(t,${seconds(fade.outEndMs)})`;
152
+ return `min(${rise},${fall})`;
153
+ }
154
+
108
155
  /**
109
- * The clip's own sound with each window replaced by its cleaned range: the base muted inside every window, each
110
- * window cut from its cleaned file and delayed into place, summed without level change. As long as the base; 48 kHz
111
- * stereo like the speech track; a mono answer goes to both channels as it is, not up-mixed at -3 dB.
156
+ * The clip's own sound with each window replaced by its cleaned range, crossfaded at every join (`fadeMs`, default
157
+ * `DEFAULT_SPEECH_RANGE_FADE_MS`; 0 switches at once): each window is cut from its cleaned file to its fade bounds,
158
+ * faded in and out linearly and delayed into place in samples; the base is multiplied by one minus the windows'
159
+ * gains, so the sum keeps its level. As long as the base; 48 kHz stereo like the speech track; a mono answer goes to
160
+ * both channels as it is, not up-mixed at -3 dB.
112
161
  */
113
- export function buildRangeLayArgs(base: string, laid: readonly LaidRange[], output: string): string[] {
162
+ export function buildRangeLayArgs(base: string, laid: readonly LaidRange[], output: string, options: { fadeMs?: number } = {}): string[] {
114
163
  const format = `aformat=sample_rates=${FOOTAGE_SAMPLE_RATE}:channel_layouts=stereo`;
115
164
  if (laid.length === 0) return ["-v", "error", "-y", "-i", base, "-vn", "-af", format, "-c:a", "libmp3lame", "-q:a", "2", output];
165
+ const windows = laid.map(({ window }) => window);
166
+ const fades = getSpeechRangeFades(windows, options.fadeMs ?? DEFAULT_SPEECH_RANGE_FADE_MS);
167
+ const byWindow = new Map([...windows].sort((a, b) => a.startMs - b.startMs).map((window, index) => [window, fades[index]]));
116
168
  const inputs = ["-i", base];
117
- const mute = laid.map(({ window }) => `between(t,${seconds(window.startMs)},${seconds(window.endMs)})`).join("+");
118
- const parts = [`[0:a]${format},volume=0:enable='${mute}'[base]`];
169
+ const gains: string[] = [];
170
+ const parts: string[] = [];
119
171
  laid.forEach(({ window, file, isMono }, index) => {
172
+ const fade = byWindow.get(window);
173
+ if (fade === undefined) return;
120
174
  inputs.push("-i", file);
121
- const offset = window.startMs - window.range.startMs;
122
- const length = window.endMs - window.startMs;
175
+ gains.push(buildGainExpression(fade));
123
176
  const channels = isMono ? "pan=stereo|c0=c0|c1=c0," : "";
177
+ const fadeIn = fade.inEndMs > fade.inStartMs ? `,afade=t=in:st=0:d=${seconds(fade.inEndMs - fade.inStartMs)}` : "";
178
+ const fadeOut = fade.outEndMs > fade.outStartMs ? `,afade=t=out:st=${seconds(fade.outStartMs - fade.inStartMs)}:d=${seconds(fade.outEndMs - fade.outStartMs)}` : "";
179
+ const delay = Math.round((fade.inStartMs * FOOTAGE_SAMPLE_RATE) / 1000);
124
180
  parts.push(
125
- `[${index + 1}:a]atrim=start=${seconds(offset)}:end=${seconds(offset + length)},asetpts=PTS-STARTPTS,${channels}${format},adelay=${window.startMs}:all=1[w${index}]`,
181
+ `[${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)}]`,
126
182
  );
127
183
  });
128
- const mixed = laid.map((_, index) => `[w${index}]`).join("");
129
- parts.push(`[base]${mixed}amix=inputs=${laid.length + 1}:duration=first:normalize=0[speech]`);
184
+ parts.unshift(`[0:a]${format},aeval='val(ch)*(1-(${gains.join("+")}))':c=same[base]`);
185
+ const mixed = laid.map((_, index) => `[w${String(index)}]`).join("");
186
+ parts.push(`[base]${mixed}amix=inputs=${String(laid.length + 1)}:duration=first:normalize=0[speech]`);
130
187
  return ["-v", "error", "-y", ...inputs, "-filter_complex", parts.join(";"), "-map", "[speech]", "-c:a", "libmp3lame", "-q:a", "2", output];
131
188
  }
package/src/index.ts CHANGED
@@ -501,18 +501,31 @@ export {
501
501
  type FootageEstimateItem,
502
502
  } from "./footage/paid.js";
503
503
  export {
504
+ DEFAULT_SPEECH_RANGE_FADE_MS,
504
505
  DEFAULT_SPEECH_RANGE_MARGIN,
505
506
  buildRangeAudioArgs,
506
507
  buildRangeLayArgs,
507
508
  getSpeechRangeCache,
509
+ getSpeechRangeFades,
508
510
  getSpeechRangeWindows,
509
511
  planSpeechRanges,
510
512
  type LaidRange,
511
513
  type SpeechRange,
514
+ type SpeechRangeCacheResolver,
512
515
  type SpeechRangeClip,
516
+ type SpeechRangeFade,
513
517
  type SpeechRangeWindow,
514
518
  } from "./footage/speech-ranges.js";
515
- export { isolateSpeechRanges, type IsolateSpeechRangesOptions, type IsolatedSpeech, type IsolatedSpeechRange } from "./footage/isolate-ranges.js";
519
+ export {
520
+ DEFAULT_SPEECH_RANGE_ATTEMPTS,
521
+ DEFAULT_SPEECH_RANGE_RETRY_DELAYS_MS,
522
+ isolateSpeechRanges,
523
+ type IsolateSpeechRangesOptions,
524
+ type IsolatedSpeech,
525
+ type IsolatedSpeechRange,
526
+ type SpeechRangeOutcome,
527
+ type SpeechRangeRetry,
528
+ } from "./footage/isolate-ranges.js";
516
529
  export { RENDER_MIN_FREE_BYTES, findLowDiskProblems, getFreeBytes, getRenderTempDir, type FreeBytesReader } from "./footage/disk.js";
517
530
  export { DRAFT_FILTERS, REQUIRED_DECODERS, REQUIRED_FILTERS, checkFootageTools, findBrowserProblem, readFfmpegListing, type FootageToolsOptions } from "./footage/tools.js";
518
531
  export {
@@ -546,6 +559,7 @@ export {
546
559
  type RenderedFootage,
547
560
  type TranscribeOutcome,
548
561
  } from "./footage/pipeline.js";
562
+ export { isRetryableFootageFailure, type FootageError, type FootageFailure, type FootageFailureKind } from "./footage/failure.js";
549
563
  export {
550
564
  formatMessage,
551
565
  getMarketingMessages,