@softure-ai/marketing-kit 0.3.1 → 0.5.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 (126) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/README.md +135 -14
  3. package/dist/cli/footage.d.ts.map +1 -1
  4. package/dist/cli/footage.js +15 -6
  5. package/dist/cli/footage.js.map +1 -1
  6. package/dist/config/actions-schema.d.ts +14 -14
  7. package/dist/config/config.d.ts.map +1 -1
  8. package/dist/config/config.js +5 -0
  9. package/dist/config/config.js.map +1 -1
  10. package/dist/config/schema.d.ts +92 -69
  11. package/dist/config/schema.d.ts.map +1 -1
  12. package/dist/config/schema.js +40 -4
  13. package/dist/config/schema.js.map +1 -1
  14. package/dist/config/shot-steps.d.ts +16 -16
  15. package/dist/footage/audio.d.ts +52 -0
  16. package/dist/footage/audio.d.ts.map +1 -0
  17. package/dist/footage/audio.js +100 -0
  18. package/dist/footage/audio.js.map +1 -0
  19. package/dist/footage/captions.d.ts +57 -0
  20. package/dist/footage/captions.d.ts.map +1 -0
  21. package/dist/footage/captions.js +112 -0
  22. package/dist/footage/captions.js.map +1 -0
  23. package/dist/footage/compose.d.ts +5 -5
  24. package/dist/footage/compose.d.ts.map +1 -1
  25. package/dist/footage/compose.js +31 -22
  26. package/dist/footage/compose.js.map +1 -1
  27. package/dist/footage/edl.d.ts +54 -16
  28. package/dist/footage/edl.d.ts.map +1 -1
  29. package/dist/footage/edl.js +204 -52
  30. package/dist/footage/edl.js.map +1 -1
  31. package/dist/footage/elevenlabs.d.ts +4 -1
  32. package/dist/footage/elevenlabs.d.ts.map +1 -1
  33. package/dist/footage/elevenlabs.js +18 -6
  34. package/dist/footage/elevenlabs.js.map +1 -1
  35. package/dist/footage/fake.d.ts +2 -0
  36. package/dist/footage/fake.d.ts.map +1 -1
  37. package/dist/footage/fake.js +2 -1
  38. package/dist/footage/fake.js.map +1 -1
  39. package/dist/footage/film.d.ts +35 -1
  40. package/dist/footage/film.d.ts.map +1 -1
  41. package/dist/footage/film.js +9 -1
  42. package/dist/footage/film.js.map +1 -1
  43. package/dist/footage/frames.d.ts +38 -0
  44. package/dist/footage/frames.d.ts.map +1 -0
  45. package/dist/footage/frames.js +40 -0
  46. package/dist/footage/frames.js.map +1 -0
  47. package/dist/footage/loudness.d.ts +49 -0
  48. package/dist/footage/loudness.d.ts.map +1 -0
  49. package/dist/footage/loudness.js +114 -0
  50. package/dist/footage/loudness.js.map +1 -0
  51. package/dist/footage/normalize.d.ts +6 -2
  52. package/dist/footage/normalize.d.ts.map +1 -1
  53. package/dist/footage/normalize.js +7 -9
  54. package/dist/footage/normalize.js.map +1 -1
  55. package/dist/footage/paid.d.ts +70 -0
  56. package/dist/footage/paid.d.ts.map +1 -0
  57. package/dist/footage/paid.js +172 -0
  58. package/dist/footage/paid.js.map +1 -0
  59. package/dist/footage/pipeline.d.ts +34 -10
  60. package/dist/footage/pipeline.d.ts.map +1 -1
  61. package/dist/footage/pipeline.js +294 -85
  62. package/dist/footage/pipeline.js.map +1 -1
  63. package/dist/footage/probe.d.ts +18 -4
  64. package/dist/footage/probe.d.ts.map +1 -1
  65. package/dist/footage/probe.js +18 -13
  66. package/dist/footage/probe.js.map +1 -1
  67. package/dist/footage/process.d.ts +45 -0
  68. package/dist/footage/process.d.ts.map +1 -0
  69. package/dist/footage/process.js +109 -0
  70. package/dist/footage/process.js.map +1 -0
  71. package/dist/footage/providers.d.ts +49 -5
  72. package/dist/footage/providers.d.ts.map +1 -1
  73. package/dist/footage/providers.js +4 -0
  74. package/dist/footage/providers.js.map +1 -1
  75. package/dist/footage/publish.d.ts +62 -0
  76. package/dist/footage/publish.d.ts.map +1 -0
  77. package/dist/footage/publish.js +164 -0
  78. package/dist/footage/publish.js.map +1 -0
  79. package/dist/footage/render.d.ts +5 -4
  80. package/dist/footage/render.d.ts.map +1 -1
  81. package/dist/footage/render.js +29 -17
  82. package/dist/footage/render.js.map +1 -1
  83. package/dist/footage/sentences.d.ts +44 -0
  84. package/dist/footage/sentences.d.ts.map +1 -0
  85. package/dist/footage/sentences.js +102 -0
  86. package/dist/footage/sentences.js.map +1 -0
  87. package/dist/footage/tools.d.ts +33 -0
  88. package/dist/footage/tools.d.ts.map +1 -0
  89. package/dist/footage/tools.js +108 -0
  90. package/dist/footage/tools.js.map +1 -0
  91. package/dist/footage/words.d.ts +6 -0
  92. package/dist/footage/words.d.ts.map +1 -0
  93. package/dist/footage/words.js +14 -0
  94. package/dist/footage/words.js.map +1 -0
  95. package/dist/index.d.ts +15 -6
  96. package/dist/index.d.ts.map +1 -1
  97. package/dist/index.js +15 -6
  98. package/dist/index.js.map +1 -1
  99. package/docker/footage-worker.Dockerfile +29 -0
  100. package/package.json +2 -1
  101. package/schema/edl.schema.json +115 -0
  102. package/schema/marketing.schema.json +112 -5
  103. package/src/cli/footage.ts +13 -5
  104. package/src/config/config.ts +5 -0
  105. package/src/config/schema.ts +40 -4
  106. package/src/footage/audio.ts +123 -0
  107. package/src/footage/captions.ts +146 -0
  108. package/src/footage/compose.ts +32 -24
  109. package/src/footage/edl.ts +225 -56
  110. package/src/footage/elevenlabs.ts +21 -8
  111. package/src/footage/fake.ts +4 -1
  112. package/src/footage/film.ts +43 -2
  113. package/src/footage/frames.ts +65 -0
  114. package/src/footage/loudness.ts +143 -0
  115. package/src/footage/normalize.ts +7 -9
  116. package/src/footage/paid.ts +213 -0
  117. package/src/footage/pipeline.ts +344 -89
  118. package/src/footage/probe.ts +20 -12
  119. package/src/footage/process.ts +135 -0
  120. package/src/footage/providers.ts +56 -6
  121. package/src/footage/publish.ts +180 -0
  122. package/src/footage/render.ts +29 -19
  123. package/src/footage/sentences.ts +137 -0
  124. package/src/footage/tools.ts +119 -0
  125. package/src/footage/words.ts +15 -0
  126. package/src/index.ts +84 -0
@@ -1,4 +1,3 @@
1
- import { createHash } from "node:crypto";
2
1
  import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
3
2
  import { createRequire } from "node:module";
4
3
  import { dirname, extname, join, resolve } from "node:path";
@@ -7,20 +6,50 @@ import { LAYOUTS, resolveLayout, type LayoutOverride } from "../compose/timeline
7
6
  import type { BrandColors } from "../config/colors.js";
8
7
  import type { BrandFont } from "../config/config.js";
9
8
  import type { SfxEvent } from "../config/schema.js";
10
- import { runHyperframes } from "../render/hyperframes.js";
9
+ import { getHyperframesBin, getHyperframesEnv } from "../render/hyperframes.js";
11
10
  import { copyFonts } from "../render/render.js";
12
11
  import { err, ok, type TtsResult } from "../voice/provider.js";
13
12
  import type { TimedWord } from "../voice/voiceover.js";
14
- import { footageCacheKey, getFootageCachePath, hashFile, readCachedTranscript, writeCacheFile, writeTranscript } from "./cache.js";
13
+ import { checkMusicFileType, describeAudioProbe, probeAudio } from "./audio.js";
14
+ import { readCachedTranscript, writeCacheFile, writeTranscript } from "./cache.js";
15
15
  import { composeFootage, END_CARD_SECONDS, getFootageFilmSeconds } from "./compose.js";
16
- import { buildEdl, findEdlProblems, readEdl, remapWords, type Edl } from "./edl.js";
16
+ import { findMissingCaptionGlyphs, getCaptionPresetLayout } from "./captions.js";
17
+ import { buildEdl, readEdl, remapWords, validateEdl, type Edl } from "./edl.js";
17
18
  import { makePlaceholderTranscript } from "./fake.js";
18
- import type { FootageClip, FootageFilm } from "./film.js";
19
+ import { getFootageEdit, type FootageClip, type FootageFilm } from "./film.js";
20
+ import { DEFAULT_LOUDNESS, normalizeLoudness } from "./loudness.js";
19
21
  import { duckingKeyframes } from "./music.js";
20
22
  import { normalizeFootage, type Frame } from "./normalize.js";
21
23
  import { describeProbe, getTrimmedDuration, probeFootage, type FootageProbe } from "./probe.js";
22
- import { describePaidSteps, type FootageProviders, type PaidStep } from "./providers.js";
23
- import { buildAudioArgs, buildCutPreviewArgs, buildLastFrameArgs, buildMusicArgs, buildSpeechArgs, runFfmpeg } from "./render.js";
24
+ import {
25
+ getClipCacheKey,
26
+ getDownloadPath,
27
+ getEdlPath,
28
+ getIsolatedCache,
29
+ getPromptMusicCache,
30
+ getTranscriptCache,
31
+ getVideoMusicCache,
32
+ isUrl,
33
+ type CacheEntry,
34
+ } from "./paid.js";
35
+ import { runFfmpeg, runProcess } from "./process.js";
36
+ import { splitFilmSentences, type Sentence } from "./sentences.js";
37
+ import {
38
+ buildCoverArgs,
39
+ buildFinishArgs,
40
+ clampCoverSeconds,
41
+ findFinishProblems,
42
+ getCoverPath,
43
+ getDefaultCoverSeconds,
44
+ isPublishableAudio,
45
+ isPublishableVideo,
46
+ probeFilmFacts,
47
+ readTopLevelBoxes,
48
+ } from "./publish.js";
49
+ import { describePaidSteps, toPaidAudio, type FootageCharge, type FootageProgress, type FootageProviders, type FootageStage, type PaidAudio, type PaidStep } from "./providers.js";
50
+ import { buildAudioArgs, buildCutPreviewArgs, buildLastFrameArgs, buildMusicArgs, buildSpeechArgs } from "./render.js";
51
+
52
+ export { getEdlPath } from "./paid.js";
24
53
 
25
54
  /**
26
55
  * The footage film end to end, as standalone steps (`prepareFootage` → `transcribeFootage` → `cutFootage` →
@@ -30,7 +59,15 @@ import { buildAudioArgs, buildCutPreviewArgs, buildLastFrameArgs, buildMusicArgs
30
59
  * film's (`placeholder/` in the build folder, its own EDL).
31
60
  *
32
61
  * Build folder layout: `sources/` (downloaded URLs), `clips/<id>.mp4` (normalized), `audio/<id>.mp3`, `edl.json`
33
- * (`edl.placeholder.json`), `assets/`, `index.html`.
62
+ * (`edl.placeholder.json`), `assets/`, `index.html`, `render.mp4` (hyperframes' output until the final pass).
63
+ *
64
+ * The finished film is publishable: the speech track normalized to a loudness target before the music goes under it,
65
+ * H.264 High, AAC 48 kHz stereo, fast start, a cover JPG next to it, and its facts read back from the written file.
66
+ *
67
+ * Every step spawns ffmpeg, ffprobe and hyperframes asynchronously, so a jobs worker's event loop (and its lease
68
+ * heartbeat) keeps running. `signal` stops a run: the child process is killed, its partial file removed, and the
69
+ * step rejects with the signal's reason. `onProgress` reports each stage in seconds of media, `onCharge` each paid
70
+ * call made.
34
71
  */
35
72
 
36
73
  const require = createRequire(import.meta.url);
@@ -58,6 +95,11 @@ export interface FootageRunOptions {
58
95
  log: (line: string) => void;
59
96
  /** Downloads clip URLs; injected in tests. */
60
97
  fetch?: typeof globalThis.fetch;
98
+ /** Stops the run: the running child process is killed and the step rejects with the signal's reason. */
99
+ signal?: AbortSignal;
100
+ onProgress?: (progress: FootageProgress) => void;
101
+ /** Called after each paid call, for the app's own spend ledger. */
102
+ onCharge?: (charge: FootageCharge) => void;
61
103
  }
62
104
 
63
105
  export interface PreparedClip {
@@ -87,22 +129,36 @@ export function getFrame(film: Pick<FootageFilm, "format">): Frame {
87
129
  return LAYOUTS[film.format].frame;
88
130
  }
89
131
 
90
- export function getEdlPath(buildDir: string, isPlaceholder: boolean): string {
91
- return join(buildDir, isPlaceholder ? "edl.placeholder.json" : "edl.json");
132
+ /** Reports one stage's progress over its items, each `seconds` long; the reporter takes an item's index and its seconds done. */
133
+ function createStageProgress(
134
+ onProgress: FootageRunOptions["onProgress"],
135
+ step: FootageStage,
136
+ items: { item: string; seconds: number }[],
137
+ ): (index: number, seconds: number) => void {
138
+ const total = items.reduce((sum, item) => sum + item.seconds, 0);
139
+ const offsets = items.map((_, index) => items.slice(0, index).reduce((sum, item) => sum + item.seconds, 0));
140
+ return (index, seconds) => {
141
+ const entry = items[index];
142
+ if (onProgress === undefined || entry === undefined) return;
143
+ const done = (offsets[index] ?? 0) + Math.min(Math.max(seconds, 0), entry.seconds);
144
+ onProgress({ step, item: entry.item, itemIndex: index + 1, itemCount: items.length, done: Math.round(done * 1000) / 1000, total: Math.round(total * 1000) / 1000 });
145
+ };
92
146
  }
93
147
 
94
- const isUrl = (source: string): boolean => /^https?:\/\//i.test(source);
148
+ /** Rejects with the signal's reason once the run was aborted (before a paid call, which the provider may not stop). */
149
+ function throwIfAborted(signal: AbortSignal | undefined): void {
150
+ signal?.throwIfAborted();
151
+ }
95
152
 
96
- async function download(url: string, dir: string, fetch: typeof globalThis.fetch, log: (line: string) => void): Promise<FootageResult<string>> {
97
- const name = createHash("sha256").update(url).digest("hex").slice(0, 16);
98
- const extension = extname(new URL(url).pathname).toLowerCase() || ".mp4";
99
- const file = join(dir, `${name}${extension}`);
153
+ async function download(url: string, dir: string, options: Pick<FootageRunOptions, "fetch" | "log" | "signal">): Promise<FootageResult<string>> {
154
+ const file = getDownloadPath(url, dir);
100
155
  if (existsSync(file)) return ok(file);
101
- log(`download: ${url}`);
156
+ options.log(`download: ${url}`);
102
157
  let response: Response;
103
158
  try {
104
- response = await fetch(url);
159
+ response = await (options.fetch ?? globalThis.fetch)(url, { signal: options.signal ?? null });
105
160
  } catch (error) {
161
+ throwIfAborted(options.signal);
106
162
  return err(`downloading ${url} failed: ${String(error)}`);
107
163
  }
108
164
  if (!response.ok) return err(`downloading ${url}: the server answered ${response.status}`);
@@ -119,9 +175,12 @@ function getNormalizeStamp(clip: FootageClip, source: string, frame: Frame): str
119
175
  return JSON.stringify({ version: NORMALIZE_VERSION, source: resolve(source), size: stat.size, mtime: stat.mtimeMs, trim: clip.trim, fit: clip.fit, frame });
120
176
  }
121
177
 
122
- /** Downloads URL clips, probes every clip (all problems at once), normalizes each one that changed. */
123
- export async function prepareFootage(film: FootageFilm, options: Pick<FootageRunOptions, "buildDir" | "log" | "fetch">): Promise<FootageResult<PreparedClip[]>> {
124
- const { buildDir, log } = options;
178
+ /** Downloads URL clips, probes every clip (all problems at once) and a local music file, normalizes each clip that changed. */
179
+ export async function prepareFootage(
180
+ film: FootageFilm,
181
+ options: Pick<FootageRunOptions, "buildDir" | "log" | "fetch" | "signal" | "onProgress">,
182
+ ): Promise<FootageResult<PreparedClip[]>> {
183
+ const { buildDir, log, signal } = options;
125
184
  if (film.clips.length === 0) return err(`footage film ${film.id} has no clips.`);
126
185
  const sources: Record<string, string> = {};
127
186
  for (const clip of film.clips) {
@@ -130,39 +189,54 @@ export async function prepareFootage(film: FootageFilm, options: Pick<FootageRun
130
189
  sources[clip.id] = clip.source;
131
190
  continue;
132
191
  }
133
- const downloaded = await download(clip.source, join(buildDir, "sources"), options.fetch ?? globalThis.fetch, log);
192
+ const downloaded = await download(clip.source, join(buildDir, "sources"), options);
134
193
  if (!downloaded.ok) return err(`clip "${clip.id}": ${downloaded.error}`);
135
194
  sources[clip.id] = downloaded.value;
136
195
  }
137
- const probed = probeFootage(film.clips, sources);
196
+ const probed = await probeFootage(film.clips, sources, signal === undefined ? {} : { signal });
138
197
  if (!probed.ok) return err(probed.errors.join("\n"));
198
+ if (film.music.source.kind === "file") {
199
+ const music = await checkMusicFile(film.music.source.path, options);
200
+ if (!music.ok) return err(music.error);
201
+ }
139
202
  const frame = getFrame(film);
140
203
  const clipsDir = join(buildDir, "clips");
141
204
  mkdirSync(clipsDir, { recursive: true });
142
205
  const prepared: PreparedClip[] = [];
206
+ const stale: { clip: PreparedClip; stamp: string; stampPath: string }[] = [];
143
207
  for (const { clip, file: source, probe } of probed.clips) {
144
208
  log(describeProbe(clip, probe));
145
209
  const file = join(clipsDir, `${clip.id}.mp4`);
146
210
  const stampPath = join(clipsDir, `${clip.id}.json`);
147
211
  const stamp = getNormalizeStamp(clip, source, frame);
148
- if (!existsSync(file) || !existsSync(stampPath) || readFileSync(stampPath, "utf8") !== stamp) {
149
- normalizeFootage({ clip, file: source, probe, frame, output: file });
150
- writeFileSync(stampPath, stamp);
151
- }
152
- prepared.push({ clip, source, probe, file, duration: getTrimmedDuration(clip, probe) });
212
+ const entry: PreparedClip = { clip, source, probe, file, duration: getTrimmedDuration(clip, probe) };
213
+ if (!existsSync(file) || !existsSync(stampPath) || readFileSync(stampPath, "utf8") !== stamp) stale.push({ clip: entry, stamp, stampPath });
214
+ prepared.push(entry);
215
+ }
216
+ const progress = createStageProgress(options.onProgress, "normalize", stale.map(({ clip }) => ({ item: clip.clip.id, seconds: clip.duration })));
217
+ for (const [index, { clip, stamp, stampPath }] of stale.entries()) {
218
+ progress(index, 0);
219
+ // The stamp goes first, so a normalize stopped half-way never leaves a stamp that vouches for a partial clip.
220
+ rmSync(stampPath, { force: true });
221
+ await normalizeFootage(
222
+ { clip: clip.clip, file: clip.source, probe: clip.probe, frame, output: clip.file },
223
+ { ...(signal === undefined ? {} : { signal }), onSeconds: (seconds) => progress(index, seconds) },
224
+ );
225
+ writeFileSync(stampPath, stamp);
226
+ progress(index, clip.duration);
153
227
  }
154
228
  return ok(prepared);
155
229
  }
156
230
 
157
231
  /** The cache identity of a clip's source part: its bytes and its trim. */
158
- async function getClipKey(clip: PreparedClip): Promise<string> {
159
- return footageCacheKey("transcript", { source: await hashFile(clip.source), trim: clip.clip.trim });
232
+ function getClipKey(clip: PreparedClip): Promise<string> {
233
+ return getClipCacheKey(clip.source, clip.clip);
160
234
  }
161
235
 
162
- function extractAudio(clip: PreparedClip, buildDir: string): string {
236
+ async function extractAudio(clip: PreparedClip, buildDir: string, signal: AbortSignal | undefined): Promise<string> {
163
237
  const audio = join(buildDir, "audio", `${clip.clip.id}.mp3`);
164
238
  mkdirSync(dirname(audio), { recursive: true });
165
- runFfmpeg(`Extracting the sound of clip ${clip.clip.id}`, buildAudioArgs(clip.file, audio));
239
+ await runFfmpeg(`Extracting the sound of clip ${clip.clip.id}`, buildAudioArgs(clip.file, audio), { ...(signal === undefined ? {} : { signal }), output: audio });
166
240
  return audio;
167
241
  }
168
242
 
@@ -182,35 +256,27 @@ function transcribePlaceholder(film: FootageFilm, clips: PreparedClip[], buildDi
182
256
  export function getMusicPaidStep(film: FootageFilm, options: Pick<FootageRunOptions, "cacheDir" | "providers">, seconds: number): PaidStep | null {
183
257
  const source = film.music.source;
184
258
  if (source.kind === "none" || source.kind === "file") return null;
185
- if (source.kind === "prompt" && existsSync(getPromptMusicPath(film, options))) return null;
259
+ if (source.kind === "prompt" && existsSync(getPromptMusicCache(film, options).path)) return null;
186
260
  return { kind: "music", item: "film", provider: options.providers.music.id, seconds };
187
261
  }
188
262
 
189
- function getPromptMusicPath(film: FootageFilm, options: Pick<FootageRunOptions, "cacheDir" | "providers">): string {
190
- const source = film.music.source;
191
- const prompt = source.kind === "prompt" ? source.prompt : "";
192
- const key = footageCacheKey("music", { prompt, provider: options.providers.music.id, model: options.providers.music.model });
193
- return getFootageCachePath(options.cacheDir, film.id, "music", key);
194
- }
195
-
196
263
  /**
197
264
  * Each talking clip's words with times, from the cache or (with `isCommit`) from the speech-to-text provider, the
198
265
  * voice cleaned first when the film isolates it. Without `isCommit`, a cache miss returns the dry run: every paid
199
266
  * call the film still needs, music included, with its length.
200
267
  */
201
268
  export async function transcribeFootage(film: FootageFilm, clips: PreparedClip[], options: FootageRunOptions): Promise<FootageResult<TranscribeOutcome>> {
202
- const { buildDir, cacheDir, providers, log } = options;
269
+ const { buildDir, providers, log, signal } = options;
203
270
  if (options.isPlaceholder) return ok(transcribePlaceholder(film, clips, buildDir));
204
- const plan: { clip: PreparedClip; isolated: string | null; transcript: string }[] = [];
271
+ const plan: { clip: PreparedClip; isolated: CacheEntry | null; transcript: CacheEntry }[] = [];
205
272
  const steps: PaidStep[] = [];
206
273
  for (const clip of clips) {
207
274
  if (clip.clip.role !== "talk") continue;
208
275
  const clipKey = await getClipKey(clip);
209
- const isolated = film.isolateVoice ? getFootageCachePath(cacheDir, film.id, "isolated", footageCacheKey("isolated", { clip: clipKey, provider: providers.isolation.id })) : null;
210
- const transcriptKey = footageCacheKey("transcript", { clip: clipKey, isolated: isolated !== null, provider: providers.stt.id, model: providers.stt.model, language: film.language });
211
- const transcript = getFootageCachePath(cacheDir, film.id, "transcript", transcriptKey);
212
- if (isolated !== null && !existsSync(isolated)) steps.push({ kind: "isolate", item: `clip ${clip.clip.id}`, provider: providers.isolation.id, seconds: clip.duration });
213
- if (!existsSync(transcript)) steps.push({ kind: "transcribe", item: `clip ${clip.clip.id}`, provider: providers.stt.id, seconds: clip.duration });
276
+ const isolated = getIsolatedCache(film, clipKey, options);
277
+ const transcript = getTranscriptCache(film, clipKey, options);
278
+ if (isolated !== null && !existsSync(isolated.path)) steps.push({ kind: "isolate", item: `clip ${clip.clip.id}`, provider: providers.isolation.id, seconds: clip.duration });
279
+ if (!existsSync(transcript.path)) steps.push({ kind: "transcribe", item: `clip ${clip.clip.id}`, provider: providers.stt.id, seconds: clip.duration });
214
280
  plan.push({ clip, isolated, transcript });
215
281
  }
216
282
  if (steps.length > 0 && !options.isCommit) {
@@ -227,23 +293,36 @@ export async function transcribeFootage(film: FootageFilm, clips: PreparedClip[]
227
293
  words[clip.clip.id] = [];
228
294
  speech[clip.clip.id] = clip.file;
229
295
  }
230
- for (const { clip, isolated, transcript } of plan) {
296
+ const isolating = plan.filter(({ isolated }) => isolated !== null && !existsSync(isolated.path));
297
+ const transcribing = plan.filter(({ transcript }) => !existsSync(transcript.path));
298
+ const isolateProgress = createStageProgress(options.onProgress, "isolate", isolating.map(({ clip }) => ({ item: clip.clip.id, seconds: clip.duration })));
299
+ const transcribeProgress = createStageProgress(options.onProgress, "transcribe", transcribing.map(({ clip }) => ({ item: clip.clip.id, seconds: clip.duration })));
300
+ for (const entry of plan) {
301
+ const { clip, isolated, transcript } = entry;
231
302
  const id = clip.clip.id;
232
- let audio: string | null = null;
233
- const getAudio = (): string => (audio ??= extractAudio(clip, buildDir));
303
+ let audio: Promise<string> | null = null;
304
+ const getAudio = (): Promise<string> => (audio ??= extractAudio(clip, buildDir, signal));
234
305
  let sttInput: string | null = null;
235
306
  if (isolated !== null) {
236
- if (!existsSync(isolated)) {
307
+ if (!existsSync(isolated.path)) {
308
+ const index = isolating.indexOf(entry);
309
+ isolateProgress(index, 0);
310
+ const input = await getAudio();
311
+ throwIfAborted(signal);
237
312
  log(`voice isolation (${providers.isolation.id}): clip ${id}, ${clip.duration.toFixed(1)} s.`);
238
- const cleaned = await providers.isolation.isolate({ audio: getAudio() });
313
+ const cleaned = await providers.isolation.isolate({ audio: input, ...(signal === undefined ? {} : { signal }) });
314
+ throwIfAborted(signal);
239
315
  if (!cleaned.ok) return err(`clip "${id}": ${cleaned.error}`);
240
- writeCacheFile(isolated, cleaned.value);
241
- log(`voice isolation: saved ${isolated} (commit it).`);
316
+ const paid = toPaidAudio(cleaned.value);
317
+ writeCacheFile(isolated.path, paid.audio);
318
+ options.onCharge?.({ step: "isolate", item: id, provider: providers.isolation.id, units: clip.duration, ...(paid.credits === undefined ? {} : { credits: paid.credits }), cacheKey: isolated.key });
319
+ log(`voice isolation: saved ${isolated.path} (commit it).`);
320
+ isolateProgress(index, clip.duration);
242
321
  }
243
- speech[id] = isolated;
244
- sttInput = isolated;
322
+ speech[id] = isolated.path;
323
+ sttInput = isolated.path;
245
324
  }
246
- const cached = readCachedTranscript(transcript);
325
+ const cached = readCachedTranscript(transcript.path);
247
326
  if (!cached.ok) return err(cached.error);
248
327
  if (cached.words !== null) {
249
328
  log(`transcript: clip ${id} from the cache, nothing spent.`);
@@ -252,27 +331,42 @@ export async function transcribeFootage(film: FootageFilm, clips: PreparedClip[]
252
331
  }
253
332
  if (sttInput !== null) {
254
333
  // The provider sees the clip's id as the file name, as it does for the plain sound.
334
+ const cleaned = sttInput;
255
335
  sttInput = join(buildDir, "audio", `${id}.isolated.mp3`);
256
336
  mkdirSync(dirname(sttInput), { recursive: true });
257
- copyFileSync(isolated as string, sttInput);
337
+ copyFileSync(cleaned, sttInput);
258
338
  }
339
+ const index = transcribing.indexOf(entry);
340
+ transcribeProgress(index, 0);
341
+ const input = sttInput ?? (await getAudio());
342
+ throwIfAborted(signal);
259
343
  log(`speech to text (${providers.stt.id}): clip ${id}, ${clip.duration.toFixed(1)} s.`);
260
- const result = await providers.stt.transcribe({ audio: sttInput ?? getAudio(), language: film.language });
344
+ const result = await providers.stt.transcribe({ audio: input, language: film.language, ...(signal === undefined ? {} : { signal }) });
345
+ throwIfAborted(signal);
261
346
  if (!result.ok) return err(`clip "${id}": ${result.error}`);
262
- writeTranscript(transcript, result.value.words);
263
- log(`transcript: clip ${id}, ${result.value.words.length} words, saved ${transcript} (commit it).`);
347
+ writeTranscript(transcript.path, result.value.words);
348
+ const { credits } = result.value;
349
+ options.onCharge?.({ step: "transcribe", item: id, provider: providers.stt.id, units: clip.duration, ...(credits === undefined ? {} : { credits }), cacheKey: transcript.key });
350
+ log(`transcript: clip ${id}, ${result.value.words.length} words, saved ${transcript.path} (commit it).`);
351
+ transcribeProgress(index, clip.duration);
264
352
  words[id] = result.value.words;
265
353
  }
266
354
  return ok({ kind: "ready", words, speech });
267
355
  }
268
356
 
269
- /** The cut from the transcripts, written to the EDL file (replacing what is there). */
270
- export function cutFootage(film: FootageFilm, clips: PreparedClip[], words: Record<string, TimedWord[]>, edlPath: string): Edl {
357
+ /** The talking clips' sentences with their ids (`s1`…), as `buildEdl` names them, for choosing what to keep. */
358
+ export function getFootageSentences(clips: PreparedClip[], words: Record<string, TimedWord[]>): Sentence[] {
359
+ return splitFilmSentences(clips.map((clip) => ({ id: clip.clip.id, role: clip.clip.role, words: words[clip.clip.id] ?? [] })));
360
+ }
361
+
362
+ /** The cut from the transcripts, written to the EDL file (replacing what is there); `keepSentences` keeps only those sentences. */
363
+ export function cutFootage(film: FootageFilm, clips: PreparedClip[], words: Record<string, TimedWord[]>, edlPath: string, options: { keepSentences?: readonly string[] } = {}): Edl {
271
364
  const edl = buildEdl(
272
365
  film.id,
273
366
  clips.map((clip) => ({ id: clip.clip.id, role: clip.clip.role, duration: clip.duration, words: words[clip.clip.id] ?? [] })),
274
367
  film.cut,
275
368
  film.transitions,
369
+ { isKenBurns: getFootageEdit(film).kenBurnsPercent > 0, ...(options.keepSentences === undefined ? {} : { keepSentences: options.keepSentences }) },
276
370
  );
277
371
  mkdirSync(dirname(edlPath), { recursive: true });
278
372
  writeFileSync(edlPath, `${JSON.stringify(edl, null, 2)}\n`);
@@ -289,10 +383,21 @@ export function readEdlFile(film: FootageFilm, clips: PreparedClip[], edlPath: s
289
383
  }
290
384
  const read = readEdl(json);
291
385
  if (!read.ok) return err(`${edlPath}: ${read.error}`);
292
- const problems = findEdlProblems(read.edl, clips.map((clip) => ({ id: clip.clip.id, duration: clip.duration })), film.id);
386
+ const problems = validateEdl(read.edl, clips.map((clip) => ({ id: clip.clip.id, duration: clip.duration })), film.id);
293
387
  return problems.length > 0 ? err(`${edlPath}: ${problems.join("; ")}`) : ok(read.edl);
294
388
  }
295
389
 
390
+ /** A local music file checked like an app's upload: an accepted type, then readable audio (`probeAudio`). */
391
+ async function checkMusicFile(path: string, options: Pick<FootageRunOptions, "log" | "signal">): Promise<FootageResult<string>> {
392
+ if (!existsSync(path)) return err(`music: no file at ${path}`);
393
+ const type = checkMusicFileType({ fileName: path });
394
+ if (!type.ok) return err(`music: ${type.error}`);
395
+ const probe = await probeAudio(path, options.signal === undefined ? {} : { signal: options.signal });
396
+ if (!probe.ok) return err(`music: ${probe.error}`);
397
+ options.log(`music: ${path} (${describeAudioProbe(probe.probe)}).`);
398
+ return ok(path);
399
+ }
400
+
296
401
  /**
297
402
  * The music file for the cut: a local file as it is, generated music from the cache, or (with `isCommit`) bought
298
403
  * from the music provider and cached. Null when the film has none or the rehearsal skips generated music; a paid
@@ -303,34 +408,45 @@ async function getMusic(film: FootageFilm, edl: Edl, clips: PreparedClip[], seco
303
408
  if (source.kind === "none") return ok(null);
304
409
  if (source.kind === "file") return existsSync(source.path) ? ok(source.path) : err(`music: no file at ${source.path}`);
305
410
  if (options.isPlaceholder) return ok(null);
306
- const { providers, log } = options;
307
- let path: string;
411
+ const { providers, log, signal } = options;
412
+ let cache: CacheEntry;
308
413
  if (source.kind === "prompt") {
309
- path = getPromptMusicPath(film, options);
414
+ cache = getPromptMusicCache(film, options);
310
415
  } else {
311
416
  const clipKeys: Record<string, string> = {};
312
417
  for (const clip of clips) clipKeys[clip.clip.id] = await getClipKey(clip);
313
- const key = footageCacheKey("music", { segments: edl.segments, clips: clipKeys, description: source.description, tags: source.tags, provider: providers.music.id, model: providers.music.model });
314
- path = getFootageCachePath(options.cacheDir, film.id, "music", key);
418
+ cache = getVideoMusicCache(film, edl, clipKeys, options);
315
419
  }
420
+ const { path } = cache;
316
421
  if (existsSync(path)) {
317
422
  log(`music: from the cache ${path}, nothing spent.`);
318
423
  return ok(path);
319
424
  }
320
425
  const step: PaidStep = { kind: "music", item: "film", provider: providers.music.id, seconds };
321
426
  if (!options.isCommit) return ok(step);
322
- log(`music (${providers.music.id}): ${seconds.toFixed(1)} s.`);
323
- let bought: TtsResult<Buffer>;
427
+ const progress = createStageProgress(options.onProgress, "music", [{ item: "film", seconds }]);
428
+ progress(0, 0);
429
+ const aborting = signal === undefined ? {} : { signal };
430
+ let bought: TtsResult<Buffer | PaidAudio>;
324
431
  if (source.kind === "prompt") {
325
- bought = await providers.music.compose({ prompt: source.prompt, seconds });
432
+ throwIfAborted(signal);
433
+ log(`music (${providers.music.id}): ${seconds.toFixed(1)} s.`);
434
+ bought = await providers.music.compose({ prompt: source.prompt, seconds, ...aborting });
326
435
  } else {
327
436
  const preview = join(options.buildDir, "cut-preview.mp4");
328
- runFfmpeg("The cut preview for Video to Music", buildCutPreviewArgs(edl, Object.fromEntries(clips.map((clip) => [clip.clip.id, clip.file])), preview));
329
- bought = await providers.music.scoreVideo({ video: preview, description: source.description, tags: source.tags });
437
+ const clipFiles = Object.fromEntries(clips.map((clip) => [clip.clip.id, clip.file]));
438
+ await runFfmpeg("The cut preview for Video to Music", buildCutPreviewArgs(edl, clipFiles, preview), { ...aborting, output: preview });
439
+ throwIfAborted(signal);
440
+ log(`music (${providers.music.id}): ${seconds.toFixed(1)} s.`);
441
+ bought = await providers.music.scoreVideo({ video: preview, description: source.description, tags: source.tags, ...aborting });
330
442
  }
443
+ throwIfAborted(signal);
331
444
  if (!bought.ok) return err(`music: ${bought.error}`);
332
- writeCacheFile(path, bought.value);
445
+ const paid = toPaidAudio(bought.value);
446
+ writeCacheFile(path, paid.audio);
447
+ options.onCharge?.({ step: "music", item: "film", provider: providers.music.id, units: seconds, ...(paid.credits === undefined ? {} : { credits: paid.credits }), cacheKey: cache.key });
333
448
  log(`music: saved ${path} (commit it).`);
449
+ progress(0, seconds);
334
450
  return ok(path);
335
451
  }
336
452
 
@@ -345,9 +461,9 @@ export interface RenderFootageOptions extends FootageRunOptions {
345
461
  layout?: LayoutOverride;
346
462
  }
347
463
 
348
- export type RenderedFootage = { kind: "dry-run"; steps: PaidStep[] } | { kind: "rendered"; output: string; seconds: number; edlPath: string };
464
+ export type RenderedFootage = { kind: "dry-run"; steps: PaidStep[] } | ({ kind: "rendered"; output: string; seconds: number; edlPath: string } & FinishedFootage);
349
465
 
350
- /** Composes the cut and renders it: speech track, ducked music, end card backdrop, assets, hyperframes. */
466
+ /** Composes the cut and renders it: speech track (loudness-normalized), ducked music, end card backdrop, assets, hyperframes, final pass, cover. */
351
467
  export async function renderFootage(
352
468
  film: FootageFilm,
353
469
  clips: PreparedClip[],
@@ -355,7 +471,7 @@ export async function renderFootage(
355
471
  edl: Edl,
356
472
  options: RenderFootageOptions,
357
473
  ): Promise<FootageResult<RenderedFootage>> {
358
- const { buildDir, log } = options;
474
+ const { buildDir, log, signal } = options;
359
475
  const seconds = getFootageFilmSeconds(film, edl);
360
476
  const words = remapWords(edl, transcript.words, film.cut.fillers);
361
477
  const music = await getMusic(film, edl, clips, seconds, options);
@@ -369,14 +485,44 @@ export async function renderFootage(
369
485
  rmSync(assetsDir, { recursive: true, force: true });
370
486
  mkdirSync(assetsDir, { recursive: true });
371
487
  const clipFiles = Object.fromEntries(clips.map((clip) => [clip.clip.id, clip.file]));
372
- runFfmpeg("The speech track", buildSpeechArgs(edl, transcript.speech, join(assetsDir, "speech.mp3")));
373
- let musicAsset: string | null = null;
374
- if (typeof music.value === "string") {
488
+ const musicFile = typeof music.value === "string" ? music.value : null;
489
+ const aborting = signal === undefined ? {} : { signal };
490
+ const loudness = film.loudness === undefined ? DEFAULT_LOUDNESS : film.loudness;
491
+ const speechFile = join(assetsDir, "speech.mp3");
492
+ const rawSpeechFile = loudness === null ? speechFile : join(assetsDir, "speech.raw.mp3");
493
+ const ffmpegTrack = (label: string, output: string, args: () => string[]) => (onSeconds: (done: number) => void) => runFfmpeg(label, args(), { ...aborting, output, onSeconds });
494
+ const tracks: { item: string; seconds: number; run: (onSeconds: (done: number) => void) => Promise<void> }[] = [
495
+ { item: "speech", seconds, run: ffmpegTrack("The speech track", rawSpeechFile, () => buildSpeechArgs(edl, transcript.speech, rawSpeechFile)) },
496
+ ];
497
+ if (loudness !== null) {
498
+ tracks.push({
499
+ item: "loudness",
500
+ seconds,
501
+ run: async (onSeconds) => {
502
+ const outcome = await normalizeLoudness(rawSpeechFile, speechFile, loudness, { ...aborting, onSeconds });
503
+ log(
504
+ outcome.kind === "silent"
505
+ ? "loudness: the speech track is silent, left as it is."
506
+ : `loudness: the speech track measured ${outcome.measured.toFixed(1)} LUFS, normalized to ${loudness.target} LUFS (true peak ${loudness.truePeak} dBTP).`,
507
+ );
508
+ },
509
+ });
510
+ }
511
+ if (musicFile !== null) {
375
512
  const keyframes = duckingKeyframes(words, { volume: film.music.volume, duckedVolume: film.music.duckedVolume });
376
- runFfmpeg("The music track", buildMusicArgs({ input: music.value, seconds, keyframes, output: join(assetsDir, "music.mp3") }));
377
- musicAsset = "assets/music.mp3";
513
+ const output = join(assetsDir, "music.mp3");
514
+ tracks.push({ item: "music", seconds, run: ffmpegTrack("The music track", output, () => buildMusicArgs({ input: musicFile, seconds, keyframes, output })) });
378
515
  }
379
- runFfmpeg("The end card's backdrop", buildLastFrameArgs(edl, clipFiles, join(assetsDir, "last.jpg")));
516
+ // A single frame: counted as a moment of work so the stage's bar still ends at its total.
517
+ const lastFrame = join(assetsDir, "last.jpg");
518
+ tracks.push({ item: "last frame", seconds: 0.1, run: ffmpegTrack("The end card's backdrop", lastFrame, () => buildLastFrameArgs(edl, clipFiles, lastFrame)) });
519
+ const assetProgress = createStageProgress(options.onProgress, "assets", tracks);
520
+ for (const [index, track] of tracks.entries()) {
521
+ assetProgress(index, 0);
522
+ await track.run((done) => assetProgress(index, done));
523
+ assetProgress(index, track.seconds);
524
+ }
525
+ const musicAsset = musicFile === null ? null : "assets/music.mp3";
380
526
  const fonts = copyFonts(options.brand.fonts, join(assetsDir, "fonts"));
381
527
  if (options.brand.logo !== null) cpSync(options.brand.logo, join(assetsDir, "logo.svg"));
382
528
  const sfx: Partial<Record<SfxEvent, string>> = {};
@@ -387,7 +533,19 @@ export async function renderFootage(
387
533
  sfx[event] = `assets/sfx/${name}`;
388
534
  }
389
535
  cpSync(require.resolve("gsap/dist/gsap.min.js"), join(assetsDir, "gsap.min.js"));
390
- const layout = resolveLayout(film.format, options.layout ?? {});
536
+ const base = resolveLayout(film.format, options.layout ?? {});
537
+ // A caption preset places the 9:16 box in a platform's safe zone; the project's own caption override still wins.
538
+ const preset = film.captionPreset === undefined || film.format !== "9:16" ? null : getCaptionPresetLayout(film.captionPreset, base.caption.fontSize);
539
+ const layout = preset === null || options.layout?.caption !== undefined ? base : { ...base, caption: preset };
540
+ const missing = findMissingCaptionGlyphs({
541
+ fonts: options.brand.fonts,
542
+ captions: film.captions ? words.map((word) => word.text) : [],
543
+ endCard: film.endCard,
544
+ brandName: options.brand.name,
545
+ });
546
+ if (missing.length > 0) {
547
+ return err(`the brand fonts cannot draw every letter of the film: ${missing.map((entry) => `${entry.font} lacks ${entry.characters.join(" ")}`).join("; ")}. Add a font file that covers them (brand.fonts).`);
548
+ }
391
549
  const html = composeFootage({
392
550
  film,
393
551
  edl,
@@ -411,15 +569,112 @@ export async function renderFootage(
411
569
  writeFileSync(join(buildDir, "index.html"), html);
412
570
  mkdirSync(dirname(options.output), { recursive: true });
413
571
  log(`render: ${edl.segments.length} segments, ${seconds.toFixed(1)} s.`);
414
- const result = runHyperframes(["render", "--quality", options.quality, "-o", options.output], { cwd: buildDir, stdio: "inherit" });
415
- if (result.error !== undefined) return err(`hyperframes render did not start: ${result.error.message}.`);
416
- if (result.status !== 0) return err(`hyperframes render ended with code ${String(result.status)} (signal ${result.signal ?? "-"}).`);
417
- return ok({ kind: "rendered", output: options.output, seconds, edlPath: getEdlPath(buildDir, options.isPlaceholder) });
572
+ const renderFile = resolve(buildDir, "render.mp4");
573
+ const rendered = await runHyperframesRender(options, renderFile, seconds);
574
+ if (!rendered.ok) return rendered;
575
+ const roles = Object.fromEntries(clips.map((clip) => [clip.clip.id, clip.clip.role]));
576
+ const finished = await finishFootage(film, { renderFile, seconds, coverAt: film.cover?.at ?? getDefaultCoverSeconds(edl, roles) }, options);
577
+ if (!finished.ok) return finished;
578
+ return ok({ kind: "rendered", output: options.output, seconds, edlPath: getEdlPath(buildDir, options.isPlaceholder), ...finished.value });
579
+ }
580
+
581
+ /** What `renderFootage` reads from the written film. */
582
+ export interface FinishedFootage {
583
+ bytes: number;
584
+ width: number;
585
+ height: number;
586
+ /** The written file's real length, which may differ from the planned `seconds` by a frame or two. */
587
+ durationSeconds: number;
588
+ /** The cover JPG, or null when the film has none. */
589
+ cover: string | null;
590
+ }
591
+
592
+ /**
593
+ * The final pass over hyperframes' render: publishable codecs and fast start (stream copy where the render already
594
+ * matches), checked with ffprobe, then the cover and the file's facts.
595
+ */
596
+ async function finishFootage(
597
+ film: FootageFilm,
598
+ input: { renderFile: string; seconds: number; coverAt: number },
599
+ options: RenderFootageOptions,
600
+ ): Promise<FootageResult<FinishedFootage>> {
601
+ const { log, signal, output } = options;
602
+ const aborting = signal === undefined ? {} : { signal };
603
+ const progress = createStageProgress(options.onProgress, "finish", [{ item: "film", seconds: input.seconds }]);
604
+ progress(0, 0);
605
+ const rendered = await probeFilmFacts(input.renderFile, aborting);
606
+ if (!rendered.ok) return err(`the rendered film: ${rendered.error}`);
607
+ const isCopied = isPublishableVideo(rendered.facts.video) && (rendered.facts.audio === null || isPublishableAudio(rendered.facts.audio));
608
+ await runFfmpeg("The film's final pass", buildFinishArgs(input.renderFile, rendered.facts, output), { ...aborting, output, onSeconds: (done) => progress(0, done) });
609
+ rmSync(input.renderFile, { force: true });
610
+ const finished = await probeFilmFacts(output, aborting);
611
+ if (!finished.ok) return err(`the finished film: ${finished.error}`);
612
+ const problems = findFinishProblems(finished.facts, readTopLevelBoxes(output));
613
+ if (problems.length > 0) return err(`the finished film ${output} is not publishable: ${problems.join("; ")}.`);
614
+ progress(0, input.seconds);
615
+ const { bytes, width, height, durationSeconds } = finished.facts;
616
+ log(`finish: ${isCopied ? "streams copied" : "re-encoded"} to H.264 High, AAC 48 kHz stereo, fast start; ${width}×${height}, ${durationSeconds.toFixed(2)} s, ${bytes} bytes.`);
617
+ let cover: string | null = null;
618
+ if (film.cover !== null) {
619
+ cover = getCoverPath(output);
620
+ const at = clampCoverSeconds(input.coverAt, durationSeconds);
621
+ if (at !== input.coverAt) log(`cover: ${input.coverAt} s is past the film's end, the frame at ${at} s is used.`);
622
+ await runFfmpeg("The cover frame", buildCoverArgs(output, at, cover), { ...aborting, output: cover });
623
+ log(`cover: ${cover} (at ${at} s).`);
624
+ }
625
+ return ok({ bytes, width, height, durationSeconds, cover });
626
+ }
627
+
628
+ /** hyperframes' progress lines carry a percentage (`… 42%`); the last one on a line counts. */
629
+ export function readRenderPercent(line: string): number | null {
630
+ const matches = [...line.matchAll(/(\d{1,3}(?:\.\d+)?)\s?%/g)];
631
+ const last = matches.at(-1)?.[1];
632
+ if (last === undefined) return null;
633
+ const percent = Number(last);
634
+ return percent >= 0 && percent <= 100 ? percent : null;
635
+ }
636
+
637
+ /** The hyperframes render as a child process: its lines go to the log (progress every 10 %), its percentages to `onProgress`. */
638
+ async function runHyperframesRender(options: RenderFootageOptions, output: string, seconds: number): Promise<FootageResult<null>> {
639
+ const progress = createStageProgress(options.onProgress, "render", [{ item: "film", seconds }]);
640
+ progress(0, 0);
641
+ let loggedTenth = -1;
642
+ const onLine = (line: string): void => {
643
+ if (line.trim().length === 0) return;
644
+ const percent = readRenderPercent(line);
645
+ if (percent === null) {
646
+ options.log(line.trim());
647
+ return;
648
+ }
649
+ progress(0, (percent / 100) * seconds);
650
+ // A progress line per frame would flood the log: one line per tenth of the render is kept.
651
+ const tenth = Math.floor(percent / 10);
652
+ if (tenth > loggedTenth) {
653
+ loggedTenth = tenth;
654
+ options.log(line.trim());
655
+ }
656
+ };
657
+ const result = await runProcess({
658
+ command: process.execPath,
659
+ args: [getHyperframesBin(), "render", "--quality", options.quality, "-o", output],
660
+ cwd: options.buildDir,
661
+ env: getHyperframesEnv(),
662
+ ...(options.signal === undefined ? {} : { signal: options.signal }),
663
+ removeOnAbort: [output],
664
+ onStdoutLine: onLine,
665
+ onStderrLine: onLine,
666
+ });
667
+ if (result.kind === "not-started") return err(`hyperframes render did not start: ${result.error}.`);
668
+ if (result.code !== 0) return err(`hyperframes render ended with code ${String(result.code)} (signal ${result.signal ?? "-"}).`);
669
+ progress(0, seconds);
670
+ return ok(null);
418
671
  }
419
672
 
420
673
  export interface RenderFootageFilmOptions extends RenderFootageOptions {
421
674
  /** Build the EDL again even when the build folder holds one (by default a present EDL, maybe edited by hand, is used). */
422
675
  isRecut?: boolean;
676
+ /** When the EDL is built: the sentence ids to keep (`getFootageSentences`, `findRetakes`); absent keeps all. */
677
+ keepSentences?: readonly string[];
423
678
  }
424
679
 
425
680
  /**
@@ -440,7 +695,7 @@ export async function renderFootageFilm(film: FootageFilm, options: RenderFootag
440
695
  edl = read.value;
441
696
  options.log(`cut: ${edlPath} (${edl.segments.length} segments), as it is; softure-marketing footage --step=cut builds it again.`);
442
697
  } else {
443
- edl = cutFootage(film, clips.value, transcript.value.words, edlPath);
698
+ edl = cutFootage(film, clips.value, transcript.value.words, edlPath, options.keepSentences === undefined ? {} : { keepSentences: options.keepSentences });
444
699
  options.log(`cut: ${edl.segments.length} segments written to ${edlPath}.`);
445
700
  }
446
701
  return renderFootage(film, clips.value, transcript.value, edl, options);