@softure-ai/marketing-kit 0.34.0 → 0.36.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 (102) hide show
  1. package/CHANGELOG.md +59 -0
  2. package/NOTICE +6 -0
  3. package/README.md +49 -1
  4. package/dist/config/config.d.ts.map +1 -1
  5. package/dist/config/config.js +1 -0
  6. package/dist/config/config.js.map +1 -1
  7. package/dist/config/schema.d.ts +10 -0
  8. package/dist/config/schema.d.ts.map +1 -1
  9. package/dist/config/schema.js +9 -3
  10. package/dist/config/schema.js.map +1 -1
  11. package/dist/footage/captions.d.ts +22 -2
  12. package/dist/footage/captions.d.ts.map +1 -1
  13. package/dist/footage/captions.js +23 -4
  14. package/dist/footage/captions.js.map +1 -1
  15. package/dist/footage/compose.d.ts +11 -1
  16. package/dist/footage/compose.d.ts.map +1 -1
  17. package/dist/footage/compose.js +51 -17
  18. package/dist/footage/compose.js.map +1 -1
  19. package/dist/footage/draft-overlays.d.ts +6 -0
  20. package/dist/footage/draft-overlays.d.ts.map +1 -1
  21. package/dist/footage/draft-overlays.js +188 -4
  22. package/dist/footage/draft-overlays.js.map +1 -1
  23. package/dist/footage/draft.d.ts +14 -1
  24. package/dist/footage/draft.d.ts.map +1 -1
  25. package/dist/footage/draft.js +117 -17
  26. package/dist/footage/draft.js.map +1 -1
  27. package/dist/footage/drawn-transitions.d.ts +63 -0
  28. package/dist/footage/drawn-transitions.d.ts.map +1 -0
  29. package/dist/footage/drawn-transitions.js +177 -0
  30. package/dist/footage/drawn-transitions.js.map +1 -0
  31. package/dist/footage/edl.d.ts +42 -0
  32. package/dist/footage/edl.d.ts.map +1 -1
  33. package/dist/footage/edl.js +72 -2
  34. package/dist/footage/edl.js.map +1 -1
  35. package/dist/footage/film.d.ts +29 -5
  36. package/dist/footage/film.d.ts.map +1 -1
  37. package/dist/footage/film.js +13 -3
  38. package/dist/footage/film.js.map +1 -1
  39. package/dist/footage/hand-font.d.ts +16 -0
  40. package/dist/footage/hand-font.d.ts.map +1 -0
  41. package/dist/footage/hand-font.js +43 -0
  42. package/dist/footage/hand-font.js.map +1 -0
  43. package/dist/footage/overlay-html.d.ts +1 -0
  44. package/dist/footage/overlay-html.d.ts.map +1 -1
  45. package/dist/footage/overlay-html.js +134 -8
  46. package/dist/footage/overlay-html.js.map +1 -1
  47. package/dist/footage/overlay-motion.d.ts +35 -0
  48. package/dist/footage/overlay-motion.d.ts.map +1 -1
  49. package/dist/footage/overlay-motion.js +45 -0
  50. package/dist/footage/overlay-motion.js.map +1 -1
  51. package/dist/footage/overlay-schema.d.ts +48 -6
  52. package/dist/footage/overlay-schema.d.ts.map +1 -1
  53. package/dist/footage/overlay-schema.js +71 -18
  54. package/dist/footage/overlay-schema.js.map +1 -1
  55. package/dist/footage/overlays.d.ts +125 -1
  56. package/dist/footage/overlays.d.ts.map +1 -1
  57. package/dist/footage/overlays.js +265 -8
  58. package/dist/footage/overlays.js.map +1 -1
  59. package/dist/footage/picture.d.ts +10 -2
  60. package/dist/footage/picture.d.ts.map +1 -1
  61. package/dist/footage/picture.js +53 -13
  62. package/dist/footage/picture.js.map +1 -1
  63. package/dist/footage/pipeline.d.ts.map +1 -1
  64. package/dist/footage/pipeline.js +14 -4
  65. package/dist/footage/pipeline.js.map +1 -1
  66. package/dist/footage/split-screen.d.ts +167 -0
  67. package/dist/footage/split-screen.d.ts.map +1 -0
  68. package/dist/footage/split-screen.js +233 -0
  69. package/dist/footage/split-screen.js.map +1 -0
  70. package/dist/footage/tools.d.ts +1 -1
  71. package/dist/footage/tools.d.ts.map +1 -1
  72. package/dist/footage/tools.js +1 -1
  73. package/dist/footage/tools.js.map +1 -1
  74. package/dist/index.d.ts +8 -5
  75. package/dist/index.d.ts.map +1 -1
  76. package/dist/index.js +8 -5
  77. package/dist/index.js.map +1 -1
  78. package/fonts/Caveat-SemiBold-Latin.ttf +0 -0
  79. package/fonts/LICENSE-Caveat.txt +93 -0
  80. package/fonts/README.md +14 -0
  81. package/package.json +1 -1
  82. package/schema/edl.schema.json +167 -11
  83. package/schema/marketing.schema.json +19 -4
  84. package/src/config/config.ts +1 -0
  85. package/src/config/schema.ts +9 -3
  86. package/src/footage/captions.ts +32 -4
  87. package/src/footage/compose.ts +44 -11
  88. package/src/footage/draft-overlays.ts +217 -2
  89. package/src/footage/draft.ts +137 -17
  90. package/src/footage/drawn-transitions.ts +214 -0
  91. package/src/footage/edl.ts +67 -2
  92. package/src/footage/film.ts +23 -4
  93. package/src/footage/hand-font.ts +47 -0
  94. package/src/footage/overlay-html.ts +141 -7
  95. package/src/footage/overlay-motion.ts +49 -0
  96. package/src/footage/overlay-schema.ts +78 -19
  97. package/src/footage/overlays.ts +311 -10
  98. package/src/footage/picture.ts +58 -15
  99. package/src/footage/pipeline.ts +14 -4
  100. package/src/footage/split-screen.ts +319 -0
  101. package/src/footage/tools.ts +1 -1
  102. package/src/index.ts +62 -0
@@ -7,25 +7,28 @@ import type { BrandColors } from "../config/colors.js";
7
7
  import { err, ok } from "./failure.js";
8
8
  import type { TimedWord } from "../voice/voiceover.js";
9
9
  import { CAPTION_HIGHLIGHT_BOX_PADDING_EM, CAPTION_HIGHLIGHT_SECONDS, CAPTION_UNDERLINE_EM, getCaptionHighlight, type CaptionHighlightLook } from "./caption-highlight.js";
10
- import { getCaptionChunkLayouts, getCaptionSpans, getFootageCaptionChunks, getFootageCaptionLayout, isSameCaptionPlace, type CaptionWordsFilm } from "./captions.js";
10
+ import { getCaptionChunkLayouts, getCaptionRibbonTilt, getCaptionSpans, getFootageCaptionChunks, getFootageCaptionLayout, isSameCaptionPlace, toCaptionDisplayText, type CaptionWordsFilm } from "./captions.js";
11
11
  import { getCameraMoveFrames, getCameraOrigin, getCameraScaleExpression, type CameraAnchor, type EdlCamera } from "./camera.js";
12
12
  import { getSegmentFadeFrames, getSegmentScales, getSegmentZoomEases } from "./compose.js";
13
+ import { buildDrawnTransitionFilters, DRAWN_TRANSITION_FRAMES, FRAME_TIMING, isDrawnTransition, STUTTER_FRAMES, type DrawnTransition } from "./drawn-transitions.js";
13
14
  import { toAssColor } from "./draft-color.js";
14
15
  import { buildDraftOverlayEvents, getDraftOverlayStyles, getRoundedRectDrawing } from "./draft-overlays.js";
15
16
  import { getCaptionCornerRadius, getCornerRadiusPx, getStylePadding, type BrandStyle } from "./brand-style.js";
16
17
  import { getDraftBoxEvents } from "./draft-boxes.js";
17
18
  import { createDraftTextMeasure, wrapDraftLine, type DraftTextMeasure } from "./draft-text-width.js";
18
19
  import { CAPTION_PILL_PADDING } from "../compose/timeline.js";
19
- import { estimateTextWidth } from "./overlays.js";
20
+ import { estimateTextWidth, isHandFontNeeded } from "./overlays.js";
21
+ import { HAND_FONT } from "./hand-font.js";
20
22
  import type { OverlayColors } from "./overlay-html.js";
21
23
  import { resolveEdlOverlays, type OverlayFontRole, type ResolvedOverlay } from "./overlays.js";
22
24
  import { chooseFootageDraftFont } from "./draft-font.js";
23
25
  import { getEdlDuration, getSegmentStarts, remapWords, type Edl } from "./edl.js";
24
26
  import { declickSpeech, describeDeclick, type DeclickReport } from "./declick.js";
25
- import { getDeclickLevel, getFootageEdit, type FootageFilm } from "./film.js";
27
+ import { CAPTION_RIBBON, getDeclickLevel, getFootageEdit, type FootageFilm } from "./film.js";
26
28
  import { buildFilmMixArgs } from "./film-mix.js";
27
29
  import { DEFAULT_LOUDNESS, formatDb, getLoudnessVerdict, measureLoudness, normalizeLoudness, type MixLoudnessTarget } from "./loudness.js";
28
30
  import { duckingKeyframes, getDuckingOptions } from "./music.js";
31
+ import { buildSplitScreenFilters, getSplitLayerInputArgs, writeSplitLayers } from "./split-screen.js";
29
32
  import { FOOTAGE_FPS, getThreadArgs, type Frame } from "./normalize.js";
30
33
  import {
31
34
  findFootageMusic,
@@ -122,7 +125,7 @@ function toAssText(text: string): string {
122
125
  export type FootageDraftCaptionColors = Pick<BrandColors, "captionBackground" | "captionText" | "captionHighlight" | "captionHighlightBox" | "captionHighlightText">;
123
126
 
124
127
  export interface FootageDraftCaptionsInput {
125
- film: Pick<FootageFilm, "captions" | "captionStyle" | "captionHighlightStyle"> & CaptionWordsFilm;
128
+ film: Pick<FootageFilm, "captions" | "captionStyle" | "captionHighlightStyle" | "captionRibbonTilt"> & CaptionWordsFilm;
126
129
  edl: Edl;
127
130
  /** The film's words in film time (`remapWords`). */
128
131
  words: TimedWord[];
@@ -277,6 +280,47 @@ function getDrawnPill(input: DrawnPillInput): DrawnPill {
277
280
  return { breaks, events: getDraftBoxEvents({ layer: 0, at, styleName: "CaptionShape", box, radius, color: input.colors.background, accent: input.colors.accent, style, scale }), words };
278
281
  }
279
282
 
283
+ interface RibbonInput {
284
+ text: string;
285
+ span: { start: number; end: number };
286
+ place: CaptionLayout;
287
+ frame: Frame;
288
+ tilt: number;
289
+ measure: DraftTextMeasure;
290
+ colors: { background: string; text: string };
291
+ }
292
+
293
+ /**
294
+ * A `ribbon` chunk: its capitals broken greedily into lines that fit the caption box less a strip's padding, each line
295
+ * on its own flat strip (`CAPTION_RIBBON`) and centred on the box's axis, the block hung from the box's foot (or top)
296
+ * and turned `tilt` degrees about its middle (`\org`, `\frz`), as the render turns its caption box.
297
+ */
298
+ function getRibbonEvents(input: RibbonInput): string[] {
299
+ const { place, frame, measure } = input;
300
+ const { lineHeight, padding, radius } = CAPTION_RIBBON;
301
+ const size = place.fontSize;
302
+ const scale = frame.width / 1080;
303
+ const areaWidth = frame.width - place.left - place.right;
304
+ const pad = { x: padding.x * size, y: padding.y * size };
305
+ const lines = wrapDraftLine(input.text.split(" "), areaWidth - 2 * pad.x, size, measure).map((line) => line.join(" "));
306
+ const step = lineHeight * size;
307
+ const blockTop = place.bottom === undefined ? place.top : frame.height - place.bottom - lines.length * step;
308
+ const centre = { x: place.left + areaWidth / 2, y: blockTop + (lines.length * step) / 2 };
309
+ const turn = `\\org(${String(Math.round(centre.x))},${String(Math.round(centre.y))})\\frz${String(input.tilt)}`;
310
+ const at = `${toAssTime(input.span.start)},${toAssTime(input.span.end)}`;
311
+ const text = toAssColor(input.colors.text);
312
+ return lines.flatMap((line, index) => {
313
+ const width = measure(line, size) + 2 * pad.x;
314
+ // libass draws a line one font size tall: the strip is that plus its padding, both centred in the line's step.
315
+ const textTop = blockTop + index * step + (step - size) / 2;
316
+ const strip = { left: centre.x - width / 2, top: textTop - pad.y, width, height: size + 2 * pad.y };
317
+ return [
318
+ ...getDraftBoxEvents({ layer: 0, at, styleName: "CaptionShape", box: strip, radius: radius * scale, color: input.colors.background, accent: input.colors.background, style: { shadow: "none", border: "none" }, scale, motion: turn }),
319
+ `Dialogue: 1,${at},CaptionShape,,0,0,0,,{\\an8\\pos(${String(Math.round(centre.x))},${String(Math.round(textTop))})${turn}\\b1\\1c&H${text.slice(4)}&\\1a&H${text.slice(2, 4)}&\\bord0\\shad0}${toAssText(line)}`,
320
+ ];
321
+ });
322
+ }
323
+
280
324
  /** Where the draft's underline sits under a line, in font sizes: libass draws a line one font size tall, its baseline near 0.8. */
281
325
  const DRAFT_UNDERLINE_TOP_EM = 0.9;
282
326
 
@@ -320,6 +364,7 @@ function getDraftHighlightLook(film: Pick<FootageFilm, "captionStyle" | "caption
320
364
  export function buildFootageDraftCaptions(input: FootageDraftCaptionsInput): string | null {
321
365
  const overlays = input.overlays ?? [];
322
366
  const isHighlight = input.film.captionStyle === "highlight";
367
+ const isRibbon = input.film.captionStyle === "ribbon";
323
368
  // No chunks without captions (`getFootageCaptionChunks`): then only the overlays, if any, make the file.
324
369
  const chunks = input.film.captions ? getFootageCaptionChunks(input.film, input.words) : [];
325
370
  if (chunks.length === 0 && overlays.length === 0) return null;
@@ -389,6 +434,10 @@ export function buildFootageDraftCaptions(input: FootageDraftCaptionsInput): str
389
434
  const pillColors = { background: colors.captionBackground, accent: lit.style === "box" ? lit.box : colors.captionHighlight };
390
435
  const events = chunks.flatMap((chunk, index) => {
391
436
  const span = spans[index] as { start: number; end: number };
437
+ if (isRibbon) {
438
+ const ribbonText = toCaptionDisplayText(input.film, chunk.words.map((word) => word.text.replace(/\u00a0/g, " ")).join(" "), input.locale ?? "en-US");
439
+ return getRibbonEvents({ text: ribbonText, span, place: places[index] ?? caption, frame, tilt: getCaptionRibbonTilt(input.film), measure, colors: { background: colors.captionBackground, text: colors.captionText } });
440
+ }
392
441
  const styleName = styleNames[index] ?? "Caption";
393
442
  const pill =
394
443
  style === undefined ? null : getDrawnPill({ words: chunk.words.map((word) => word.text.replace(/\u00a0/g, " ")), span, place: places[index] ?? caption, frame, style, measure, colors: pillColors });
@@ -415,7 +464,7 @@ export function buildFootageDraftCaptions(input: FootageDraftCaptionsInput): str
415
464
  "[V4+ Styles]",
416
465
  "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding",
417
466
  ...styles.map((line) => `Style: ${line}`),
418
- ...(style === undefined || chunks.length === 0 ? [] : [`Style: CaptionShape,${family},${String(caption.fontSize)},&H00FFFFFF,&H00FFFFFF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,0,0,7,0,0,0,1`]),
467
+ ...((style === undefined && !isRibbon) || chunks.length === 0 ? [] : [`Style: CaptionShape,${family},${String(caption.fontSize)},&H00FFFFFF,&H00FFFFFF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,0,0,7,0,0,0,1`]),
419
468
  ...(overlays.length === 0 ? [] : getDraftOverlayStyles(family, input.overlayColors ?? FOOTAGE_DRAFT_OVERLAY_COLORS)),
420
469
  "",
421
470
  "[Events]",
@@ -454,6 +503,8 @@ export interface FootageDraftArgsInput {
454
503
  overlays?: readonly ResolvedOverlay[];
455
504
  /** The folder libass loads the captions' font from, or null for the system's fonts. */
456
505
  fontsDir: string | null;
506
+ /** Each split segment's layer (`renderSplitLayerPng` at the draft's size), by segment id; needed for every split. */
507
+ splitLayers?: Record<string, string>;
457
508
  output: string;
458
509
  /**
459
510
  * ffmpeg's threads for every segment's decoder, the filter graph and the encoder; by default ffmpeg's own choice,
@@ -472,6 +523,13 @@ export interface DraftSegmentPlan {
472
523
  start: number;
473
524
  /** The cross-fade from the segment before, in seconds; 0 for a plain cut. */
474
525
  fade: number;
526
+ /**
527
+ * The drawn transition from the segment before (`whip`, `card`, `paper`) and its frames, over which the outgoing
528
+ * segment plays on under this one as under a fade; null for any other cut, or a segment too short for it.
529
+ */
530
+ drawn: { kind: DrawnTransition; frames: number } | null;
531
+ /** Whether the segment starts on a `stutter`: `STUTTER_FRAMES` frames at the full frame, then `scale`. */
532
+ isStutter: boolean;
475
533
  /** The zoom the segment starts at (`getSegmentScales`). */
476
534
  scale: number;
477
535
  /** The zoom it ends at: above `scale` for a `kenburns` segment, `scale` otherwise. */
@@ -502,13 +560,25 @@ export function planFootageDraft(film: Pick<FootageFilm, "edit">, edl: Edl, over
502
560
  const eases = getSegmentZoomEases(edl, edit);
503
561
  const starts = getSegmentStarts(edl);
504
562
  const fades = edl.segments.map((segment, index) => r3(Math.min(getSegmentFadeFrames(edl, index, edit) / FOOTAGE_FPS, segment.end - segment.start)));
563
+ // A drawn transition only on a segment longer than its frames (the EDL check refuses a shorter one).
564
+ const drawn = edl.segments.map((segment, index) =>
565
+ index > 0 && isDrawnTransition(segment.transition) && Math.round((segment.end - segment.start) * FOOTAGE_FPS) > DRAWN_TRANSITION_FRAMES[segment.transition]
566
+ ? { kind: segment.transition, frames: DRAWN_TRANSITION_FRAMES[segment.transition] }
567
+ : null,
568
+ );
569
+ const overlaps = edl.segments.map((_, index) => {
570
+ const own = drawn[index];
571
+ return own === null || own === undefined ? (fades[index] as number) : r3(own.frames / FOOTAGE_FPS);
572
+ });
505
573
  return edl.segments.map((segment, index) => {
506
574
  const scale = scales[index] as number;
507
575
  return {
508
576
  length: r3(segment.end - segment.start),
509
- seconds: r3(segment.end - segment.start + (fades[index + 1] ?? 0)),
577
+ seconds: r3(segment.end - segment.start + (overlaps[index + 1] ?? 0)),
510
578
  start: starts[index] as number,
511
579
  fade: fades[index] as number,
580
+ drawn: drawn[index] ?? null,
581
+ isStutter: segment.transition === "stutter",
512
582
  scale,
513
583
  endScale: segment.camera !== undefined ? segment.camera.to : segment.motion === "kenburns" ? r4(scale * kenBurnsScale) : scale,
514
584
  startScale: (eases[index] as number) > 0 ? (scales[index - 1] as number) : scale,
@@ -542,6 +612,8 @@ function buildPictureFilters(plan: DraftSegmentPlan, draft: Frame): string[] {
542
612
  `zoompan=z='${zoom}':x='(iw-iw/zoom)*${origin.x}':y='(ih-ih/zoom)*${origin.y}':d=1:s=${draft.width}x${draft.height}:fps=${FOOTAGE_FPS}`;
543
613
  // The zoom runs over the segment's own length, as the render's tween does, and holds through a fade's tail.
544
614
  const frames = Math.max(1, Math.round(plan.length * FOOTAGE_FPS));
615
+ // A stutter: the full frame for its first frames, then its tight framing (it has no move and no punch-in).
616
+ if (plan.isStutter) return [zoompan(`if(lt(on,${STUTTER_FRAMES}),1,${plan.scale})`)];
545
617
  const own =
546
618
  plan.easeFrames > 0
547
619
  ? `${plan.startScale}+(${r4(plan.scale - plan.startScale)})*(1-pow(1-min(on/${plan.easeFrames},1),2))`
@@ -562,6 +634,28 @@ function buildPictureFilters(plan: DraftSegmentPlan, draft: Frame): string[] {
562
634
  return [`scale=${size}`];
563
635
  }
564
636
 
637
+ /**
638
+ * A drawn transition in the draft: the cut so far is split where the incoming segment starts, its tail (the outgoing
639
+ * segment playing on) blended with the incoming head as the render's picture blends them, and the rest of the
640
+ * incoming segment follows.
641
+ */
642
+ function buildDrawnJoin(input: { joined: string; incoming: string; output: string; plan: DraftSegmentPlan; drawn: { kind: DrawnTransition; frames: number }; frame: Frame; index: number }): string[] {
643
+ const { joined, incoming, output, drawn, index } = input;
644
+ const at = Math.round(input.plan.start * FOOTAGE_FPS);
645
+ const p = `d${String(index)}`;
646
+ return [
647
+ `[${joined}]split[${p}a][${p}b]`,
648
+ `[${p}a]trim=end_frame=${String(at)},setpts=PTS-STARTPTS,${FRAME_TIMING}[${p}head]`,
649
+ `[${p}b]trim=start_frame=${String(at)}:end_frame=${String(at + drawn.frames)},setpts=PTS-STARTPTS,${FRAME_TIMING}[${p}tail]`,
650
+ `[${incoming}]split[${p}c][${p}d]`,
651
+ `[${p}c]trim=end_frame=${String(drawn.frames)},setpts=PTS-STARTPTS,${FRAME_TIMING}[${p}in]`,
652
+ `[${p}d]trim=start_frame=${String(drawn.frames)},setpts=PTS-STARTPTS,${FRAME_TIMING}[${p}rest]`,
653
+ ...buildDrawnTransitionFilters({ kind: drawn.kind, outgoing: `${p}tail`, incoming: `${p}in`, output: `${p}blend`, frame: input.frame, prefix: `${p}t` }),
654
+ // concat changes the time base; a later xfade needs both of its inputs on the segments' own.
655
+ `[${p}head][${p}blend][${p}rest]concat=n=3:v=1:a=0,settb=1/${FOOTAGE_FPS},fps=${FOOTAGE_FPS}[${output}]`,
656
+ ];
657
+ }
658
+
565
659
  /**
566
660
  * The ffmpeg arguments of the draft: each segment read from its own seek into its clip, zoomed and scaled to the
567
661
  * draft's width, joined by `xfade` at `fade` cuts and `concat` at the others, the captions burned in (`ass`), the
@@ -575,15 +669,15 @@ export function buildFootageDraftArgs(input: FootageDraftArgsInput): string[] {
575
669
  const threads = getThreadArgs(input.threads, "draft.threads");
576
670
  const inputs: string[] = [];
577
671
  const parts: string[] = [];
672
+ let inputCount = 0;
673
+ const getClip = (id: string): string => {
674
+ const clip = input.clips[id];
675
+ if (clip === undefined) throw new Error(`No file for clip "${id}" of the EDL.`);
676
+ return clip;
677
+ };
578
678
  edl.segments.forEach((segment, index) => {
579
- const clip = input.clips[segment.clip];
580
- if (clip === undefined) throw new Error(`No file for clip "${segment.clip}" of the EDL.`);
581
679
  const plan = plans[index] as DraftSegmentPlan;
582
- // Before an input, -threads sizes that input's decoder: one decoder runs per segment.
583
- inputs.push(...threads.output, "-ss", String(r3(segment.start)), "-t", String(plan.seconds), "-i", clip);
584
- const filters = [
585
- "setpts=PTS-STARTPTS",
586
- ...buildPictureFilters(plan, draft),
680
+ const fit = [
587
681
  "setsar=1",
588
682
  `fps=${FOOTAGE_FPS}`,
589
683
  "format=yuv420p",
@@ -595,12 +689,33 @@ export function buildFootageDraftArgs(input: FootageDraftArgsInput): string[] {
595
689
  // ffmpeg 7.1's setpts leaves the frame rate unknown (1/0), which xfade refuses (#1057); fps states it again.
596
690
  `fps=${FOOTAGE_FPS}`,
597
691
  ];
598
- parts.push(`[${index}:v]${filters.join(",")}[v${index}]`);
692
+ const { split } = segment;
693
+ if (split !== undefined) {
694
+ // A split screen holds still: its three bands and its layer, at the draft's size, as the render's picture draws them.
695
+ const layer = input.splitLayers?.[segment.id];
696
+ if (layer === undefined) throw new Error(`No split layer for segment "${segment.id}" of the EDL.`);
697
+ const first = inputCount;
698
+ for (const band of split.bands) inputs.push(...threads.output, "-ss", String(r3(band.start)), "-t", String(plan.seconds), "-i", getClip(band.clip));
699
+ inputs.push(...getSplitLayerInputArgs(layer, plan.seconds, FOOTAGE_FPS));
700
+ inputCount += 4;
701
+ const bands: [string, string, string] = [`${String(first)}:v`, `${String(first + 1)}:v`, `${String(first + 2)}:v`];
702
+ parts.push(...buildSplitScreenFilters({ inputs: bands, layer: `${String(first + 3)}:v`, split, frame: draft, fit: ["setpts=PTS-STARTPTS", ...fit], output: `v${index}`, prefix: `sp${String(index)}` }));
703
+ return;
704
+ }
705
+ // Before an input, -threads sizes that input's decoder: one decoder runs per segment.
706
+ inputs.push(...threads.output, "-ss", String(r3(segment.start)), "-t", String(plan.seconds), "-i", getClip(segment.clip));
707
+ parts.push(`[${inputCount}:v]${["setpts=PTS-STARTPTS", ...buildPictureFilters(plan, draft), ...fit].join(",")}[v${index}]`);
708
+ inputCount += 1;
599
709
  });
600
710
  let joined = "v0";
601
711
  plans.forEach((plan, index) => {
602
712
  if (index === 0) return;
603
713
  const label = `j${index}`;
714
+ if (plan.drawn !== null) {
715
+ parts.push(...buildDrawnJoin({ joined, incoming: `v${index}`, output: label, plan, drawn: plan.drawn, frame: draft, index }));
716
+ joined = label;
717
+ return;
718
+ }
604
719
  parts.push(
605
720
  plan.fade > 0
606
721
  ? `[${joined}][v${index}]xfade=transition=fade:duration=${plan.fade}:offset=${plan.start}[${label}]`
@@ -614,7 +729,7 @@ export function buildFootageDraftArgs(input: FootageDraftArgsInput): string[] {
614
729
  } else {
615
730
  parts.push(`[${joined}]null[draft]`);
616
731
  }
617
- const soundInput = edl.segments.length;
732
+ const soundInput = inputCount;
618
733
  const mix = input.mix ?? null;
619
734
  const music = mix === null ? (input.music ?? null) : null;
620
735
  if (music !== null) parts.push(`[${soundInput}:a][${soundInput + 1}:a]amix=inputs=2:duration=first:normalize=0[sound]`);
@@ -798,12 +913,15 @@ async function runRenderFootageDraft(
798
913
  ...(overlays.length === 0 ? {} : { overlays, overlayColors }),
799
914
  ...(Object.keys(roleFonts).length === 0 ? {} : { overlayFonts: Object.fromEntries(Object.entries(roleFonts).map(([role, chosen]) => [role, chosen.family])) }),
800
915
  ...(options.brand?.locale === undefined ? {} : { locale: options.brand.locale }),
801
- ...(options.brand?.style === undefined ? {} : { style: options.brand.style, measure: createDraftTextMeasure(readFileSync(font.file)) }),
916
+ ...(options.brand?.style === undefined ? {} : { style: options.brand.style }),
917
+ // A drawn pill and a ribbon break their lines by the font's own widths.
918
+ ...(options.brand?.style !== undefined || film.captionStyle === "ribbon" ? { measure: createDraftTextMeasure(readFileSync(font.file)) } : {}),
802
919
  });
803
920
  if (captions !== null) {
804
921
  writeFileSync(join(draftDir, "captions.ass"), captions);
805
922
  mkdirSync(join(draftDir, "fonts"));
806
- for (const file of new Set([font.file, ...Object.values(roleFonts).map((chosen) => chosen.file)])) copyFileSync(file, join(draftDir, "fonts", basename(file)));
923
+ const handFont = isHandFontNeeded(overlays) ? [HAND_FONT.file] : [];
924
+ for (const file of new Set([font.file, ...Object.values(roleFonts).map((chosen) => chosen.file), ...handFont])) copyFileSync(file, join(draftDir, "fonts", basename(file)));
807
925
  if (brandFont === null && options.brand?.fonts.body != null) {
808
926
  log(`draft: the brand's body font ${options.brand.fonts.body.family} has no TrueType or OpenType file ffmpeg can read; the captions use ${FOOTAGE_DRAFT_FONT.family}.`);
809
927
  }
@@ -850,6 +968,7 @@ async function runRenderFootageDraft(
850
968
  prepared = mixed.value;
851
969
  }
852
970
  report("film", 0);
971
+ const splitLayers = writeSplitLayers(edl.segments, getFootageDraftFrame(frame, options.width), draftDir, true);
853
972
  // Run in the draft folder: the captions file and the font folder are relative names, so no path needs escaping in the filter graph.
854
973
  const args = buildFootageDraftArgs({
855
974
  film,
@@ -864,6 +983,7 @@ async function runRenderFootageDraft(
864
983
  captions: captions === null ? null : "captions.ass",
865
984
  ...(overlays.length === 0 ? {} : { overlays }),
866
985
  fontsDir: captions === null ? null : "fonts",
986
+ ...(Object.keys(splitLayers).length === 0 ? {} : { splitLayers }),
867
987
  output,
868
988
  });
869
989
  await runFfmpeg("The footage draft", args, { ...aborting, output, cwd: draftDir, onSeconds: (done) => report("film", done) });
@@ -0,0 +1,214 @@
1
+ import type { Frame } from "./normalize.js";
2
+ import { FOOTAGE_FPS } from "./normalize.js";
3
+
4
+ /**
5
+ * Drawn transitions between two shots, the same frames in the draft (`draft.ts`) and the render's picture
6
+ * (`picture.ts`): both give the outgoing segment a tail that plays on under the incoming one, as a dissolve does, and
7
+ * blend the tail with the incoming head through `buildDrawnTransitionFilters`. Nothing is taken from outside the code:
8
+ * the paper's grain is ffmpeg's noise, its torn edge a sum of sines.
9
+ *
10
+ * - `whip`: the outgoing shot slides left faster and faster under a growing horizontal blur (8 frames), the incoming
11
+ * one slides in from the right still blurred, lands from 110 % and comes sharp (6 frames). No sound of its own.
12
+ * - `card`: the incoming shot appears in the middle as a small card (a quarter of the frame, tilted 3°, rounded
13
+ * corners) and grows over the outgoing one until it fills the frame, eased out.
14
+ * - `paper`: a paper grain settles over the outgoing shot (4 frames), then a torn edge opens from the middle onto the
15
+ * incoming one (8 frames).
16
+ *
17
+ * The `stutter` is not drawn here: it is a scale (the first `STUTTER_FRAMES` frames at the full frame, then the
18
+ * segment's tight framing), set where the other zooms are (`getSegmentScales`, the draft's zoom).
19
+ */
20
+
21
+ export const DRAWN_TRANSITIONS = ["whip", "card", "paper"] as const;
22
+
23
+ export type DrawnTransition = (typeof DRAWN_TRANSITIONS)[number];
24
+
25
+ /** Each drawn transition's length in frames at 30 fps (the reference reels, measured). */
26
+ export const DRAWN_TRANSITION_FRAMES: Readonly<Record<DrawnTransition, number>> = { whip: 14, card: 13, paper: 12 };
27
+
28
+ /** The whip's outgoing half; the rest of its frames are the incoming shot landing. */
29
+ export const WHIP_OUT_FRAMES = 8;
30
+
31
+ /** The paper's grain fade-in over the outgoing shot, before the tear opens. */
32
+ export const PAPER_FADE_FRAMES = 4;
33
+
34
+ /** How many frames a stutter shows the full frame before its tight framing. */
35
+ export const STUTTER_FRAMES = 5;
36
+
37
+ /** The stutter's tight framing when the segment sets no camera of its own. */
38
+ export const STUTTER_SCALE = 1.5;
39
+
40
+ /** How far the whip slides on each side, as a share of the frame's width. */
41
+ const WHIP_TRAVEL = 0.6;
42
+ /** The whip's horizontal blur on its outgoing frames, as a share of the frame's width (0: sharp). */
43
+ const WHIP_OUT_BLUR = [0, 0, 0, 0.002, 0.006, 0.014, 0.028, 0.05] as const;
44
+ /** The whip's blur on its incoming frames, falling to sharp. */
45
+ const WHIP_IN_BLUR = [0.042, 0.022, 0.01, 0.004, 0.0015, 0] as const;
46
+ /** The whip's landing zoom on the incoming shot. */
47
+ const WHIP_LANDING_SCALE = 1.1;
48
+
49
+ /** The card's first size (a share of the frame), tilt in radians (3°) and corner radius (a share of the width). */
50
+ const CARD_START_SCALE = 0.25;
51
+ const CARD_START_TILT = 0.0524;
52
+ const CARD_CORNER = 0.035;
53
+
54
+ /** The paper's colour, how strongly its grain multiplies the outgoing shot, how far the tear opens and its rim. */
55
+ const PAPER_COLOR = "0xEDE6D8";
56
+ const PAPER_STRENGTH = 0.55;
57
+ const PAPER_OPEN = 0.62;
58
+ const PAPER_RIM = 0.012;
59
+ /** The torn edge across the height: a sum of sines (amplitude as a share of the width, frequency, phase). */
60
+ const PAPER_TEAR: readonly (readonly [number, number, number])[] = [
61
+ [0.035, 31, 1.3],
62
+ [0.02, 83, 0.7],
63
+ [0.012, 197, 2.1],
64
+ [0.006, 421, 0.4],
65
+ ];
66
+ /** The paper's white at the torn rim (luma, limited range). */
67
+ const PAPER_RIM_LUMA = 232;
68
+
69
+ const r4 = (value: number): number => Math.round(value * 10000) / 10000 || 0;
70
+
71
+ /** Whether a transition is one of the drawn ones. */
72
+ export function isDrawnTransition(transition: string): transition is DrawnTransition {
73
+ return (DRAWN_TRANSITIONS as readonly string[]).includes(transition);
74
+ }
75
+
76
+ /** The frames the outgoing segment plays on under the incoming one: a fade's own or the film's, a drawn transition's own, else 0. */
77
+ export function getTransitionOverlapFrames(segment: { transition: string; fadeFrames?: number | undefined }, filmFadeFrames: number): number {
78
+ if (segment.transition === "fade") return segment.fadeFrames ?? filmFadeFrames;
79
+ return isDrawnTransition(segment.transition) ? DRAWN_TRANSITION_FRAMES[segment.transition] : 0;
80
+ }
81
+
82
+ export interface DrawnTransitionFiltersInput {
83
+ kind: DrawnTransition;
84
+ /** The outgoing tail's label: exactly the transition's frames, the frame's size, yuv420p at 30 fps. */
85
+ outgoing: string;
86
+ /** The incoming head's label, the same. */
87
+ incoming: string;
88
+ /** The label the blended frames go out on (as many frames, yuv420p, 30 fps). */
89
+ output: string;
90
+ frame: Frame;
91
+ /** A prefix for the graph's inner labels, unique in the graph. */
92
+ prefix: string;
93
+ }
94
+
95
+ /** The filter chains (to join with `;`) that blend an outgoing tail and an incoming head into the transition's frames. */
96
+ export function buildDrawnTransitionFilters(input: DrawnTransitionFiltersInput): string[] {
97
+ switch (input.kind) {
98
+ case "whip":
99
+ return buildWhipFilters(input);
100
+ case "card":
101
+ return buildCardFilters(input);
102
+ case "paper":
103
+ return buildPaperFilters(input);
104
+ }
105
+ }
106
+
107
+ /**
108
+ * The film's time base with every frame numbered on it, after a `trim`, a blend or a `concat`: each frame then has its
109
+ * place, so a `concat` lays the pieces end to end. (An `fps` filter here drops the last frame of a stream whose frames
110
+ * carry no duration, as `overlay`, `blend` and `interleave` leave them.)
111
+ */
112
+ export const FRAME_TIMING = `settb=1/${FOOTAGE_FPS},setpts=N`;
113
+
114
+ /** The closing filters every transition ends on: the film's pixel format, square pixels and frame rate. */
115
+ function closeStream(): string {
116
+ return `format=yuv420p,setsar=1,${FRAME_TIMING}`;
117
+ }
118
+
119
+ /** One `gblur` per frame of `sigmas` (shares of the width), horizontal only, on that frame alone; none for a sharp frame. */
120
+ function blurSteps(sigmas: readonly number[], width: number): string[] {
121
+ return sigmas.flatMap((share, frame) => (share > 0 ? [`gblur=sigma=${r4(share * width)}:sigmaV=0:enable='eq(n,${String(frame)})'`] : []));
122
+ }
123
+
124
+ function buildWhipFilters(input: DrawnTransitionFiltersInput): string[] {
125
+ const { width: w, height: h } = input.frame;
126
+ const p = input.prefix;
127
+ const inFrames = DRAWN_TRANSITION_FRAMES.whip - WHIP_OUT_FRAMES;
128
+ const last = WHIP_OUT_FRAMES - 1;
129
+ const land = inFrames - 1;
130
+ // The slide wraps the shot around (a strip of the shot beside itself), so the blur streaks never show an edge.
131
+ const out = [`hstack`, `crop=w=${w}:h=${h}:x='${w}*${WHIP_TRAVEL}*pow(n/${last},2)':y=0`, ...blurSteps(WHIP_OUT_BLUR, w), "setpts=PTS-STARTPTS", FRAME_TIMING];
132
+ const into = [
133
+ `hstack`,
134
+ `crop=w=${w}:h=${h}:x='${w}*(1-${WHIP_TRAVEL}*pow(1-(n+1)/${inFrames},2))':y=0`,
135
+ `zoompan=z='${WHIP_LANDING_SCALE}-${r4(WHIP_LANDING_SCALE - 1)}*(1-pow(1-on/${land},2))':x='(iw-iw/zoom)/2':y='(ih-ih/zoom)/2':d=1:s=${w}x${h}:fps=${FOOTAGE_FPS}`,
136
+ ...blurSteps(WHIP_IN_BLUR, w),
137
+ "setpts=PTS-STARTPTS",
138
+ FRAME_TIMING,
139
+ ];
140
+ return [
141
+ `[${input.outgoing}]trim=end_frame=${WHIP_OUT_FRAMES},setpts=PTS-STARTPTS,split[${p}o1][${p}o2]`,
142
+ `[${p}o1][${p}o2]${out.join(",")}[${p}out]`,
143
+ `[${input.incoming}]trim=start_frame=${WHIP_OUT_FRAMES}:end_frame=${DRAWN_TRANSITION_FRAMES.whip},setpts=PTS-STARTPTS,split[${p}i1][${p}i2]`,
144
+ `[${p}i1][${p}i2]${into.join(",")}[${p}in]`,
145
+ `[${p}out][${p}in]concat=n=2:v=1:a=0,${closeStream()}[${input.output}]`,
146
+ ];
147
+ }
148
+
149
+ /** The card's size, tilt and corner on frame `k` (0-based) of `frames`, eased out (`1 - (1 - t)^2`) to the full frame. */
150
+ export function getCardFrame(k: number, frames: number = DRAWN_TRANSITION_FRAMES.card): { scale: number; tilt: number; corner: number } {
151
+ const eased = 1 - (1 - (k + 1) / frames) ** 2;
152
+ return { scale: r4(CARD_START_SCALE + (1 - CARD_START_SCALE) * eased), tilt: r4(CARD_START_TILT * (1 - eased)), corner: r4(CARD_CORNER * (1 - eased)) };
153
+ }
154
+
155
+ /** An even size of at least 2 px, as yuv420p needs. */
156
+ function toEven(value: number): number {
157
+ return Math.max(2, 2 * Math.floor(value / 2));
158
+ }
159
+
160
+ function buildCardFilters(input: DrawnTransitionFiltersInput): string[] {
161
+ const { width: w, height: h } = input.frame;
162
+ const p = input.prefix;
163
+ const frames = DRAWN_TRANSITION_FRAMES.card;
164
+ // Each frame is its own chain at a fixed size: a size that changes mid-stream breaks `geq` and `rotate`.
165
+ const labels = Array.from({ length: frames }, (_, k) => `${p}c${String(k)}`);
166
+ const chains = labels.map((label, k) => {
167
+ const { scale, tilt, corner } = getCardFrame(k, frames);
168
+ const radius = r4(corner * w);
169
+ const chain = [`trim=start_frame=${String(k)}:end_frame=${String(k + 1)}`, `scale=${String(toEven(w * scale))}:${String(toEven(h * scale))}`];
170
+ if (radius >= 0.5) {
171
+ chain.push(`geq=lum='lum(X,Y)':cb='cb(X,Y)':cr='cr(X,Y)':a='255*lte(hypot(max(0,abs(X-W/2)-(W/2-${radius})),max(0,abs(Y-H/2)-(H/2-${radius}))),${radius})'`);
172
+ }
173
+ if (tilt > 0) chain.push(`rotate=${tilt}:c=black@0:ow=rotw(${tilt}):oh=roth(${tilt})`);
174
+ chain.push(`pad=${w}:${h}:(ow-iw)/2:(oh-ih)/2:color=black@0`, "setsar=1");
175
+ return `[${p}s${String(k)}]${chain.join(",")}[${label}]`;
176
+ });
177
+ return [
178
+ `[${input.incoming}]trim=end_frame=${frames},setpts=PTS-STARTPTS,format=yuva420p,split=${frames}${labels.map((_, k) => `[${p}s${String(k)}]`).join("")}`,
179
+ ...chains,
180
+ // One-frame chains keep their own times, so `interleave` lays them out in order (a `concat` of them drops frames).
181
+ `${labels.map((label) => `[${label}]`).join("")}interleave=nb_inputs=${frames}[${p}card]`,
182
+ `[${input.outgoing}]trim=end_frame=${frames},setpts=PTS-STARTPTS,format=yuv420p[${p}under]`,
183
+ `[${p}under][${p}card]overlay=0:0:format=auto,${closeStream()}[${input.output}]`,
184
+ ];
185
+ }
186
+
187
+ /** The paper's tear: a sum of sines along the height, as a share of the width (the `blend` expression's `Y` and `H`). */
188
+ function getTearExpression(): string {
189
+ return `(${PAPER_TEAR.map(([amplitude, frequency, phase]) => `${amplitude}*sin(Y/H*${frequency}+${phase})`).join("+")})`;
190
+ }
191
+
192
+ /** How far the tear has opened on frame `N` (the `blend` expression's frame), as a share of the width; closed during the grain's fade. */
193
+ function getOpenExpression(frames: number): string {
194
+ const opening = frames - PAPER_FADE_FRAMES;
195
+ return `if(lt(N,${PAPER_FADE_FRAMES}),-1,${PAPER_OPEN}*(0.5-0.5*cos(PI*(N-${PAPER_FADE_FRAMES}+1)/${opening})))`;
196
+ }
197
+
198
+ function buildPaperFilters(input: DrawnTransitionFiltersInput): string[] {
199
+ const { width: w, height: h } = input.frame;
200
+ const p = input.prefix;
201
+ const frames = DRAWN_TRANSITION_FRAMES.paper;
202
+ const strength = `min(1,(N+1)/${PAPER_FADE_FRAMES})*${PAPER_STRENGTH}`;
203
+ // Below 0 inside the tear (the incoming shot), up to the rim the torn paper's white, beyond it the papered shot.
204
+ const edge = `(abs(X/W-0.5)-(${getOpenExpression(frames)})-${getTearExpression()})`;
205
+ const tear = (rim: number): string => `'if(lt(${edge},0),A,if(lt(${edge},${PAPER_RIM}),${String(rim)},B))'`;
206
+ return [
207
+ // A static grain (no temporal noise) softened more along the height, as paper fibres run.
208
+ `color=c=${PAPER_COLOR}:s=${w}x${h}:r=${FOOTAGE_FPS},trim=end_frame=${frames},format=yuv420p,noise=c0s=28:c0f=a,gblur=sigma=${r4(Math.max(0.6, w / 900))}:sigmaV=${r4(Math.max(1.5, w / 360))}[${p}grain]`,
209
+ `[${input.outgoing}]trim=end_frame=${frames},setpts=PTS-STARTPTS,format=yuv420p[${p}under]`,
210
+ `[${input.incoming}]trim=end_frame=${frames},setpts=PTS-STARTPTS,format=yuv420p[${p}over]`,
211
+ `[${p}under][${p}grain]blend=c0_expr='A*(1-${strength})+A*B/255*${strength}':c1_expr='A*(1-${strength})+B*${strength}':c2_expr='A*(1-${strength})+B*${strength}'[${p}papered]`,
212
+ `[${p}over][${p}papered]blend=c0_expr=${tear(PAPER_RIM_LUMA)}:c1_expr=${tear(128)}:c2_expr=${tear(128)},${closeStream()}[${input.output}]`,
213
+ ];
214
+ }