@softure-ai/marketing-kit 0.10.0 → 0.12.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 (91) hide show
  1. package/CHANGELOG.md +82 -0
  2. package/README.md +81 -9
  3. package/dist/cli/footage.js +1 -1
  4. package/dist/cli/footage.js.map +1 -1
  5. package/dist/compose/timeline.d.ts +23 -3
  6. package/dist/compose/timeline.d.ts.map +1 -1
  7. package/dist/compose/timeline.js +31 -11
  8. package/dist/compose/timeline.js.map +1 -1
  9. package/dist/config/actions-schema.d.ts +14 -14
  10. package/dist/config/config.d.ts.map +1 -1
  11. package/dist/config/config.js +2 -0
  12. package/dist/config/config.js.map +1 -1
  13. package/dist/config/schema.d.ts +83 -70
  14. package/dist/config/schema.d.ts.map +1 -1
  15. package/dist/config/schema.js +21 -1
  16. package/dist/config/schema.js.map +1 -1
  17. package/dist/config/shot-steps.d.ts +16 -16
  18. package/dist/footage/captions.d.ts +45 -3
  19. package/dist/footage/captions.d.ts.map +1 -1
  20. package/dist/footage/captions.js +65 -5
  21. package/dist/footage/captions.js.map +1 -1
  22. package/dist/footage/compose.d.ts.map +1 -1
  23. package/dist/footage/compose.js +8 -4
  24. package/dist/footage/compose.js.map +1 -1
  25. package/dist/footage/declick.d.ts +106 -0
  26. package/dist/footage/declick.d.ts.map +1 -0
  27. package/dist/footage/declick.js +296 -0
  28. package/dist/footage/declick.js.map +1 -0
  29. package/dist/footage/draft.d.ts +8 -3
  30. package/dist/footage/draft.d.ts.map +1 -1
  31. package/dist/footage/draft.js +55 -22
  32. package/dist/footage/draft.js.map +1 -1
  33. package/dist/footage/edl.d.ts +28 -2
  34. package/dist/footage/edl.d.ts.map +1 -1
  35. package/dist/footage/edl.js +53 -2
  36. package/dist/footage/edl.js.map +1 -1
  37. package/dist/footage/film.d.ts +29 -3
  38. package/dist/footage/film.d.ts.map +1 -1
  39. package/dist/footage/film.js +12 -0
  40. package/dist/footage/film.js.map +1 -1
  41. package/dist/footage/isolate-ranges.d.ts +37 -0
  42. package/dist/footage/isolate-ranges.d.ts.map +1 -0
  43. package/dist/footage/isolate-ranges.js +113 -0
  44. package/dist/footage/isolate-ranges.js.map +1 -0
  45. package/dist/footage/loudness.d.ts +58 -0
  46. package/dist/footage/loudness.d.ts.map +1 -1
  47. package/dist/footage/loudness.js +80 -0
  48. package/dist/footage/loudness.js.map +1 -1
  49. package/dist/footage/paid.d.ts +18 -0
  50. package/dist/footage/paid.d.ts.map +1 -1
  51. package/dist/footage/paid.js +32 -2
  52. package/dist/footage/paid.js.map +1 -1
  53. package/dist/footage/pipeline.d.ts +51 -6
  54. package/dist/footage/pipeline.d.ts.map +1 -1
  55. package/dist/footage/pipeline.js +120 -23
  56. package/dist/footage/pipeline.js.map +1 -1
  57. package/dist/footage/providers.d.ts +5 -0
  58. package/dist/footage/providers.d.ts.map +1 -1
  59. package/dist/footage/publish.d.ts +26 -2
  60. package/dist/footage/publish.d.ts.map +1 -1
  61. package/dist/footage/publish.js +48 -14
  62. package/dist/footage/publish.js.map +1 -1
  63. package/dist/footage/speech-ranges.d.ts +65 -0
  64. package/dist/footage/speech-ranges.d.ts.map +1 -0
  65. package/dist/footage/speech-ranges.js +98 -0
  66. package/dist/footage/speech-ranges.js.map +1 -0
  67. package/dist/index.d.ts +11 -8
  68. package/dist/index.d.ts.map +1 -1
  69. package/dist/index.js +11 -8
  70. package/dist/index.js.map +1 -1
  71. package/package.json +1 -1
  72. package/schema/edl.schema.json +17 -0
  73. package/schema/marketing.schema.json +43 -1
  74. package/src/cli/footage.ts +1 -1
  75. package/src/compose/timeline.ts +41 -10
  76. package/src/config/config.ts +2 -0
  77. package/src/config/schema.ts +23 -1
  78. package/src/footage/captions.ts +81 -6
  79. package/src/footage/compose.ts +8 -4
  80. package/src/footage/declick.ts +353 -0
  81. package/src/footage/draft.ts +58 -23
  82. package/src/footage/edl.ts +69 -2
  83. package/src/footage/film.ts +37 -3
  84. package/src/footage/isolate-ranges.ts +161 -0
  85. package/src/footage/loudness.ts +112 -0
  86. package/src/footage/paid.ts +40 -2
  87. package/src/footage/pipeline.ts +178 -25
  88. package/src/footage/providers.ts +2 -0
  89. package/src/footage/publish.ts +67 -15
  90. package/src/footage/speech-ranges.ts +131 -0
  91. package/src/index.ts +72 -0
@@ -13,14 +13,31 @@ 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 } from "./compose.js";
16
- import { findMissingCaptionGlyphs, getFootageCaptionLayout } from "./captions.js";
16
+ import { findMissingCaptionGlyphs, getCaptionBounds, getFootageCaptionLayout } from "./captions.js";
17
17
  import { findLowDiskProblems, getFreeBytes, getRenderTempDir, type FreeBytesReader } from "./disk.js";
18
18
  import { buildEdl, getEdlDuration, readEdl, remapWords, validateEdl, type Edl } from "./edl.js";
19
19
  import { makePlaceholderTranscript } from "./fake.js";
20
20
  import { chooseCutTransitions, type CutMeasure } from "./cuts.js";
21
- import { DEFAULT_AUTO_THRESHOLD, getFootageEdit, type FootageClip, type FootageFilm, type MusicSource } from "./film.js";
21
+ import { declickSpeech, describeDeclick, type DeclickReport } from "./declick.js";
22
+ import { DEFAULT_AUTO_THRESHOLD, getDeclickLevel, getFootageEdit, type FootageClip, type FootageFilm, type MusicSource } from "./film.js";
22
23
  import { getFilmKeyTerms } from "./keyterms.js";
23
- import { DEFAULT_LOUDNESS, getLoudnessFilter, measureLoudness, normalizeLoudness } from "./loudness.js";
24
+ import {
25
+ buildMixArgs,
26
+ DEFAULT_LOUDNESS,
27
+ findLoudnessProblems,
28
+ formatDb,
29
+ getFirstMixAttempt,
30
+ getMixTolerance,
31
+ getMixFilter,
32
+ getNextMixAttempt,
33
+ measureLoudness,
34
+ MIX_ATTEMPTS,
35
+ normalizeLoudness,
36
+ type LoudnessMeasurement,
37
+ type MixAttempt,
38
+ type MixLoudness,
39
+ type MixLoudnessTarget,
40
+ } from "./loudness.js";
24
41
  import { duckingKeyframes, getDuckingOptions } from "./music.js";
25
42
  import { FOOTAGE_FPS, normalizeFootage, type Frame, type NormalizeEncoder } from "./normalize.js";
26
43
  import { buildPictureConcatArgs, buildPictureList, buildPicturePieceArgs, getPictureFrames, planFootagePicture } from "./picture.js";
@@ -43,12 +60,14 @@ import {
43
60
  buildFinishArgs,
44
61
  clampCoverSeconds,
45
62
  findFinishProblems,
63
+ findFinishVideoProblems,
46
64
  getCoverPath,
47
65
  getDefaultCoverSeconds,
48
66
  isPublishableAudio,
49
67
  isPublishableVideo,
50
68
  probeFilmFacts,
51
69
  readTopLevelBoxes,
70
+ type FinishVideo,
52
71
  } from "./publish.js";
53
72
  import { describePaidSteps, toPaidAudio, type FootageCharge, type FootageProgress, type FootageProviders, type FootageStage, type PaidAudio, type PaidStep } from "./providers.js";
54
73
  import { buildAudioArgs, buildCutPreviewArgs, buildLastFrameArgs, buildMusicArgs, buildSpeechArgs, getSpeechCutOptions } from "./render.js";
@@ -471,8 +490,11 @@ export function describeCutMeasures(cuts: CutMeasure[]): string[] {
471
490
  return cuts.map((cut) => `${cut.segment}: ${cut.transition} (difference ${cut.difference.toFixed(3)})`);
472
491
  }
473
492
 
474
- /** The EDL file as written by `cutFootage` or edited by hand, checked against the clips. */
475
- export function readEdlFile(film: FootageFilm, clips: PreparedClip[], edlPath: string): FootageResult<Edl> {
493
+ /**
494
+ * The EDL file as written by `cutFootage` or edited by hand, checked against the clips and (a segment's own caption
495
+ * box) against the film's frame, with the caption size the project's `layout` gives.
496
+ */
497
+ export function readEdlFile(film: FootageFilm, clips: PreparedClip[], edlPath: string, layout: LayoutOverride = {}): FootageResult<Edl> {
476
498
  let json: unknown;
477
499
  try {
478
500
  json = JSON.parse(readFileSync(edlPath, "utf8")) as unknown;
@@ -481,7 +503,8 @@ export function readEdlFile(film: FootageFilm, clips: PreparedClip[], edlPath: s
481
503
  }
482
504
  const read = readEdl(json);
483
505
  if (!read.ok) return err(`${edlPath}: ${read.error}`);
484
- const problems = validateEdl(read.edl, clips.map((clip) => ({ id: clip.clip.id, duration: clip.duration })), film.id);
506
+ const bounds = getCaptionBounds(getFrame(film).height, getFootageCaptionLayout(film, layout));
507
+ const problems = validateEdl(read.edl, clips.map((clip) => ({ id: clip.clip.id, duration: clip.duration })), film.id, bounds);
485
508
  return problems.length > 0 ? err(`${edlPath}: ${problems.join("; ")}`) : ok(read.edl);
486
509
  }
487
510
 
@@ -588,6 +611,17 @@ async function getMusic(film: FootageFilm, edl: Edl, clips: PreparedClip[], seco
588
611
  return ok(path);
589
612
  }
590
613
 
614
+ /**
615
+ * The speech chain's files: the cut speech, the declicked track and the final `speech.mp3`. The last stage that runs
616
+ * writes `speech.mp3`; the declicked track is float WAV when the loudness pass follows (one lossy encode fewer).
617
+ */
618
+ export function getSpeechChainFiles(assetsDir: string, stages: { isDeclick: boolean; isLoudness: boolean }): { rawSpeechFile: string; declickedFile: string; speechFile: string } {
619
+ const speechFile = join(assetsDir, "speech.mp3");
620
+ const rawSpeechFile = stages.isDeclick || stages.isLoudness ? join(assetsDir, "speech.raw.mp3") : speechFile;
621
+ const declickedFile = !stages.isDeclick ? rawSpeechFile : stages.isLoudness ? join(assetsDir, "speech.declicked.wav") : speechFile;
622
+ return { rawSpeechFile, declickedFile, speechFile };
623
+ }
624
+
591
625
  export interface RenderFootageOptions extends FootageRunOptions {
592
626
  brand: FootageBrand;
593
627
  sfx: Partial<Record<SfxEvent, string>>;
@@ -620,9 +654,24 @@ export interface RenderFootageOptions extends FootageRunOptions {
620
654
  * `slow`). `quality: "draft"` with `crf: 18` encodes fast at the published quality. By default the tier's CRF.
621
655
  */
622
656
  crf?: number;
657
+ /**
658
+ * Re-encode the picture in the final pass instead of copying it: H.264 High, yuv420p, at this x264 preset and CRF,
659
+ * optionally capped at `maxBitrate` (issue #1068). `quality: "draft", crf: 18` plus `{ preset: "veryfast", crf: 20 }`
660
+ * publishes High at a controlled size. By default the picture is copied when publishable.
661
+ */
662
+ finishVideo?: FinishVideo;
623
663
  }
624
664
 
625
- export type RenderedFootage = { kind: "dry-run"; steps: PaidStep[] } | ({ kind: "rendered"; output: string; seconds: number; edlPath: string } & FinishedFootage);
665
+ export type RenderedFootage =
666
+ | { kind: "dry-run"; steps: PaidStep[] }
667
+ | ({
668
+ kind: "rendered";
669
+ output: string;
670
+ seconds: number;
671
+ edlPath: string;
672
+ /** What the speech track's declick stage did (`FootageFilm.speech.declick`); null when it is off. */
673
+ declick: DeclickReport | null;
674
+ } & FinishedFootage);
626
675
 
627
676
  /**
628
677
  * Composes the cut and renders it: speech track (loudness-normalized), ducked music, end card backdrop, assets,
@@ -642,6 +691,8 @@ async function runRenderFootage(
642
691
  options: RenderFootageOptions,
643
692
  ): Promise<FootageResult<RenderedFootage>> {
644
693
  const { buildDir, log, signal } = options;
694
+ const finishVideoProblems = options.finishVideo === undefined ? [] : findFinishVideoProblems(options.finishVideo);
695
+ if (finishVideoProblems.length > 0) return err(finishVideoProblems.join(" "));
645
696
  const lowDisk = findLowDiskProblems({ temp: getRenderTempDir(process.env, options.tempDir), build: buildDir }, options.readFreeBytes ?? getFreeBytes);
646
697
  if (lowDisk.length > 0) return err(`not enough disk space to render: ${lowDisk.join(" ")}`);
647
698
  const seconds = getFootageFilmSeconds(film, edl);
@@ -660,18 +711,29 @@ async function runRenderFootage(
660
711
  const musicFile = typeof music.value === "string" ? music.value : null;
661
712
  const aborting = signal === undefined ? {} : { signal };
662
713
  const loudness = film.loudness === undefined ? DEFAULT_LOUDNESS : film.loudness;
663
- const speechFile = join(assetsDir, "speech.mp3");
664
- const rawSpeechFile = loudness === null ? speechFile : join(assetsDir, "speech.raw.mp3");
714
+ const declickLevel = getDeclickLevel(film);
715
+ const { speechFile, rawSpeechFile, declickedFile } = getSpeechChainFiles(assetsDir, { isDeclick: declickLevel !== "off", isLoudness: loudness !== null });
665
716
  const ffmpegTrack = (label: string, output: string, args: () => string[]) => (onSeconds: (done: number) => void) => runFfmpeg(label, args(), { ...aborting, output, onSeconds });
666
717
  const tracks: { item: string; seconds: number; run: (onSeconds: (done: number) => void) => Promise<void> }[] = [
667
718
  { item: "speech", seconds, run: ffmpegTrack("The speech track", rawSpeechFile, () => buildSpeechArgs(edl, transcript.speech, rawSpeechFile, getSpeechCutOptions(getFootageEdit(film)))) },
668
719
  ];
720
+ let declick: DeclickReport | null = null;
721
+ if (declickLevel !== "off") {
722
+ tracks.push({
723
+ item: "declick",
724
+ seconds,
725
+ run: async (onSeconds) => {
726
+ declick = await declickSpeech({ input: rawSpeechFile, output: declickedFile, words, level: declickLevel, seconds, ...aborting, onSeconds });
727
+ log(describeDeclick(declick));
728
+ },
729
+ });
730
+ }
669
731
  if (loudness !== null) {
670
732
  tracks.push({
671
733
  item: "loudness",
672
734
  seconds,
673
735
  run: async (onSeconds) => {
674
- const outcome = await normalizeLoudness(rawSpeechFile, speechFile, loudness, { ...aborting, onSeconds });
736
+ const outcome = await normalizeLoudness(declickedFile, speechFile, loudness, { ...aborting, onSeconds });
675
737
  log(
676
738
  outcome.kind === "silent"
677
739
  ? "loudness: the speech track is silent, left as it is."
@@ -755,7 +817,7 @@ async function runRenderFootage(
755
817
  const roles = Object.fromEntries(clips.map((clip) => [clip.clip.id, clip.clip.role]));
756
818
  const finished = await finishFootage(film, { renderFile, seconds, coverAt: film.cover?.at ?? getDefaultCoverSeconds(edl, roles) }, options);
757
819
  if (!finished.ok) return finished;
758
- return ok({ kind: "rendered", output: options.output, seconds, edlPath: getEdlPath(buildDir, options.isPlaceholder), ...finished.value });
820
+ return ok({ kind: "rendered", output: options.output, seconds, edlPath: getEdlPath(buildDir, options.isPlaceholder), declick, ...finished.value });
759
821
  }
760
822
 
761
823
  /** What `renderFootage` reads from the written film. */
@@ -767,17 +829,37 @@ export interface FinishedFootage {
767
829
  durationSeconds: number;
768
830
  /** The cover JPG, or null when the film has none. */
769
831
  cover: string | null;
832
+ /** The finished file's sound as measured (EBU R128, true peak oversampled); null for a film without sound or a silent mix. */
833
+ loudness: MixLoudness | null;
834
+ /**
835
+ * What the mix's last stage did: the render's mix as measured, the gain applied (0 when `keep: "speech"` found the
836
+ * mix inside its window) and the limiter's ceiling; null when no stage ran (no sound, a silent mix, `mixLoudness: null`).
837
+ */
838
+ mix: FinishedMix | null;
839
+ }
840
+
841
+ /** The mix's last stage in `FinishedFootage`. */
842
+ export interface FinishedMix {
843
+ /** The render's mix before the stage. */
844
+ measured: MixLoudness;
845
+ gainDb: number;
846
+ ceilingDbtp: number;
847
+ /** What the gain kept (`MixLoudnessTarget.keep`). */
848
+ keep: "loudness" | "speech";
770
849
  }
771
850
 
772
851
  /**
773
- * The final pass over hyperframes' render: the mix normalized to `film.mixLoudness` (measured on the render, one
774
- * linear gain; the picture still copied), publishable codecs and fast start (stream copy where the render already
775
- * matches), checked with ffprobe, then the cover and the file's facts. Exported for tests only.
852
+ * The final pass over hyperframes' render: the mix brought to `film.mixLoudness` (measured on the render; one linear
853
+ * gain and a true peak limiter, encoded to AAC on its own and measured, the limiter lowered and encoded again while
854
+ * the codec's overshoot breaks the limit), muxed with the picture (copied where the render already matches;
855
+ * `finishVideo` re-encodes it to H.264 High at its preset and CRF), publishable codecs and fast start, checked with
856
+ * ffprobe, the finished file's sound measured and held to the target, then the cover and the file's facts. Exported
857
+ * for tests only.
776
858
  */
777
859
  export async function finishFootage(
778
860
  film: Pick<FootageFilm, "mixLoudness" | "cover">,
779
861
  input: { renderFile: string; seconds: number; coverAt: number },
780
- options: Pick<RenderFootageOptions, "log" | "signal" | "output" | "onProgress">,
862
+ options: Pick<RenderFootageOptions, "log" | "signal" | "output" | "onProgress" | "finishVideo">,
781
863
  ): Promise<FootageResult<FinishedFootage>> {
782
864
  const { log, signal, output } = options;
783
865
  const aborting = signal === undefined ? {} : { signal };
@@ -785,29 +867,55 @@ export async function finishFootage(
785
867
  progress(0, 0);
786
868
  const rendered = await probeFilmFacts(input.renderFile, aborting);
787
869
  if (!rendered.ok) return err(`the rendered film: ${rendered.error}`);
788
- const mixLoudness = film.mixLoudness === undefined ? DEFAULT_LOUDNESS : film.mixLoudness;
789
- let audioFilter: string | undefined;
870
+ const mixLoudness: MixLoudnessTarget | null = film.mixLoudness === undefined ? DEFAULT_LOUDNESS : film.mixLoudness;
871
+ let audioFile: string | undefined;
872
+ let mix: FinishedMix | null = null;
790
873
  if (mixLoudness !== null && rendered.facts.audio !== null) {
791
874
  const measured = await measureLoudness(input.renderFile, mixLoudness, { label: "the film's mix", ...aborting });
792
875
  if (measured.kind === "silent") {
793
876
  log("loudness: the film's mix is silent, left as it is.");
794
877
  } else {
795
- audioFilter = getLoudnessFilter(measured.measurement, mixLoudness);
796
- log(`loudness: the film's mix measured ${measured.measurement.inputI.toFixed(1)} LUFS, normalized to ${mixLoudness.target} LUFS (true peak ${mixLoudness.truePeak} dBTP).`);
878
+ audioFile = join(dirname(input.renderFile), "mix.m4a");
879
+ const mixed = await finishMix({ input: input.renderFile, output: audioFile, measurement: measured.measurement, target: mixLoudness, ...aborting });
880
+ if (!mixed.ok) {
881
+ rmSync(audioFile, { force: true });
882
+ return mixed;
883
+ }
884
+ const { attempt, tries } = mixed.value;
885
+ const keep = mixLoudness.keep ?? "loudness";
886
+ mix = { measured: { integrated: measured.measurement.inputI, truePeak: measured.measurement.inputTp }, gainDb: attempt.gainDb, ceilingDbtp: attempt.ceilingDbtp, keep };
887
+ const kept = keep === "speech" ? ` (speech kept: ${formatDb(mixLoudness.target)} ± ${getMixTolerance(mixLoudness)} LUFS)` : "";
888
+ log(
889
+ `loudness: the film's mix measured ${formatDb(measured.measurement.inputI)} LUFS, true peak ${formatDb(measured.measurement.inputTp)} dBTP; ` +
890
+ `gain ${formatDb(attempt.gainDb)} dB${kept}, limiter at ${formatDb(attempt.ceilingDbtp)} dBTP (encode ${tries} of ${MIX_ATTEMPTS}).`,
891
+ );
797
892
  }
798
893
  }
799
- const isVideoCopied = isPublishableVideo(rendered.facts.video);
800
- const isAudioCopied = audioFilter === undefined && (rendered.facts.audio === null || isPublishableAudio(rendered.facts.audio));
801
- const finishArgs = buildFinishArgs(input.renderFile, rendered.facts, output, audioFilter === undefined ? {} : { audioFilter });
894
+ const { finishVideo } = options;
895
+ const isVideoCopied = finishVideo === undefined && isPublishableVideo(rendered.facts.video);
896
+ const isAudioCopied = audioFile === undefined && (rendered.facts.audio === null || isPublishableAudio(rendered.facts.audio));
897
+ const finishArgs = buildFinishArgs(input.renderFile, rendered.facts, output, { ...(audioFile === undefined ? {} : { audioFile }), ...(finishVideo === undefined ? {} : { video: finishVideo }) });
802
898
  await runFfmpeg("The film's final pass", finishArgs, { ...aborting, output, onSeconds: (done) => progress(0, done) });
803
899
  rmSync(input.renderFile, { force: true });
900
+ if (audioFile !== undefined) rmSync(audioFile, { force: true });
804
901
  const finished = await probeFilmFacts(output, aborting);
805
902
  if (!finished.ok) return err(`the finished film: ${finished.error}`);
806
903
  const problems = findFinishProblems(finished.facts, readTopLevelBoxes(output));
807
904
  if (problems.length > 0) return err(`the finished film ${output} is not publishable: ${problems.join("; ")}.`);
905
+ let loudness: MixLoudness | null = null;
906
+ if (finished.facts.audio !== null) {
907
+ const measured = await measureLoudness(output, mixLoudness ?? DEFAULT_LOUDNESS, { label: "the finished film", ...aborting });
908
+ if (measured.kind === "measured") {
909
+ loudness = { integrated: measured.measurement.inputI, truePeak: measured.measurement.inputTp };
910
+ // A mix left as rendered (`mixLoudness: null`) or silent is reported, not held to a target it was not brought to.
911
+ const misses = mixLoudness === null || audioFile === undefined ? [] : findLoudnessProblems(loudness, mixLoudness);
912
+ if (misses.length > 0) return err(`the finished film ${output} measures ${describeMixLoudness(loudness)}: ${misses.join("; ")}.`);
913
+ log(`loudness: the finished film measures ${formatDb(loudness.integrated)} LUFS, true peak ${formatDb(loudness.truePeak)} dBTP.`);
914
+ }
915
+ }
808
916
  progress(0, input.seconds);
809
917
  const { bytes, width, height, durationSeconds } = finished.facts;
810
- const streams = isVideoCopied && isAudioCopied ? "streams copied" : isVideoCopied ? "picture copied, sound re-encoded" : "re-encoded";
918
+ const streams = describeFinishStreams({ isVideoCopied, isAudioCopied, hasAudio: rendered.facts.audio !== null, ...(finishVideo === undefined ? {} : { finishVideo }) });
811
919
  log(`finish: ${streams} to H.264 ${finished.facts.video.profile ?? ""}, AAC 48 kHz stereo, fast start; ${width}×${height}, ${durationSeconds.toFixed(2)} s, ${bytes} bytes.`);
812
920
  let cover: string | null = null;
813
921
  if (film.cover !== null) {
@@ -817,7 +925,52 @@ export async function finishFootage(
817
925
  await runFfmpeg("The cover frame", buildCoverArgs(output, at, cover), { ...aborting, output: cover });
818
926
  log(`cover: ${cover} (at ${at} s).`);
819
927
  }
820
- return ok({ bytes, width, height, durationSeconds, cover });
928
+ return ok({ bytes, width, height, durationSeconds, cover, loudness, mix });
929
+ }
930
+
931
+ /**
932
+ * The mix's sound brought to `target` on its own: gain and limiter, encoded to AAC, measured; while the encoded file
933
+ * misses the target the gain and the ceiling are corrected and it is encoded again, at most `MIX_ATTEMPTS` times. An
934
+ * error names the last measurement.
935
+ */
936
+ async function finishMix(input: {
937
+ input: string;
938
+ output: string;
939
+ measurement: LoudnessMeasurement;
940
+ target: MixLoudnessTarget;
941
+ signal?: AbortSignal;
942
+ }): Promise<FootageResult<{ attempt: MixAttempt; tries: number; measured: MixLoudness }>> {
943
+ const aborting = input.signal === undefined ? {} : { signal: input.signal };
944
+ let attempt = getFirstMixAttempt(input.measurement, input.target);
945
+ let misses: string[] = [];
946
+ let measured: MixLoudness = { integrated: input.measurement.inputI, truePeak: input.measurement.inputTp };
947
+ for (let tries = 1; tries <= MIX_ATTEMPTS; tries += 1) {
948
+ await runFfmpeg("The film's mix", buildMixArgs({ input: input.input, filter: getMixFilter(attempt), output: input.output }), { ...aborting, output: input.output });
949
+ const encoded = await measureLoudness(input.output, input.target, { label: "the film's encoded mix", ...aborting });
950
+ if (encoded.kind === "silent") return err("the film's mix measures silent after its gain and limiter.");
951
+ measured = { integrated: encoded.measurement.inputI, truePeak: encoded.measurement.inputTp };
952
+ misses = findLoudnessProblems(measured, input.target);
953
+ if (misses.length === 0) return ok({ attempt, tries, measured });
954
+ if (tries < MIX_ATTEMPTS) attempt = getNextMixAttempt(attempt, measured, input.target);
955
+ }
956
+ return err(
957
+ `the film's mix still measures ${describeMixLoudness(measured)} after ${MIX_ATTEMPTS} encodes (last: gain ${formatDb(attempt.gainDb)} dB, ` +
958
+ `limiter at ${formatDb(attempt.ceilingDbtp)} dBTP): ${misses.join("; ")}.`,
959
+ );
960
+ }
961
+
962
+ /** Both measurements of a mix, as an error names them. */
963
+ function describeMixLoudness(measured: MixLoudness): string {
964
+ return `${formatDb(measured.integrated)} LUFS integrated, ${formatDb(measured.truePeak)} dBTP true peak`;
965
+ }
966
+
967
+ /** What the final pass did to each stream, for its log line. */
968
+ function describeFinishStreams(pass: { isVideoCopied: boolean; isAudioCopied: boolean; hasAudio: boolean; finishVideo?: FinishVideo }): string {
969
+ if (pass.finishVideo === undefined) return pass.isVideoCopied && pass.isAudioCopied ? "streams copied" : pass.isVideoCopied ? "picture copied, sound re-encoded" : "re-encoded";
970
+ const { preset, crf, maxBitrate } = pass.finishVideo;
971
+ const picture = `picture re-encoded (${preset} CRF ${crf}${maxBitrate === undefined ? "" : `, max ${maxBitrate}`})`;
972
+ if (!pass.hasAudio) return picture;
973
+ return `${picture}, sound ${pass.isAudioCopied ? "copied" : "re-encoded"}`;
821
974
  }
822
975
 
823
976
  /** hyperframes' progress lines carry a percentage (`… 42%`); the last one on a line counts. */
@@ -949,7 +1102,7 @@ async function runRenderFootageFilm(film: FootageFilm, options: RenderFootageFil
949
1102
  const edlPath = getEdlPath(options.buildDir, options.isPlaceholder);
950
1103
  let edl: Edl;
951
1104
  if (existsSync(edlPath) && options.isRecut !== true) {
952
- const read = readEdlFile(film, clips.value, edlPath);
1105
+ const read = readEdlFile(film, clips.value, edlPath, options.layout);
953
1106
  if (!read.ok) return read;
954
1107
  edl = read.value;
955
1108
  options.log(`cut: ${edlPath} (${edl.segments.length} segments), as it is; softure-marketing footage --step=cut builds it again.`);
@@ -109,6 +109,8 @@ export interface FootageCharge {
109
109
  keyTerms?: number;
110
110
  /** The paid cache's key of the result (the file name's first part under `<cacheDir>/<film id>/`). */
111
111
  cacheKey: string;
112
+ /** The part of the clip a range isolation cleaned (`isolateSpeechRanges`), in seconds of the trimmed clip; absent: the whole clip. */
113
+ range?: { start: number; end: number };
112
114
  }
113
115
 
114
116
  /** A stage of a footage run that reports progress. */
@@ -5,7 +5,7 @@ import { z } from "zod";
5
5
 
6
6
  import { getSegmentStarts, type Edl } from "./edl.js";
7
7
  import type { ClipRole } from "./film.js";
8
- import { FOOTAGE_SAMPLE_RATE } from "./normalize.js";
8
+ import { FOOTAGE_SAMPLE_RATE, X264_PRESETS, type X264Preset } from "./normalize.js";
9
9
  import { runProcess } from "./process.js";
10
10
 
11
11
  /**
@@ -15,7 +15,7 @@ import { runProcess } from "./process.js";
15
15
  */
16
16
 
17
17
  /** The audio bitrate of a re-encoded track. */
18
- const AUDIO_BITRATE = "192k";
18
+ export const FINISHED_AUDIO_BITRATE = "192k";
19
19
  /** The quality of a re-encoded picture (x264's constant rate factor; 18 is visually lossless). */
20
20
  const VIDEO_CRF = 18;
21
21
  /** How far before the film's end the latest cover frame is taken, so a frame still exists there. */
@@ -103,25 +103,77 @@ export function isPublishableAudio(audio: NonNullable<FilmFacts["audio"]>): bool
103
103
  return audio.codec === "aac" && audio.sampleRate === FOOTAGE_SAMPLE_RATE && audio.channels === 2;
104
104
  }
105
105
 
106
+ /**
107
+ * How the final pass encodes the picture when an app asks for it (issue #1068): H.264 High, yuv420p, at this x264
108
+ * `preset` and `crf` (a whole number from 0 to 51), optionally capped at `maxBitrate` (an ffmpeg rate such as `"12M"`
109
+ * or `"12000k"`; the encoder's buffer is twice the cap). A `quality: "draft"` render plus `{ preset: "veryfast",
110
+ * crf: 20 }` publishes High at a controlled size for about a quarter of what hyperframes' `standard` tier costs.
111
+ */
112
+ export interface FinishVideo {
113
+ preset: X264Preset;
114
+ crf: number;
115
+ maxBitrate?: string;
116
+ }
117
+
118
+ /** A rate ffmpeg reads: a positive number with an optional `k` or `M` suffix. */
119
+ const BITRATE_PATTERN = /^(\d+(?:\.\d+)?)([kM]?)$/;
120
+
121
+ /** What makes a `FinishVideo` unusable, one sentence per value; empty when nothing does. */
122
+ export function findFinishVideoProblems(video: FinishVideo): string[] {
123
+ const problems: string[] = [];
124
+ if (!(X264_PRESETS as readonly string[]).includes(video.preset)) problems.push(`finishVideo.preset must be one of ${X264_PRESETS.join(", ")}, got ${String(video.preset)}.`);
125
+ if (!Number.isInteger(video.crf) || video.crf < 0 || video.crf > 51) problems.push(`finishVideo.crf must be a whole number from 0 to 51, got ${String(video.crf)}.`);
126
+ if (video.maxBitrate !== undefined) {
127
+ const match = BITRATE_PATTERN.exec(video.maxBitrate);
128
+ if (match === null || Number(match[1]) <= 0) problems.push(`finishVideo.maxBitrate must be a positive rate such as "12M" or "12000k", got "${video.maxBitrate}".`);
129
+ }
130
+ return problems;
131
+ }
132
+
133
+ /** The encoder's buffer for a rate cap: twice the cap, in the cap's unit. */
134
+ function getBufferSize(maxBitrate: string): string {
135
+ const match = BITRATE_PATTERN.exec(maxBitrate);
136
+ if (match === null) throw new Error(`finishVideo.maxBitrate "${maxBitrate}" is not a rate; check it with findFinishVideoProblems first.`);
137
+ return `${String(Number(match[1]) * 2)}${match[2] ?? ""}`;
138
+ }
139
+
140
+ /** The picture's encoder arguments: H.264 High yuv420p at the given preset and CRF, capped when asked. */
141
+ function getVideoEncodeArgs(video: FinishVideo): string[] {
142
+ const cap = video.maxBitrate === undefined ? [] : ["-maxrate", video.maxBitrate, "-bufsize", getBufferSize(video.maxBitrate)];
143
+ return ["-c:v", "libx264", "-profile:v", "high", "-pix_fmt", "yuv420p", "-preset", video.preset, "-crf", String(video.crf), ...cap];
144
+ }
145
+
106
146
  /**
107
147
  * The final pass: each stream that is already publishable is copied, the other re-encoded (the picture to H.264 High),
108
- * and the `moov` box moved to the front. A film without sound keeps none. `audioFilter` (the mix's loudness pass)
109
- * re-encodes the sound through it.
148
+ * and the `moov` box moved to the front. A film without sound keeps none. `audioFile` (the mix's finished sound, AAC
149
+ * encoded on its own) replaces the render's sound, copied as it is; `audioFilter` re-encodes the sound through it.
150
+ * `video` re-encodes the picture whatever it is, at its preset and CRF (issue #1068).
110
151
  */
111
- export function buildFinishArgs(input: string, facts: Pick<FilmFacts, "video" | "audio">, output: string, options: { audioFilter?: string } = {}): string[] {
112
- const video = isPublishableVideo(facts.video)
113
- ? ["-c:v", "copy"]
114
- : ["-c:v", "libx264", "-profile:v", "high", "-pix_fmt", "yuv420p", "-preset", "medium", "-crf", String(VIDEO_CRF)];
115
- const encodeAudio = ["-c:a", "aac", "-b:a", AUDIO_BITRATE, "-ar", String(FOOTAGE_SAMPLE_RATE), "-ac", "2"];
152
+ export function buildFinishArgs(
153
+ input: string,
154
+ facts: Pick<FilmFacts, "video" | "audio">,
155
+ output: string,
156
+ options: { audioFilter?: string; audioFile?: string; video?: FinishVideo } = {},
157
+ ): string[] {
158
+ const video =
159
+ options.video !== undefined
160
+ ? getVideoEncodeArgs(options.video)
161
+ : isPublishableVideo(facts.video)
162
+ ? ["-c:v", "copy"]
163
+ : getVideoEncodeArgs({ preset: "medium", crf: VIDEO_CRF });
164
+ const encodeAudio = ["-c:a", "aac", "-b:a", FINISHED_AUDIO_BITRATE, "-ar", String(FOOTAGE_SAMPLE_RATE), "-ac", "2"];
165
+ const inputs = options.audioFile === undefined ? ["-i", input] : ["-i", input, "-i", options.audioFile];
116
166
  const audio =
117
167
  facts.audio === null
118
168
  ? []
119
- : options.audioFilter !== undefined
120
- ? ["-map", "0:a:0", "-af", options.audioFilter, ...encodeAudio]
121
- : isPublishableAudio(facts.audio)
122
- ? ["-map", "0:a:0", "-c:a", "copy"]
123
- : ["-map", "0:a:0", ...encodeAudio];
124
- return ["-v", "error", "-y", "-i", input, "-map", "0:v:0", ...video, ...audio, "-movflags", "+faststart", output];
169
+ : options.audioFile !== undefined
170
+ ? ["-map", "1:a:0", "-c:a", "copy"]
171
+ : options.audioFilter !== undefined
172
+ ? ["-map", "0:a:0", "-af", options.audioFilter, ...encodeAudio]
173
+ : isPublishableAudio(facts.audio)
174
+ ? ["-map", "0:a:0", "-c:a", "copy"]
175
+ : ["-map", "0:a:0", ...encodeAudio];
176
+ return ["-v", "error", "-y", ...inputs, "-map", "0:v:0", ...video, ...audio, "-movflags", "+faststart", output];
125
177
  }
126
178
 
127
179
  /** The types of an MP4's top-level boxes, in file order (`ftyp`, `moov`, `mdat`, …). */
@@ -0,0 +1,131 @@
1
+ import { footageCacheKey, getFootageCachePath } from "./cache.js";
2
+ import { getSoundSpan, type Edl } from "./edl.js";
3
+ import type { ClipRole } from "./film.js";
4
+ import { FOOTAGE_SAMPLE_RATE } from "./normalize.js";
5
+
6
+ /**
7
+ * The parts of each talking clip a cut hears, as ranges in whole milliseconds, and how their cleaned voice is laid
8
+ * back over the clip's own sound: pure planning and ffmpeg argument builders for `isolateSpeechRanges` and the
9
+ * per-range estimate, tested without ffmpeg.
10
+ */
11
+
12
+ /** Seconds added on each side of a sound span, so a cut's cross-fade and fades read cleaned sound. */
13
+ export const DEFAULT_SPEECH_RANGE_MARGIN = 0.25;
14
+
15
+ /** A range of a clip's trimmed sound, in whole milliseconds (the cache key's unit). */
16
+ export interface SpeechRange {
17
+ clip: string;
18
+ startMs: number;
19
+ endMs: number;
20
+ }
21
+
22
+ /** Where a range's cleaned sound is laid in its clip, in milliseconds; inside the range. */
23
+ export interface SpeechRangeWindow {
24
+ range: SpeechRange;
25
+ startMs: number;
26
+ endMs: number;
27
+ }
28
+
29
+ export interface SpeechRangeClip {
30
+ id: string;
31
+ role: ClipRole;
32
+ /** Seconds after the trim. */
33
+ duration: number;
34
+ }
35
+
36
+ /**
37
+ * The ranges the cut hears of each talking clip: every segment's sound span (its own clip's or `audio`'s), and the
38
+ * picture clip's own span when `audio.ownVolume` keeps it under, widened by `margin` seconds on each side, clamped to
39
+ * the clip and rounded out to whole milliseconds. Identical ranges and ranges inside another are dropped (the larger
40
+ * one is laid there anyway); the rest are not merged, so a moved segment changes only its own range. Sorted by clip
41
+ * order, then start.
42
+ */
43
+ export function planSpeechRanges(edl: Edl, clips: readonly SpeechRangeClip[], options: { margin?: number } = {}): SpeechRange[] {
44
+ const margin = Math.max(0, options.margin ?? DEFAULT_SPEECH_RANGE_MARGIN);
45
+ const byId = new Map(clips.map((clip) => [clip.id, clip]));
46
+ const found = new Map<string, SpeechRange[]>();
47
+ const add = (span: { clip: string; start: number; end: number }): void => {
48
+ const clip = byId.get(span.clip);
49
+ if (clip === undefined || clip.role !== "talk") return;
50
+ const clipMs = Math.floor(clip.duration * 1000);
51
+ const startMs = Math.max(0, Math.floor((span.start - margin) * 1000));
52
+ const endMs = Math.min(clipMs, Math.ceil((span.end + margin) * 1000));
53
+ if (endMs <= startMs) return;
54
+ const list = found.get(clip.id) ?? [];
55
+ list.push({ clip: clip.id, startMs, endMs });
56
+ found.set(clip.id, list);
57
+ };
58
+ for (const segment of edl.segments) {
59
+ add(getSoundSpan(segment));
60
+ if (segment.audio !== undefined && segment.audio.ownVolume > 0) add(segment);
61
+ }
62
+ const ranges: SpeechRange[] = [];
63
+ for (const clip of clips) {
64
+ const list = (found.get(clip.id) ?? []).sort((a, b) => a.startMs - b.startMs || b.endMs - a.endMs);
65
+ for (const range of list) {
66
+ const isInside = ranges.some((kept) => kept.clip === range.clip && kept.startMs <= range.startMs && kept.endMs >= range.endMs);
67
+ if (!isInside) ranges.push(range);
68
+ }
69
+ }
70
+ return ranges;
71
+ }
72
+
73
+ /**
74
+ * Where each of one clip's ranges is laid: the whole range, except that two overlapping neighbours switch at the
75
+ * middle of their overlap. Takes ranges of one clip, none inside another (as `planSpeechRanges` answers them).
76
+ */
77
+ export function getSpeechRangeWindows(ranges: readonly SpeechRange[]): SpeechRangeWindow[] {
78
+ const sorted = [...ranges].sort((a, b) => a.startMs - b.startMs);
79
+ return sorted.map((range, index) => {
80
+ const before = sorted[index - 1];
81
+ const after = sorted[index + 1];
82
+ const startMs = before !== undefined && before.endMs > range.startMs ? Math.round((range.startMs + before.endMs) / 2) : range.startMs;
83
+ const endMs = after !== undefined && after.startMs < range.endMs ? Math.round((after.startMs + range.endMs) / 2) : range.endMs;
84
+ return { range, startMs, endMs };
85
+ });
86
+ }
87
+
88
+ /** The paid cache of one range's cleaned voice: keyed by the clip's identity, the range in milliseconds and the provider. */
89
+ export function getSpeechRangeCache(filmId: string, clipKey: string, range: SpeechRange, options: { cacheDir: string; provider: string }): { key: string; path: string } {
90
+ const key = footageCacheKey("isolated", { clip: clipKey, range: [range.startMs, range.endMs], provider: options.provider });
91
+ return { key, path: getFootageCachePath(options.cacheDir, filmId, "isolated", key) };
92
+ }
93
+
94
+ const seconds = (ms: number): string => (ms / 1000).toFixed(3);
95
+
96
+ /** One range of a clip's sound (`audio`, read from its start) as mp3, for the isolation provider. */
97
+ export function buildRangeAudioArgs(audio: string, range: Pick<SpeechRange, "startMs" | "endMs">, output: string): string[] {
98
+ return ["-v", "error", "-y", "-ss", seconds(range.startMs), "-t", seconds(range.endMs - range.startMs), "-i", audio, "-vn", "-c:a", "libmp3lame", "-q:a", "2", output];
99
+ }
100
+
101
+ /** A cleaned range laid back: its file, and whether it is mono (panned to both channels at full level). */
102
+ export interface LaidRange {
103
+ window: SpeechRangeWindow;
104
+ file: string;
105
+ isMono: boolean;
106
+ }
107
+
108
+ /**
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.
112
+ */
113
+ export function buildRangeLayArgs(base: string, laid: readonly LaidRange[], output: string): string[] {
114
+ const format = `aformat=sample_rates=${FOOTAGE_SAMPLE_RATE}:channel_layouts=stereo`;
115
+ if (laid.length === 0) return ["-v", "error", "-y", "-i", base, "-vn", "-af", format, "-c:a", "libmp3lame", "-q:a", "2", output];
116
+ 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]`];
119
+ laid.forEach(({ window, file, isMono }, index) => {
120
+ inputs.push("-i", file);
121
+ const offset = window.startMs - window.range.startMs;
122
+ const length = window.endMs - window.startMs;
123
+ const channels = isMono ? "pan=stereo|c0=c0|c1=c0," : "";
124
+ 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}]`,
126
+ );
127
+ });
128
+ const mixed = laid.map((_, index) => `[w${index}]`).join("");
129
+ parts.push(`[base]${mixed}amix=inputs=${laid.length + 1}:duration=first:normalize=0[speech]`);
130
+ return ["-v", "error", "-y", ...inputs, "-filter_complex", parts.join(";"), "-map", "[speech]", "-c:a", "libmp3lame", "-q:a", "2", output];
131
+ }