@softure-ai/marketing-kit 0.15.0 → 0.16.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 (108) hide show
  1. package/CHANGELOG.md +66 -0
  2. package/README.md +119 -16
  3. package/dist/config/schema.d.ts +2 -1
  4. package/dist/config/schema.d.ts.map +1 -1
  5. package/dist/config/schema.js +7 -0
  6. package/dist/config/schema.js.map +1 -1
  7. package/dist/footage/clip-sound.d.ts +58 -0
  8. package/dist/footage/clip-sound.d.ts.map +1 -0
  9. package/dist/footage/clip-sound.js +103 -0
  10. package/dist/footage/clip-sound.js.map +1 -0
  11. package/dist/footage/declick.d.ts +1 -1
  12. package/dist/footage/declick.d.ts.map +1 -1
  13. package/dist/footage/declick.js +3 -4
  14. package/dist/footage/declick.js.map +1 -1
  15. package/dist/footage/draft.d.ts +19 -5
  16. package/dist/footage/draft.d.ts.map +1 -1
  17. package/dist/footage/draft.js +92 -22
  18. package/dist/footage/draft.js.map +1 -1
  19. package/dist/footage/elevenlabs.d.ts +5 -0
  20. package/dist/footage/elevenlabs.d.ts.map +1 -1
  21. package/dist/footage/elevenlabs.js +10 -3
  22. package/dist/footage/elevenlabs.js.map +1 -1
  23. package/dist/footage/failure.d.ts +12 -1
  24. package/dist/footage/failure.d.ts.map +1 -1
  25. package/dist/footage/failure.js +10 -1
  26. package/dist/footage/failure.js.map +1 -1
  27. package/dist/footage/fake.d.ts +10 -1
  28. package/dist/footage/fake.d.ts.map +1 -1
  29. package/dist/footage/fake.js +19 -4
  30. package/dist/footage/fake.js.map +1 -1
  31. package/dist/footage/hyperframes-capture.d.ts +30 -0
  32. package/dist/footage/hyperframes-capture.d.ts.map +1 -0
  33. package/dist/footage/hyperframes-capture.js +80 -0
  34. package/dist/footage/hyperframes-capture.js.map +1 -0
  35. package/dist/footage/isolate-ranges.d.ts +25 -6
  36. package/dist/footage/isolate-ranges.d.ts.map +1 -1
  37. package/dist/footage/isolate-ranges.js +37 -16
  38. package/dist/footage/isolate-ranges.js.map +1 -1
  39. package/dist/footage/loudness.d.ts +16 -2
  40. package/dist/footage/loudness.d.ts.map +1 -1
  41. package/dist/footage/loudness.js +10 -7
  42. package/dist/footage/loudness.js.map +1 -1
  43. package/dist/footage/paid.d.ts +12 -2
  44. package/dist/footage/paid.d.ts.map +1 -1
  45. package/dist/footage/paid.js +8 -3
  46. package/dist/footage/paid.js.map +1 -1
  47. package/dist/footage/pipeline.d.ts +8 -2
  48. package/dist/footage/pipeline.d.ts.map +1 -1
  49. package/dist/footage/pipeline.js +54 -45
  50. package/dist/footage/pipeline.js.map +1 -1
  51. package/dist/footage/providers.d.ts +5 -0
  52. package/dist/footage/providers.d.ts.map +1 -1
  53. package/dist/footage/providers.js.map +1 -1
  54. package/dist/footage/render.d.ts +1 -1
  55. package/dist/footage/render.d.ts.map +1 -1
  56. package/dist/footage/render.js +4 -3
  57. package/dist/footage/render.js.map +1 -1
  58. package/dist/footage/speech-ranges.d.ts +51 -10
  59. package/dist/footage/speech-ranges.d.ts.map +1 -1
  60. package/dist/footage/speech-ranges.js +90 -15
  61. package/dist/footage/speech-ranges.js.map +1 -1
  62. package/dist/index.d.ts +9 -6
  63. package/dist/index.d.ts.map +1 -1
  64. package/dist/index.js +8 -5
  65. package/dist/index.js.map +1 -1
  66. package/dist/og/index.d.ts +2 -0
  67. package/dist/og/index.d.ts.map +1 -1
  68. package/dist/og/index.js +2 -0
  69. package/dist/og/index.js.map +1 -1
  70. package/dist/og/photo-cover.d.ts +55 -0
  71. package/dist/og/photo-cover.d.ts.map +1 -0
  72. package/dist/og/photo-cover.js +215 -0
  73. package/dist/og/photo-cover.js.map +1 -0
  74. package/dist/og/photo.d.ts +51 -0
  75. package/dist/og/photo.d.ts.map +1 -0
  76. package/dist/og/photo.js +154 -0
  77. package/dist/og/photo.js.map +1 -0
  78. package/dist/voice/provider-failure.d.ts +41 -0
  79. package/dist/voice/provider-failure.d.ts.map +1 -0
  80. package/dist/voice/provider-failure.js +68 -0
  81. package/dist/voice/provider-failure.js.map +1 -0
  82. package/dist/voice/provider.d.ts +7 -1
  83. package/dist/voice/provider.d.ts.map +1 -1
  84. package/dist/voice/provider.js +1 -1
  85. package/dist/voice/provider.js.map +1 -1
  86. package/package.json +2 -1
  87. package/schema/marketing.schema.json +6 -0
  88. package/src/config/schema.ts +7 -0
  89. package/src/footage/clip-sound.ts +124 -0
  90. package/src/footage/declick.ts +3 -4
  91. package/src/footage/draft.ts +123 -22
  92. package/src/footage/elevenlabs.ts +11 -3
  93. package/src/footage/failure.ts +14 -1
  94. package/src/footage/fake.ts +28 -4
  95. package/src/footage/hyperframes-capture.ts +100 -0
  96. package/src/footage/isolate-ranges.ts +62 -22
  97. package/src/footage/loudness.ts +17 -8
  98. package/src/footage/paid.ts +25 -3
  99. package/src/footage/pipeline.ts +61 -46
  100. package/src/footage/providers.ts +5 -0
  101. package/src/footage/render.ts +4 -3
  102. package/src/footage/speech-ranges.ts +129 -16
  103. package/src/index.ts +41 -1
  104. package/src/og/index.ts +23 -0
  105. package/src/og/photo-cover.ts +280 -0
  106. package/src/og/photo.ts +177 -0
  107. package/src/voice/provider-failure.ts +98 -0
  108. package/src/voice/provider.ts +7 -2
@@ -1,4 +1,4 @@
1
- import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
1
+ import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
2
2
  import { createRequire } from "node:module";
3
3
  import { dirname, extname, join, resolve } from "node:path";
4
4
 
@@ -7,14 +7,16 @@ import type { BrandColors } from "../config/colors.js";
7
7
  import type { BrandFont } from "../config/config.js";
8
8
  import type { SfxEvent } from "../config/schema.js";
9
9
  import { getHyperframesBin, getHyperframesEnv } from "../render/hyperframes.js";
10
+ import { readHyperframesCapture, type HyperframesCapture } from "./hyperframes-capture.js";
10
11
  import { copyFonts } from "../render/render.js";
11
12
  import type { TtsResult } from "../voice/provider.js";
12
13
  import type { TimedWord } from "../voice/voiceover.js";
13
14
  import { checkMusicFileType, describeAudioProbe, probeAudio } from "./audio.js";
15
+ import { prepareClipSounds } from "./clip-sound.js";
14
16
  import { readCachedTranscript, writeCacheFile, writeTranscript } from "./cache.js";
15
17
  import { composeFootage, END_CARD_SECONDS, getFootageFilmSeconds, getFootageSfxCues } from "./compose.js";
16
18
  import { findMissingCaptionGlyphs, getCaptionBounds, getFootageCaptionLayout } from "./captions.js";
17
- import { err, ok, type FootageResult } from "./failure.js";
19
+ import { err, getProviderFootageFailure, ok, type FootageResult } from "./failure.js";
18
20
  import { findLowDiskProblems, getFreeBytes, getRenderTempDir, type FreeBytesReader } from "./disk.js";
19
21
  import { buildEdl, getEdlDuration, readEdl, remapWords, validateEdl, type Edl } from "./edl.js";
20
22
  import { makePlaceholderTranscript } from "./fake.js";
@@ -24,6 +26,7 @@ import { DEFAULT_AUTO_THRESHOLD, getDeclickLevel, getFootageEdit, type FootageCl
24
26
  import { getFilmKeyTerms } from "./keyterms.js";
25
27
  import { buildFilmMixArgs } from "./film-mix.js";
26
28
  import {
29
+ AUDIO_BITRATE_RANGE_KBPS,
27
30
  buildMixArgs,
28
31
  DEFAULT_LOUDNESS,
29
32
  formatDb,
@@ -85,7 +88,8 @@ export { getEdlPath } from "./paid.js";
85
88
  * (a transcript from each clip's `script`, no isolation, no generated music) and keeps its files apart from the real
86
89
  * film's (`placeholder/` in the build folder, its own EDL).
87
90
  *
88
- * Build folder layout: `sources/` (downloaded URLs), `clips/<id>.mp4` (normalized), `audio/<id>.mp3`, `edl.json`
91
+ * Build folder layout: `sources/` (downloaded URLs), `clips/<id>.mp4` (normalized), `audio/<id>.wav` (the clip's
92
+ * lossless, pre-gained sound; `audio/<id>.isolated.wav` its cleaned voice), `edl.json`
89
93
  * (`edl.placeholder.json`), `assets/`, `index.html`, `render.mp4` (hyperframes' output until the final pass).
90
94
  *
91
95
  * The finished film is publishable: the speech track normalized to a loudness target before the music goes under it,
@@ -283,23 +287,28 @@ function getClipKey(clip: PreparedClip): Promise<string> {
283
287
  return getClipCacheKey(clip.source, clip.clip);
284
288
  }
285
289
 
286
- async function extractAudio(clip: PreparedClip, buildDir: string, signal: AbortSignal | undefined): Promise<string> {
287
- const audio = join(buildDir, "audio", `${clip.clip.id}.mp3`);
288
- mkdirSync(dirname(audio), { recursive: true });
289
- await runFfmpeg(`Extracting the sound of clip ${clip.clip.id}`, buildAudioArgs(clip.file, audio), { ...(signal === undefined ? {} : { signal }), output: audio });
290
- return audio;
290
+ /** The cached cleaned voice (the provider's file) decoded into the build folder as lossless WAV, named by the clip's id. */
291
+ async function decodeIsolatedVoice(cached: string, clipId: string, buildDir: string, signal: AbortSignal | undefined): Promise<string> {
292
+ const output = join(buildDir, "audio", `${clipId}.isolated.wav`);
293
+ mkdirSync(dirname(output), { recursive: true });
294
+ await runFfmpeg(`Decoding the cleaned voice of clip ${clipId}`, buildAudioArgs(cached, output), { ...(signal === undefined ? {} : { signal }), output });
295
+ return output;
291
296
  }
292
297
 
293
- /** The free transcripts of `--placeholder`, written under `placeholder/` for a look. */
294
- function transcribePlaceholder(film: FootageFilm, clips: PreparedClip[], buildDir: string): TranscribeOutcome {
298
+ /** Each clip's lossless, pre-gained sound (`prepareClipSounds`), by clip id. */
299
+ async function getClipSoundFiles(clips: PreparedClip[], buildDir: string, signal: AbortSignal | undefined): Promise<Record<string, string>> {
300
+ const sounds = await prepareClipSounds(clips, { buildDir, ...(signal === undefined ? {} : { signal }) });
301
+ return Object.fromEntries(Object.entries(sounds).map(([id, sound]) => [id, sound.file]));
302
+ }
303
+
304
+ /** The free transcripts of `--placeholder`, written under `placeholder/` for a look; the speech is each clip's lossless sound. */
305
+ async function transcribePlaceholder(clips: PreparedClip[], buildDir: string, signal: AbortSignal | undefined): Promise<TranscribeOutcome> {
295
306
  const words: Record<string, TimedWord[]> = {};
296
- const speech: Record<string, string> = {};
297
307
  for (const clip of clips) {
298
308
  words[clip.clip.id] = clip.clip.role === "talk" ? makePlaceholderTranscript(clip.clip.script, clip.duration) : [];
299
309
  writeTranscript(join(buildDir, "placeholder", `${clip.clip.id}.transcript.json`), words[clip.clip.id] ?? []);
300
- speech[clip.clip.id] = clip.file;
301
310
  }
302
- return { kind: "ready", words, speech };
311
+ return { kind: "ready", words, speech: await getClipSoundFiles(clips, buildDir, signal) };
303
312
  }
304
313
 
305
314
  /** The paid music step, when the film's music still has to be bought; null when it is cached or free. */
@@ -322,7 +331,7 @@ export function transcribeFootage(film: FootageFilm, clips: PreparedClip[], opti
322
331
  /** The body of `transcribeFootage`, inside its ffmpeg failure reporting. */
323
332
  async function runTranscribeFootage(film: FootageFilm, clips: PreparedClip[], options: FootageRunOptions): Promise<FootageResult<TranscribeOutcome>> {
324
333
  const { buildDir, providers, log, signal } = options;
325
- if (options.isPlaceholder) return ok(transcribePlaceholder(film, clips, buildDir));
334
+ if (options.isPlaceholder) return ok(await transcribePlaceholder(clips, buildDir, signal));
326
335
  const keyTerms = getFilmKeyTerms(film);
327
336
  if (!keyTerms.ok) return err(`footage film ${film.id}: ${keyTerms.errors.join(" ")}`, { kind: "input" });
328
337
  const sttKeyTerms = keyTerms.terms.length === 0 ? {} : { keyTerms: keyTerms.terms };
@@ -346,11 +355,9 @@ async function runTranscribeFootage(film: FootageFilm, clips: PreparedClip[], op
346
355
  return ok({ kind: "dry-run", steps: all });
347
356
  }
348
357
  const words: Record<string, TimedWord[]> = {};
349
- const speech: Record<string, string> = {};
350
- for (const clip of clips) {
351
- words[clip.clip.id] = [];
352
- speech[clip.clip.id] = clip.file;
353
- }
358
+ for (const clip of clips) words[clip.clip.id] = [];
359
+ // Every clip's sound, lossless and pre-gained: what the isolator, the speech to text and the speech track hear (#1139).
360
+ const speech = await getClipSoundFiles(clips, buildDir, signal);
354
361
  const isolating = plan.filter(({ isolated }) => isolated !== null && !existsSync(isolated.path));
355
362
  const transcribing = plan.filter(({ transcript }) => !existsSync(transcript.path));
356
363
  const isolateProgress = createStageProgress(options.onProgress, "isolate", isolating.map(({ clip }) => ({ item: clip.clip.id, seconds: clip.duration })));
@@ -358,27 +365,27 @@ async function runTranscribeFootage(film: FootageFilm, clips: PreparedClip[], op
358
365
  for (const entry of plan) {
359
366
  const { clip, isolated, transcript } = entry;
360
367
  const id = clip.clip.id;
361
- let audio: Promise<string> | null = null;
362
- const getAudio = (): Promise<string> => (audio ??= extractAudio(clip, buildDir, signal));
368
+ const sound = speech[id] ?? clip.file;
363
369
  let sttInput: string | null = null;
364
370
  if (isolated !== null) {
365
371
  if (!existsSync(isolated.path)) {
366
372
  const index = isolating.indexOf(entry);
367
373
  isolateProgress(index, 0);
368
- const input = await getAudio();
369
374
  throwIfAborted(signal);
370
375
  log(`voice isolation (${providers.isolation.id}): clip ${id}, ${clip.duration.toFixed(1)} s.`);
371
- const cleaned = await providers.isolation.isolate({ audio: input, ...(signal === undefined ? {} : { signal }) });
376
+ const cleaned = await providers.isolation.isolate({ audio: sound, ...(signal === undefined ? {} : { signal }) });
372
377
  throwIfAborted(signal);
373
- if (!cleaned.ok) return err(`clip "${id}": ${cleaned.error}`);
378
+ if (!cleaned.ok) return err(`clip "${id}": ${cleaned.error}`, getProviderFootageFailure(cleaned.providerFailure));
374
379
  const paid = toPaidAudio(cleaned.value);
375
380
  writeCacheFile(isolated.path, paid.audio);
376
381
  options.onCharge?.({ step: "isolate", item: id, provider: providers.isolation.id, units: clip.duration, ...(paid.credits === undefined ? {} : { credits: paid.credits }), cacheKey: isolated.key });
377
382
  log(`voice isolation: saved ${isolated.path} (commit it).`);
378
383
  isolateProgress(index, clip.duration);
379
384
  }
380
- speech[id] = isolated.path;
381
- sttInput = isolated.path;
385
+ // The provider's file decoded once: the speech track and the speech to text read it lossless, named by the clip.
386
+ const decoded = await decodeIsolatedVoice(isolated.path, id, buildDir, signal);
387
+ speech[id] = decoded;
388
+ sttInput = decoded;
382
389
  }
383
390
  const cached = readCachedTranscript(transcript.path);
384
391
  if (!cached.ok) return err(cached.error);
@@ -387,21 +394,15 @@ async function runTranscribeFootage(film: FootageFilm, clips: PreparedClip[], op
387
394
  words[id] = cached.words;
388
395
  continue;
389
396
  }
390
- if (sttInput !== null) {
391
- // The provider sees the clip's id as the file name, as it does for the plain sound.
392
- const cleaned = sttInput;
393
- sttInput = join(buildDir, "audio", `${id}.isolated.mp3`);
394
- mkdirSync(dirname(sttInput), { recursive: true });
395
- copyFileSync(cleaned, sttInput);
396
- }
397
397
  const index = transcribing.indexOf(entry);
398
398
  transcribeProgress(index, 0);
399
- const input = sttInput ?? (await getAudio());
399
+ // The provider sees the clip's id as the file name, for the cleaned voice as for the plain sound.
400
+ const input = sttInput ?? sound;
400
401
  throwIfAborted(signal);
401
402
  log(`speech to text (${providers.stt.id}): clip ${id}, ${clip.duration.toFixed(1)} s.`);
402
403
  const result = await providers.stt.transcribe({ audio: input, language: film.language, ...sttKeyTerms, ...(signal === undefined ? {} : { signal }) });
403
404
  throwIfAborted(signal);
404
- if (!result.ok) return err(`clip "${id}": ${result.error}`);
405
+ if (!result.ok) return err(`clip "${id}": ${result.error}`, getProviderFootageFailure(result.providerFailure));
405
406
  writeTranscript(transcript.path, result.value.words);
406
407
  const { credits } = result.value;
407
408
  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 });
@@ -607,7 +608,7 @@ async function getMusic(film: FootageFilm, edl: Edl, clips: PreparedClip[], seco
607
608
  return ok(null);
608
609
  }
609
610
  throwIfAborted(signal);
610
- if (!bought.ok) return err(`music: ${bought.error}`);
611
+ if (!bought.ok) return err(`music: ${bought.error}`, getProviderFootageFailure(bought.providerFailure));
611
612
  const paid = toPaidAudio(bought.value);
612
613
  writeCacheFile(path, paid.audio);
613
614
  options.onCharge?.({ step: "music", item: "film", provider: providers.music.id, units: seconds, ...(paid.credits === undefined ? {} : { credits: paid.credits }), cacheKey: cache.key });
@@ -617,12 +618,12 @@ async function getMusic(film: FootageFilm, edl: Edl, clips: PreparedClip[], seco
617
618
  }
618
619
 
619
620
  /**
620
- * The speech chain's files: the cut speech, the declicked track and the final `speech.mp3`. The last stage that runs
621
- * writes `speech.mp3`; the declicked track is float WAV when the loudness pass follows (one lossy encode fewer).
621
+ * The speech chain's files, all lossless float WAV (issue #1139): the cut speech, the declicked track and the final
622
+ * `speech.wav`, which the last stage that runs writes. The film's final AAC is the chain's only lossy encode.
622
623
  */
623
624
  export function getSpeechChainFiles(assetsDir: string, stages: { isDeclick: boolean; isLoudness: boolean }): { rawSpeechFile: string; declickedFile: string; speechFile: string } {
624
- const speechFile = join(assetsDir, "speech.mp3");
625
- const rawSpeechFile = stages.isDeclick || stages.isLoudness ? join(assetsDir, "speech.raw.mp3") : speechFile;
625
+ const speechFile = join(assetsDir, "speech.wav");
626
+ const rawSpeechFile = stages.isDeclick || stages.isLoudness ? join(assetsDir, "speech.raw.wav") : speechFile;
626
627
  const declickedFile = !stages.isDeclick ? rawSpeechFile : stages.isLoudness ? join(assetsDir, "speech.declicked.wav") : speechFile;
627
628
  return { rawSpeechFile, declickedFile, speechFile };
628
629
  }
@@ -676,6 +677,11 @@ export type RenderedFootage =
676
677
  edlPath: string;
677
678
  /** What the speech track's declick stage did (`FootageFilm.speech.declick`); null when it is off. */
678
679
  declick: DeclickReport | null;
680
+ /**
681
+ * How hyperframes captured the frames (issue #1145): the capture path (`screenshot` is the slower one), the GPU
682
+ * mode, each stage's seconds and the screenshot hint, read from hyperframes' summary; null when it printed none.
683
+ */
684
+ capture: HyperframesCapture | null;
679
685
  } & FinishedFootage);
680
686
 
681
687
  /**
@@ -826,7 +832,7 @@ async function runRenderFootage(
826
832
  assets: {
827
833
  clips: Object.fromEntries(clips.map((clip) => [clip.clip.id, `clips/${clip.clip.id}.mp4`])),
828
834
  picture: "assets/picture.mp4",
829
- speech: "assets/speech.mp3",
835
+ speech: "assets/speech.wav",
830
836
  music: musicAsset,
831
837
  lastFrame: "assets/last.jpg",
832
838
  logo: options.brand.logo === null ? null : "assets/logo.svg",
@@ -844,7 +850,7 @@ async function runRenderFootage(
844
850
  const roles = Object.fromEntries(clips.map((clip) => [clip.clip.id, clip.clip.role]));
845
851
  const finished = await finishFootage(film, { renderFile, seconds, coverAt: film.cover?.at ?? getDefaultCoverSeconds(edl, roles), mix: prepared.value }, options);
846
852
  if (!finished.ok) return finished;
847
- return ok({ kind: "rendered", output: options.output, seconds, edlPath: getEdlPath(buildDir, options.isPlaceholder), declick, ...finished.value });
853
+ return ok({ kind: "rendered", output: options.output, seconds, edlPath: getEdlPath(buildDir, options.isPlaceholder), declick, capture: rendered.value, ...finished.value });
848
854
  }
849
855
 
850
856
  /** What `renderFootage` reads from the written film. */
@@ -1011,6 +1017,10 @@ async function finishMix(input: {
1011
1017
  signal?: AbortSignal;
1012
1018
  }): Promise<FootageResult<{ attempt: MixAttempt; tries: number; probes: number; measured: MixLoudness }>> {
1013
1019
  const aborting = input.signal === undefined ? {} : { signal: input.signal };
1020
+ const bitrate = input.target.audioBitrateKbps;
1021
+ if (bitrate !== undefined && !(Number.isInteger(bitrate) && bitrate >= AUDIO_BITRATE_RANGE_KBPS.min && bitrate <= AUDIO_BITRATE_RANGE_KBPS.max)) {
1022
+ return err(`mixLoudness.audioBitrateKbps must be a whole number from ${String(AUDIO_BITRATE_RANGE_KBPS.min)} to ${String(AUDIO_BITRATE_RANGE_KBPS.max)}, got ${String(bitrate)}.`, { kind: "input" });
1023
+ }
1014
1024
  const attempts = getMixAttempts(input.target);
1015
1025
  const probe = async (attempt: MixAttempt): Promise<MixLoudness> => {
1016
1026
  const probed = await measureLoudness(input.input, input.target, { label: "the film's mix through its limiter", filter: getMixFilter(attempt), ...aborting });
@@ -1025,7 +1035,7 @@ async function finishMix(input: {
1025
1035
  const solved = await solveMixGain({ ceilingDbtp, startGainDb, target: input.target, shift, measure: probe });
1026
1036
  probes += solved.probes.length;
1027
1037
  const attempt = solved.best.attempt;
1028
- await runFfmpeg("The film's mix", buildMixArgs({ input: input.input, filter: getMixFilter(attempt), output: input.output }), { ...aborting, output: input.output });
1038
+ await runFfmpeg("The film's mix", buildMixArgs({ input: input.input, filter: getMixFilter(attempt), output: input.output, ...(input.target.audioBitrateKbps === undefined ? {} : { bitrateKbps: input.target.audioBitrateKbps }) }), { ...aborting, output: input.output });
1029
1039
  const encoded = await measureLoudness(input.output, input.target, { label: "the film's encoded mix", ...aborting });
1030
1040
  if (encoded.kind === "silent") return err("the film's mix measures silent after its gain and limiter.", { kind: "loudness", loudness: null });
1031
1041
  const measured = { integrated: encoded.measurement.inputI, truePeak: encoded.measurement.inputTp };
@@ -1121,15 +1131,20 @@ async function buildPicture(input: BuildPictureInput): Promise<void> {
1121
1131
  input.onSeconds(getPictureFrames(pieces) / FOOTAGE_FPS);
1122
1132
  }
1123
1133
 
1124
- /** The hyperframes render as a child process: its lines go to the log (progress every 10 %), its percentages to `onProgress`. */
1125
- async function runHyperframesRender(options: RenderFootageOptions, output: string, seconds: number): Promise<FootageResult<null>> {
1134
+ /**
1135
+ * The hyperframes render as a child process: its lines go to the log (progress every 10 %), its percentages to
1136
+ * `onProgress`; it answers the capture report read from its summary (null when it printed none).
1137
+ */
1138
+ async function runHyperframesRender(options: RenderFootageOptions, output: string, seconds: number): Promise<FootageResult<HyperframesCapture | null>> {
1126
1139
  const progress = createStageProgress(options.onProgress, "render", [{ item: "film", seconds }]);
1127
1140
  progress(0, 0);
1128
1141
  let loggedTenth = -1;
1142
+ const lines: string[] = [];
1129
1143
  const onLine = (line: string): void => {
1130
1144
  if (line.trim().length === 0) return;
1131
1145
  const percent = readRenderPercent(line);
1132
1146
  if (percent === null) {
1147
+ lines.push(line);
1133
1148
  options.log(line.trim());
1134
1149
  return;
1135
1150
  }
@@ -1160,7 +1175,7 @@ async function runHyperframesRender(options: RenderFootageOptions, output: strin
1160
1175
  if (result.kind === "not-started") return err(`hyperframes render did not start: ${result.error}.`);
1161
1176
  if (result.code !== 0) return err(`hyperframes render ended with code ${String(result.code)} (signal ${result.signal ?? "-"}).`);
1162
1177
  progress(0, seconds);
1163
- return ok(null);
1178
+ return ok(readHyperframesCapture(lines));
1164
1179
  }
1165
1180
 
1166
1181
  export interface RenderFootageFilmOptions extends RenderFootageOptions {
@@ -42,6 +42,11 @@ export interface SttProvider {
42
42
  /** Removes background noise from speech; returns the cleaned audio (mp3), alone or with the reported charge. */
43
43
  export interface IsolationProvider {
44
44
  readonly id: string;
45
+ /**
46
+ * The shortest input in seconds the provider accepts; absent: no minimum. `planSpeechRanges` merges and widens the
47
+ * cut's ranges to reach it and never sends a range still shorter.
48
+ */
49
+ readonly minSeconds?: number;
45
50
  isolate(input: { audio: string; signal?: AbortSignal }): Promise<TtsResult<Buffer | PaidAudio>>;
46
51
  }
47
52
 
@@ -1,3 +1,4 @@
1
+ import { getAudioCodecArgs } from "./clip-sound.js";
1
2
  import { getSoundSpan, type Edl } from "./edl.js";
2
3
  import { DEFAULT_EDIT, type FootageEdit } from "./film.js";
3
4
  import { FOOTAGE_SAMPLE_RATE } from "./normalize.js";
@@ -105,7 +106,7 @@ export function buildSpeechArgs(edl: Edl, sources: Record<string, string>, outpu
105
106
  const joined = edl.segments.map((_, index) => `[a${index}]`).join("");
106
107
  parts.push(`${joined}concat=n=${edl.segments.length}:v=0:a=1[speech]`);
107
108
  }
108
- return ["-v", "error", "-y", ...inputs, "-filter_complex", parts.join(";"), "-map", "[speech]", "-c:a", "libmp3lame", "-q:a", "2", output];
109
+ return ["-v", "error", "-y", ...inputs, "-filter_complex", parts.join(";"), "-map", "[speech]", ...getAudioCodecArgs(output), output];
109
110
  }
110
111
 
111
112
  /** The music track: looped to the film's length, ducked by the keyframes, faded in and out. */
@@ -147,7 +148,7 @@ export function buildLastFrameArgs(edl: Edl, clips: Record<string, string>, outp
147
148
  return ["-v", "error", "-y", "-ss", String(at), "-i", clip, "-frames:v", "1", "-q:v", "2", output];
148
149
  }
149
150
 
150
- /** Audio extracted from a normalized clip, for the providers and the speech track. */
151
+ /** A file's sound alone, encoded by the output's extension (`getAudioCodecArgs`: `.wav` lossless). */
151
152
  export function buildAudioArgs(clip: string, output: string): string[] {
152
- return ["-v", "error", "-y", "-i", clip, "-vn", "-c:a", "libmp3lame", "-q:a", "2", output];
153
+ return ["-v", "error", "-y", "-i", clip, "-vn", ...getAudioCodecArgs(output), output];
153
154
  }
@@ -1,7 +1,11 @@
1
+ import { extname } from "node:path";
2
+
1
3
  import { footageCacheKey, getFootageCachePath } from "./cache.js";
4
+ import { getAudioCodecArgs } from "./clip-sound.js";
2
5
  import { getSoundSpan, type Edl } from "./edl.js";
3
6
  import type { ClipRole } from "./film.js";
4
7
  import { FOOTAGE_SAMPLE_RATE } from "./normalize.js";
8
+ import type { IsolationProvider } from "./providers.js";
5
9
 
6
10
  /**
7
11
  * The parts of each talking clip a cut hears, as ranges in whole milliseconds, and how their cleaned voice is laid
@@ -12,11 +16,31 @@ import { FOOTAGE_SAMPLE_RATE } from "./normalize.js";
12
16
  /** Seconds added on each side of a sound span, so a cut's cross-fade and fades read cleaned sound. */
13
17
  export const DEFAULT_SPEECH_RANGE_MARGIN = 0.25;
14
18
 
19
+ /** Seconds of the largest gap between two ranges of a clip that are isolated as one range (`planSpeechRanges`). */
20
+ export const DEFAULT_SPEECH_RANGE_MERGE_GAP = 2;
21
+
22
+ /** Seconds a range shorter than the provider's minimum is widened past it, so the cut file is safely long enough. */
23
+ export const DEFAULT_SPEECH_RANGE_MIN_PAD = 0.4;
24
+
25
+ /** Why a planned range is not sent: shorter than the provider's minimum even after merging and widening. */
26
+ export interface SpeechRangeSkip {
27
+ reason: "too_short";
28
+ /** The provider's minimum, in seconds. */
29
+ minSeconds: number;
30
+ }
31
+
15
32
  /** A range of a clip's trimmed sound, in whole milliseconds (the cache key's unit). */
16
33
  export interface SpeechRange {
17
34
  clip: string;
18
35
  startMs: number;
19
36
  endMs: number;
37
+ /**
38
+ * The part of the range the cut hears, when the range was widened with the clip's own context to reach the
39
+ * provider's minimum; absent: the whole range. Only this part of the cleaned voice is laid.
40
+ */
41
+ heard?: { startMs: number; endMs: number };
42
+ /** Set when the range cannot pass the provider (the clip itself is shorter than its minimum): it is not sent. */
43
+ skip?: SpeechRangeSkip;
20
44
  }
21
45
 
22
46
  /** Where a range's cleaned sound is laid in its clip, in milliseconds; inside the range. */
@@ -33,15 +57,35 @@ export interface SpeechRangeClip {
33
57
  duration: number;
34
58
  }
35
59
 
60
+ export interface PlanSpeechRangesOptions {
61
+ /** Seconds added on each side of a sound span; default `DEFAULT_SPEECH_RANGE_MARGIN` (0.25). */
62
+ margin?: number;
63
+ /** The isolation provider's minimum input in seconds (`IsolationProvider.minSeconds`); absent: no minimum. */
64
+ minSeconds?: number;
65
+ /**
66
+ * Ranges of a clip at most this many seconds apart are isolated as one range; default
67
+ * `DEFAULT_SPEECH_RANGE_MERGE_GAP` (2). `null` keeps every range apart (only identical ranges and ranges inside
68
+ * another are dropped); `Infinity` isolates each clip's whole used span once.
69
+ */
70
+ mergeGap?: number | null;
71
+ /** Seconds a range shorter than `minSeconds` is widened past it; default `DEFAULT_SPEECH_RANGE_MIN_PAD` (0.4). */
72
+ minPad?: number;
73
+ }
74
+
36
75
  /**
37
- * The ranges the cut hears of each talking clip: every segment's sound span (its own clip's or `audio`'s), and the
76
+ * The source ranges to isolate of each talking clip: every segment's sound span (its own clip's or `audio`'s), and the
38
77
  * picture clip's own span when `audio.ownVolume` keeps it under, widened by `margin` seconds on each side, clamped to
39
- * the clip and rounded out to whole milliseconds. Identical ranges and ranges inside another are dropped (the larger
40
- * one is laid there anyway); the rest are not merged, so a moved segment changes only its own range. Sorted by clip
41
- * order, then start.
78
+ * the clip and rounded out to whole milliseconds. Identical ranges and ranges inside another are dropped; ranges of a
79
+ * clip at most `mergeGap` seconds apart become one. With `minSeconds`, a range still shorter is widened symmetrically
80
+ * with the clip's own context to `minSeconds + minPad` (shifted where the clip's edge stops it; `heard` keeps the part
81
+ * the cut hears), ranges the widening brought within `mergeGap` are merged, and a range still shorter (a clip shorter
82
+ * than the minimum) is marked `skip`. Sorted by clip order, then start.
42
83
  */
43
- export function planSpeechRanges(edl: Edl, clips: readonly SpeechRangeClip[], options: { margin?: number } = {}): SpeechRange[] {
84
+ export function planSpeechRanges(edl: Edl, clips: readonly SpeechRangeClip[], options: PlanSpeechRangesOptions = {}): SpeechRange[] {
44
85
  const margin = Math.max(0, options.margin ?? DEFAULT_SPEECH_RANGE_MARGIN);
86
+ const mergeGap = options.mergeGap === undefined ? DEFAULT_SPEECH_RANGE_MERGE_GAP : options.mergeGap;
87
+ const gapMs = mergeGap === null ? null : Math.max(0, mergeGap) * 1000;
88
+ const minSeconds = options.minSeconds !== undefined && options.minSeconds > 0 ? options.minSeconds : null;
45
89
  const byId = new Map(clips.map((clip) => [clip.id, clip]));
46
90
  const found = new Map<string, SpeechRange[]>();
47
91
  const add = (span: { clip: string; start: number; end: number }): void => {
@@ -62,25 +106,90 @@ export function planSpeechRanges(edl: Edl, clips: readonly SpeechRangeClip[], op
62
106
  const ranges: SpeechRange[] = [];
63
107
  for (const clip of clips) {
64
108
  const list = (found.get(clip.id) ?? []).sort((a, b) => a.startMs - b.startMs || b.endMs - a.endMs);
109
+ let kept: SpeechRange[] = [];
65
110
  for (const range of list) {
66
- const isInside = ranges.some((kept) => kept.clip === range.clip && kept.startMs <= range.startMs && kept.endMs >= range.endMs);
67
- if (!isInside) ranges.push(range);
111
+ const isInside = kept.some((other) => other.startMs <= range.startMs && other.endMs >= range.endMs);
112
+ if (!isInside) kept.push(range);
113
+ }
114
+ if (gapMs !== null) kept = mergeSpeechRanges(kept, gapMs);
115
+ if (minSeconds !== null) {
116
+ const minMs = Math.ceil(minSeconds * 1000);
117
+ const targetMs = Math.ceil((minSeconds + Math.max(0, options.minPad ?? DEFAULT_SPEECH_RANGE_MIN_PAD)) * 1000);
118
+ const clipMs = Math.floor(clip.duration * 1000);
119
+ kept = kept.map((range) => widenSpeechRange(range, { minMs, targetMs, clipMs }));
120
+ if (gapMs !== null) kept = mergeSpeechRanges(kept, gapMs);
121
+ kept = kept.map((range) => (range.endMs - range.startMs < minMs ? { ...range, skip: { reason: "too_short", minSeconds } } : range));
68
122
  }
123
+ ranges.push(...kept);
69
124
  }
70
125
  return ranges;
71
126
  }
72
127
 
128
+ /** How `isolateSpeechRanges` and the estimate plan the ranges: the caller's margin and merge gap, the provider's minimum. */
129
+ export function getPlanOptions(options: Pick<PlanSpeechRangesOptions, "margin" | "mergeGap" | "minPad">, isolation: IsolationProvider): PlanSpeechRangesOptions {
130
+ return {
131
+ ...(options.margin === undefined ? {} : { margin: options.margin }),
132
+ ...(options.mergeGap === undefined ? {} : { mergeGap: options.mergeGap }),
133
+ ...(options.minPad === undefined ? {} : { minPad: options.minPad }),
134
+ ...(isolation.minSeconds === undefined ? {} : { minSeconds: isolation.minSeconds }),
135
+ };
136
+ }
137
+
138
+ /** The part of a range the cut hears. */
139
+ function getHeard(range: SpeechRange): { startMs: number; endMs: number } {
140
+ return range.heard ?? { startMs: range.startMs, endMs: range.endMs };
141
+ }
142
+
143
+ /** A range with `heard` set only when it is narrower than the range. */
144
+ function withHeard(range: Pick<SpeechRange, "clip" | "startMs" | "endMs">, heard: { startMs: number; endMs: number }): SpeechRange {
145
+ const isWhole = heard.startMs <= range.startMs && heard.endMs >= range.endMs;
146
+ return isWhole ? { clip: range.clip, startMs: range.startMs, endMs: range.endMs } : { clip: range.clip, startMs: range.startMs, endMs: range.endMs, heard };
147
+ }
148
+
149
+ /** One clip's ranges (sorted by start) with every two at most `gapMs` apart merged into one; the heard parts joined. */
150
+ function mergeSpeechRanges(ranges: readonly SpeechRange[], gapMs: number): SpeechRange[] {
151
+ const merged: SpeechRange[] = [];
152
+ for (const range of [...ranges].sort((a, b) => a.startMs - b.startMs)) {
153
+ const last = merged.at(-1);
154
+ if (last === undefined || range.startMs - last.endMs > gapMs) {
155
+ merged.push(range);
156
+ continue;
157
+ }
158
+ const lastHeard = getHeard(last);
159
+ const heard = getHeard(range);
160
+ merged[merged.length - 1] = withHeard(
161
+ { clip: last.clip, startMs: last.startMs, endMs: Math.max(last.endMs, range.endMs) },
162
+ { startMs: Math.min(lastHeard.startMs, heard.startMs), endMs: Math.max(lastHeard.endMs, heard.endMs) },
163
+ );
164
+ }
165
+ return merged;
166
+ }
167
+
168
+ /** A range shorter than `minMs` widened symmetrically to `targetMs` with the clip's own context, inside the clip. */
169
+ function widenSpeechRange(range: SpeechRange, limits: { minMs: number; targetMs: number; clipMs: number }): SpeechRange {
170
+ const length = range.endMs - range.startMs;
171
+ if (length >= limits.minMs) return range;
172
+ const target = Math.min(limits.targetMs, limits.clipMs);
173
+ const endMs = Math.min(limits.clipMs, Math.max(0, range.startMs - Math.floor((target - length) / 2)) + target);
174
+ const startMs = Math.max(0, endMs - target);
175
+ return withHeard({ clip: range.clip, startMs, endMs }, getHeard(range));
176
+ }
177
+
73
178
  /**
74
- * Where each of one clip's ranges is laid: the whole range, except that two overlapping neighbours switch at the
75
- * middle of their overlap. Takes ranges of one clip, none inside another (as `planSpeechRanges` answers them).
179
+ * Where each of one clip's ranges is laid: the part the cut hears (`heard`, else the whole range), except that two
180
+ * overlapping neighbours switch at the middle of their overlap. Takes ranges of one clip, none inside another (as
181
+ * `planSpeechRanges` answers them).
76
182
  */
77
183
  export function getSpeechRangeWindows(ranges: readonly SpeechRange[]): SpeechRangeWindow[] {
78
- const sorted = [...ranges].sort((a, b) => a.startMs - b.startMs);
184
+ const sorted = [...ranges].sort((a, b) => getHeard(a).startMs - getHeard(b).startMs);
79
185
  return sorted.map((range, index) => {
186
+ const heard = getHeard(range);
80
187
  const before = sorted[index - 1];
81
188
  const after = sorted[index + 1];
82
- const startMs = before !== undefined && before.endMs > range.startMs ? Math.round((range.startMs + before.endMs) / 2) : range.startMs;
83
- const endMs = after !== undefined && after.startMs < range.endMs ? Math.round((after.startMs + range.endMs) / 2) : range.endMs;
189
+ const beforeEnd = before === undefined ? null : getHeard(before).endMs;
190
+ const afterStart = after === undefined ? null : getHeard(after).startMs;
191
+ const startMs = beforeEnd !== null && beforeEnd > heard.startMs ? Math.round((heard.startMs + beforeEnd) / 2) : heard.startMs;
192
+ const endMs = afterStart !== null && afterStart < heard.endMs ? Math.round((afterStart + heard.endMs) / 2) : heard.endMs;
84
193
  return { range, startMs, endMs };
85
194
  });
86
195
  }
@@ -96,9 +205,13 @@ export type SpeechRangeCacheResolver = (range: SpeechRange, clipKey: string) =>
96
205
 
97
206
  const seconds = (ms: number): string => (ms / 1000).toFixed(3);
98
207
 
99
- /** One range of a clip's sound (`audio`, read from its start) as mp3, for the isolation provider. */
208
+ /**
209
+ * One range of a clip's sound (`audio`, read from its start) for the isolation provider: 24-bit PCM for a `.wav`
210
+ * output (lossless, issue #1139), else as `getAudioCodecArgs` encodes it.
211
+ */
100
212
  export function buildRangeAudioArgs(audio: string, range: Pick<SpeechRange, "startMs" | "endMs">, output: string): string[] {
101
- return ["-v", "error", "-y", "-ss", seconds(range.startMs), "-t", seconds(range.endMs - range.startMs), "-i", audio, "-vn", "-c:a", "libmp3lame", "-q:a", "2", output];
213
+ const codec = extname(output).toLowerCase() === ".wav" ? ["-c:a", "pcm_s24le"] : getAudioCodecArgs(output);
214
+ return ["-v", "error", "-y", "-ss", seconds(range.startMs), "-t", seconds(range.endMs - range.startMs), "-i", audio, "-vn", ...codec, output];
102
215
  }
103
216
 
104
217
  /** A cleaned range laid back: its file, and whether it is mono (panned to both channels at full level). */
@@ -161,7 +274,7 @@ function buildGainExpression(fade: SpeechRangeFade): string {
161
274
  */
162
275
  export function buildRangeLayArgs(base: string, laid: readonly LaidRange[], output: string, options: { fadeMs?: number } = {}): string[] {
163
276
  const format = `aformat=sample_rates=${FOOTAGE_SAMPLE_RATE}:channel_layouts=stereo`;
164
- if (laid.length === 0) return ["-v", "error", "-y", "-i", base, "-vn", "-af", format, "-c:a", "libmp3lame", "-q:a", "2", output];
277
+ if (laid.length === 0) return ["-v", "error", "-y", "-i", base, "-vn", "-af", format, ...getAudioCodecArgs(output), output];
165
278
  const windows = laid.map(({ window }) => window);
166
279
  const fades = getSpeechRangeFades(windows, options.fadeMs ?? DEFAULT_SPEECH_RANGE_FADE_MS);
167
280
  const byWindow = new Map([...windows].sort((a, b) => a.startMs - b.startMs).map((window, index) => [window, fades[index]]));
@@ -184,5 +297,5 @@ export function buildRangeLayArgs(base: string, laid: readonly LaidRange[], outp
184
297
  parts.unshift(`[0:a]${format},aeval='val(ch)*(1-(${gains.join("+")}))':c=same[base]`);
185
298
  const mixed = laid.map((_, index) => `[w${String(index)}]`).join("");
186
299
  parts.push(`[base]${mixed}amix=inputs=${String(laid.length + 1)}:duration=first:normalize=0[speech]`);
187
- return ["-v", "error", "-y", ...inputs, "-filter_complex", parts.join(";"), "-map", "[speech]", "-c:a", "libmp3lame", "-q:a", "2", output];
300
+ return ["-v", "error", "-y", ...inputs, "-filter_complex", parts.join(";"), "-map", "[speech]", ...getAudioCodecArgs(output), output];
188
301
  }
package/src/index.ts CHANGED
@@ -84,6 +84,17 @@ export {
84
84
  type TtsRequest,
85
85
  } from "./voice/voiceover.js";
86
86
  export type { TtsEstimate, TtsInput, TtsProvider, TtsRecording, TtsResult } from "./voice/provider.js";
87
+ export {
88
+ describeProviderFailure,
89
+ getConnectionFailure,
90
+ getLocalRefusal,
91
+ getProviderFailure,
92
+ getProviderFailureKind,
93
+ readProviderErrorBody,
94
+ PROVIDER_MESSAGE_LENGTH,
95
+ type ProviderFailure,
96
+ type ProviderFailureKind,
97
+ } from "./voice/provider-failure.js";
87
98
  export { ELEVENLABS_API_KEY_ENV, ELEVENLABS_PROVIDER_ID, createElevenLabsProvider, type ElevenLabsOptions } from "./voice/elevenlabs.js";
88
99
  export { createFakeTtsProvider, type FakeTtsOptions, type FakeTtsProvider } from "./voice/fake.js";
89
100
  export { createTtsProvider, type CreateTtsProviderOptions, type TtsProviderId } from "./voice/providers.js";
@@ -156,11 +167,14 @@ export {
156
167
  loadOgFonts,
157
168
  renderConfiguredOgImage,
158
169
  renderOgImage,
170
+ renderPhotoCover,
159
171
  type ConfiguredOgImageOptions,
160
172
  type OgBrand,
161
173
  type OgImageInput,
162
174
  type OgResult,
163
175
  type OgTemplateId,
176
+ type PhotoCover,
177
+ type PhotoCoverInput,
164
178
  } from "./og/index.js";
165
179
  export { buildPosts, postsMarkdown, type PlatformPost, type PostsInput } from "./posts/posts.js";
166
180
  export { createActionScene, getLocator, runAction, type LocatorSource } from "./record/actions.js";
@@ -293,6 +307,7 @@ export {
293
307
  type SttTranscript,
294
308
  } from "./footage/providers.js";
295
309
  export {
310
+ ELEVENLABS_ISOLATION_MIN_SECONDS,
296
311
  ELEVENLABS_MUSIC_MODEL,
297
312
  ELEVENLABS_STT_MODEL,
298
313
  createElevenLabsFootageProviders,
@@ -309,6 +324,7 @@ export {
309
324
  createFakeMusicProvider,
310
325
  createFakeSttProvider,
311
326
  makePlaceholderTranscript,
327
+ type FakeIsolationOptions,
312
328
  type FakeIsolationProvider,
313
329
  type FakeMusicProvider,
314
330
  type FakeSttOptions,
@@ -419,6 +435,18 @@ export {
419
435
  type PicturePieceArgsInput,
420
436
  } from "./footage/picture.js";
421
437
  export {
438
+ SPEECH_PRE_GAIN,
439
+ buildClipSoundArgs,
440
+ buildClipSoundMeasureArgs,
441
+ getAudioCodecArgs,
442
+ getClipSoundPath,
443
+ getPreGainDb,
444
+ prepareClipSounds,
445
+ type ClipSound,
446
+ type ClipSoundInput,
447
+ } from "./footage/clip-sound.js";
448
+ export {
449
+ AUDIO_BITRATE_RANGE_KBPS,
422
450
  DEFAULT_LOUDNESS,
423
451
  buildLoudnessArgs,
424
452
  buildLoudnessMeasureArgs,
@@ -503,6 +531,8 @@ export {
503
531
  export {
504
532
  DEFAULT_SPEECH_RANGE_FADE_MS,
505
533
  DEFAULT_SPEECH_RANGE_MARGIN,
534
+ DEFAULT_SPEECH_RANGE_MERGE_GAP,
535
+ DEFAULT_SPEECH_RANGE_MIN_PAD,
506
536
  buildRangeAudioArgs,
507
537
  buildRangeLayArgs,
508
538
  getSpeechRangeCache,
@@ -510,10 +540,12 @@ export {
510
540
  getSpeechRangeWindows,
511
541
  planSpeechRanges,
512
542
  type LaidRange,
543
+ type PlanSpeechRangesOptions,
513
544
  type SpeechRange,
514
545
  type SpeechRangeCacheResolver,
515
546
  type SpeechRangeClip,
516
547
  type SpeechRangeFade,
548
+ type SpeechRangeSkip,
517
549
  type SpeechRangeWindow,
518
550
  } from "./footage/speech-ranges.js";
519
551
  export {
@@ -526,6 +558,14 @@ export {
526
558
  type SpeechRangeOutcome,
527
559
  type SpeechRangeRetry,
528
560
  } from "./footage/isolate-ranges.js";
561
+ export {
562
+ HYPERFRAMES_CAPTURE_STAGES,
563
+ readHyperframesCapture,
564
+ type HyperframesCapture,
565
+ type HyperframesCapturePath,
566
+ type HyperframesCaptureStage,
567
+ type HyperframesGpuMode,
568
+ } from "./footage/hyperframes-capture.js";
529
569
  export { RENDER_MIN_FREE_BYTES, findLowDiskProblems, getFreeBytes, getRenderTempDir, type FreeBytesReader } from "./footage/disk.js";
530
570
  export { DRAFT_FILTERS, REQUIRED_DECODERS, REQUIRED_FILTERS, checkFootageTools, findBrowserProblem, readFfmpegListing, type FootageToolsOptions } from "./footage/tools.js";
531
571
  export {
@@ -559,7 +599,7 @@ export {
559
599
  type RenderedFootage,
560
600
  type TranscribeOutcome,
561
601
  } from "./footage/pipeline.js";
562
- export { isRetryableFootageFailure, type FootageError, type FootageFailure, type FootageFailureKind } from "./footage/failure.js";
602
+ export { getProviderFootageFailure, isRetryableFootageFailure, type FootageError, type FootageFailure, type FootageFailureKind } from "./footage/failure.js";
563
603
  export {
564
604
  formatMessage,
565
605
  getMarketingMessages,