@softure-ai/marketing-kit 0.11.0 → 0.12.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 (91) hide show
  1. package/CHANGELOG.md +71 -0
  2. package/README.md +66 -9
  3. package/dist/cli/footage.js +1 -1
  4. package/dist/cli/footage.js.map +1 -1
  5. package/dist/compose/timeline.d.ts +23 -3
  6. package/dist/compose/timeline.d.ts.map +1 -1
  7. package/dist/compose/timeline.js +31 -11
  8. package/dist/compose/timeline.js.map +1 -1
  9. package/dist/config/actions-schema.d.ts +14 -14
  10. package/dist/config/config.d.ts.map +1 -1
  11. package/dist/config/config.js +2 -0
  12. package/dist/config/config.js.map +1 -1
  13. package/dist/config/schema.d.ts +83 -70
  14. package/dist/config/schema.d.ts.map +1 -1
  15. package/dist/config/schema.js +21 -1
  16. package/dist/config/schema.js.map +1 -1
  17. package/dist/config/shot-steps.d.ts +16 -16
  18. package/dist/footage/captions.d.ts +45 -3
  19. package/dist/footage/captions.d.ts.map +1 -1
  20. package/dist/footage/captions.js +65 -5
  21. package/dist/footage/captions.js.map +1 -1
  22. package/dist/footage/compose.d.ts.map +1 -1
  23. package/dist/footage/compose.js +8 -4
  24. package/dist/footage/compose.js.map +1 -1
  25. package/dist/footage/declick.d.ts +106 -0
  26. package/dist/footage/declick.d.ts.map +1 -0
  27. package/dist/footage/declick.js +296 -0
  28. package/dist/footage/declick.js.map +1 -0
  29. package/dist/footage/draft.d.ts +8 -3
  30. package/dist/footage/draft.d.ts.map +1 -1
  31. package/dist/footage/draft.js +55 -22
  32. package/dist/footage/draft.js.map +1 -1
  33. package/dist/footage/edl.d.ts +28 -2
  34. package/dist/footage/edl.d.ts.map +1 -1
  35. package/dist/footage/edl.js +53 -2
  36. package/dist/footage/edl.js.map +1 -1
  37. package/dist/footage/film.d.ts +29 -3
  38. package/dist/footage/film.d.ts.map +1 -1
  39. package/dist/footage/film.js +12 -0
  40. package/dist/footage/film.js.map +1 -1
  41. package/dist/footage/isolate-ranges.d.ts +37 -0
  42. package/dist/footage/isolate-ranges.d.ts.map +1 -0
  43. package/dist/footage/isolate-ranges.js +113 -0
  44. package/dist/footage/isolate-ranges.js.map +1 -0
  45. package/dist/footage/loudness.d.ts +58 -0
  46. package/dist/footage/loudness.d.ts.map +1 -1
  47. package/dist/footage/loudness.js +80 -0
  48. package/dist/footage/loudness.js.map +1 -1
  49. package/dist/footage/paid.d.ts +18 -0
  50. package/dist/footage/paid.d.ts.map +1 -1
  51. package/dist/footage/paid.js +32 -2
  52. package/dist/footage/paid.js.map +1 -1
  53. package/dist/footage/pipeline.d.ts +43 -5
  54. package/dist/footage/pipeline.d.ts.map +1 -1
  55. package/dist/footage/pipeline.js +103 -20
  56. package/dist/footage/pipeline.js.map +1 -1
  57. package/dist/footage/providers.d.ts +5 -0
  58. package/dist/footage/providers.d.ts.map +1 -1
  59. package/dist/footage/publish.d.ts +11 -2
  60. package/dist/footage/publish.d.ts.map +1 -1
  61. package/dist/footage/publish.js +14 -10
  62. package/dist/footage/publish.js.map +1 -1
  63. package/dist/footage/speech-ranges.d.ts +65 -0
  64. package/dist/footage/speech-ranges.d.ts.map +1 -0
  65. package/dist/footage/speech-ranges.js +98 -0
  66. package/dist/footage/speech-ranges.js.map +1 -0
  67. package/dist/index.d.ts +10 -7
  68. package/dist/index.d.ts.map +1 -1
  69. package/dist/index.js +10 -7
  70. package/dist/index.js.map +1 -1
  71. package/package.json +1 -1
  72. package/schema/edl.schema.json +17 -0
  73. package/schema/marketing.schema.json +43 -1
  74. package/src/cli/footage.ts +1 -1
  75. package/src/compose/timeline.ts +41 -10
  76. package/src/config/config.ts +2 -0
  77. package/src/config/schema.ts +23 -1
  78. package/src/footage/captions.ts +81 -6
  79. package/src/footage/compose.ts +8 -4
  80. package/src/footage/declick.ts +353 -0
  81. package/src/footage/draft.ts +58 -23
  82. package/src/footage/edl.ts +69 -2
  83. package/src/footage/film.ts +37 -3
  84. package/src/footage/isolate-ranges.ts +161 -0
  85. package/src/footage/loudness.ts +112 -0
  86. package/src/footage/paid.ts +40 -2
  87. package/src/footage/pipeline.ts +155 -22
  88. package/src/footage/providers.ts +2 -0
  89. package/src/footage/publish.ts +20 -11
  90. package/src/footage/speech-ranges.ts +131 -0
  91. package/src/index.ts +70 -0
@@ -0,0 +1,131 @@
1
+ import { footageCacheKey, getFootageCachePath } from "./cache.js";
2
+ import { getSoundSpan, type Edl } from "./edl.js";
3
+ import type { ClipRole } from "./film.js";
4
+ import { FOOTAGE_SAMPLE_RATE } from "./normalize.js";
5
+
6
+ /**
7
+ * The parts of each talking clip a cut hears, as ranges in whole milliseconds, and how their cleaned voice is laid
8
+ * back over the clip's own sound: pure planning and ffmpeg argument builders for `isolateSpeechRanges` and the
9
+ * per-range estimate, tested without ffmpeg.
10
+ */
11
+
12
+ /** Seconds added on each side of a sound span, so a cut's cross-fade and fades read cleaned sound. */
13
+ export const DEFAULT_SPEECH_RANGE_MARGIN = 0.25;
14
+
15
+ /** A range of a clip's trimmed sound, in whole milliseconds (the cache key's unit). */
16
+ export interface SpeechRange {
17
+ clip: string;
18
+ startMs: number;
19
+ endMs: number;
20
+ }
21
+
22
+ /** Where a range's cleaned sound is laid in its clip, in milliseconds; inside the range. */
23
+ export interface SpeechRangeWindow {
24
+ range: SpeechRange;
25
+ startMs: number;
26
+ endMs: number;
27
+ }
28
+
29
+ export interface SpeechRangeClip {
30
+ id: string;
31
+ role: ClipRole;
32
+ /** Seconds after the trim. */
33
+ duration: number;
34
+ }
35
+
36
+ /**
37
+ * The ranges the cut hears of each talking clip: every segment's sound span (its own clip's or `audio`'s), and the
38
+ * 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.
42
+ */
43
+ export function planSpeechRanges(edl: Edl, clips: readonly SpeechRangeClip[], options: { margin?: number } = {}): SpeechRange[] {
44
+ const margin = Math.max(0, options.margin ?? DEFAULT_SPEECH_RANGE_MARGIN);
45
+ const byId = new Map(clips.map((clip) => [clip.id, clip]));
46
+ const found = new Map<string, SpeechRange[]>();
47
+ const add = (span: { clip: string; start: number; end: number }): void => {
48
+ const clip = byId.get(span.clip);
49
+ if (clip === undefined || clip.role !== "talk") return;
50
+ const clipMs = Math.floor(clip.duration * 1000);
51
+ const startMs = Math.max(0, Math.floor((span.start - margin) * 1000));
52
+ const endMs = Math.min(clipMs, Math.ceil((span.end + margin) * 1000));
53
+ if (endMs <= startMs) return;
54
+ const list = found.get(clip.id) ?? [];
55
+ list.push({ clip: clip.id, startMs, endMs });
56
+ found.set(clip.id, list);
57
+ };
58
+ for (const segment of edl.segments) {
59
+ add(getSoundSpan(segment));
60
+ if (segment.audio !== undefined && segment.audio.ownVolume > 0) add(segment);
61
+ }
62
+ const ranges: SpeechRange[] = [];
63
+ for (const clip of clips) {
64
+ const list = (found.get(clip.id) ?? []).sort((a, b) => a.startMs - b.startMs || b.endMs - a.endMs);
65
+ 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);
68
+ }
69
+ }
70
+ return ranges;
71
+ }
72
+
73
+ /**
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).
76
+ */
77
+ export function getSpeechRangeWindows(ranges: readonly SpeechRange[]): SpeechRangeWindow[] {
78
+ const sorted = [...ranges].sort((a, b) => a.startMs - b.startMs);
79
+ return sorted.map((range, index) => {
80
+ const before = sorted[index - 1];
81
+ 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;
84
+ return { range, startMs, endMs };
85
+ });
86
+ }
87
+
88
+ /** The paid cache of one range's cleaned voice: keyed by the clip's identity, the range in milliseconds and the provider. */
89
+ export function getSpeechRangeCache(filmId: string, clipKey: string, range: SpeechRange, options: { cacheDir: string; provider: string }): { key: string; path: string } {
90
+ const key = footageCacheKey("isolated", { clip: clipKey, range: [range.startMs, range.endMs], provider: options.provider });
91
+ return { key, path: getFootageCachePath(options.cacheDir, filmId, "isolated", key) };
92
+ }
93
+
94
+ const seconds = (ms: number): string => (ms / 1000).toFixed(3);
95
+
96
+ /** One range of a clip's sound (`audio`, read from its start) as mp3, for the isolation provider. */
97
+ export function buildRangeAudioArgs(audio: string, range: Pick<SpeechRange, "startMs" | "endMs">, output: string): string[] {
98
+ return ["-v", "error", "-y", "-ss", seconds(range.startMs), "-t", seconds(range.endMs - range.startMs), "-i", audio, "-vn", "-c:a", "libmp3lame", "-q:a", "2", output];
99
+ }
100
+
101
+ /** A cleaned range laid back: its file, and whether it is mono (panned to both channels at full level). */
102
+ export interface LaidRange {
103
+ window: SpeechRangeWindow;
104
+ file: string;
105
+ isMono: boolean;
106
+ }
107
+
108
+ /**
109
+ * The clip's own sound with each window replaced by its cleaned range: the base muted inside every window, each
110
+ * window cut from its cleaned file and delayed into place, summed without level change. As long as the base; 48 kHz
111
+ * stereo like the speech track; a mono answer goes to both channels as it is, not up-mixed at -3 dB.
112
+ */
113
+ export function buildRangeLayArgs(base: string, laid: readonly LaidRange[], output: string): string[] {
114
+ const format = `aformat=sample_rates=${FOOTAGE_SAMPLE_RATE}:channel_layouts=stereo`;
115
+ if (laid.length === 0) return ["-v", "error", "-y", "-i", base, "-vn", "-af", format, "-c:a", "libmp3lame", "-q:a", "2", output];
116
+ const inputs = ["-i", base];
117
+ const mute = laid.map(({ window }) => `between(t,${seconds(window.startMs)},${seconds(window.endMs)})`).join("+");
118
+ const parts = [`[0:a]${format},volume=0:enable='${mute}'[base]`];
119
+ laid.forEach(({ window, file, isMono }, index) => {
120
+ inputs.push("-i", file);
121
+ const offset = window.startMs - window.range.startMs;
122
+ const length = window.endMs - window.startMs;
123
+ const channels = isMono ? "pan=stereo|c0=c0|c1=c0," : "";
124
+ parts.push(
125
+ `[${index + 1}:a]atrim=start=${seconds(offset)}:end=${seconds(offset + length)},asetpts=PTS-STARTPTS,${channels}${format},adelay=${window.startMs}:all=1[w${index}]`,
126
+ );
127
+ });
128
+ const mixed = laid.map((_, index) => `[w${index}]`).join("");
129
+ parts.push(`[base]${mixed}amix=inputs=${laid.length + 1}:duration=first:normalize=0[speech]`);
130
+ return ["-v", "error", "-y", ...inputs, "-filter_complex", parts.join(";"), "-map", "[speech]", "-c:a", "libmp3lame", "-q:a", "2", output];
131
+ }
package/src/index.ts CHANGED
@@ -104,6 +104,7 @@ export {
104
104
  VIDEO_FORMATS,
105
105
  cameraPose,
106
106
  captionChunks,
107
+ splitAfterKept,
107
108
  crossfadeArgs,
108
109
  fitScale,
109
110
  fitsFrame,
@@ -119,6 +120,7 @@ export {
119
120
  widePose,
120
121
  type CameraPose,
121
122
  type CaptionChunk,
123
+ type CaptionChunkOptions,
122
124
  type CaptionLayout,
123
125
  type CrossfadeInput,
124
126
  type DeviceKind,
@@ -183,6 +185,7 @@ export {
183
185
  DEFAULT_AUTO_THRESHOLD,
184
186
  JUMP_TRANSITIONS,
185
187
  DEFAULT_CUT,
188
+ DEFAULT_CAPTION_KEEP_WITH_NEXT,
186
189
  DEFAULT_FILLERS,
187
190
  DEFAULT_MUSIC_VOLUME,
188
191
  DEFAULT_TRANSITIONS,
@@ -191,6 +194,7 @@ export {
191
194
  CAPTION_STYLES,
192
195
  DEFAULT_EDIT,
193
196
  getDefaultFillers,
197
+ getDeclickLevel,
194
198
  getFootageEdit,
195
199
  type CaptionPreset,
196
200
  type CaptionStyle,
@@ -203,9 +207,33 @@ export {
203
207
  type FootageClip,
204
208
  type FootageFilm,
205
209
  type FootageMusic,
210
+ type FootageSpeech,
206
211
  type FootageTransitions,
207
212
  type MusicSource,
208
213
  } from "./footage/film.js";
214
+ export {
215
+ DECLICK_GATE_FADE,
216
+ DECLICK_IMPULSE_DB,
217
+ DECLICK_LEVELS,
218
+ DECLICK_MAX_IMPULSE,
219
+ DECLICK_SETTINGS,
220
+ DECLICK_WORD_WINDOW,
221
+ buildDeclickDecodeArgs,
222
+ buildDeclickEncodeArgs,
223
+ declickSamples,
224
+ declickSpeech,
225
+ describeDeclick,
226
+ findImpulses,
227
+ getDeclickGain,
228
+ getGateWindows,
229
+ getRunningMedian,
230
+ type ActiveDeclickLevel,
231
+ type DeclickLevel,
232
+ type DeclickReport,
233
+ type DeclickSettings,
234
+ type DeclickSpeechOptions,
235
+ type TimeSpan as DeclickSpan,
236
+ } from "./footage/declick.js";
209
237
  export {
210
238
  MIN_CLIP_SECONDS,
211
239
  describeProbe,
@@ -295,6 +323,7 @@ export {
295
323
  diffEdl,
296
324
  edlSchema,
297
325
  findEdlProblems,
326
+ findSegmentAt,
298
327
  getEdlDuration,
299
328
  getEdlJsonSchema,
300
329
  getSegmentStarts,
@@ -307,6 +336,8 @@ export {
307
336
  type BuildEdlOptions,
308
337
  type Edl,
309
338
  type EdlAudio,
339
+ type EdlCaption,
340
+ type EdlCaptionBounds,
310
341
  type EdlClip,
311
342
  type EdlSegment,
312
343
  type SegmentMotion,
@@ -314,14 +345,23 @@ export {
314
345
  export { findRetakes, splitFilmSentences, splitSentences, type RetakeKind, type RetakeSuggestion, type Sentence } from "./footage/sentences.js";
315
346
  export {
316
347
  CAPTION_SAFE_ZONES,
348
+ applySegmentCaption,
317
349
  findMissingCaptionGlyphs,
350
+ getCaptionBounds,
351
+ getCaptionChunkLayouts,
352
+ getCaptionKeepsWithNext,
353
+ getFootageCaptionChunks,
318
354
  getCaptionPresetLayout,
319
355
  getCaptionSpans,
320
356
  getFootageCaptionLayout,
357
+ getSegmentCaptionLayout,
358
+ isSameCaptionPlace,
321
359
  phraseChunks,
322
360
  type CaptionSpan,
361
+ type CaptionWordsFilm,
323
362
  type MissingCaptionGlyphs,
324
363
  type PhraseChunk,
364
+ type PhraseChunkOptions,
325
365
  type SafeZone,
326
366
  } from "./footage/captions.js";
327
367
  export {
@@ -371,15 +411,29 @@ export {
371
411
  DEFAULT_LOUDNESS,
372
412
  buildLoudnessArgs,
373
413
  buildLoudnessMeasureArgs,
414
+ buildMixArgs,
415
+ findLoudnessProblems,
416
+ formatDb,
417
+ getFirstMixAttempt,
374
418
  getLoudnessFilter,
419
+ getMixFilter,
420
+ getMixGain,
421
+ getMixTolerance,
422
+ getNextMixAttempt,
375
423
  isSilent,
376
424
  measureLoudness,
425
+ MIX_ATTEMPTS,
426
+ MIX_ENCODE_HEADROOM,
427
+ MIX_LOUDNESS_TOLERANCE,
377
428
  normalizeLoudness,
378
429
  readLoudnessMeasurement,
379
430
  type LoudnessMeasureOutcome,
380
431
  type LoudnessMeasurement,
381
432
  type LoudnessOutcome,
382
433
  type LoudnessTarget,
434
+ type MixAttempt,
435
+ type MixLoudness,
436
+ type MixLoudnessTarget,
383
437
  } from "./footage/loudness.js";
384
438
  export {
385
439
  buildCoverArgs,
@@ -414,6 +468,7 @@ export { FFMPEG_FAILURE_STDERR_LINES, formatFfmpegCommand, splitFilterGraph, typ
414
468
  export { buildFfmpegFailureScript, FFMPEG_FAILURE_FILES, writeFfmpegFailure, type FfmpegFailureInput } from "./footage/ffmpeg-failure.js";
415
469
  export {
416
470
  estimateFootageFilm,
471
+ estimateSpeechRanges,
417
472
  findCachedStep,
418
473
  getDownloadPath,
419
474
  type EstimateFootageOptions,
@@ -421,6 +476,19 @@ export {
421
476
  type FootageEstimate,
422
477
  type FootageEstimateItem,
423
478
  } from "./footage/paid.js";
479
+ export {
480
+ DEFAULT_SPEECH_RANGE_MARGIN,
481
+ buildRangeAudioArgs,
482
+ buildRangeLayArgs,
483
+ getSpeechRangeCache,
484
+ getSpeechRangeWindows,
485
+ planSpeechRanges,
486
+ type LaidRange,
487
+ type SpeechRange,
488
+ type SpeechRangeClip,
489
+ type SpeechRangeWindow,
490
+ } from "./footage/speech-ranges.js";
491
+ export { isolateSpeechRanges, type IsolateSpeechRangesOptions, type IsolatedSpeech, type IsolatedSpeechRange } from "./footage/isolate-ranges.js";
424
492
  export { RENDER_MIN_FREE_BYTES, findLowDiskProblems, getFreeBytes, getRenderTempDir, type FreeBytesReader } from "./footage/disk.js";
425
493
  export { DRAFT_FILTERS, REQUIRED_DECODERS, REQUIRED_FILTERS, checkFootageTools, findBrowserProblem, readFfmpegListing, type FootageToolsOptions } from "./footage/tools.js";
426
494
  export {
@@ -431,6 +499,7 @@ export {
431
499
  findFootageMusic,
432
500
  getEdlPath,
433
501
  getFrame,
502
+ getSpeechChainFiles,
434
503
  prepareFootage,
435
504
  getFootageSentences,
436
505
  readEdlFile,
@@ -439,6 +508,7 @@ export {
439
508
  renderFootageFilm,
440
509
  transcribeFootage,
441
510
  type FinishedFootage,
511
+ type FinishedMix,
442
512
  type FootageBrand,
443
513
  type FootageMusicLookup,
444
514
  type FootageResult,