@softure-ai/marketing-kit 0.6.0 → 0.8.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 (107) hide show
  1. package/CHANGELOG.md +75 -0
  2. package/README.md +90 -11
  3. package/dist/cli/footage.d.ts.map +1 -1
  4. package/dist/cli/footage.js +5 -2
  5. package/dist/cli/footage.js.map +1 -1
  6. package/dist/compose/compose.d.ts.map +1 -1
  7. package/dist/compose/compose.js +3 -3
  8. package/dist/compose/compose.js.map +1 -1
  9. package/dist/compose/timeline.d.ts +16 -0
  10. package/dist/compose/timeline.d.ts.map +1 -1
  11. package/dist/compose/timeline.js +17 -1
  12. package/dist/compose/timeline.js.map +1 -1
  13. package/dist/config/config.d.ts.map +1 -1
  14. package/dist/config/config.js +18 -2
  15. package/dist/config/config.js.map +1 -1
  16. package/dist/config/schema.d.ts +16 -0
  17. package/dist/config/schema.d.ts.map +1 -1
  18. package/dist/config/schema.js +50 -3
  19. package/dist/config/schema.js.map +1 -1
  20. package/dist/footage/captions.d.ts +5 -1
  21. package/dist/footage/captions.d.ts.map +1 -1
  22. package/dist/footage/captions.js +6 -2
  23. package/dist/footage/captions.js.map +1 -1
  24. package/dist/footage/compose.d.ts +13 -2
  25. package/dist/footage/compose.d.ts.map +1 -1
  26. package/dist/footage/compose.js +75 -23
  27. package/dist/footage/compose.js.map +1 -1
  28. package/dist/footage/cuts.d.ts +44 -0
  29. package/dist/footage/cuts.d.ts.map +1 -0
  30. package/dist/footage/cuts.js +83 -0
  31. package/dist/footage/cuts.js.map +1 -0
  32. package/dist/footage/draft.d.ts +17 -3
  33. package/dist/footage/draft.d.ts.map +1 -1
  34. package/dist/footage/draft.js +28 -14
  35. package/dist/footage/draft.js.map +1 -1
  36. package/dist/footage/edl.d.ts +2 -1
  37. package/dist/footage/edl.d.ts.map +1 -1
  38. package/dist/footage/edl.js +5 -2
  39. package/dist/footage/edl.js.map +1 -1
  40. package/dist/footage/film.d.ts +42 -3
  41. package/dist/footage/film.d.ts.map +1 -1
  42. package/dist/footage/film.js +7 -1
  43. package/dist/footage/film.js.map +1 -1
  44. package/dist/footage/loudness.d.ts +20 -3
  45. package/dist/footage/loudness.d.ts.map +1 -1
  46. package/dist/footage/loudness.js +36 -18
  47. package/dist/footage/loudness.js.map +1 -1
  48. package/dist/footage/music.d.ts +3 -0
  49. package/dist/footage/music.d.ts.map +1 -1
  50. package/dist/footage/music.js +5 -0
  51. package/dist/footage/music.js.map +1 -1
  52. package/dist/footage/normalize.d.ts +27 -7
  53. package/dist/footage/normalize.d.ts.map +1 -1
  54. package/dist/footage/normalize.js +39 -19
  55. package/dist/footage/normalize.js.map +1 -1
  56. package/dist/footage/picture.d.ts +42 -0
  57. package/dist/footage/picture.d.ts.map +1 -0
  58. package/dist/footage/picture.js +141 -0
  59. package/dist/footage/picture.js.map +1 -0
  60. package/dist/footage/pipeline.d.ts +55 -1
  61. package/dist/footage/pipeline.d.ts.map +1 -1
  62. package/dist/footage/pipeline.js +136 -19
  63. package/dist/footage/pipeline.js.map +1 -1
  64. package/dist/footage/publish.d.ts +4 -2
  65. package/dist/footage/publish.d.ts.map +1 -1
  66. package/dist/footage/publish.js +8 -5
  67. package/dist/footage/publish.js.map +1 -1
  68. package/dist/footage/render.d.ts +17 -2
  69. package/dist/footage/render.d.ts.map +1 -1
  70. package/dist/footage/render.js +62 -13
  71. package/dist/footage/render.js.map +1 -1
  72. package/dist/footage/tonemap-lut.d.ts +45 -0
  73. package/dist/footage/tonemap-lut.d.ts.map +1 -0
  74. package/dist/footage/tonemap-lut.js +100 -0
  75. package/dist/footage/tonemap-lut.js.map +1 -0
  76. package/dist/footage/tools.d.ts +4 -4
  77. package/dist/footage/tools.d.ts.map +1 -1
  78. package/dist/footage/tools.js +4 -4
  79. package/dist/footage/tools.js.map +1 -1
  80. package/dist/index.d.ts +9 -6
  81. package/dist/index.d.ts.map +1 -1
  82. package/dist/index.js +9 -6
  83. package/dist/index.js.map +1 -1
  84. package/docker/footage-worker.Dockerfile +1 -0
  85. package/package.json +1 -1
  86. package/schema/marketing.schema.json +105 -4
  87. package/src/cli/footage.ts +4 -2
  88. package/src/compose/compose.ts +13 -3
  89. package/src/compose/timeline.ts +27 -1
  90. package/src/config/config.ts +18 -2
  91. package/src/config/schema.ts +52 -3
  92. package/src/footage/captions.ts +6 -2
  93. package/src/footage/compose.ts +86 -23
  94. package/src/footage/cuts.ts +104 -0
  95. package/src/footage/draft.ts +43 -14
  96. package/src/footage/edl.ts +5 -2
  97. package/src/footage/film.ts +47 -4
  98. package/src/footage/loudness.ts +38 -16
  99. package/src/footage/music.ts +7 -0
  100. package/src/footage/normalize.ts +47 -22
  101. package/src/footage/picture.ts +179 -0
  102. package/src/footage/pipeline.ts +179 -22
  103. package/src/footage/publish.ts +8 -5
  104. package/src/footage/render.ts +72 -13
  105. package/src/footage/tonemap-lut.ts +109 -0
  106. package/src/footage/tools.ts +4 -4
  107. package/src/index.ts +37 -2
@@ -8,7 +8,8 @@ import { runFfmpeg, runProcess } from "./process.js";
8
8
  /**
9
9
  * The speech track's loudness, measured and normalized in two passes of ffmpeg's `loudnorm` (EBU R128): the first
10
10
  * pass measures, the second applies one linear gain from that measurement, so a quiet phone clip is not left quiet
11
- * and a loud one does not clip. It runs before the music is mixed under the speech.
11
+ * and a loud one does not clip. It runs on the speech track before the music is mixed under it, and on the finished
12
+ * film's mix (`FootageFilm.mixLoudness`), so the published file plays at the target whatever the music adds.
12
13
  */
13
14
 
14
15
  export interface LoudnessTarget {
@@ -48,9 +49,9 @@ function getLoudnormFilter(target: LoudnessTarget): string {
48
49
  return `loudnorm=I=${target.target}:TP=${target.truePeak}:LRA=${LOUDNESS_RANGE}`;
49
50
  }
50
51
 
51
- /** The first pass: decodes the track, prints the measurement on stderr, writes nothing. */
52
+ /** The first pass: decodes the sound only (a film's picture is skipped), prints the measurement on stderr, writes nothing. */
52
53
  export function buildLoudnessMeasureArgs(input: string, target: LoudnessTarget): string[] {
53
- return ["-hide_banner", "-nostats", "-i", input, "-af", `${getLoudnormFilter(target)}:print_format=json`, "-f", "null", "-"];
54
+ return ["-hide_banner", "-nostats", "-i", input, "-vn", "-af", `${getLoudnormFilter(target)}:print_format=json`, "-f", "null", "-"];
54
55
  }
55
56
 
56
57
  /** The measurement from the first pass's stderr (its last JSON block); null when there is none or it is incomplete. */
@@ -70,8 +71,12 @@ export function readLoudnessMeasurement(stderr: string): LoudnessMeasurement | n
70
71
  const parsed = measurementSchema.safeParse(json);
71
72
  if (!parsed.success) return null;
72
73
  const value = parsed.data;
73
- // `-inf` (silence) reads as -Infinity, which `isSilent` tells apart.
74
- const read = (text: string): number => (text.trim() === "-inf" ? -Infinity : Number(text));
74
+ // Silence prints `-inf` loudness and an `inf` offset; both read as infinities, which `isSilent` tells apart.
75
+ const read = (text: string): number => {
76
+ const trimmed = text.trim();
77
+ if (trimmed === "-inf") return -Infinity;
78
+ return trimmed === "inf" || trimmed === "+inf" ? Infinity : Number(trimmed);
79
+ };
75
80
  const measurement = {
76
81
  inputI: read(value.input_i),
77
82
  inputTp: read(value.input_tp),
@@ -87,11 +92,10 @@ export function isSilent(measurement: LoudnessMeasurement): boolean {
87
92
  return !Number.isFinite(measurement.inputI) || measurement.inputI < SILENCE_LUFS || !Number.isFinite(measurement.inputThresh);
88
93
  }
89
94
 
90
- /** The second pass: one linear gain from the measurement, resampled back to the film's rate (`loudnorm` runs at 192 kHz). */
91
- export function buildLoudnessArgs(options: { input: string; measurement: LoudnessMeasurement; target: LoudnessTarget; output: string }): string[] {
92
- const { measurement } = options;
95
+ /** The second pass's filter: one linear gain from the measurement, resampled back to the film's rate (`loudnorm` runs at 192 kHz). */
96
+ export function getLoudnessFilter(measurement: LoudnessMeasurement, target: LoudnessTarget): string {
93
97
  const filter = [
94
- getLoudnormFilter(options.target),
98
+ getLoudnormFilter(target),
95
99
  `measured_I=${measurement.inputI}`,
96
100
  `measured_TP=${measurement.inputTp}`,
97
101
  `measured_LRA=${measurement.inputLra}`,
@@ -99,6 +103,11 @@ export function buildLoudnessArgs(options: { input: string; measurement: Loudnes
99
103
  `offset=${measurement.targetOffset}`,
100
104
  "linear=true",
101
105
  ].join(":");
106
+ return `${filter},aresample=${FOOTAGE_SAMPLE_RATE}`;
107
+ }
108
+
109
+ /** The speech track's second pass, written as an mp3 at the film's rate. */
110
+ export function buildLoudnessArgs(options: { input: string; measurement: LoudnessMeasurement; target: LoudnessTarget; output: string }): string[] {
102
111
  return [
103
112
  "-v",
104
113
  "error",
@@ -106,7 +115,7 @@ export function buildLoudnessArgs(options: { input: string; measurement: Loudnes
106
115
  "-i",
107
116
  options.input,
108
117
  "-af",
109
- `${filter},aresample=${FOOTAGE_SAMPLE_RATE}`,
118
+ getLoudnessFilter(options.measurement, options.target),
110
119
  "-ar",
111
120
  String(FOOTAGE_SAMPLE_RATE),
112
121
  "-c:a",
@@ -117,6 +126,22 @@ export function buildLoudnessArgs(options: { input: string; measurement: Loudnes
117
126
  ];
118
127
  }
119
128
 
129
+ export type LoudnessMeasureOutcome = { kind: "measured"; measurement: LoudnessMeasurement } | { kind: "silent" };
130
+
131
+ /**
132
+ * The first pass over `input`: its measurement, or silent when no gain can bring it to the target. Throws naming
133
+ * `label` (what is measured) when ffmpeg fails, rejects with the signal's reason on abort.
134
+ */
135
+ export async function measureLoudness(input: string, target: LoudnessTarget, options: { label: string; signal?: AbortSignal }): Promise<LoudnessMeasureOutcome> {
136
+ const step = `Measuring ${options.label}'s loudness`;
137
+ const measured = await runProcess({ command: "ffmpeg", args: buildLoudnessMeasureArgs(input, target), ...(options.signal === undefined ? {} : { signal: options.signal }) });
138
+ if (measured.kind === "not-started") throw new Error(`${step}: ffmpeg did not start (${measured.error}).`);
139
+ if (measured.code !== 0) throw new Error(`${step}: ffmpeg ended with code ${String(measured.code)}: ${measured.stderr.trim().split("\n").slice(-3).join(" | ")}.`);
140
+ const measurement = readLoudnessMeasurement(measured.stderr);
141
+ if (measurement === null) throw new Error(`${step}: ffmpeg printed no loudnorm measurement for ${input}.`);
142
+ return isSilent(measurement) ? { kind: "silent" } : { kind: "measured", measurement };
143
+ }
144
+
120
145
  export type LoudnessOutcome = { kind: "normalized"; measured: number } | { kind: "silent" };
121
146
 
122
147
  /**
@@ -125,15 +150,12 @@ export type LoudnessOutcome = { kind: "normalized"; measured: number } | { kind:
125
150
  */
126
151
  export async function normalizeLoudness(input: string, output: string, target: LoudnessTarget, options: { signal?: AbortSignal; onSeconds?: (seconds: number) => void } = {}): Promise<LoudnessOutcome> {
127
152
  const signal = options.signal === undefined ? {} : { signal: options.signal };
128
- const measured = await runProcess({ command: "ffmpeg", args: buildLoudnessMeasureArgs(input, target), ...signal });
129
- if (measured.kind === "not-started") throw new Error(`Measuring the speech track's loudness: ffmpeg did not start (${measured.error}).`);
130
- if (measured.code !== 0) throw new Error(`Measuring the speech track's loudness: ffmpeg ended with code ${String(measured.code)}: ${measured.stderr.trim().split("\n").slice(-3).join(" | ")}.`);
131
- const measurement = readLoudnessMeasurement(measured.stderr);
132
- if (measurement === null) throw new Error(`Measuring the speech track's loudness: ffmpeg printed no loudnorm measurement for ${input}.`);
133
- if (isSilent(measurement)) {
153
+ const measured = await measureLoudness(input, target, { label: "the speech track", ...signal });
154
+ if (measured.kind === "silent") {
134
155
  copyFileSync(input, output);
135
156
  return { kind: "silent" };
136
157
  }
158
+ const { measurement } = measured;
137
159
  await runFfmpeg("Normalizing the speech track's loudness", buildLoudnessArgs({ input, measurement, target, output }), {
138
160
  ...signal,
139
161
  output,
@@ -1,4 +1,5 @@
1
1
  import type { TimedWord } from "../voice/voiceover.js";
2
+ import type { FootageMusic } from "./film.js";
2
3
 
3
4
  /**
4
5
  * Music under the voice: loud between sentences, ducked while someone speaks. The envelope is a list of keyframes
@@ -22,6 +23,12 @@ export interface DuckingOptions {
22
23
  gap?: number;
23
24
  }
24
25
 
26
+ /** A film's music settings as ducking options: its volumes, and its attack and release when it sets them. */
27
+ export function getDuckingOptions(music: Pick<FootageMusic, "volume" | "duckedVolume" | "attack" | "release">): DuckingOptions {
28
+ const { volume, duckedVolume, attack, release } = music;
29
+ return { volume, duckedVolume, ...(attack === undefined ? {} : { attack }), ...(release === undefined ? {} : { release }) };
30
+ }
31
+
25
32
  const r3 = (value: number): number => Math.round(value * 1000) / 1000 || 0;
26
33
 
27
34
  /** Stretches of speech: the words joined when less than `gap` seconds apart. */
@@ -1,6 +1,9 @@
1
+ import { dirname, resolve } from "node:path";
2
+
1
3
  import type { ClipFit, FootageClip } from "./film.js";
2
4
  import { getTrimmedDuration, type FootageProbe, type HdrKind } from "./probe.js";
3
5
  import { runFfmpeg, type FfmpegRunOptions } from "./process.js";
6
+ import { ensureToneMapLut, getToneMapTransfer, HABLE_STAGES } from "./tonemap-lut.js";
4
7
 
5
8
  /**
6
9
  * One intermediate format for every clip, so the composition can cut between them freely: the film's frame at
@@ -27,20 +30,21 @@ export function resolveFit(fit: ClipFit, probe: Pick<FootageProbe, "displayWidth
27
30
  return Math.abs(clipAspect - frameAspect) / frameAspect <= CROP_ASPECT_TOLERANCE ? "crop" : "blur";
28
31
  }
29
32
 
30
- const TRANSFER_INPUT: Record<HdrKind, string> = { pq: "smpte2084", hlg: "arib-std-b67", "dolby-vision": "arib-std-b67" };
31
-
32
33
  /**
33
- * HDR to SDR BT.709 on the CPU: to linear light (zscale), Hable tone curve, back to BT.709. A Dolby Vision phone
34
- * clip is read through its HLG base layer.
34
+ * HDR to SDR BT.709 on the CPU. A Dolby Vision phone clip is read through its HLG base layer. With `lut` (the file
35
+ * name of the transfer's tone map LUT, `ensureToneMapLut`, in the folder ffmpeg runs in): to 16-bit R'G'B', the LUT
36
+ * to linear BT.709 light, the BT.709 transfer and matrix, about half the cost; colours outside BT.709 are clipped per
37
+ * RGB channel. Without it: to linear light (zscale), the Hable curve in float, back to BT.709, the same curve the LUT
38
+ * is made from; colours outside BT.709 are clamped in YUV.
35
39
  */
36
- export function toneMapFilter(hdr: HdrKind | null, transfer: string | null): string[] {
40
+ export function toneMapFilter(hdr: HdrKind | null, transfer: string | null, lut?: string): string[] {
37
41
  if (hdr === null) return [];
38
- const input = transfer === "smpte2084" || transfer === "arib-std-b67" ? transfer : TRANSFER_INPUT[hdr];
42
+ if (lut !== undefined) {
43
+ return ["zscale=min=bt2020nc:m=gbr:r=full", "format=gbrp16le", `lut3d=file=${lut}:interp=tetrahedral`, "zscale=tin=linear:pin=bt709:t=bt709:p=bt709:m=bt709:r=tv", "format=yuv420p"];
44
+ }
39
45
  return [
40
- `zscale=tin=${input}:pin=bt2020:min=bt2020nc:t=linear:npl=100`,
41
- "format=gbrpf32le",
42
- "zscale=p=bt709",
43
- "tonemap=tonemap=hable:desat=0",
46
+ `zscale=tin=${getToneMapTransfer(hdr, transfer)}:pin=bt2020:min=bt2020nc:t=linear:npl=100`,
47
+ ...HABLE_STAGES,
44
48
  "zscale=t=bt709:m=bt709:r=tv",
45
49
  // Back to 8-bit before scaling: the blur fill on float frames crashed ffmpeg 6.1.
46
50
  "format=yuv420p",
@@ -50,13 +54,13 @@ export function toneMapFilter(hdr: HdrKind | null, transfer: string | null): str
50
54
  /**
51
55
  * The video filter graph from input 0's picture to `[v]`. Every stage runs on as little as it can: frames are
52
56
  * dropped to 30 fps first, then the picture is scaled to the frame (crop: covered and cropped to it; blur: fitted
53
- * inside it), and only then tone-mapped, so the float stages of an HDR clip work on frame-sized pictures instead of
57
+ * inside it), and only then tone-mapped, so the tone map of an HDR clip works on frame-sized pictures instead of
54
58
  * the source's (a 4K phone clip has 4x the pixels of a 1080x1920 frame). The blur's background is made from the
55
- * fitted picture.
59
+ * fitted picture. `toneMapLut` as in `toneMapFilter`.
56
60
  */
57
- export function buildVideoFilter(options: { fit: "crop" | "blur"; frame: Frame; hdr: HdrKind | null; transfer: string | null }): string {
61
+ export function buildVideoFilter(options: { fit: "crop" | "blur"; frame: Frame; hdr: HdrKind | null; transfer: string | null; toneMapLut?: string }): string {
58
62
  const { width, height } = options.frame;
59
- const toneMap = toneMapFilter(options.hdr, options.transfer);
63
+ const toneMap = toneMapFilter(options.hdr, options.transfer, options.toneMapLut);
60
64
  const tail = "setsar=1,format=yuv420p";
61
65
  if (options.fit === "crop") {
62
66
  const cover = `scale=${width}:${height}:force_original_aspect_ratio=increase,crop=${width}:${height}`;
@@ -96,12 +100,21 @@ export interface NormalizeInput {
96
100
  frame: Frame;
97
101
  output: string;
98
102
  encoder?: NormalizeEncoder;
103
+ /**
104
+ * The tone map LUT's file name for an HDR clip, resolved in the folder ffmpeg runs in (`toneMapFilter`). Without it
105
+ * `buildNormalizeArgs` uses the float chain; `normalizeFootage` makes the LUT next to the output and uses it.
106
+ */
107
+ toneMapLut?: string;
99
108
  }
100
109
 
101
- /** The thread arguments: global filter threads (before the inputs) and encoder threads (before the output). */
102
- function getThreadArgs(threads: number | undefined): { global: string[]; output: string[] } {
110
+ /**
111
+ * The thread arguments: global filter threads (before the inputs) and encoder threads (before the output; the same
112
+ * flag before an input sets that input's decoder threads). Throws, naming `option`, when `threads` is not a positive
113
+ * whole number.
114
+ */
115
+ export function getThreadArgs(threads: number | undefined, option: string): { global: string[]; output: string[] } {
103
116
  if (threads === undefined) return { global: [], output: [] };
104
- if (!Number.isInteger(threads) || threads < 1) throw new Error(`normalize.threads must be a positive whole number, got ${threads}.`);
117
+ if (!Number.isInteger(threads) || threads < 1) throw new Error(`${option} must be a positive whole number, got ${threads}.`);
105
118
  return { global: ["-filter_complex_threads", String(threads)], output: ["-threads", String(threads)] };
106
119
  }
107
120
 
@@ -111,7 +124,7 @@ export function buildNormalizeArgs(input: NormalizeInput): string[] {
111
124
  const duration = getTrimmedDuration(clip, probe);
112
125
  const fit = resolveFit(clip.fit, probe, frame);
113
126
  const seek = clip.trim.start > 0 ? ["-ss", String(clip.trim.start)] : [];
114
- const threads = getThreadArgs(input.encoder?.threads);
127
+ const threads = getThreadArgs(input.encoder?.threads, "normalize.threads");
115
128
  const silence = probe.hasAudio ? [] : ["-f", "lavfi", "-i", `anullsrc=r=${FOOTAGE_SAMPLE_RATE}:cl=stereo`];
116
129
  return [
117
130
  "-v",
@@ -125,7 +138,7 @@ export function buildNormalizeArgs(input: NormalizeInput): string[] {
125
138
  "-t",
126
139
  duration.toFixed(3),
127
140
  "-filter_complex",
128
- buildVideoFilter({ fit, frame, hdr: probe.hdr, transfer: probe.colorTransfer }),
141
+ buildVideoFilter({ fit, frame, hdr: probe.hdr, transfer: probe.colorTransfer, ...(input.toneMapLut === undefined ? {} : { toneMapLut: input.toneMapLut }) }),
129
142
  "-map",
130
143
  "[v]",
131
144
  "-map",
@@ -161,8 +174,20 @@ export function buildNormalizeArgs(input: NormalizeInput): string[] {
161
174
 
162
175
  /**
163
176
  * Runs ffmpeg for one clip without blocking; throws with the clip's id when it fails (a broken file is not an expected
164
- * outcome here). An abort removes the partial output and rejects with the signal's reason.
177
+ * outcome here). An HDR clip without `toneMapLut` gets its transfer's LUT made once in the output's folder, and ffmpeg
178
+ * runs there so the graph names the LUT without a path. An abort removes the partial output and rejects with the
179
+ * signal's reason.
165
180
  */
166
- export async function normalizeFootage(input: NormalizeInput, options: Omit<FfmpegRunOptions, "output"> = {}): Promise<void> {
167
- await runFfmpeg(`Normalizing clip ${input.clip.id} (${input.file})`, buildNormalizeArgs(input), { ...options, output: input.output });
181
+ export async function normalizeFootage(input: NormalizeInput, options: Omit<FfmpegRunOptions, "output" | "cwd"> = {}): Promise<void> {
182
+ const step = `Normalizing clip ${input.clip.id} (${input.file})`;
183
+ const output = resolve(input.output);
184
+ const { hdr, colorTransfer } = input.probe;
185
+ if (hdr === null || input.toneMapLut !== undefined) {
186
+ await runFfmpeg(step, buildNormalizeArgs(input), { ...options, output });
187
+ return;
188
+ }
189
+ const dir = dirname(output);
190
+ const toneMapLut = await ensureToneMapLut(getToneMapTransfer(hdr, colorTransfer), dir, options.signal === undefined ? {} : { signal: options.signal });
191
+ const args = buildNormalizeArgs({ ...input, file: resolve(input.file), output, toneMapLut });
192
+ await runFfmpeg(step, args, { ...options, output, cwd: dir });
168
193
  }
@@ -0,0 +1,179 @@
1
+ import { getSegmentScales } from "./compose.js";
2
+ import { getEdlDuration, getSegmentStarts, type Edl } from "./edl.js";
3
+ import { getFootageEdit, type FootageFilm } from "./film.js";
4
+ import { FOOTAGE_FPS, getThreadArgs, type NormalizeEncoder } from "./normalize.js";
5
+
6
+ /**
7
+ * The cut's picture in film time, which the render's composition plays as one `<video>`: one short ffmpeg per segment
8
+ * (run one after the other, so one decoder at a time) and a stream-copy join. hyperframes then extracts the whole
9
+ * film's frames with one ffmpeg, and its Chrome holds one video instead of one per segment (issue #1030: the
10
+ * extraction peak falls from about 1 GB to 0.2 GB, the capture's from 1.7 GB to 1.1 GB on a 45 s 1080x1920 film).
11
+ *
12
+ * Every piece starts on a film frame and runs to the next segment's frame, so rounding never adds up along the cut.
13
+ * A cross-fade is drawn into the incoming piece: the outgoing segment's tail, held at the zoom it ends on, dissolves
14
+ * into the incoming clip (`xfade`), as the per-segment composition plays it. Zoom cuts and Ken Burns stay tweens on
15
+ * the composition's video.
16
+ */
17
+
18
+ /** The point a zoom keeps still, as the composition's `transform-origin: 50% 42%`. */
19
+ const ZOOM_ORIGIN = { x: 0.5, y: 0.42 } as const;
20
+ /** How far a segment marked `kenburns` zooms when the film's `kenBurnsPercent` is 0, as in the composition. */
21
+ const HAND_KEN_BURNS_PERCENT = 4;
22
+ const PICTURE_CRF = 18;
23
+ const DEFAULT_PICTURE_PRESET = "veryfast";
24
+
25
+ const r3 = (value: number): number => Math.round(value * 1000) / 1000 || 0;
26
+
27
+ /** The outgoing segment's tail under a cross-fade. */
28
+ export interface PictureFadeTail {
29
+ clip: string;
30
+ /** Seconds in the clip: where the outgoing segment ends. */
31
+ start: number;
32
+ frames: number;
33
+ /** The zoom the outgoing segment ends on, held through the fade. */
34
+ scale: number;
35
+ }
36
+
37
+ /** One segment's piece of the picture. */
38
+ export interface PicturePiece {
39
+ clip: string;
40
+ /** Seconds in the clip where the piece starts. */
41
+ start: number;
42
+ /** The piece's first film frame. */
43
+ frame: number;
44
+ frames: number;
45
+ /** For a `fade` cut, the outgoing tail the piece dissolves from; null for any other cut. */
46
+ fade: PictureFadeTail | null;
47
+ }
48
+
49
+ /** The film frame a film second falls on. */
50
+ function toFrame(seconds: number): number {
51
+ return Math.round(seconds * FOOTAGE_FPS);
52
+ }
53
+
54
+ /** The picture's pieces, one per segment, covering the cut's frames without a gap. Throws on an EDL without segments. */
55
+ export function planFootagePicture(film: Pick<FootageFilm, "edit">, edl: Edl): PicturePiece[] {
56
+ if (edl.segments.length === 0) throw new Error("The EDL has no segments.");
57
+ const edit = getFootageEdit(film);
58
+ const kenBurnsScale = 1 + (edit.kenBurnsPercent > 0 ? edit.kenBurnsPercent : HAND_KEN_BURNS_PERCENT) / 100;
59
+ const scales = getSegmentScales(edl, edit.zoomPercent);
60
+ const starts = getSegmentStarts(edl);
61
+ const lastFrame = toFrame(getEdlDuration(edl));
62
+ return edl.segments.map((segment, index) => {
63
+ const frame = toFrame(starts[index] as number);
64
+ const nextStart = starts[index + 1];
65
+ const frames = Math.max(1, (nextStart === undefined ? lastFrame : toFrame(nextStart)) - frame);
66
+ const previous = edl.segments[index - 1];
67
+ const fadeFrames = segment.transition === "fade" ? Math.min(frames, edit.fadeFrames) : 0;
68
+ let fade: PictureFadeTail | null = null;
69
+ if (previous !== undefined && fadeFrames > 0) {
70
+ const previousScale = scales[index - 1] as number;
71
+ // The outgoing segment's Ken Burns tween ends at its end; its tail holds the zoom it reached.
72
+ const scale = previous.motion === "kenburns" ? Math.round(previousScale * kenBurnsScale * 10000) / 10000 : previousScale;
73
+ fade = { clip: previous.clip, start: r3(previous.end), frames: fadeFrames, scale };
74
+ }
75
+ return { clip: segment.clip, start: r3(segment.start), frame, frames, fade };
76
+ });
77
+ }
78
+
79
+ /** The number of frames the picture has: the cut's length in film frames. */
80
+ export function getPictureFrames(pieces: readonly PicturePiece[]): number {
81
+ return pieces.reduce((sum, piece) => sum + piece.frames, 0);
82
+ }
83
+
84
+ /** Filters that bring a stream to the film's rate and pixel format and exactly `frames` long (a short clip holds its last frame). */
85
+ function fitStream(frames: number): string[] {
86
+ const seconds = r3(frames / FOOTAGE_FPS);
87
+ return [
88
+ "setpts=PTS-STARTPTS",
89
+ `fps=${FOOTAGE_FPS}`,
90
+ "format=yuv420p",
91
+ "setsar=1",
92
+ `tpad=stop_mode=clone:stop_duration=${seconds}`,
93
+ `trim=end_frame=${frames}`,
94
+ "setpts=PTS-STARTPTS",
95
+ `settb=1/${FOOTAGE_FPS}`,
96
+ ];
97
+ }
98
+
99
+ /** A crop to `scale` about the zoom origin and back to the clip's size; nothing at scale 1. */
100
+ function zoomFilters(scale: number): string[] {
101
+ if (scale === 1) return [];
102
+ return [`crop=iw/${scale}:ih/${scale}:(iw-iw/${scale})*${ZOOM_ORIGIN.x}:(ih-ih/${scale})*${ZOOM_ORIGIN.y}`, `scale=iw*${scale}:ih*${scale}`];
103
+ }
104
+
105
+ export interface PicturePieceArgsInput {
106
+ piece: PicturePiece;
107
+ /** The normalized clips by id. */
108
+ clips: Record<string, string>;
109
+ output: string;
110
+ /** The intermediate clips' encoder (`RenderFootageOptions.normalize`): its preset and threads encode the piece too. */
111
+ encoder?: NormalizeEncoder;
112
+ }
113
+
114
+ /** One piece's ffmpeg arguments: its clip (and a fade's outgoing tail), exactly `frames` frames, H.264 without sound. */
115
+ export function buildPicturePieceArgs(input: PicturePieceArgsInput): string[] {
116
+ const { piece, clips } = input;
117
+ const getClip = (id: string): string => {
118
+ const file = clips[id];
119
+ if (file === undefined) throw new Error(`No file for clip "${id}" of the EDL.`);
120
+ return file;
121
+ };
122
+ const threads = getThreadArgs(input.encoder?.threads, "normalize.threads");
123
+ const seconds = (frames: number): string => String(r3(frames / FOOTAGE_FPS + 1 / FOOTAGE_FPS));
124
+ const inputs = [...threads.output, "-ss", String(piece.start), "-t", seconds(piece.frames), "-i", getClip(piece.clip)];
125
+ let graph = `[0:v]${fitStream(piece.frames).join(",")}[picture]`;
126
+ if (piece.fade !== null) {
127
+ const { fade } = piece;
128
+ inputs.push(...threads.output, "-ss", String(fade.start), "-t", seconds(fade.frames), "-i", getClip(fade.clip));
129
+ const tail = [...zoomFilters(fade.scale), ...fitStream(fade.frames)];
130
+ graph = [
131
+ `[0:v]${fitStream(piece.frames).join(",")}[incoming]`,
132
+ `[1:v]${tail.join(",")}[outgoing]`,
133
+ // xfade's output is the outgoing tail plus the incoming piece minus the fade: the piece's own length.
134
+ `[outgoing][incoming]xfade=transition=fade:duration=${r3(fade.frames / FOOTAGE_FPS)}:offset=0,trim=end_frame=${piece.frames}[picture]`,
135
+ ].join(";");
136
+ }
137
+ return [
138
+ "-v",
139
+ "error",
140
+ "-y",
141
+ ...threads.global,
142
+ ...inputs,
143
+ "-filter_complex",
144
+ graph,
145
+ "-map",
146
+ "[picture]",
147
+ "-an",
148
+ "-frames:v",
149
+ String(piece.frames),
150
+ "-c:v",
151
+ "libx264",
152
+ "-preset",
153
+ input.encoder?.preset ?? DEFAULT_PICTURE_PRESET,
154
+ "-crf",
155
+ String(PICTURE_CRF),
156
+ "-g",
157
+ String(FOOTAGE_FPS / 2),
158
+ "-pix_fmt",
159
+ "yuv420p",
160
+ "-color_primaries",
161
+ "bt709",
162
+ "-color_trc",
163
+ "bt709",
164
+ "-colorspace",
165
+ "bt709",
166
+ ...threads.output,
167
+ input.output,
168
+ ];
169
+ }
170
+
171
+ /** The concat demuxer's list: one `file` line per piece, quotes escaped as the demuxer reads them. */
172
+ export function buildPictureList(files: readonly string[]): string {
173
+ return `${files.map((file) => `file '${file.replace(/'/g, "'\\''")}'`).join("\n")}\n`;
174
+ }
175
+
176
+ /** Joins the pieces by stream copy (they share one encoder's settings) into the picture, fast start. */
177
+ export function buildPictureConcatArgs(list: string, output: string): string[] {
178
+ return ["-v", "error", "-y", "-f", "concat", "-safe", "0", "-i", list, "-c", "copy", "-movflags", "+faststart", output];
179
+ }