@softure-ai/marketing-kit 0.4.0 → 0.6.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 (98) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/README.md +87 -6
  3. package/dist/config/config.d.ts.map +1 -1
  4. package/dist/config/config.js +7 -0
  5. package/dist/config/config.js.map +1 -1
  6. package/dist/config/schema.d.ts +1 -0
  7. package/dist/config/schema.d.ts.map +1 -1
  8. package/dist/config/schema.js +11 -0
  9. package/dist/config/schema.js.map +1 -1
  10. package/dist/footage/audio.d.ts +56 -0
  11. package/dist/footage/audio.d.ts.map +1 -0
  12. package/dist/footage/audio.js +112 -0
  13. package/dist/footage/audio.js.map +1 -0
  14. package/dist/footage/captions.d.ts +21 -2
  15. package/dist/footage/captions.d.ts.map +1 -1
  16. package/dist/footage/captions.js +29 -0
  17. package/dist/footage/captions.js.map +1 -1
  18. package/dist/footage/compose.d.ts.map +1 -1
  19. package/dist/footage/compose.js +4 -5
  20. package/dist/footage/compose.js.map +1 -1
  21. package/dist/footage/disk.d.ts +25 -0
  22. package/dist/footage/disk.d.ts.map +1 -0
  23. package/dist/footage/disk.js +72 -0
  24. package/dist/footage/disk.js.map +1 -0
  25. package/dist/footage/draft.d.ts +105 -0
  26. package/dist/footage/draft.d.ts.map +1 -0
  27. package/dist/footage/draft.js +282 -0
  28. package/dist/footage/draft.js.map +1 -0
  29. package/dist/footage/elevenlabs.d.ts.map +1 -1
  30. package/dist/footage/elevenlabs.js +2 -0
  31. package/dist/footage/elevenlabs.js.map +1 -1
  32. package/dist/footage/film.d.ts +12 -0
  33. package/dist/footage/film.d.ts.map +1 -1
  34. package/dist/footage/film.js.map +1 -1
  35. package/dist/footage/keyterms.d.ts +26 -0
  36. package/dist/footage/keyterms.d.ts.map +1 -0
  37. package/dist/footage/keyterms.js +36 -0
  38. package/dist/footage/keyterms.js.map +1 -0
  39. package/dist/footage/normalize.d.ts +21 -2
  40. package/dist/footage/normalize.d.ts.map +1 -1
  41. package/dist/footage/normalize.js +35 -11
  42. package/dist/footage/normalize.js.map +1 -1
  43. package/dist/footage/paid.d.ts +2 -1
  44. package/dist/footage/paid.d.ts.map +1 -1
  45. package/dist/footage/paid.js +13 -3
  46. package/dist/footage/paid.js.map +1 -1
  47. package/dist/footage/pipeline.d.ts +21 -4
  48. package/dist/footage/pipeline.d.ts.map +1 -1
  49. package/dist/footage/pipeline.js +58 -10
  50. package/dist/footage/pipeline.js.map +1 -1
  51. package/dist/footage/probe.d.ts +10 -0
  52. package/dist/footage/probe.d.ts.map +1 -1
  53. package/dist/footage/probe.js +10 -5
  54. package/dist/footage/probe.js.map +1 -1
  55. package/dist/footage/process.d.ts +2 -0
  56. package/dist/footage/process.d.ts.map +1 -1
  57. package/dist/footage/process.js +1 -0
  58. package/dist/footage/process.js.map +1 -1
  59. package/dist/footage/providers.d.ts +12 -3
  60. package/dist/footage/providers.d.ts.map +1 -1
  61. package/dist/footage/providers.js.map +1 -1
  62. package/dist/footage/render.d.ts +1 -1
  63. package/dist/footage/render.d.ts.map +1 -1
  64. package/dist/footage/render.js +5 -3
  65. package/dist/footage/render.js.map +1 -1
  66. package/dist/footage/tools.d.ts +15 -3
  67. package/dist/footage/tools.d.ts.map +1 -1
  68. package/dist/footage/tools.js +15 -2
  69. package/dist/footage/tools.js.map +1 -1
  70. package/dist/index.d.ts +8 -4
  71. package/dist/index.d.ts.map +1 -1
  72. package/dist/index.js +8 -4
  73. package/dist/index.js.map +1 -1
  74. package/docker/footage-worker.Dockerfile +6 -0
  75. package/fonts/DejaVuSans-Bold-Latin.ttf +0 -0
  76. package/fonts/LICENSE-DejaVu.txt +46 -0
  77. package/fonts/README.md +12 -0
  78. package/package.json +2 -1
  79. package/schema/marketing.schema.json +7 -0
  80. package/src/config/config.ts +8 -0
  81. package/src/config/schema.ts +11 -0
  82. package/src/footage/audio.ts +136 -0
  83. package/src/footage/captions.ts +39 -2
  84. package/src/footage/compose.ts +4 -5
  85. package/src/footage/disk.ts +75 -0
  86. package/src/footage/draft.ts +366 -0
  87. package/src/footage/elevenlabs.ts +1 -0
  88. package/src/footage/film.ts +16 -1
  89. package/src/footage/keyterms.ts +38 -0
  90. package/src/footage/normalize.ts +47 -10
  91. package/src/footage/paid.ts +12 -3
  92. package/src/footage/pipeline.ts +67 -13
  93. package/src/footage/probe.ts +10 -5
  94. package/src/footage/process.ts +3 -0
  95. package/src/footage/providers.ts +10 -3
  96. package/src/footage/render.ts +5 -3
  97. package/src/footage/tools.ts +23 -3
  98. package/src/index.ts +46 -2
@@ -10,15 +10,18 @@ import { getHyperframesBin, getHyperframesEnv } from "../render/hyperframes.js";
10
10
  import { copyFonts } from "../render/render.js";
11
11
  import { err, ok, type TtsResult } from "../voice/provider.js";
12
12
  import type { TimedWord } from "../voice/voiceover.js";
13
+ import { checkMusicFileType, describeAudioProbe, probeAudio } from "./audio.js";
13
14
  import { readCachedTranscript, writeCacheFile, writeTranscript } from "./cache.js";
14
15
  import { composeFootage, END_CARD_SECONDS, getFootageFilmSeconds } from "./compose.js";
15
- import { findMissingCaptionGlyphs, getCaptionPresetLayout } from "./captions.js";
16
+ import { findMissingCaptionGlyphs, getFootageCaptionLayout } from "./captions.js";
17
+ import { findLowDiskProblems, getFreeBytes, getRenderTempDir, type FreeBytesReader } from "./disk.js";
16
18
  import { buildEdl, readEdl, remapWords, validateEdl, type Edl } from "./edl.js";
17
19
  import { makePlaceholderTranscript } from "./fake.js";
18
- import { getFootageEdit, type FootageClip, type FootageFilm } from "./film.js";
20
+ import { getFootageEdit, type FootageClip, type FootageFilm, type MusicSource } from "./film.js";
21
+ import { getFilmKeyTerms } from "./keyterms.js";
19
22
  import { DEFAULT_LOUDNESS, normalizeLoudness } from "./loudness.js";
20
23
  import { duckingKeyframes } from "./music.js";
21
- import { normalizeFootage, type Frame } from "./normalize.js";
24
+ import { normalizeFootage, type Frame, type NormalizeEncoder } from "./normalize.js";
22
25
  import { describeProbe, getTrimmedDuration, probeFootage, type FootageProbe } from "./probe.js";
23
26
  import {
24
27
  getClipCacheKey,
@@ -71,7 +74,7 @@ export { getEdlPath } from "./paid.js";
71
74
 
72
75
  const require = createRequire(import.meta.url);
73
76
  /** Bumped when the normalized format changes, so older normalized clips are made again. */
74
- const NORMALIZE_VERSION = 1;
77
+ const NORMALIZE_VERSION = 2;
75
78
 
76
79
  export interface FootageBrand {
77
80
  name: string;
@@ -99,6 +102,11 @@ export interface FootageRunOptions {
99
102
  onProgress?: (progress: FootageProgress) => void;
100
103
  /** Called after each paid call, for the app's own spend ledger. */
101
104
  onCharge?: (charge: FootageCharge) => void;
105
+ /**
106
+ * How the normalized clips are encoded (`preset`, `threads`): a small worker trades file size for speed. Not part of
107
+ * the normalize stamp, so changing it does not normalize clips already made again.
108
+ */
109
+ normalize?: NormalizeEncoder;
102
110
  }
103
111
 
104
112
  export interface PreparedClip {
@@ -174,10 +182,10 @@ function getNormalizeStamp(clip: FootageClip, source: string, frame: Frame): str
174
182
  return JSON.stringify({ version: NORMALIZE_VERSION, source: resolve(source), size: stat.size, mtime: stat.mtimeMs, trim: clip.trim, fit: clip.fit, frame });
175
183
  }
176
184
 
177
- /** Downloads URL clips, probes every clip (all problems at once), normalizes each one that changed. */
185
+ /** Downloads URL clips, probes every clip (all problems at once) and a local music file, normalizes each clip that changed. */
178
186
  export async function prepareFootage(
179
187
  film: FootageFilm,
180
- options: Pick<FootageRunOptions, "buildDir" | "log" | "fetch" | "signal" | "onProgress">,
188
+ options: Pick<FootageRunOptions, "buildDir" | "log" | "fetch" | "signal" | "onProgress" | "normalize">,
181
189
  ): Promise<FootageResult<PreparedClip[]>> {
182
190
  const { buildDir, log, signal } = options;
183
191
  if (film.clips.length === 0) return err(`footage film ${film.id} has no clips.`);
@@ -194,6 +202,10 @@ export async function prepareFootage(
194
202
  }
195
203
  const probed = await probeFootage(film.clips, sources, signal === undefined ? {} : { signal });
196
204
  if (!probed.ok) return err(probed.errors.join("\n"));
205
+ if (film.music.source.kind === "file") {
206
+ const music = await checkMusicFile(film.music.source, options);
207
+ if (!music.ok) return err(music.error);
208
+ }
197
209
  const frame = getFrame(film);
198
210
  const clipsDir = join(buildDir, "clips");
199
211
  mkdirSync(clipsDir, { recursive: true });
@@ -214,7 +226,7 @@ export async function prepareFootage(
214
226
  // The stamp goes first, so a normalize stopped half-way never leaves a stamp that vouches for a partial clip.
215
227
  rmSync(stampPath, { force: true });
216
228
  await normalizeFootage(
217
- { clip: clip.clip, file: clip.source, probe: clip.probe, frame, output: clip.file },
229
+ { clip: clip.clip, file: clip.source, probe: clip.probe, frame, output: clip.file, ...(options.normalize === undefined ? {} : { encoder: options.normalize }) },
218
230
  { ...(signal === undefined ? {} : { signal }), onSeconds: (seconds) => progress(index, seconds) },
219
231
  );
220
232
  writeFileSync(stampPath, stamp);
@@ -263,6 +275,9 @@ export function getMusicPaidStep(film: FootageFilm, options: Pick<FootageRunOpti
263
275
  export async function transcribeFootage(film: FootageFilm, clips: PreparedClip[], options: FootageRunOptions): Promise<FootageResult<TranscribeOutcome>> {
264
276
  const { buildDir, providers, log, signal } = options;
265
277
  if (options.isPlaceholder) return ok(transcribePlaceholder(film, clips, buildDir));
278
+ const keyTerms = getFilmKeyTerms(film);
279
+ if (!keyTerms.ok) return err(`footage film ${film.id}: ${keyTerms.errors.join(" ")}`);
280
+ const sttKeyTerms = keyTerms.terms.length === 0 ? {} : { keyTerms: keyTerms.terms };
266
281
  const plan: { clip: PreparedClip; isolated: CacheEntry | null; transcript: CacheEntry }[] = [];
267
282
  const steps: PaidStep[] = [];
268
283
  for (const clip of clips) {
@@ -336,12 +351,12 @@ export async function transcribeFootage(film: FootageFilm, clips: PreparedClip[]
336
351
  const input = sttInput ?? (await getAudio());
337
352
  throwIfAborted(signal);
338
353
  log(`speech to text (${providers.stt.id}): clip ${id}, ${clip.duration.toFixed(1)} s.`);
339
- const result = await providers.stt.transcribe({ audio: input, language: film.language, ...(signal === undefined ? {} : { signal }) });
354
+ const result = await providers.stt.transcribe({ audio: input, language: film.language, ...sttKeyTerms, ...(signal === undefined ? {} : { signal }) });
340
355
  throwIfAborted(signal);
341
356
  if (!result.ok) return err(`clip "${id}": ${result.error}`);
342
357
  writeTranscript(transcript.path, result.value.words);
343
358
  const { credits } = result.value;
344
- options.onCharge?.({ step: "transcribe", item: id, provider: providers.stt.id, units: clip.duration, ...(credits === undefined ? {} : { credits }), cacheKey: transcript.key });
359
+ options.onCharge?.({ step: "transcribe", item: id, provider: providers.stt.id, units: clip.duration, ...(credits === undefined ? {} : { credits }), ...(keyTerms.terms.length === 0 ? {} : { keyTerms: keyTerms.terms.length }), cacheKey: transcript.key });
345
360
  log(`transcript: clip ${id}, ${result.value.words.length} words, saved ${transcript.path} (commit it).`);
346
361
  transcribeProgress(index, clip.duration);
347
362
  words[id] = result.value.words;
@@ -382,6 +397,27 @@ export function readEdlFile(film: FootageFilm, clips: PreparedClip[], edlPath: s
382
397
  return problems.length > 0 ? err(`${edlPath}: ${problems.join("; ")}`) : ok(read.edl);
383
398
  }
384
399
 
400
+ /**
401
+ * A local music file checked like an app's upload: an accepted type, then readable audio (`probeAudio`). The type comes
402
+ * from the source's declared name (else the path) and content type; with no extension and no content type (a storage
403
+ * key) the type check is skipped and the probe alone decides.
404
+ */
405
+ async function checkMusicFile(source: Extract<MusicSource, { kind: "file" }>, options: Pick<FootageRunOptions, "log" | "signal">): Promise<FootageResult<string>> {
406
+ const { path, fileName, contentType } = source;
407
+ if (!existsSync(path)) return err(`music: no file at ${path}`);
408
+ const name = fileName ?? path;
409
+ if (extname(name) === "" && contentType === undefined) {
410
+ options.log(`music: ${path} has no extension and no declared name or content type; the probe checks it.`);
411
+ } else {
412
+ const type = checkMusicFileType(contentType === undefined ? { fileName: name } : { fileName: name, contentType });
413
+ if (!type.ok) return err(`music: ${type.error}`);
414
+ }
415
+ const probe = await probeAudio(path, options.signal === undefined ? {} : { signal: options.signal });
416
+ if (!probe.ok) return err(`music: ${probe.error}`);
417
+ options.log(`music: ${path} (${describeAudioProbe(probe.probe)}).`);
418
+ return ok(path);
419
+ }
420
+
385
421
  /**
386
422
  * The music file for the cut: a local file as it is, generated music from the cache, or (with `isCommit`) bought
387
423
  * from the music provider and cached. Null when the film has none or the rehearsal skips generated music; a paid
@@ -443,11 +479,22 @@ export interface RenderFootageOptions extends FootageRunOptions {
443
479
  output: string;
444
480
  /** A project's override of the format's caption box (`marketing.json` `layout`). */
445
481
  layout?: LayoutOverride;
482
+ /**
483
+ * hyperframes' temp folder, passed to it as `TMPDIR` (created when missing): the clips' frames are extracted there,
484
+ * so it needs room (a data volume, not a small tmpfs). By default the `TMPDIR` the process already has.
485
+ */
486
+ tempDir?: string;
487
+ /** Reads a folder's free bytes for the disk check; injected in tests. */
488
+ readFreeBytes?: FreeBytesReader;
446
489
  }
447
490
 
448
491
  export type RenderedFootage = { kind: "dry-run"; steps: PaidStep[] } | ({ kind: "rendered"; output: string; seconds: number; edlPath: string } & FinishedFootage);
449
492
 
450
- /** Composes the cut and renders it: speech track (loudness-normalized), ducked music, end card backdrop, assets, hyperframes, final pass, cover. */
493
+ /**
494
+ * Composes the cut and renders it: speech track (loudness-normalized), ducked music, end card backdrop, assets,
495
+ * hyperframes, final pass, cover. First of all it checks that hyperframes' temp folder and the build folder have the
496
+ * 1 GiB free hyperframes requires, so a full disk ends the run with a sentence before anything is bought or built.
497
+ */
451
498
  export async function renderFootage(
452
499
  film: FootageFilm,
453
500
  clips: PreparedClip[],
@@ -456,6 +503,8 @@ export async function renderFootage(
456
503
  options: RenderFootageOptions,
457
504
  ): Promise<FootageResult<RenderedFootage>> {
458
505
  const { buildDir, log, signal } = options;
506
+ const lowDisk = findLowDiskProblems({ temp: getRenderTempDir(process.env, options.tempDir), build: buildDir }, options.readFreeBytes ?? getFreeBytes);
507
+ if (lowDisk.length > 0) return err(`not enough disk space to render: ${lowDisk.join(" ")}`);
459
508
  const seconds = getFootageFilmSeconds(film, edl);
460
509
  const words = remapWords(edl, transcript.words, film.cut.fillers);
461
510
  const music = await getMusic(film, edl, clips, seconds, options);
@@ -519,8 +568,7 @@ export async function renderFootage(
519
568
  cpSync(require.resolve("gsap/dist/gsap.min.js"), join(assetsDir, "gsap.min.js"));
520
569
  const base = resolveLayout(film.format, options.layout ?? {});
521
570
  // A caption preset places the 9:16 box in a platform's safe zone; the project's own caption override still wins.
522
- const preset = film.captionPreset === undefined || film.format !== "9:16" ? null : getCaptionPresetLayout(film.captionPreset, base.caption.fontSize);
523
- const layout = preset === null || options.layout?.caption !== undefined ? base : { ...base, caption: preset };
571
+ const layout = { ...base, caption: getFootageCaptionLayout(film, options.layout ?? {}) };
524
572
  const missing = findMissingCaptionGlyphs({
525
573
  fonts: options.brand.fonts,
526
574
  captions: film.captions ? words.map((word) => word.text) : [],
@@ -638,11 +686,17 @@ async function runHyperframesRender(options: RenderFootageOptions, output: strin
638
686
  options.log(line.trim());
639
687
  }
640
688
  };
689
+ const env = getHyperframesEnv();
690
+ if (options.tempDir !== undefined && options.tempDir.length > 0) {
691
+ const tempDir = resolve(options.tempDir);
692
+ mkdirSync(tempDir, { recursive: true });
693
+ env.TMPDIR = tempDir;
694
+ }
641
695
  const result = await runProcess({
642
696
  command: process.execPath,
643
697
  args: [getHyperframesBin(), "render", "--quality", options.quality, "-o", output],
644
698
  cwd: options.buildDir,
645
- env: getHyperframesEnv(),
699
+ env,
646
700
  ...(options.signal === undefined ? {} : { signal: options.signal }),
647
701
  removeOnAbort: [output],
648
702
  onStdoutLine: onLine,
@@ -101,18 +101,23 @@ export function readFootageProbe(json: unknown): ProbeResult {
101
101
  };
102
102
  }
103
103
 
104
- /** Runs ffprobe on one file (or URL) without blocking; an error names the file and the reason. Rejects only on abort. */
105
- export async function probeFile(path: string, options: { signal?: AbortSignal } = {}): Promise<ProbeResult> {
104
+ /** Runs ffprobe (`-show_streams -show_format -of json`) on one file or URL and parses its JSON; an error names the file. Rejects only on abort. */
105
+ export async function runFfprobe(path: string, options: { signal?: AbortSignal } = {}): Promise<{ ok: true; json: unknown } | { ok: false; error: string }> {
106
106
  const result = await runProcess({ command: "ffprobe", args: ["-v", "error", "-show_streams", "-show_format", "-of", "json", path], ...options });
107
107
  if (result.kind === "not-started") return { ok: false, error: `ffprobe did not start for ${path}: ${result.error}` };
108
108
  if (result.code !== 0) return { ok: false, error: `ffprobe cannot read ${path}: ${result.stderr.trim() || `code ${String(result.code)}`}` };
109
- let json: unknown;
110
109
  try {
111
- json = JSON.parse(result.stdout);
110
+ return { ok: true, json: JSON.parse(result.stdout) as unknown };
112
111
  } catch (error) {
113
112
  return { ok: false, error: `ffprobe printed no JSON for ${path}: ${String(error)}` };
114
113
  }
115
- const read = readFootageProbe(json);
114
+ }
115
+
116
+ /** Runs ffprobe on one file (or URL) without blocking; an error names the file and the reason. Rejects only on abort. */
117
+ export async function probeFile(path: string, options: { signal?: AbortSignal } = {}): Promise<ProbeResult> {
118
+ const output = await runFfprobe(path, options);
119
+ if (!output.ok) return output;
120
+ const read = readFootageProbe(output.json);
116
121
  return read.ok ? read : { ok: false, error: `${path}: ${read.error}` };
117
122
  }
118
123
 
@@ -109,6 +109,8 @@ export interface FfmpegRunOptions {
109
109
  output?: string;
110
110
  /** Seconds of output written so far, as ffmpeg reports them. */
111
111
  onSeconds?: (seconds: number) => void;
112
+ /** The folder ffmpeg runs in, so relative names in the arguments and the filter graph resolve there. */
113
+ cwd?: string;
112
114
  }
113
115
 
114
116
  /** Runs ffmpeg with its progress on stdout; throws naming the step when it fails (a broken input or machine). */
@@ -118,6 +120,7 @@ export async function runFfmpeg(step: string, args: string[], options: FfmpegRun
118
120
  command: "ffmpeg",
119
121
  args: ["-progress", "pipe:1", "-nostats", ...args],
120
122
  ...(options.signal === undefined ? {} : { signal: options.signal }),
123
+ ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
121
124
  removeOnAbort: options.output === undefined ? [] : [options.output],
122
125
  onStdoutLine: (line) => {
123
126
  const seconds = readFfmpegProgressSeconds(line);
@@ -11,6 +11,8 @@ export interface SttInput {
11
11
  audio: string;
12
12
  /** ISO 639 code the speech is in. */
13
13
  language: string;
14
+ /** Key terms the transcript should spell as given (normalized by `normalizeKeyTerms`); absent: none. */
15
+ keyTerms?: string[];
14
16
  /** Aborts the request. */
15
17
  signal?: AbortSignal;
16
18
  }
@@ -87,8 +89,11 @@ export function describePaidSteps(steps: PaidStep[]): string[] {
87
89
  return lines;
88
90
  }
89
91
 
90
- /** Credits per second billed, for each paid step; the caller's prices (the kit hard-codes none). */
91
- export type FootageRates = Record<PaidStepKind, number>;
92
+ /**
93
+ * Credits per second billed, for each paid step; the caller's prices (the kit hard-codes none). `keyTerms` is the
94
+ * surcharge per second of speech to text with key terms (keyterm prompting), added to `transcribe`; absent: 0.
95
+ */
96
+ export type FootageRates = Record<PaidStepKind, number> & { keyTerms?: number };
92
97
 
93
98
  /** One paid call made, as `onCharge` reports it: what for, how much was billed and where its result is cached. */
94
99
  export interface FootageCharge {
@@ -100,12 +105,14 @@ export interface FootageCharge {
100
105
  units: number;
101
106
  /** The provider's reported charge, when its API returns one. */
102
107
  credits?: number;
108
+ /** How many key terms a speech to text call sent (billed with keyterm prompting's surcharge); absent: none. */
109
+ keyTerms?: number;
103
110
  /** The paid cache's key of the result (the file name's first part under `<cacheDir>/<film id>/`). */
104
111
  cacheKey: string;
105
112
  }
106
113
 
107
114
  /** A stage of a footage run that reports progress. */
108
- export type FootageStage = "normalize" | PaidStepKind | "assets" | "render" | "finish";
115
+ export type FootageStage = "normalize" | PaidStepKind | "assets" | "render" | "finish" | "draft";
109
116
 
110
117
  /**
111
118
  * Progress of a footage run. `done` and `total` are seconds of media across the whole stage (a bar per stage);
@@ -61,15 +61,17 @@ export function buildMusicArgs(options: { input: string; seconds: number; keyfra
61
61
  return ["-v", "error", "-y", "-stream_loop", "-1", "-i", options.input, "-t", String(seconds), "-af", filters.join(","), "-c:a", "libmp3lame", "-q:a", "2", options.output];
62
62
  }
63
63
 
64
- /** A small silent copy of the cut, what Video to Music scores. */
64
+ /** A small silent copy of the cut, what Video to Music scores: each segment read from its own seek into its clip. */
65
65
  export function buildCutPreviewArgs(edl: Edl, clips: Record<string, string>, output: string): string[] {
66
66
  const inputs: string[] = [];
67
67
  const parts: string[] = [];
68
68
  edl.segments.forEach((segment, index) => {
69
69
  const clip = clips[segment.clip];
70
70
  if (clip === undefined) throw new Error(`No file for clip "${segment.clip}" of the EDL.`);
71
- inputs.push("-i", clip);
72
- parts.push(`[${index}:v]trim=start=${segment.start}:end=${segment.end},setpts=PTS-STARTPTS,scale=540:-2,setsar=1[v${index}]`);
71
+ // Seeking the input (accurate while transcoding; normalized clips have a keyframe every half second) instead of
72
+ // trim, which decodes the clip from its start for every segment.
73
+ inputs.push("-ss", String(r3(segment.start)), "-t", String(r3(segment.end - segment.start)), "-i", clip);
74
+ parts.push(`[${index}:v]setpts=PTS-STARTPTS,scale=540:-2,setsar=1[v${index}]`);
73
75
  });
74
76
  const joined = edl.segments.map((_, index) => `[v${index}]`).join("");
75
77
  const graph = `${parts.join(";")};${joined}concat=n=${edl.segments.length}:v=1:a=0[cut]`;
@@ -3,6 +3,7 @@ import { homedir } from "node:os";
3
3
  import { join } from "node:path";
4
4
 
5
5
  import { getHyperframesBin, getHyperframesEnv, HYPERFRAMES_VERSION } from "../render/hyperframes.js";
6
+ import { findLowDiskProblems, getFreeBytes, getRenderTempDir, type FreeBytesReader } from "./disk.js";
6
7
  import { runProcess } from "./process.js";
7
8
 
8
9
  /**
@@ -18,15 +19,26 @@ export interface FootageToolsOptions {
18
19
  * worker image ships the browser, so the default is false.
19
20
  */
20
21
  isBrowserDownloadAllowed?: boolean;
21
- /** The environment the run sees (`HYPERFRAMES_BROWSER_PATH`, `PRODUCER_HEADLESS_SHELL_PATH`, `HOME`). */
22
+ /** Check the filters the fast draft draws with (`renderFootageDraft`): `ass` (libass and libfreetype), `xfade`, `zoompan`. */
23
+ needsDraft?: boolean;
24
+ /** The environment the run sees (`HYPERFRAMES_BROWSER_PATH`, `PRODUCER_HEADLESS_SHELL_PATH`, `HOME`, `TMPDIR`). */
22
25
  env?: NodeJS.ProcessEnv;
26
+ /** The render's temp folder, as passed to `renderFootage`; by default `TMPDIR` of `env`, else `os.tmpdir()`. */
27
+ tempDir?: string;
28
+ /** The film's build folder, where hyperframes writes its render; checked for free space when given. */
29
+ buildDir?: string;
23
30
  signal?: AbortSignal;
31
+ /** Reads a folder's free bytes; injected in tests. */
32
+ readFreeBytes?: FreeBytesReader;
24
33
  }
25
34
 
26
35
  /** What the footage blocks need from ffmpeg: decoders and filters, by the name ffmpeg lists them under. */
27
36
  export const REQUIRED_DECODERS = ["hevc", "h264"] as const;
28
37
  export const REQUIRED_FILTERS = ["zscale", "tonemap"] as const;
38
+ /** What the fast draft needs on top: libass (with libfreetype) for the captions, `xfade` for fades, `zoompan` for Ken Burns. */
39
+ export const DRAFT_FILTERS = ["ass", "xfade", "zoompan"] as const;
29
40
 
41
+ const DRAFT_INSTALL_HINT = "install an ffmpeg built with libass and libfreetype (macOS: brew install ffmpeg, Debian/Ubuntu: apt install ffmpeg)";
30
42
  const INSTALL_HINT = "install an ffmpeg built with libzimg (macOS: brew install ffmpeg, Debian/Ubuntu: apt install ffmpeg)";
31
43
 
32
44
  /** The names in `ffmpeg -decoders` or `-filters` output: the second column of each listing line. */
@@ -83,8 +95,9 @@ export function findBrowserProblem(env: NodeJS.ProcessEnv): string | null {
83
95
 
84
96
  /**
85
97
  * Checks the machine for a footage run: ffmpeg and ffprobe run, ffmpeg decodes HEVC and H.264 and has `zscale` and
86
- * `tonemap` (HDR clips), and, for a render, hyperframes runs and has its browser. Returns every problem found; an
87
- * empty list means the machine is ready.
98
+ * `tonemap` (HDR clips), for a draft (`needsDraft`) `ass`, `xfade` and `zoompan`, and, for a render, hyperframes runs
99
+ * and has its browser, and its temp folder (and the build folder, when given) has the 1 GiB free hyperframes requires.
100
+ * Returns every problem found; an empty list means the machine is ready.
88
101
  */
89
102
  export async function checkFootageTools(options: FootageToolsOptions = {}): Promise<string[]> {
90
103
  const { signal } = options;
@@ -100,6 +113,11 @@ export async function checkFootageTools(options: FootageToolsOptions = {}): Prom
100
113
  for (const filter of REQUIRED_FILTERS) {
101
114
  if (filters?.has(filter) !== true) problems.push(`ffmpeg has no ${filter} filter (HDR clips need it): ${INSTALL_HINT}.`);
102
115
  }
116
+ if (options.needsDraft === true) {
117
+ for (const filter of DRAFT_FILTERS) {
118
+ if (filters?.has(filter) !== true) problems.push(`ffmpeg has no ${filter} filter (the draft needs it): ${DRAFT_INSTALL_HINT}.`);
119
+ }
120
+ }
103
121
  }
104
122
  if (!(await isRunnable("ffprobe", ["-version"], aborting))) problems.push(`no ffprobe in PATH: it comes with ffmpeg; ${INSTALL_HINT}.`);
105
123
  if (options.needsRender === false) return problems;
@@ -115,5 +133,7 @@ export async function checkFootageTools(options: FootageToolsOptions = {}): Prom
115
133
  const browser = findBrowserProblem(env);
116
134
  if (browser !== null) problems.push(browser);
117
135
  }
136
+ const temp = getRenderTempDir(env, options.tempDir);
137
+ problems.push(...findLowDiskProblems(options.buildDir === undefined ? { temp } : { temp, build: options.buildDir }, options.readFreeBytes ?? getFreeBytes));
118
138
  return problems;
119
139
  }
package/src/index.ts CHANGED
@@ -208,12 +208,37 @@ export {
208
208
  probeFile,
209
209
  probeFootage,
210
210
  readFootageProbe,
211
+ runFfprobe,
211
212
  type FootageProbe,
212
213
  type HdrKind,
213
214
  type ProbeResult,
214
215
  type ProbedClip,
215
216
  } from "./footage/probe.js";
216
- export { FOOTAGE_FPS, FOOTAGE_SAMPLE_RATE, buildNormalizeArgs, buildVideoFilter, normalizeFootage, resolveFit, toneMapFilter, type Frame, type NormalizeInput } from "./footage/normalize.js";
217
+ export {
218
+ MUSIC_FILE_TYPES,
219
+ checkMusicFileType,
220
+ describeAudioProbe,
221
+ probeAudio,
222
+ readAudioProbe,
223
+ type AudioProbe,
224
+ type AudioProbeFailure,
225
+ type AudioProbeResult,
226
+ type MusicFileTypeCheck,
227
+ } from "./footage/audio.js";
228
+ export {
229
+ FOOTAGE_FPS,
230
+ FOOTAGE_SAMPLE_RATE,
231
+ X264_PRESETS,
232
+ buildNormalizeArgs,
233
+ buildVideoFilter,
234
+ normalizeFootage,
235
+ resolveFit,
236
+ toneMapFilter,
237
+ type Frame,
238
+ type NormalizeEncoder,
239
+ type NormalizeInput,
240
+ type X264Preset,
241
+ } from "./footage/normalize.js";
217
242
  export {
218
243
  describePaidSteps,
219
244
  toPaidAudio,
@@ -253,6 +278,7 @@ export {
253
278
  type FakeSttOptions,
254
279
  type FakeSttProvider,
255
280
  } from "./footage/fake.js";
281
+ export { SCRIBE_KEYTERM_LIMITS, getFilmKeyTerms, normalizeKeyTerms, type KeyTermsResult } from "./footage/keyterms.js";
256
282
  export { footageCacheKey, getFootageCachePath, hashFile, readCachedTranscript, type FootageCacheKind } from "./footage/cache.js";
257
283
  export {
258
284
  MIN_SEGMENT_SECONDS,
@@ -282,7 +308,10 @@ export {
282
308
  CAPTION_SAFE_ZONES,
283
309
  findMissingCaptionGlyphs,
284
310
  getCaptionPresetLayout,
311
+ getCaptionSpans,
312
+ getFootageCaptionLayout,
285
313
  phraseChunks,
314
+ type CaptionSpan,
286
315
  type MissingCaptionGlyphs,
287
316
  type PhraseChunk,
288
317
  type SafeZone,
@@ -291,6 +320,20 @@ export { MAX_FRAMES, buildFrameArgs, extractFrames, getFrameTimes, type ExtractF
291
320
  export { duckingKeyframes, getSpeechSpans, volumeExpression, type DuckingOptions, type VolumeKeyframe } from "./footage/music.js";
292
321
  export { END_CARD_SECONDS, FADE_SECONDS, composeFootage, getFootageFilmSeconds, getSegmentScales, type FootageComposeAssets, type FootageComposeInput } from "./footage/compose.js";
293
322
  export { buildCutPreviewArgs, buildLastFrameArgs, buildMusicArgs, buildSpeechArgs } from "./footage/render.js";
323
+ export {
324
+ FOOTAGE_DRAFT_FONT,
325
+ FOOTAGE_DRAFT_WIDTH,
326
+ buildFootageDraftArgs,
327
+ buildFootageDraftCaptions,
328
+ getFootageDraftFrame,
329
+ planFootageDraft,
330
+ renderFootageDraft,
331
+ type DraftSegmentPlan,
332
+ type FootageDraft,
333
+ type FootageDraftArgsInput,
334
+ type FootageDraftCaptionsInput,
335
+ type RenderFootageDraftOptions,
336
+ } from "./footage/draft.js";
294
337
  export {
295
338
  DEFAULT_LOUDNESS,
296
339
  buildLoudnessArgs,
@@ -327,7 +370,8 @@ export {
327
370
  type FootageEstimate,
328
371
  type FootageEstimateItem,
329
372
  } from "./footage/paid.js";
330
- export { REQUIRED_DECODERS, REQUIRED_FILTERS, checkFootageTools, findBrowserProblem, readFfmpegListing, type FootageToolsOptions } from "./footage/tools.js";
373
+ export { RENDER_MIN_FREE_BYTES, findLowDiskProblems, getFreeBytes, getRenderTempDir, type FreeBytesReader } from "./footage/disk.js";
374
+ export { DRAFT_FILTERS, REQUIRED_DECODERS, REQUIRED_FILTERS, checkFootageTools, findBrowserProblem, readFfmpegListing, type FootageToolsOptions } from "./footage/tools.js";
331
375
  export {
332
376
  cutFootage,
333
377
  getEdlPath,