@softure-ai/marketing-kit 0.6.0 → 0.7.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 (97) hide show
  1. package/CHANGELOG.md +55 -0
  2. package/README.md +64 -8
  3. package/dist/cli/footage.d.ts.map +1 -1
  4. package/dist/cli/footage.js +5 -2
  5. package/dist/cli/footage.js.map +1 -1
  6. package/dist/compose/compose.d.ts.map +1 -1
  7. package/dist/compose/compose.js +3 -3
  8. package/dist/compose/compose.js.map +1 -1
  9. package/dist/compose/timeline.d.ts +16 -0
  10. package/dist/compose/timeline.d.ts.map +1 -1
  11. package/dist/compose/timeline.js +17 -1
  12. package/dist/compose/timeline.js.map +1 -1
  13. package/dist/config/config.d.ts.map +1 -1
  14. package/dist/config/config.js +18 -2
  15. package/dist/config/config.js.map +1 -1
  16. package/dist/config/schema.d.ts +16 -0
  17. package/dist/config/schema.d.ts.map +1 -1
  18. package/dist/config/schema.js +50 -3
  19. package/dist/config/schema.js.map +1 -1
  20. package/dist/footage/captions.d.ts +5 -1
  21. package/dist/footage/captions.d.ts.map +1 -1
  22. package/dist/footage/captions.js +6 -2
  23. package/dist/footage/captions.js.map +1 -1
  24. package/dist/footage/compose.d.ts +13 -2
  25. package/dist/footage/compose.d.ts.map +1 -1
  26. package/dist/footage/compose.js +75 -23
  27. package/dist/footage/compose.js.map +1 -1
  28. package/dist/footage/cuts.d.ts +44 -0
  29. package/dist/footage/cuts.d.ts.map +1 -0
  30. package/dist/footage/cuts.js +83 -0
  31. package/dist/footage/cuts.js.map +1 -0
  32. package/dist/footage/draft.d.ts +17 -3
  33. package/dist/footage/draft.d.ts.map +1 -1
  34. package/dist/footage/draft.js +28 -14
  35. package/dist/footage/draft.js.map +1 -1
  36. package/dist/footage/edl.d.ts +2 -1
  37. package/dist/footage/edl.d.ts.map +1 -1
  38. package/dist/footage/edl.js +5 -2
  39. package/dist/footage/edl.js.map +1 -1
  40. package/dist/footage/film.d.ts +42 -3
  41. package/dist/footage/film.d.ts.map +1 -1
  42. package/dist/footage/film.js +7 -1
  43. package/dist/footage/film.js.map +1 -1
  44. package/dist/footage/loudness.d.ts +20 -3
  45. package/dist/footage/loudness.d.ts.map +1 -1
  46. package/dist/footage/loudness.js +36 -18
  47. package/dist/footage/loudness.js.map +1 -1
  48. package/dist/footage/music.d.ts +3 -0
  49. package/dist/footage/music.d.ts.map +1 -1
  50. package/dist/footage/music.js +5 -0
  51. package/dist/footage/music.js.map +1 -1
  52. package/dist/footage/normalize.d.ts +9 -0
  53. package/dist/footage/normalize.d.ts.map +1 -1
  54. package/dist/footage/normalize.js +8 -4
  55. package/dist/footage/normalize.js.map +1 -1
  56. package/dist/footage/picture.d.ts +42 -0
  57. package/dist/footage/picture.d.ts.map +1 -0
  58. package/dist/footage/picture.js +141 -0
  59. package/dist/footage/picture.js.map +1 -0
  60. package/dist/footage/pipeline.d.ts +46 -1
  61. package/dist/footage/pipeline.d.ts.map +1 -1
  62. package/dist/footage/pipeline.js +128 -19
  63. package/dist/footage/pipeline.js.map +1 -1
  64. package/dist/footage/publish.d.ts +4 -2
  65. package/dist/footage/publish.d.ts.map +1 -1
  66. package/dist/footage/publish.js +8 -5
  67. package/dist/footage/publish.js.map +1 -1
  68. package/dist/footage/render.d.ts +17 -2
  69. package/dist/footage/render.d.ts.map +1 -1
  70. package/dist/footage/render.js +62 -13
  71. package/dist/footage/render.js.map +1 -1
  72. package/dist/index.d.ts +8 -6
  73. package/dist/index.d.ts.map +1 -1
  74. package/dist/index.js +8 -6
  75. package/dist/index.js.map +1 -1
  76. package/docker/footage-worker.Dockerfile +1 -0
  77. package/package.json +1 -1
  78. package/schema/marketing.schema.json +105 -4
  79. package/src/cli/footage.ts +4 -2
  80. package/src/compose/compose.ts +13 -3
  81. package/src/compose/timeline.ts +27 -1
  82. package/src/config/config.ts +18 -2
  83. package/src/config/schema.ts +52 -3
  84. package/src/footage/captions.ts +6 -2
  85. package/src/footage/compose.ts +86 -23
  86. package/src/footage/cuts.ts +104 -0
  87. package/src/footage/draft.ts +43 -14
  88. package/src/footage/edl.ts +5 -2
  89. package/src/footage/film.ts +47 -4
  90. package/src/footage/loudness.ts +38 -16
  91. package/src/footage/music.ts +7 -0
  92. package/src/footage/normalize.ts +8 -4
  93. package/src/footage/picture.ts +179 -0
  94. package/src/footage/pipeline.ts +166 -22
  95. package/src/footage/publish.ts +8 -5
  96. package/src/footage/render.ts +72 -13
  97. package/src/index.ts +36 -2
@@ -98,18 +98,21 @@ export function isPublishableAudio(audio: NonNullable<FilmFacts["audio"]>): bool
98
98
 
99
99
  /**
100
100
  * The final pass: each stream that is already publishable is copied, the other re-encoded, and the `moov` box moved
101
- * to the front. A film without sound keeps none.
101
+ * to the front. A film without sound keeps none. `audioFilter` (the mix's loudness pass) re-encodes the sound through it.
102
102
  */
103
- export function buildFinishArgs(input: string, facts: Pick<FilmFacts, "video" | "audio">, output: string): string[] {
103
+ export function buildFinishArgs(input: string, facts: Pick<FilmFacts, "video" | "audio">, output: string, options: { audioFilter?: string } = {}): string[] {
104
104
  const video = isPublishableVideo(facts.video)
105
105
  ? ["-c:v", "copy"]
106
106
  : ["-c:v", "libx264", "-profile:v", "high", "-pix_fmt", "yuv420p", "-preset", "medium", "-crf", String(VIDEO_CRF)];
107
+ const encodeAudio = ["-c:a", "aac", "-b:a", AUDIO_BITRATE, "-ar", String(FOOTAGE_SAMPLE_RATE), "-ac", "2"];
107
108
  const audio =
108
109
  facts.audio === null
109
110
  ? []
110
- : isPublishableAudio(facts.audio)
111
- ? ["-map", "0:a:0", "-c:a", "copy"]
112
- : ["-map", "0:a:0", "-c:a", "aac", "-b:a", AUDIO_BITRATE, "-ar", String(FOOTAGE_SAMPLE_RATE), "-ac", "2"];
111
+ : options.audioFilter !== undefined
112
+ ? ["-map", "0:a:0", "-af", options.audioFilter, ...encodeAudio]
113
+ : isPublishableAudio(facts.audio)
114
+ ? ["-map", "0:a:0", "-c:a", "copy"]
115
+ : ["-map", "0:a:0", ...encodeAudio];
113
116
  return ["-v", "error", "-y", "-i", input, "-map", "0:v:0", ...video, ...audio, "-movflags", "+faststart", output];
114
117
  }
115
118
 
@@ -1,21 +1,42 @@
1
1
  import { getSoundSpan, type Edl } from "./edl.js";
2
+ import { DEFAULT_EDIT, type FootageEdit } from "./film.js";
2
3
  import { FOOTAGE_SAMPLE_RATE } from "./normalize.js";
3
4
  import { volumeExpression, type VolumeKeyframe } from "./music.js";
4
5
 
5
6
  /** ffmpeg steps of the footage render: pure argument builders, tested without ffmpeg (`runFfmpeg` in `process.ts` runs them). */
6
7
 
7
- /** A short fade at every cut of the speech track, so a cut never clicks. */
8
- const CUT_FADE_SECONDS = 0.02;
9
8
  const MUSIC_FADE_IN = 1;
10
9
  const MUSIC_FADE_OUT = 1.5;
11
10
 
12
11
  const r3 = (value: number): number => Math.round(value * 1000) / 1000 || 0;
12
+ const r4 = (value: number): number => Math.round(value * 10000) / 10000 || 0;
13
+
14
+ /** How the speech track is joined at the cuts. */
15
+ export interface SpeechCutOptions {
16
+ /** The fade at every cut, in seconds; default 0.02 (`DEFAULT_EDIT.cutAudioFadeMs`), so a cut never clicks. */
17
+ fadeSeconds?: number;
18
+ /**
19
+ * Cross-fade the two sides of every cut over `fadeSeconds`, centred on the cut: each side runs on into its source
20
+ * for half the fade (silence where the source ends). By default each side fades out and in (a short dip).
21
+ */
22
+ isCrossfade?: boolean;
23
+ }
24
+
25
+ /** The film's cut sound settings (`edit.cutAudioFadeMs`, `edit.isCutAudioCrossfade`) as `buildSpeechArgs` takes them. */
26
+ export function getSpeechCutOptions(edit: Pick<FootageEdit, "cutAudioFadeMs" | "isCutAudioCrossfade">): Required<SpeechCutOptions> {
27
+ return { fadeSeconds: r4(edit.cutAudioFadeMs / 1000), isCrossfade: edit.isCutAudioCrossfade };
28
+ }
13
29
 
14
30
  /**
15
31
  * The speech track: every segment's sound cut from its sound span (its own clip's, or `audio`'s: a J/L-cut or b-roll
16
- * over speech) and joined in order; `audio.ownVolume` keeps the picture clip's own sound under it.
32
+ * over speech) and joined in order; `audio.ownVolume` keeps the picture clip's own sound under it. Each cut fades over
33
+ * `fadeSeconds`: a short dip, or with `isCrossfade` a cross-fade centred on the cut. Either way the track is exactly
34
+ * the cut's length and every word stays under its picture.
17
35
  */
18
- export function buildSpeechArgs(edl: Edl, sources: Record<string, string>, output: string): string[] {
36
+ export function buildSpeechArgs(edl: Edl, sources: Record<string, string>, output: string, options: SpeechCutOptions = {}): string[] {
37
+ const fadeSeconds = options.fadeSeconds ?? r4(DEFAULT_EDIT.cutAudioFadeMs / 1000);
38
+ if (!(fadeSeconds > 0)) throw new Error(`The speech track's cut fade must be above 0 seconds, got ${String(fadeSeconds)}.`);
39
+ const isCrossfade = options.isCrossfade === true && edl.segments.length > 1;
19
40
  const inputs: string[] = [];
20
41
  const parts: string[] = [];
21
42
  const getSource = (clip: string): string => {
@@ -23,30 +44,68 @@ export function buildSpeechArgs(edl: Edl, sources: Record<string, string>, outpu
23
44
  if (source === undefined) throw new Error(`No audio for clip "${clip}" of the EDL.`);
24
45
  return source;
25
46
  };
47
+ const addInput = (clip: string): number => {
48
+ const input = inputs.length / 2;
49
+ inputs.push("-i", getSource(clip));
50
+ return input;
51
+ };
52
+ const format = `asetpts=PTS-STARTPTS,aformat=sample_rates=${FOOTAGE_SAMPLE_RATE}:channel_layouts=stereo`;
26
53
  const cut = (input: number, span: { start: number; end: number }, duration: number): string =>
27
- `[${input}:a]atrim=start=${span.start}:end=${span.end},asetpts=PTS-STARTPTS,aformat=sample_rates=${FOOTAGE_SAMPLE_RATE}:channel_layouts=stereo,apad=whole_dur=${duration}`;
54
+ `[${input}:a]atrim=start=${span.start}:end=${span.end},${format},apad=whole_dur=${duration}`;
55
+ const last = edl.segments.length - 1;
56
+ const half = r4(fadeSeconds / 2);
28
57
  edl.segments.forEach((segment, index) => {
29
58
  const sound = getSoundSpan(segment);
30
59
  const duration = r3(segment.end - segment.start);
31
- const fades = `afade=t=in:d=${CUT_FADE_SECONDS},afade=t=out:st=${r3(Math.max(0, duration - CUT_FADE_SECONDS))}:d=${CUT_FADE_SECONDS}`;
32
- const input = inputs.length / 2;
33
- inputs.push("-i", getSource(sound.clip));
34
60
  const own = segment.audio?.ownVolume ?? 0;
61
+ if (isCrossfade) {
62
+ // Half the fade on each side of the cut, read on into the source; where the source starts too late, silence.
63
+ const head = index === 0 ? 0 : half;
64
+ const tail = index === last ? 0 : half;
65
+ const length = r4(duration + head + tail);
66
+ const extend = (input: number, span: { start: number; end: number }): string => {
67
+ const lead = Math.min(head, span.start);
68
+ const silence = Math.round((head - lead) * 1000);
69
+ const delay = silence > 0 ? `,adelay=${silence}:all=1` : "";
70
+ return `[${input}:a]atrim=start=${r4(span.start - lead)}:end=${r4(span.start + duration + tail)},${format}${delay},apad=whole_dur=${length},atrim=end=${length}`;
71
+ };
72
+ const input = addInput(sound.clip);
73
+ if (own <= 0) {
74
+ parts.push(`${extend(input, sound)}[a${index}]`);
75
+ return;
76
+ }
77
+ const ownInput = addInput(segment.clip);
78
+ parts.push(`${extend(input, sound)}[s${index}]`);
79
+ parts.push(`${extend(ownInput, segment)},volume=${own}[o${index}]`);
80
+ parts.push(`[s${index}][o${index}]amix=inputs=2:duration=first:normalize=0[a${index}]`);
81
+ return;
82
+ }
83
+ const fades = `afade=t=in:d=${fadeSeconds},afade=t=out:st=${r3(Math.max(0, duration - fadeSeconds))}:d=${fadeSeconds}`;
84
+ const input = addInput(sound.clip);
35
85
  // A borrowed span may be a few milliseconds longer than the picture: it is cut to the picture's length.
36
86
  const fit = segment.audio === undefined ? "" : `,atrim=end=${duration}`;
37
87
  if (own <= 0) {
38
88
  parts.push(`${cut(input, sound, duration)}${fit},${fades}[a${index}]`);
39
89
  return;
40
90
  }
41
- const ownInput = inputs.length / 2;
42
- inputs.push("-i", getSource(segment.clip));
91
+ const ownInput = addInput(segment.clip);
43
92
  parts.push(`${cut(input, sound, duration)},atrim=end=${duration}[s${index}]`);
44
93
  parts.push(`${cut(ownInput, segment, duration)},atrim=end=${duration},volume=${own}[o${index}]`);
45
94
  parts.push(`[s${index}][o${index}]amix=inputs=2:duration=first:normalize=0,${fades}[a${index}]`);
46
95
  });
47
- const joined = edl.segments.map((_, index) => `[a${index}]`).join("");
48
- const graph = `${parts.join(";")};${joined}concat=n=${edl.segments.length}:v=0:a=1[speech]`;
49
- return ["-v", "error", "-y", ...inputs, "-filter_complex", graph, "-map", "[speech]", "-c:a", "libmp3lame", "-q:a", "2", output];
96
+ if (isCrossfade) {
97
+ let joined = "a0";
98
+ for (let index = 1; index <= last; index++) {
99
+ parts.push(`[${joined}][a${index}]acrossfade=d=${fadeSeconds}:c1=tri:c2=tri[x${index}]`);
100
+ joined = `x${index}`;
101
+ }
102
+ const total = r3(edl.segments.reduce((sum, segment) => sum + r3(segment.end - segment.start), 0));
103
+ parts.push(`[${joined}]afade=t=in:d=${fadeSeconds},afade=t=out:st=${r3(Math.max(0, total - fadeSeconds))}:d=${fadeSeconds}[speech]`);
104
+ } else {
105
+ const joined = edl.segments.map((_, index) => `[a${index}]`).join("");
106
+ parts.push(`${joined}concat=n=${edl.segments.length}:v=0:a=1[speech]`);
107
+ }
108
+ return ["-v", "error", "-y", ...inputs, "-filter_complex", parts.join(";"), "-map", "[speech]", "-c:a", "libmp3lame", "-q:a", "2", output];
50
109
  }
51
110
 
52
111
  /** The music track: looped to the film's length, ducked by the keyframes, faded in and out. */
package/src/index.ts CHANGED
@@ -94,6 +94,8 @@ export { describeVoiceoverBatch, produceVoiceovers, type VoiceoverBatchItem, typ
94
94
  export { getPlaceholderKey, isPlaceholderKey, makePlaceholderWords, writePlaceholderVoiceover, type PlaceholderPace, type WritePlaceholderOptions } from "./voice/placeholder.js";
95
95
  export {
96
96
  BROWSER_BAR_HEIGHT,
97
+ CAPTION_LINE_HEIGHT,
98
+ CAPTION_PILL_PADDING,
97
99
  DEVICE_KINDS,
98
100
  LAYOUTS,
99
101
  LAYOUT_NAMES,
@@ -105,6 +107,7 @@ export {
105
107
  crossfadeArgs,
106
108
  fitScale,
107
109
  fitsFrame,
110
+ getCaptionPositionCss,
108
111
  getGeometry,
109
112
  getLayoutName,
110
113
  getTransitionSeconds,
@@ -177,10 +180,13 @@ export {
177
180
  CLIP_FITS,
178
181
  CLIP_ROLES,
179
182
  CUT_TRANSITIONS,
183
+ DEFAULT_AUTO_THRESHOLD,
184
+ JUMP_TRANSITIONS,
180
185
  DEFAULT_CUT,
181
186
  DEFAULT_FILLERS,
182
187
  DEFAULT_MUSIC_VOLUME,
183
188
  DEFAULT_TRANSITIONS,
189
+ CAPTION_MIN_FONT_SCALE,
184
190
  CAPTION_PRESETS,
185
191
  CAPTION_STYLES,
186
192
  DEFAULT_EDIT,
@@ -193,6 +199,7 @@ export {
193
199
  type ClipRole,
194
200
  type CutOptions,
195
201
  type CutTransition,
202
+ type JumpTransition,
196
203
  type FootageClip,
197
204
  type FootageFilm,
198
205
  type FootageMusic,
@@ -316,10 +323,20 @@ export {
316
323
  type PhraseChunk,
317
324
  type SafeZone,
318
325
  } from "./footage/captions.js";
326
+ export {
327
+ CUT_THUMBNAIL,
328
+ buildCutFrameArgs,
329
+ chooseCutTransition,
330
+ chooseCutTransitions,
331
+ findAutoCuts,
332
+ measureFrameDifference,
333
+ type ChooseCutTransitionsOptions,
334
+ type CutMeasure,
335
+ } from "./footage/cuts.js";
319
336
  export { MAX_FRAMES, buildFrameArgs, extractFrames, getFrameTimes, type ExtractFramesOptions, type ExtractedFrame, type FrameSpacing } from "./footage/frames.js";
320
- export { duckingKeyframes, getSpeechSpans, volumeExpression, type DuckingOptions, type VolumeKeyframe } from "./footage/music.js";
337
+ export { duckingKeyframes, getDuckingOptions, getSpeechSpans, volumeExpression, type DuckingOptions, type VolumeKeyframe } from "./footage/music.js";
321
338
  export { END_CARD_SECONDS, FADE_SECONDS, composeFootage, getFootageFilmSeconds, getSegmentScales, type FootageComposeAssets, type FootageComposeInput } from "./footage/compose.js";
322
- export { buildCutPreviewArgs, buildLastFrameArgs, buildMusicArgs, buildSpeechArgs } from "./footage/render.js";
339
+ export { buildCutPreviewArgs, buildLastFrameArgs, buildMusicArgs, buildSpeechArgs, getSpeechCutOptions, type SpeechCutOptions } from "./footage/render.js";
323
340
  export {
324
341
  FOOTAGE_DRAFT_FONT,
325
342
  FOOTAGE_DRAFT_WIDTH,
@@ -334,13 +351,26 @@ export {
334
351
  type FootageDraftCaptionsInput,
335
352
  type RenderFootageDraftOptions,
336
353
  } from "./footage/draft.js";
354
+ export {
355
+ buildPictureConcatArgs,
356
+ buildPictureList,
357
+ buildPicturePieceArgs,
358
+ getPictureFrames,
359
+ planFootagePicture,
360
+ type PictureFadeTail,
361
+ type PicturePiece,
362
+ type PicturePieceArgsInput,
363
+ } from "./footage/picture.js";
337
364
  export {
338
365
  DEFAULT_LOUDNESS,
339
366
  buildLoudnessArgs,
340
367
  buildLoudnessMeasureArgs,
368
+ getLoudnessFilter,
341
369
  isSilent,
370
+ measureLoudness,
342
371
  normalizeLoudness,
343
372
  readLoudnessMeasurement,
373
+ type LoudnessMeasureOutcome,
344
374
  type LoudnessMeasurement,
345
375
  type LoudnessOutcome,
346
376
  type LoudnessTarget,
@@ -373,7 +403,10 @@ export {
373
403
  export { RENDER_MIN_FREE_BYTES, findLowDiskProblems, getFreeBytes, getRenderTempDir, type FreeBytesReader } from "./footage/disk.js";
374
404
  export { DRAFT_FILTERS, REQUIRED_DECODERS, REQUIRED_FILTERS, checkFootageTools, findBrowserProblem, readFfmpegListing, type FootageToolsOptions } from "./footage/tools.js";
375
405
  export {
406
+ CUTS_FILE,
376
407
  cutFootage,
408
+ cutFootageFilm,
409
+ describeCutMeasures,
377
410
  getEdlPath,
378
411
  getFrame,
379
412
  prepareFootage,
@@ -388,6 +421,7 @@ export {
388
421
  type FootageResult,
389
422
  type FootageRunOptions,
390
423
  type PreparedClip,
424
+ type CutFootageFilmOptions,
391
425
  type RenderFootageFilmOptions,
392
426
  type RenderFootageOptions,
393
427
  type RenderedFootage,