@softure-ai/marketing-kit 0.13.2 → 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 (60) hide show
  1. package/CHANGELOG.md +65 -0
  2. package/README.md +45 -13
  3. package/dist/config/schema.d.ts +2 -0
  4. package/dist/config/schema.d.ts.map +1 -1
  5. package/dist/config/schema.js +10 -2
  6. package/dist/config/schema.js.map +1 -1
  7. package/dist/footage/compose.d.ts +13 -0
  8. package/dist/footage/compose.d.ts.map +1 -1
  9. package/dist/footage/compose.js +26 -14
  10. package/dist/footage/compose.js.map +1 -1
  11. package/dist/footage/draft.js +2 -2
  12. package/dist/footage/draft.js.map +1 -1
  13. package/dist/footage/failure.d.ts +42 -0
  14. package/dist/footage/failure.d.ts.map +1 -0
  15. package/dist/footage/failure.js +14 -0
  16. package/dist/footage/failure.js.map +1 -0
  17. package/dist/footage/film-mix.d.ts +31 -0
  18. package/dist/footage/film-mix.d.ts.map +1 -0
  19. package/dist/footage/film-mix.js +45 -0
  20. package/dist/footage/film-mix.js.map +1 -0
  21. package/dist/footage/isolate-ranges.d.ts +47 -4
  22. package/dist/footage/isolate-ranges.d.ts.map +1 -1
  23. package/dist/footage/isolate-ranges.js +64 -14
  24. package/dist/footage/isolate-ranges.js.map +1 -1
  25. package/dist/footage/loudness.d.ts +91 -27
  26. package/dist/footage/loudness.d.ts.map +1 -1
  27. package/dist/footage/loudness.js +143 -69
  28. package/dist/footage/loudness.js.map +1 -1
  29. package/dist/footage/paid.d.ts +3 -0
  30. package/dist/footage/paid.d.ts.map +1 -1
  31. package/dist/footage/paid.js +2 -1
  32. package/dist/footage/paid.js.map +1 -1
  33. package/dist/footage/pipeline.d.ts +40 -12
  34. package/dist/footage/pipeline.d.ts.map +1 -1
  35. package/dist/footage/pipeline.js +137 -80
  36. package/dist/footage/pipeline.js.map +1 -1
  37. package/dist/footage/publish.js +4 -4
  38. package/dist/footage/publish.js.map +1 -1
  39. package/dist/footage/speech-ranges.d.ts +29 -4
  40. package/dist/footage/speech-ranges.d.ts.map +1 -1
  41. package/dist/footage/speech-ranges.js +56 -11
  42. package/dist/footage/speech-ranges.js.map +1 -1
  43. package/dist/index.d.ts +7 -5
  44. package/dist/index.d.ts.map +1 -1
  45. package/dist/index.js +6 -4
  46. package/dist/index.js.map +1 -1
  47. package/package.json +1 -1
  48. package/schema/marketing.schema.json +13 -1
  49. package/src/config/schema.ts +14 -2
  50. package/src/footage/compose.ts +33 -12
  51. package/src/footage/draft.ts +2 -2
  52. package/src/footage/failure.ts +44 -0
  53. package/src/footage/film-mix.ts +65 -0
  54. package/src/footage/isolate-ranges.ts +110 -14
  55. package/src/footage/loudness.ts +166 -68
  56. package/src/footage/paid.ts +5 -2
  57. package/src/footage/pipeline.ts +173 -90
  58. package/src/footage/publish.ts +4 -4
  59. package/src/footage/speech-ranges.ts +68 -11
  60. package/src/index.ts +43 -8
@@ -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
- import { composeFootage, END_CARD_SECONDS, getFootageFilmSeconds } from "./compose.js";
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";
@@ -21,23 +22,25 @@ import { chooseCutTransitions, type CutMeasure } from "./cuts.js";
21
22
  import { declickSpeech, describeDeclick, type DeclickReport } from "./declick.js";
22
23
  import { DEFAULT_AUTO_THRESHOLD, getDeclickLevel, getFootageEdit, type FootageClip, type FootageFilm, type MusicSource } from "./film.js";
23
24
  import { getFilmKeyTerms } from "./keyterms.js";
25
+ import { buildFilmMixArgs } from "./film-mix.js";
24
26
  import {
25
27
  buildMixArgs,
26
28
  DEFAULT_LOUDNESS,
27
- findLoudnessProblems,
28
29
  formatDb,
29
- getFirstMixAttempt,
30
- getMixTolerance,
30
+ getFirstMixCeiling,
31
+ getLoudnessVerdict,
32
+ getMixAttempts,
31
33
  getMixFilter,
32
- getNextMixAttempt,
34
+ getMixGain,
35
+ getMixTolerance,
36
+ getNextMixCeiling,
33
37
  measureLoudness,
34
- MIX_ATTEMPTS,
35
38
  normalizeLoudness,
39
+ solveMixGain,
36
40
  type LoudnessMeasurement,
37
41
  type MixAttempt,
38
42
  type MixLoudness,
39
43
  type MixLoudnessTarget,
40
- type MixTry,
41
44
  } from "./loudness.js";
42
45
  import { duckingKeyframes, getDuckingOptions } from "./music.js";
43
46
  import { FOOTAGE_FPS, normalizeFootage, type Frame, type NormalizeEncoder } from "./normalize.js";
@@ -99,6 +102,8 @@ const require = createRequire(import.meta.url);
99
102
  /** Bumped when the normalized format changes, so older normalized clips are made again. */
100
103
  const NORMALIZE_VERSION = 2;
101
104
 
105
+ export type { FootageResult } from "./failure.js";
106
+
102
107
  export interface FootageBrand {
103
108
  name: string;
104
109
  /** BCP 47, e.g. `en-US`. */
@@ -149,7 +154,6 @@ export interface PreparedClip {
149
154
  duration: number;
150
155
  }
151
156
 
152
- export type FootageResult<T> = TtsResult<T>;
153
157
 
154
158
  export type TranscribeOutcome =
155
159
  | { kind: "dry-run"; steps: PaidStep[] }
@@ -227,23 +231,23 @@ async function runPrepareFootage(
227
231
  options: Pick<FootageRunOptions, "buildDir" | "log" | "fetch" | "signal" | "onProgress" | "normalize">,
228
232
  ): Promise<FootageResult<PreparedClip[]>> {
229
233
  const { buildDir, log, signal } = options;
230
- 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" });
231
235
  const sources: Record<string, string> = {};
232
236
  for (const clip of film.clips) {
233
237
  if (!isUrl(clip.source)) {
234
- 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" });
235
239
  sources[clip.id] = clip.source;
236
240
  continue;
237
241
  }
238
242
  const downloaded = await download(clip.source, join(buildDir, "sources"), options);
239
- if (!downloaded.ok) return err(`clip "${clip.id}": ${downloaded.error}`);
243
+ if (!downloaded.ok) return err(`clip "${clip.id}": ${downloaded.error}`, downloaded.failure);
240
244
  sources[clip.id] = downloaded.value;
241
245
  }
242
246
  const probed = await probeFootage(film.clips, sources, signal === undefined ? {} : { signal });
243
247
  if (!probed.ok) return err(probed.errors.join("\n"));
244
248
  if (film.music.source.kind === "file") {
245
249
  const music = await checkMusicFile(film.music.source, options);
246
- if (!music.ok) return err(music.error);
250
+ if (!music.ok) return music;
247
251
  }
248
252
  const frame = getFrame(film);
249
253
  const clipsDir = join(buildDir, "clips");
@@ -320,7 +324,7 @@ async function runTranscribeFootage(film: FootageFilm, clips: PreparedClip[], op
320
324
  const { buildDir, providers, log, signal } = options;
321
325
  if (options.isPlaceholder) return ok(transcribePlaceholder(film, clips, buildDir));
322
326
  const keyTerms = getFilmKeyTerms(film);
323
- 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" });
324
328
  const sttKeyTerms = keyTerms.terms.length === 0 ? {} : { keyTerms: keyTerms.terms };
325
329
  const plan: { clip: PreparedClip; isolated: CacheEntry | null; transcript: CacheEntry }[] = [];
326
330
  const steps: PaidStep[] = [];
@@ -500,13 +504,13 @@ export function readEdlFile(film: FootageFilm, clips: PreparedClip[], edlPath: s
500
504
  try {
501
505
  json = JSON.parse(readFileSync(edlPath, "utf8")) as unknown;
502
506
  } catch (error) {
503
- return err(`${edlPath}: not JSON (${String(error)})`);
507
+ return err(`${edlPath}: not JSON (${String(error)})`, { kind: "input" });
504
508
  }
505
509
  const read = readEdl(json);
506
- if (!read.ok) return err(`${edlPath}: ${read.error}`);
510
+ if (!read.ok) return err(`${edlPath}: ${read.error}`, { kind: "input" });
507
511
  const bounds = getCaptionBounds(getFrame(film).height, getFootageCaptionLayout(film, layout));
508
512
  const problems = validateEdl(read.edl, clips.map((clip) => ({ id: clip.clip.id, duration: clip.duration })), film.id, bounds);
509
- 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);
510
514
  }
511
515
 
512
516
  /**
@@ -516,16 +520,16 @@ export function readEdlFile(film: FootageFilm, clips: PreparedClip[], edlPath: s
516
520
  */
517
521
  async function checkMusicFile(source: Extract<MusicSource, { kind: "file" }>, options: Pick<FootageRunOptions, "log" | "signal">): Promise<FootageResult<string>> {
518
522
  const { path, fileName, contentType } = source;
519
- if (!existsSync(path)) return err(`music: no file at ${path}`);
523
+ if (!existsSync(path)) return err(`music: no file at ${path}`, { kind: "input" });
520
524
  const name = fileName ?? path;
521
525
  if (extname(name) === "" && contentType === undefined) {
522
526
  options.log(`music: ${path} has no extension and no declared name or content type; the probe checks it.`);
523
527
  } else {
524
528
  const type = checkMusicFileType(contentType === undefined ? { fileName: name } : { fileName: name, contentType });
525
- if (!type.ok) return err(`music: ${type.error}`);
529
+ if (!type.ok) return err(`music: ${type.error}`, { kind: "input" });
526
530
  }
527
531
  const probe = await probeAudio(path, options.signal === undefined ? {} : { signal: options.signal });
528
- if (!probe.ok) return err(`music: ${probe.error}`);
532
+ if (!probe.ok) return err(`music: ${probe.error}`, { kind: "input" });
529
533
  options.log(`music: ${path} (${describeAudioProbe(probe.probe)}).`);
530
534
  return ok(path);
531
535
  }
@@ -550,7 +554,7 @@ export async function findFootageMusic(
550
554
  ): Promise<FootageResult<FootageMusicLookup>> {
551
555
  const source = film.music.source;
552
556
  if (source.kind === "none") return ok({ kind: "none" });
553
- 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" });
554
558
  let cache: CacheEntry;
555
559
  if (source.kind === "prompt") {
556
560
  cache = getPromptMusicCache(film, options);
@@ -693,7 +697,7 @@ async function runRenderFootage(
693
697
  ): Promise<FootageResult<RenderedFootage>> {
694
698
  const { buildDir, log, signal } = options;
695
699
  const finishVideoProblems = options.finishVideo === undefined ? [] : findFinishVideoProblems(options.finishVideo);
696
- if (finishVideoProblems.length > 0) return err(finishVideoProblems.join(" "));
700
+ if (finishVideoProblems.length > 0) return err(finishVideoProblems.join(" "), { kind: "input" });
697
701
  const lowDisk = findLowDiskProblems({ temp: getRenderTempDir(process.env, options.tempDir), build: buildDir }, options.readFreeBytes ?? getFreeBytes);
698
702
  if (lowDisk.length > 0) return err(`not enough disk space to render: ${lowDisk.join(" ")}`);
699
703
  const seconds = getFootageFilmSeconds(film, edl);
@@ -748,6 +752,32 @@ async function runRenderFootage(
748
752
  const output = join(assetsDir, "music.mp3");
749
753
  tracks.push({ item: "music", seconds, run: ffmpegTrack("The music track", output, () => buildMusicArgs({ input: musicFile, seconds, keyframes, output })) });
750
754
  }
755
+ const sfx: Partial<Record<SfxEvent, string>> = {};
756
+ mkdirSync(join(assetsDir, "sfx"), { recursive: true });
757
+ for (const [event, source] of Object.entries(options.sfx) as [SfxEvent, string][]) {
758
+ const name = `${event}${extname(source)}`;
759
+ cpSync(source, join(assetsDir, "sfx", name));
760
+ sfx[event] = `assets/sfx/${name}`;
761
+ }
762
+ // The film's mix, brought to `mixLoudness` and gated before hyperframes captures a frame (issue #1124).
763
+ const mixLoudness = getMixLoudnessTarget(film);
764
+ // Widened: the mix track assigns it inside a closure, which narrowing does not see.
765
+ let mixed = ok(null) as FootageResult<PreparedMix | null>;
766
+ if (mixLoudness !== null) {
767
+ const mixSource = join(buildDir, "mix.wav");
768
+ const musicTrack = musicFile === null ? null : { file: join(assetsDir, "music.mp3"), seconds };
769
+ const cues = getFootageSfxCues(film, edl, sfx).map((cue) => ({ ...cue, src: join(buildDir, cue.src) }));
770
+ tracks.push({
771
+ item: "mix",
772
+ seconds,
773
+ run: async (onSeconds) => {
774
+ const args = buildFilmMixArgs({ speech: { file: speechFile, seconds: getEdlDuration(edl) }, music: musicTrack, sfx: cues, seconds, output: mixSource });
775
+ await runFfmpeg("The film's mix", args, { ...aborting, output: mixSource, onSeconds });
776
+ mixed = await mixFootage(mixLoudness, { mixSource, output: join(buildDir, "mix.m4a") }, { log, ...aborting });
777
+ rmSync(mixSource, { force: true });
778
+ },
779
+ });
780
+ }
751
781
  // A single frame: counted as a moment of work so the stage's bar still ends at its total.
752
782
  const lastFrame = join(assetsDir, "last.jpg");
753
783
  tracks.push({ item: "last frame", seconds: 0.1, run: ffmpegTrack("The end card's backdrop", lastFrame, () => buildLastFrameArgs(edl, clipFiles, lastFrame)) });
@@ -765,16 +795,12 @@ async function runRenderFootage(
765
795
  await track.run((done) => assetProgress(index, done));
766
796
  assetProgress(index, track.seconds);
767
797
  }
798
+ // A mix that misses its target fails here, before any frame is rendered.
799
+ const prepared = mixed;
800
+ if (!prepared.ok) return prepared;
768
801
  const musicAsset = musicFile === null ? null : "assets/music.mp3";
769
802
  const fonts = copyFonts(options.brand.fonts, join(assetsDir, "fonts"));
770
803
  if (options.brand.logo !== null) cpSync(options.brand.logo, join(assetsDir, "logo.svg"));
771
- const sfx: Partial<Record<SfxEvent, string>> = {};
772
- mkdirSync(join(assetsDir, "sfx"), { recursive: true });
773
- for (const [event, source] of Object.entries(options.sfx) as [SfxEvent, string][]) {
774
- const name = `${event}${extname(source)}`;
775
- cpSync(source, join(assetsDir, "sfx", name));
776
- sfx[event] = `assets/sfx/${name}`;
777
- }
778
804
  cpSync(require.resolve("gsap/dist/gsap.min.js"), join(assetsDir, "gsap.min.js"));
779
805
  const base = resolveLayout(film.format, options.layout ?? {});
780
806
  // A caption preset places the 9:16 box in a platform's safe zone; the project's own caption override still wins.
@@ -786,7 +812,7 @@ async function runRenderFootage(
786
812
  brandName: options.brand.name,
787
813
  });
788
814
  if (missing.length > 0) {
789
- 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" });
790
816
  }
791
817
  const html = composeFootage({
792
818
  film,
@@ -816,7 +842,7 @@ async function runRenderFootage(
816
842
  const rendered = await runHyperframesRender(options, renderFile, seconds);
817
843
  if (!rendered.ok) return rendered;
818
844
  const roles = Object.fromEntries(clips.map((clip) => [clip.clip.id, clip.clip.role]));
819
- const finished = await finishFootage(film, { renderFile, seconds, coverAt: film.cover?.at ?? getDefaultCoverSeconds(edl, roles) }, options);
845
+ const finished = await finishFootage(film, { renderFile, seconds, coverAt: film.cover?.at ?? getDefaultCoverSeconds(edl, roles), mix: prepared.value }, options);
820
846
  if (!finished.ok) return finished;
821
847
  return ok({ kind: "rendered", output: options.output, seconds, edlPath: getEdlPath(buildDir, options.isPlaceholder), declick, ...finished.value });
822
848
  }
@@ -831,35 +857,89 @@ export interface FinishedFootage {
831
857
  /** The cover JPG, or null when the film has none. */
832
858
  cover: string | null;
833
859
  /** The finished file's sound as measured (EBU R128, true peak oversampled); null for a film without sound or a silent mix. */
834
- loudness: MixLoudness | null;
860
+ loudness: FinishedLoudness | null;
835
861
  /**
836
- * What the mix's last stage did: the render's mix as measured, the gain applied (0 when `keep: "speech"` found the
862
+ * What the mix's last stage did: the film's mix as measured, the gain applied (0 when `keep: "speech"` found the
837
863
  * mix inside its window) and the limiter's ceiling; null when no stage ran (no sound, a silent mix, `mixLoudness: null`).
838
864
  */
839
865
  mix: FinishedMix | null;
840
866
  }
841
867
 
868
+ /** The finished file's sound in `FinishedFootage`. */
869
+ export interface FinishedLoudness extends MixLoudness {
870
+ /**
871
+ * A sentence naming both values when the mix landed in `mixLoudness.warnTolerance`'s near-miss band instead of
872
+ * inside its tolerance; null otherwise.
873
+ */
874
+ warning: string | null;
875
+ }
876
+
842
877
  /** The mix's last stage in `FinishedFootage`. */
843
878
  export interface FinishedMix {
844
- /** The render's mix before the stage. */
879
+ /** The film's mix before the stage. */
845
880
  measured: MixLoudness;
846
881
  gainDb: number;
847
882
  ceilingDbtp: number;
848
883
  /** What the gain kept (`MixLoudnessTarget.keep`). */
849
884
  keep: "loudness" | "speech";
885
+ /** How many encodes the stage took. */
886
+ encodes: number;
887
+ }
888
+
889
+ /** A film's mix brought to its target by `mixFootage`: the encoded sound the final pass muxes, and what the stage did. */
890
+ export interface PreparedMix {
891
+ audioFile: string;
892
+ mix: FinishedMix;
893
+ }
894
+
895
+ /** The film's mix target: `mixLoudness`, the default when absent, null when the film keeps the render's sound. */
896
+ function getMixLoudnessTarget(film: Pick<FootageFilm, "mixLoudness">): MixLoudnessTarget | null {
897
+ return film.mixLoudness === undefined ? DEFAULT_LOUDNESS : film.mixLoudness;
850
898
  }
851
899
 
852
900
  /**
853
- * The final pass over hyperframes' render: the mix brought to `film.mixLoudness` (measured on the render; one linear
854
- * gain and a true peak limiter, encoded to AAC on its own and measured, the limiter lowered and encoded again while
855
- * the codec's overshoot breaks the limit), muxed with the picture (copied where the render already matches;
856
- * `finishVideo` re-encodes it to H.264 High at its preset and CRF), publishable codecs and fast start, checked with
857
- * ffprobe, the finished file's sound measured and held to the target, then the cover and the file's facts. Exported
858
- * for tests only.
901
+ * The mix stage over a film's sound (`mixSource`, any file ffmpeg reads): measured, brought to `target` and encoded
902
+ * to `output` (AAC) by `finishMix`; null when the mix is silent (the final pass then keeps the render's sound). An
903
+ * error names the last measurement. `renderFootage` runs it before hyperframes renders a frame (issue #1124).
904
+ */
905
+ export async function mixFootage(
906
+ target: MixLoudnessTarget,
907
+ input: { mixSource: string; output: string },
908
+ options: { log: (line: string) => void; signal?: AbortSignal },
909
+ ): Promise<FootageResult<PreparedMix | null>> {
910
+ const aborting = options.signal === undefined ? {} : { signal: options.signal };
911
+ const measured = await measureLoudness(input.mixSource, target, { label: "the film's mix", ...aborting });
912
+ if (measured.kind === "silent") {
913
+ options.log("loudness: the film's mix is silent, left as it is.");
914
+ return ok(null);
915
+ }
916
+ const mixed = await finishMix({ input: input.mixSource, output: input.output, measurement: measured.measurement, target, ...aborting });
917
+ if (!mixed.ok) {
918
+ rmSync(input.output, { force: true });
919
+ return mixed;
920
+ }
921
+ const { attempt, tries, probes } = mixed.value;
922
+ const keep = target.keep ?? "loudness";
923
+ const mix = { measured: { integrated: measured.measurement.inputI, truePeak: measured.measurement.inputTp }, gainDb: attempt.gainDb, ceilingDbtp: attempt.ceilingDbtp, keep, encodes: tries };
924
+ const kept = keep === "speech" ? ` (speech kept: ${formatDb(target.target)} ± ${getMixTolerance(target)} LUFS)` : "";
925
+ options.log(
926
+ `loudness: the film's mix measured ${formatDb(measured.measurement.inputI)} LUFS, true peak ${formatDb(measured.measurement.inputTp)} dBTP; ` +
927
+ `gain ${formatDb(attempt.gainDb)} dB${kept}, limiter at ${formatDb(attempt.ceilingDbtp)} dBTP (encode ${tries} of ${getMixAttempts(target)}, ${probes} uncompressed probes).`,
928
+ );
929
+ return ok({ audioFile: input.output, mix });
930
+ }
931
+
932
+ /**
933
+ * The final pass over hyperframes' render: the film's mix (`input.mix`, prepared by `mixFootage` before the render;
934
+ * null keeps the render's sound; absent, the render's own sound goes through `mixFootage` here) muxed with the
935
+ * picture (copied where the render already matches; `finishVideo` re-encodes it to H.264 High at its preset and CRF),
936
+ * publishable codecs and fast start, checked with ffprobe, the finished file's sound measured and held to the target
937
+ * (a near miss inside `warnTolerance` finishes with `loudness.warning`), then the cover and the file's facts.
938
+ * Exported for tests only.
859
939
  */
860
940
  export async function finishFootage(
861
941
  film: Pick<FootageFilm, "mixLoudness" | "cover">,
862
- input: { renderFile: string; seconds: number; coverAt: number },
942
+ input: { renderFile: string; seconds: number; coverAt: number; mix?: PreparedMix | null },
863
943
  options: Pick<RenderFootageOptions, "log" | "signal" | "output" | "onProgress" | "finishVideo">,
864
944
  ): Promise<FootageResult<FinishedFootage>> {
865
945
  const { log, signal, output } = options;
@@ -868,30 +948,15 @@ export async function finishFootage(
868
948
  progress(0, 0);
869
949
  const rendered = await probeFilmFacts(input.renderFile, aborting);
870
950
  if (!rendered.ok) return err(`the rendered film: ${rendered.error}`);
871
- const mixLoudness: MixLoudnessTarget | null = film.mixLoudness === undefined ? DEFAULT_LOUDNESS : film.mixLoudness;
872
- let audioFile: string | undefined;
873
- let mix: FinishedMix | null = null;
874
- if (mixLoudness !== null && rendered.facts.audio !== null) {
875
- const measured = await measureLoudness(input.renderFile, mixLoudness, { label: "the film's mix", ...aborting });
876
- if (measured.kind === "silent") {
877
- log("loudness: the film's mix is silent, left as it is.");
878
- } else {
879
- audioFile = join(dirname(input.renderFile), "mix.m4a");
880
- const mixed = await finishMix({ input: input.renderFile, output: audioFile, measurement: measured.measurement, target: mixLoudness, ...aborting });
881
- if (!mixed.ok) {
882
- rmSync(audioFile, { force: true });
883
- return mixed;
884
- }
885
- const { attempt, tries } = mixed.value;
886
- const keep = mixLoudness.keep ?? "loudness";
887
- mix = { measured: { integrated: measured.measurement.inputI, truePeak: measured.measurement.inputTp }, gainDb: attempt.gainDb, ceilingDbtp: attempt.ceilingDbtp, keep };
888
- const kept = keep === "speech" ? ` (speech kept: ${formatDb(mixLoudness.target)} ± ${getMixTolerance(mixLoudness)} LUFS)` : "";
889
- log(
890
- `loudness: the film's mix measured ${formatDb(measured.measurement.inputI)} LUFS, true peak ${formatDb(measured.measurement.inputTp)} dBTP; ` +
891
- `gain ${formatDb(attempt.gainDb)} dB${kept}, limiter at ${formatDb(attempt.ceilingDbtp)} dBTP (encode ${tries} of ${MIX_ATTEMPTS}).`,
892
- );
893
- }
951
+ const mixLoudness = getMixLoudnessTarget(film);
952
+ let prepared: PreparedMix | null = input.mix ?? null;
953
+ if (input.mix === undefined && mixLoudness !== null && rendered.facts.audio !== null) {
954
+ const mixed = await mixFootage(mixLoudness, { mixSource: input.renderFile, output: join(dirname(input.renderFile), "mix.m4a") }, { log, ...aborting });
955
+ if (!mixed.ok) return mixed;
956
+ prepared = mixed.value;
894
957
  }
958
+ const audioFile = prepared?.audioFile;
959
+ const mix = prepared?.mix ?? null;
895
960
  const { finishVideo } = options;
896
961
  const isVideoCopied = finishVideo === undefined && isPublishableVideo(rendered.facts.video);
897
962
  const isAudioCopied = audioFile === undefined && (rendered.facts.audio === null || isPublishableAudio(rendered.facts.audio));
@@ -902,21 +967,23 @@ export async function finishFootage(
902
967
  const finished = await probeFilmFacts(output, aborting);
903
968
  if (!finished.ok) return err(`the finished film: ${finished.error}`);
904
969
  const problems = findFinishProblems(finished.facts, readTopLevelBoxes(output));
905
- if (problems.length > 0) return err(`the finished film ${output} is not publishable: ${problems.join("; ")}.`);
906
- let loudness: MixLoudness | null = null;
970
+ if (problems.length > 0) return err(`the finished film ${output} is not publishable: ${problems.join("; ")}.`, { kind: "publishable", problems });
971
+ let loudness: FinishedLoudness | null = null;
907
972
  if (finished.facts.audio !== null) {
908
973
  const measured = await measureLoudness(output, mixLoudness ?? DEFAULT_LOUDNESS, { label: "the finished film", ...aborting });
909
974
  if (measured.kind === "measured") {
910
- loudness = { integrated: measured.measurement.inputI, truePeak: measured.measurement.inputTp };
975
+ const sound = { integrated: measured.measurement.inputI, truePeak: measured.measurement.inputTp };
911
976
  // A mix left as rendered (`mixLoudness: null`) or silent is reported, not held to a target it was not brought to.
912
- const misses = mixLoudness === null || audioFile === undefined ? [] : findLoudnessProblems(loudness, mixLoudness);
913
- if (misses.length > 0) return err(`the finished film ${output} measures ${describeMixLoudness(loudness)}: ${misses.join("; ")}.`);
914
- log(`loudness: the finished film measures ${formatDb(loudness.integrated)} LUFS, true peak ${formatDb(loudness.truePeak)} dBTP.`);
977
+ const verdict = mixLoudness === null || audioFile === undefined ? { kind: "pass" as const } : getLoudnessVerdict(sound, mixLoudness);
978
+ if (verdict.kind === "fail") return err(`the finished film ${output} measures ${describeMixLoudness(sound)}: ${verdict.problems.join("; ")}.`, { kind: "loudness", loudness: sound });
979
+ loudness = { ...sound, warning: verdict.kind === "warn" ? `the finished film ${output}: ${verdict.warning}` : null };
980
+ log(`loudness: the finished film measures ${formatDb(sound.integrated)} LUFS, true peak ${formatDb(sound.truePeak)} dBTP.`);
981
+ if (loudness.warning !== null) log(`loudness warning: ${loudness.warning}`);
915
982
  }
916
983
  }
917
984
  progress(0, input.seconds);
918
985
  const { bytes, width, height, durationSeconds } = finished.facts;
919
- const streams = describeFinishStreams({ isVideoCopied, isAudioCopied, hasAudio: rendered.facts.audio !== null, ...(finishVideo === undefined ? {} : { finishVideo }) });
986
+ const streams = describeFinishStreams({ isVideoCopied, isAudioCopied, hasAudio: finished.facts.audio !== null, ...(finishVideo === undefined ? {} : { finishVideo }) });
920
987
  log(`finish: ${streams} to H.264 ${finished.facts.video.profile ?? ""}, AAC 48 kHz stereo, fast start; ${width}×${height}, ${durationSeconds.toFixed(2)} s, ${bytes} bytes.`);
921
988
  let cover: string | null = null;
922
989
  if (film.cover !== null) {
@@ -930,9 +997,11 @@ export async function finishFootage(
930
997
  }
931
998
 
932
999
  /**
933
- * The mix's sound brought to `target` on its own: gain and limiter, encoded to AAC, measured; while the encoded file
934
- * misses the target the gain and the ceiling are corrected and it is encoded again, at most `MIX_ATTEMPTS` times. An
935
- * error names the last measurement.
1000
+ * The mix's sound brought to `target` on its own, at a fixed ceiling (issue #1124): the gain is solved on
1001
+ * uncompressed passes (`solveMixGain`), then the mix is encoded to AAC and measured. While the encode misses, the
1002
+ * ceiling is lowered only by its true peak excess (the codec's overshoot) and the gain solved again at it, shifted by
1003
+ * the codec's measured loudness drift, at most `getMixAttempts` encodes. A last encode inside `warnTolerance` passes
1004
+ * (the finished file's gate names the warning); otherwise an error names the last measurement.
936
1005
  */
937
1006
  async function finishMix(input: {
938
1007
  input: string;
@@ -940,26 +1009,40 @@ async function finishMix(input: {
940
1009
  measurement: LoudnessMeasurement;
941
1010
  target: MixLoudnessTarget;
942
1011
  signal?: AbortSignal;
943
- }): Promise<FootageResult<{ attempt: MixAttempt; tries: number; measured: MixLoudness }>> {
1012
+ }): Promise<FootageResult<{ attempt: MixAttempt; tries: number; probes: number; measured: MixLoudness }>> {
944
1013
  const aborting = input.signal === undefined ? {} : { signal: input.signal };
945
- let attempt = getFirstMixAttempt(input.measurement, input.target);
946
- let misses: string[] = [];
947
- let measured: MixLoudness = { integrated: input.measurement.inputI, truePeak: input.measurement.inputTp };
948
- const done: MixTry[] = [];
949
- for (let tries = 1; tries <= MIX_ATTEMPTS; tries += 1) {
1014
+ const attempts = getMixAttempts(input.target);
1015
+ const probe = async (attempt: MixAttempt): Promise<MixLoudness> => {
1016
+ const probed = await measureLoudness(input.input, input.target, { label: "the film's mix through its limiter", filter: getMixFilter(attempt), ...aborting });
1017
+ // A probe through a limiter on a mix that is not silent does not go silent; if it does, the encode reports it.
1018
+ return probed.kind === "silent" ? { integrated: -Infinity, truePeak: -Infinity } : { integrated: probed.measurement.inputI, truePeak: probed.measurement.inputTp };
1019
+ };
1020
+ let ceilingDbtp = getFirstMixCeiling(input.target);
1021
+ let startGainDb = getMixGain(input.measurement.inputI, input.target);
1022
+ let shift = 0;
1023
+ let probes = 0;
1024
+ for (let tries = 1; tries <= attempts; tries += 1) {
1025
+ const solved = await solveMixGain({ ceilingDbtp, startGainDb, target: input.target, shift, measure: probe });
1026
+ probes += solved.probes.length;
1027
+ const attempt = solved.best.attempt;
950
1028
  await runFfmpeg("The film's mix", buildMixArgs({ input: input.input, filter: getMixFilter(attempt), output: input.output }), { ...aborting, output: input.output });
951
1029
  const encoded = await measureLoudness(input.output, input.target, { label: "the film's encoded mix", ...aborting });
952
- if (encoded.kind === "silent") return err("the film's mix measures silent after its gain and limiter.");
953
- measured = { integrated: encoded.measurement.inputI, truePeak: encoded.measurement.inputTp };
954
- misses = findLoudnessProblems(measured, input.target);
955
- if (misses.length === 0) return ok({ attempt, tries, measured });
956
- done.push({ attempt, measured });
957
- if (tries < MIX_ATTEMPTS) attempt = getNextMixAttempt(done, input.measurement.inputI, input.target);
1030
+ if (encoded.kind === "silent") return err("the film's mix measures silent after its gain and limiter.", { kind: "loudness", loudness: null });
1031
+ const measured = { integrated: encoded.measurement.inputI, truePeak: encoded.measurement.inputTp };
1032
+ const verdict = getLoudnessVerdict(measured, input.target);
1033
+ if (verdict.kind === "pass" || (verdict.kind === "warn" && tries === attempts)) return ok({ attempt, tries, probes, measured });
1034
+ if (tries === attempts) {
1035
+ return err(
1036
+ `the film's mix still measures ${describeMixLoudness(measured)} after ${attempts} encodes (last: gain ${formatDb(attempt.gainDb)} dB, ` +
1037
+ `limiter at ${formatDb(attempt.ceilingDbtp)} dBTP): ${verdict.kind === "fail" ? verdict.problems.join("; ") : ""}.`,
1038
+ { kind: "loudness", loudness: measured },
1039
+ );
1040
+ }
1041
+ shift = Number.isFinite(solved.best.measured.integrated) ? measured.integrated - solved.best.measured.integrated : 0;
1042
+ ceilingDbtp = getNextMixCeiling(attempt.ceilingDbtp, measured, input.target);
1043
+ startGainDb = attempt.gainDb;
958
1044
  }
959
- return err(
960
- `the film's mix still measures ${describeMixLoudness(measured)} after ${MIX_ATTEMPTS} encodes (last: gain ${formatDb(attempt.gainDb)} dB, ` +
961
- `limiter at ${formatDb(attempt.ceilingDbtp)} dBTP): ${misses.join("; ")}.`,
962
- );
1045
+ return err(`the film's mix was not encoded: mixLoudness.attempts is ${attempts}.`, { kind: "input" });
963
1046
  }
964
1047
 
965
1048
  /** Both measurements of a mix, as an error names them. */
@@ -164,10 +164,10 @@ export function buildFinishArgs(
164
164
  const encodeAudio = ["-c:a", "aac", "-b:a", FINISHED_AUDIO_BITRATE, "-ar", String(FOOTAGE_SAMPLE_RATE), "-ac", "2"];
165
165
  const inputs = options.audioFile === undefined ? ["-i", input] : ["-i", input, "-i", options.audioFile];
166
166
  const audio =
167
- facts.audio === null
168
- ? []
169
- : options.audioFile !== undefined
170
- ? ["-map", "1:a:0", "-c:a", "copy"]
167
+ options.audioFile !== undefined
168
+ ? ["-map", "1:a:0", "-c:a", "copy"]
169
+ : facts.audio === null
170
+ ? []
171
171
  : options.audioFilter !== undefined
172
172
  ? ["-map", "0:a:0", "-af", options.audioFilter, ...encodeAudio]
173
173
  : isPublishableAudio(facts.audio)
@@ -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
  }