@softure-ai/marketing-kit 0.13.1 → 0.14.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 +45 -0
  2. package/README.md +27 -8
  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/film-mix.d.ts +27 -0
  12. package/dist/footage/film-mix.d.ts.map +1 -0
  13. package/dist/footage/film-mix.js +36 -0
  14. package/dist/footage/film-mix.js.map +1 -0
  15. package/dist/footage/loudness.d.ts +91 -27
  16. package/dist/footage/loudness.d.ts.map +1 -1
  17. package/dist/footage/loudness.js +143 -69
  18. package/dist/footage/loudness.js.map +1 -1
  19. package/dist/footage/pipeline.d.ts +38 -10
  20. package/dist/footage/pipeline.d.ts.map +1 -1
  21. package/dist/footage/pipeline.js +119 -63
  22. package/dist/footage/pipeline.js.map +1 -1
  23. package/dist/footage/publish.js +4 -4
  24. package/dist/footage/publish.js.map +1 -1
  25. package/dist/index.d.ts +4 -3
  26. package/dist/index.d.ts.map +1 -1
  27. package/dist/index.js +3 -2
  28. package/dist/index.js.map +1 -1
  29. package/dist/og/element.d.ts.map +1 -1
  30. package/dist/og/element.js +8 -2
  31. package/dist/og/element.js.map +1 -1
  32. package/package.json +2 -2
  33. package/schema/marketing.schema.json +13 -1
  34. package/src/config/schema.ts +14 -2
  35. package/src/footage/compose.ts +33 -12
  36. package/src/footage/film-mix.ts +57 -0
  37. package/src/footage/loudness.ts +166 -68
  38. package/src/footage/pipeline.ts +151 -72
  39. package/src/footage/publish.ts +4 -4
  40. package/src/index.ts +28 -7
  41. package/src/og/element.ts +9 -2
@@ -12,7 +12,7 @@ import { err, ok, 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
17
  import { findLowDiskProblems, getFreeBytes, getRenderTempDir, type FreeBytesReader } from "./disk.js";
18
18
  import { buildEdl, getEdlDuration, readEdl, remapWords, validateEdl, type Edl } from "./edl.js";
@@ -21,23 +21,25 @@ import { chooseCutTransitions, type CutMeasure } from "./cuts.js";
21
21
  import { declickSpeech, describeDeclick, type DeclickReport } from "./declick.js";
22
22
  import { DEFAULT_AUTO_THRESHOLD, getDeclickLevel, getFootageEdit, type FootageClip, type FootageFilm, type MusicSource } from "./film.js";
23
23
  import { getFilmKeyTerms } from "./keyterms.js";
24
+ import { buildFilmMixArgs } from "./film-mix.js";
24
25
  import {
25
26
  buildMixArgs,
26
27
  DEFAULT_LOUDNESS,
27
- findLoudnessProblems,
28
28
  formatDb,
29
- getFirstMixAttempt,
30
- getMixTolerance,
29
+ getFirstMixCeiling,
30
+ getLoudnessVerdict,
31
+ getMixAttempts,
31
32
  getMixFilter,
32
- getNextMixAttempt,
33
+ getMixGain,
34
+ getMixTolerance,
35
+ getNextMixCeiling,
33
36
  measureLoudness,
34
- MIX_ATTEMPTS,
35
37
  normalizeLoudness,
38
+ solveMixGain,
36
39
  type LoudnessMeasurement,
37
40
  type MixAttempt,
38
41
  type MixLoudness,
39
42
  type MixLoudnessTarget,
40
- type MixTry,
41
43
  } from "./loudness.js";
42
44
  import { duckingKeyframes, getDuckingOptions } from "./music.js";
43
45
  import { FOOTAGE_FPS, normalizeFootage, type Frame, type NormalizeEncoder } from "./normalize.js";
@@ -748,6 +750,31 @@ async function runRenderFootage(
748
750
  const output = join(assetsDir, "music.mp3");
749
751
  tracks.push({ item: "music", seconds, run: ffmpegTrack("The music track", output, () => buildMusicArgs({ input: musicFile, seconds, keyframes, output })) });
750
752
  }
753
+ const sfx: Partial<Record<SfxEvent, string>> = {};
754
+ mkdirSync(join(assetsDir, "sfx"), { recursive: true });
755
+ for (const [event, source] of Object.entries(options.sfx) as [SfxEvent, string][]) {
756
+ const name = `${event}${extname(source)}`;
757
+ cpSync(source, join(assetsDir, "sfx", name));
758
+ sfx[event] = `assets/sfx/${name}`;
759
+ }
760
+ // The film's mix, brought to `mixLoudness` and gated before hyperframes captures a frame (issue #1124).
761
+ const mixLoudness = getMixLoudnessTarget(film);
762
+ let mixed: FootageResult<PreparedMix | null> = ok(null);
763
+ if (mixLoudness !== null) {
764
+ const mixSource = join(buildDir, "mix.wav");
765
+ const musicTrack = musicFile === null ? null : { file: join(assetsDir, "music.mp3"), seconds };
766
+ const cues = getFootageSfxCues(film, edl, sfx).map((cue) => ({ ...cue, src: join(buildDir, cue.src) }));
767
+ tracks.push({
768
+ item: "mix",
769
+ seconds,
770
+ run: async (onSeconds) => {
771
+ const args = buildFilmMixArgs({ speech: { file: speechFile, seconds: getEdlDuration(edl) }, music: musicTrack, sfx: cues, seconds, output: mixSource });
772
+ await runFfmpeg("The film's mix", args, { ...aborting, output: mixSource, onSeconds });
773
+ mixed = await mixFootage(mixLoudness, { mixSource, output: join(buildDir, "mix.m4a") }, { log, ...aborting });
774
+ rmSync(mixSource, { force: true });
775
+ },
776
+ });
777
+ }
751
778
  // A single frame: counted as a moment of work so the stage's bar still ends at its total.
752
779
  const lastFrame = join(assetsDir, "last.jpg");
753
780
  tracks.push({ item: "last frame", seconds: 0.1, run: ffmpegTrack("The end card's backdrop", lastFrame, () => buildLastFrameArgs(edl, clipFiles, lastFrame)) });
@@ -765,16 +792,12 @@ async function runRenderFootage(
765
792
  await track.run((done) => assetProgress(index, done));
766
793
  assetProgress(index, track.seconds);
767
794
  }
795
+ // A mix that misses its target fails here, before any frame is rendered.
796
+ const prepared = mixed;
797
+ if (!prepared.ok) return prepared;
768
798
  const musicAsset = musicFile === null ? null : "assets/music.mp3";
769
799
  const fonts = copyFonts(options.brand.fonts, join(assetsDir, "fonts"));
770
800
  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
801
  cpSync(require.resolve("gsap/dist/gsap.min.js"), join(assetsDir, "gsap.min.js"));
779
802
  const base = resolveLayout(film.format, options.layout ?? {});
780
803
  // A caption preset places the 9:16 box in a platform's safe zone; the project's own caption override still wins.
@@ -816,7 +839,7 @@ async function runRenderFootage(
816
839
  const rendered = await runHyperframesRender(options, renderFile, seconds);
817
840
  if (!rendered.ok) return rendered;
818
841
  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);
842
+ const finished = await finishFootage(film, { renderFile, seconds, coverAt: film.cover?.at ?? getDefaultCoverSeconds(edl, roles), mix: prepared.value }, options);
820
843
  if (!finished.ok) return finished;
821
844
  return ok({ kind: "rendered", output: options.output, seconds, edlPath: getEdlPath(buildDir, options.isPlaceholder), declick, ...finished.value });
822
845
  }
@@ -831,35 +854,89 @@ export interface FinishedFootage {
831
854
  /** The cover JPG, or null when the film has none. */
832
855
  cover: string | null;
833
856
  /** 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;
857
+ loudness: FinishedLoudness | null;
835
858
  /**
836
- * What the mix's last stage did: the render's mix as measured, the gain applied (0 when `keep: "speech"` found the
859
+ * What the mix's last stage did: the film's mix as measured, the gain applied (0 when `keep: "speech"` found the
837
860
  * mix inside its window) and the limiter's ceiling; null when no stage ran (no sound, a silent mix, `mixLoudness: null`).
838
861
  */
839
862
  mix: FinishedMix | null;
840
863
  }
841
864
 
865
+ /** The finished file's sound in `FinishedFootage`. */
866
+ export interface FinishedLoudness extends MixLoudness {
867
+ /**
868
+ * A sentence naming both values when the mix landed in `mixLoudness.warnTolerance`'s near-miss band instead of
869
+ * inside its tolerance; null otherwise.
870
+ */
871
+ warning: string | null;
872
+ }
873
+
842
874
  /** The mix's last stage in `FinishedFootage`. */
843
875
  export interface FinishedMix {
844
- /** The render's mix before the stage. */
876
+ /** The film's mix before the stage. */
845
877
  measured: MixLoudness;
846
878
  gainDb: number;
847
879
  ceilingDbtp: number;
848
880
  /** What the gain kept (`MixLoudnessTarget.keep`). */
849
881
  keep: "loudness" | "speech";
882
+ /** How many encodes the stage took. */
883
+ encodes: number;
884
+ }
885
+
886
+ /** A film's mix brought to its target by `mixFootage`: the encoded sound the final pass muxes, and what the stage did. */
887
+ export interface PreparedMix {
888
+ audioFile: string;
889
+ mix: FinishedMix;
890
+ }
891
+
892
+ /** The film's mix target: `mixLoudness`, the default when absent, null when the film keeps the render's sound. */
893
+ function getMixLoudnessTarget(film: Pick<FootageFilm, "mixLoudness">): MixLoudnessTarget | null {
894
+ return film.mixLoudness === undefined ? DEFAULT_LOUDNESS : film.mixLoudness;
895
+ }
896
+
897
+ /**
898
+ * The mix stage over a film's sound (`mixSource`, any file ffmpeg reads): measured, brought to `target` and encoded
899
+ * to `output` (AAC) by `finishMix`; null when the mix is silent (the final pass then keeps the render's sound). An
900
+ * error names the last measurement. `renderFootage` runs it before hyperframes renders a frame (issue #1124).
901
+ */
902
+ export async function mixFootage(
903
+ target: MixLoudnessTarget,
904
+ input: { mixSource: string; output: string },
905
+ options: { log: (line: string) => void; signal?: AbortSignal },
906
+ ): Promise<FootageResult<PreparedMix | null>> {
907
+ const aborting = options.signal === undefined ? {} : { signal: options.signal };
908
+ const measured = await measureLoudness(input.mixSource, target, { label: "the film's mix", ...aborting });
909
+ if (measured.kind === "silent") {
910
+ options.log("loudness: the film's mix is silent, left as it is.");
911
+ return ok(null);
912
+ }
913
+ const mixed = await finishMix({ input: input.mixSource, output: input.output, measurement: measured.measurement, target, ...aborting });
914
+ if (!mixed.ok) {
915
+ rmSync(input.output, { force: true });
916
+ return mixed;
917
+ }
918
+ const { attempt, tries, probes } = mixed.value;
919
+ const keep = target.keep ?? "loudness";
920
+ const mix = { measured: { integrated: measured.measurement.inputI, truePeak: measured.measurement.inputTp }, gainDb: attempt.gainDb, ceilingDbtp: attempt.ceilingDbtp, keep, encodes: tries };
921
+ const kept = keep === "speech" ? ` (speech kept: ${formatDb(target.target)} ± ${getMixTolerance(target)} LUFS)` : "";
922
+ options.log(
923
+ `loudness: the film's mix measured ${formatDb(measured.measurement.inputI)} LUFS, true peak ${formatDb(measured.measurement.inputTp)} dBTP; ` +
924
+ `gain ${formatDb(attempt.gainDb)} dB${kept}, limiter at ${formatDb(attempt.ceilingDbtp)} dBTP (encode ${tries} of ${getMixAttempts(target)}, ${probes} uncompressed probes).`,
925
+ );
926
+ return ok({ audioFile: input.output, mix });
850
927
  }
851
928
 
852
929
  /**
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.
930
+ * The final pass over hyperframes' render: the film's mix (`input.mix`, prepared by `mixFootage` before the render;
931
+ * null keeps the render's sound; absent, the render's own sound goes through `mixFootage` here) muxed with the
932
+ * picture (copied where the render already matches; `finishVideo` re-encodes it to H.264 High at its preset and CRF),
933
+ * publishable codecs and fast start, checked with ffprobe, the finished file's sound measured and held to the target
934
+ * (a near miss inside `warnTolerance` finishes with `loudness.warning`), then the cover and the file's facts.
935
+ * Exported for tests only.
859
936
  */
860
937
  export async function finishFootage(
861
938
  film: Pick<FootageFilm, "mixLoudness" | "cover">,
862
- input: { renderFile: string; seconds: number; coverAt: number },
939
+ input: { renderFile: string; seconds: number; coverAt: number; mix?: PreparedMix | null },
863
940
  options: Pick<RenderFootageOptions, "log" | "signal" | "output" | "onProgress" | "finishVideo">,
864
941
  ): Promise<FootageResult<FinishedFootage>> {
865
942
  const { log, signal, output } = options;
@@ -868,30 +945,15 @@ export async function finishFootage(
868
945
  progress(0, 0);
869
946
  const rendered = await probeFilmFacts(input.renderFile, aborting);
870
947
  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
- }
948
+ const mixLoudness = getMixLoudnessTarget(film);
949
+ let prepared: PreparedMix | null = input.mix ?? null;
950
+ if (input.mix === undefined && mixLoudness !== null && rendered.facts.audio !== null) {
951
+ const mixed = await mixFootage(mixLoudness, { mixSource: input.renderFile, output: join(dirname(input.renderFile), "mix.m4a") }, { log, ...aborting });
952
+ if (!mixed.ok) return mixed;
953
+ prepared = mixed.value;
894
954
  }
955
+ const audioFile = prepared?.audioFile;
956
+ const mix = prepared?.mix ?? null;
895
957
  const { finishVideo } = options;
896
958
  const isVideoCopied = finishVideo === undefined && isPublishableVideo(rendered.facts.video);
897
959
  const isAudioCopied = audioFile === undefined && (rendered.facts.audio === null || isPublishableAudio(rendered.facts.audio));
@@ -903,20 +965,22 @@ export async function finishFootage(
903
965
  if (!finished.ok) return err(`the finished film: ${finished.error}`);
904
966
  const problems = findFinishProblems(finished.facts, readTopLevelBoxes(output));
905
967
  if (problems.length > 0) return err(`the finished film ${output} is not publishable: ${problems.join("; ")}.`);
906
- let loudness: MixLoudness | null = null;
968
+ let loudness: FinishedLoudness | null = null;
907
969
  if (finished.facts.audio !== null) {
908
970
  const measured = await measureLoudness(output, mixLoudness ?? DEFAULT_LOUDNESS, { label: "the finished film", ...aborting });
909
971
  if (measured.kind === "measured") {
910
- loudness = { integrated: measured.measurement.inputI, truePeak: measured.measurement.inputTp };
972
+ const sound = { integrated: measured.measurement.inputI, truePeak: measured.measurement.inputTp };
911
973
  // 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.`);
974
+ 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("; ")}.`);
976
+ loudness = { ...sound, warning: verdict.kind === "warn" ? `the finished film ${output}: ${verdict.warning}` : null };
977
+ log(`loudness: the finished film measures ${formatDb(sound.integrated)} LUFS, true peak ${formatDb(sound.truePeak)} dBTP.`);
978
+ if (loudness.warning !== null) log(`loudness warning: ${loudness.warning}`);
915
979
  }
916
980
  }
917
981
  progress(0, input.seconds);
918
982
  const { bytes, width, height, durationSeconds } = finished.facts;
919
- const streams = describeFinishStreams({ isVideoCopied, isAudioCopied, hasAudio: rendered.facts.audio !== null, ...(finishVideo === undefined ? {} : { finishVideo }) });
983
+ const streams = describeFinishStreams({ isVideoCopied, isAudioCopied, hasAudio: finished.facts.audio !== null, ...(finishVideo === undefined ? {} : { finishVideo }) });
920
984
  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
985
  let cover: string | null = null;
922
986
  if (film.cover !== null) {
@@ -930,9 +994,11 @@ export async function finishFootage(
930
994
  }
931
995
 
932
996
  /**
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.
997
+ * The mix's sound brought to `target` on its own, at a fixed ceiling (issue #1124): the gain is solved on
998
+ * uncompressed passes (`solveMixGain`), then the mix is encoded to AAC and measured. While the encode misses, the
999
+ * ceiling is lowered only by its true peak excess (the codec's overshoot) and the gain solved again at it, shifted by
1000
+ * the codec's measured loudness drift, at most `getMixAttempts` encodes. A last encode inside `warnTolerance` passes
1001
+ * (the finished file's gate names the warning); otherwise an error names the last measurement.
936
1002
  */
937
1003
  async function finishMix(input: {
938
1004
  input: string;
@@ -940,26 +1006,39 @@ async function finishMix(input: {
940
1006
  measurement: LoudnessMeasurement;
941
1007
  target: MixLoudnessTarget;
942
1008
  signal?: AbortSignal;
943
- }): Promise<FootageResult<{ attempt: MixAttempt; tries: number; measured: MixLoudness }>> {
1009
+ }): Promise<FootageResult<{ attempt: MixAttempt; tries: number; probes: number; measured: MixLoudness }>> {
944
1010
  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) {
1011
+ const attempts = getMixAttempts(input.target);
1012
+ const probe = async (attempt: MixAttempt): Promise<MixLoudness> => {
1013
+ const probed = await measureLoudness(input.input, input.target, { label: "the film's mix through its limiter", filter: getMixFilter(attempt), ...aborting });
1014
+ // A probe through a limiter on a mix that is not silent does not go silent; if it does, the encode reports it.
1015
+ return probed.kind === "silent" ? { integrated: -Infinity, truePeak: -Infinity } : { integrated: probed.measurement.inputI, truePeak: probed.measurement.inputTp };
1016
+ };
1017
+ let ceilingDbtp = getFirstMixCeiling(input.target);
1018
+ let startGainDb = getMixGain(input.measurement.inputI, input.target);
1019
+ let shift = 0;
1020
+ let probes = 0;
1021
+ for (let tries = 1; tries <= attempts; tries += 1) {
1022
+ const solved = await solveMixGain({ ceilingDbtp, startGainDb, target: input.target, shift, measure: probe });
1023
+ probes += solved.probes.length;
1024
+ const attempt = solved.best.attempt;
950
1025
  await runFfmpeg("The film's mix", buildMixArgs({ input: input.input, filter: getMixFilter(attempt), output: input.output }), { ...aborting, output: input.output });
951
1026
  const encoded = await measureLoudness(input.output, input.target, { label: "the film's encoded mix", ...aborting });
952
1027
  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);
1028
+ const measured = { integrated: encoded.measurement.inputI, truePeak: encoded.measurement.inputTp };
1029
+ const verdict = getLoudnessVerdict(measured, input.target);
1030
+ if (verdict.kind === "pass" || (verdict.kind === "warn" && tries === attempts)) return ok({ attempt, tries, probes, measured });
1031
+ if (tries === attempts) {
1032
+ return err(
1033
+ `the film's mix still measures ${describeMixLoudness(measured)} after ${attempts} encodes (last: gain ${formatDb(attempt.gainDb)} dB, ` +
1034
+ `limiter at ${formatDb(attempt.ceilingDbtp)} dBTP): ${verdict.kind === "fail" ? verdict.problems.join("; ") : ""}.`,
1035
+ );
1036
+ }
1037
+ shift = Number.isFinite(solved.best.measured.integrated) ? measured.integrated - solved.best.measured.integrated : 0;
1038
+ ceilingDbtp = getNextMixCeiling(attempt.ceilingDbtp, measured, input.target);
1039
+ startGainDb = attempt.gainDb;
958
1040
  }
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
- );
1041
+ return err(`the film's mix was not encoded: mixLoudness.attempts is ${attempts}.`);
963
1042
  }
964
1043
 
965
1044
  /** 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)
package/src/index.ts CHANGED
@@ -376,7 +376,18 @@ export {
376
376
  } from "./footage/cuts.js";
377
377
  export { MAX_FRAMES, buildFrameArgs, extractFrames, getFrameTimes, type ExtractFramesOptions, type ExtractedFrame, type FrameSpacing } from "./footage/frames.js";
378
378
  export { duckingKeyframes, getDuckingOptions, getSpeechSpans, volumeExpression, type DuckingOptions, type VolumeKeyframe } from "./footage/music.js";
379
- export { END_CARD_SECONDS, FADE_SECONDS, composeFootage, getFootageFilmSeconds, getSegmentScales, type FootageComposeAssets, type FootageComposeInput } from "./footage/compose.js";
379
+ export {
380
+ END_CARD_SECONDS,
381
+ FADE_SECONDS,
382
+ composeFootage,
383
+ getFootageFilmSeconds,
384
+ getFootageSfxCues,
385
+ getSegmentScales,
386
+ type FootageComposeAssets,
387
+ type FootageComposeInput,
388
+ type FootageSfxCue,
389
+ } from "./footage/compose.js";
390
+ export { buildFilmMixArgs, type FilmMixInput } from "./footage/film-mix.js";
380
391
  export { buildCutPreviewArgs, buildLastFrameArgs, buildMusicArgs, buildSpeechArgs, getSpeechCutOptions, type SpeechCutOptions } from "./footage/render.js";
381
392
  export {
382
393
  FOOTAGE_DRAFT_CAPTION_COLORS,
@@ -414,21 +425,29 @@ export {
414
425
  buildMixArgs,
415
426
  findLoudnessProblems,
416
427
  formatDb,
417
- getFirstMixAttempt,
418
- getLimiterSlope,
428
+ getBestGainProbe,
429
+ getFirstMixCeiling,
419
430
  getLoudnessFilter,
431
+ getLoudnessVerdict,
432
+ getMixAim,
433
+ getMixAttempts,
420
434
  getMixFilter,
421
435
  getMixGain,
422
436
  getMixTolerance,
423
- getNextMixAttempt,
437
+ getNextGainProbe,
438
+ getNextMixCeiling,
424
439
  isSilent,
425
440
  measureLoudness,
441
+ MIX_AIM_EDGE_MARGIN,
426
442
  MIX_ATTEMPTS,
427
443
  MIX_ENCODE_HEADROOM,
428
- MIX_LIMITER_SLOPE,
429
- MIX_LIMITER_SLOPE_MAX,
444
+ MIX_GAIN_PRECISION,
445
+ MIX_GAIN_PROBES,
430
446
  MIX_LOUDNESS_TOLERANCE,
431
- MIX_RETRY_EDGE_MARGIN,
447
+ MIX_LOWPASS_HZ,
448
+ solveMixGain,
449
+ type LoudnessVerdict,
450
+ type MixAim,
432
451
  normalizeLoudness,
433
452
  readLoudnessMeasurement,
434
453
  type LoudnessMeasureOutcome,
@@ -513,7 +532,9 @@ export {
513
532
  renderFootageFilm,
514
533
  transcribeFootage,
515
534
  type FinishedFootage,
535
+ type FinishedLoudness,
516
536
  type FinishedMix,
537
+ type PreparedMix,
517
538
  type FootageBrand,
518
539
  type FootageMusicLookup,
519
540
  type FootageResult,
package/src/og/element.ts CHANGED
@@ -12,11 +12,18 @@ export interface OgNode {
12
12
  props: { style?: OgStyle; children?: OgChild | OgChild[]; [attribute: string]: unknown };
13
13
  }
14
14
 
15
+ /**
16
+ * Satori 0.36 and later follow CSS and size a box's content (`content-box`): a `width` or `100%` no longer includes the
17
+ * padding and border. Every template was written for the border box, so it is the default on every element.
18
+ */
19
+ const BOX_SIZING: OgStyle = { boxSizing: "border-box" };
20
+
15
21
  /** `h("div", { style }, ...children)`: one element; empty children are dropped. */
16
22
  export function h(type: string, props: OgNode["props"], ...children: (OgChild | null | false)[]): OgNode {
17
23
  const kept = children.filter((child): child is OgChild => child !== null && child !== false);
18
- if (kept.length === 0) return { type, props };
19
- return { type, props: { ...props, children: kept.length === 1 ? kept[0] : kept } };
24
+ const sized = { ...props, style: { ...BOX_SIZING, ...props.style } };
25
+ if (kept.length === 0) return { type, props: sized };
26
+ return { type, props: { ...sized, children: kept.length === 1 ? kept[0] : kept } };
20
27
  }
21
28
 
22
29
  /** Every node of a tree, the root first. */