@softure-ai/marketing-kit 0.33.0 → 0.35.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 (93) hide show
  1. package/CHANGELOG.md +53 -0
  2. package/NOTICE +6 -0
  3. package/README.md +39 -0
  4. package/dist/config/schema.d.ts +8 -0
  5. package/dist/config/schema.d.ts.map +1 -1
  6. package/dist/config/schema.js +1 -1
  7. package/dist/config/schema.js.map +1 -1
  8. package/dist/footage/camera.d.ts +67 -0
  9. package/dist/footage/camera.d.ts.map +1 -0
  10. package/dist/footage/camera.js +89 -0
  11. package/dist/footage/camera.js.map +1 -0
  12. package/dist/footage/compose.d.ts +7 -1
  13. package/dist/footage/compose.d.ts.map +1 -1
  14. package/dist/footage/compose.js +45 -10
  15. package/dist/footage/compose.js.map +1 -1
  16. package/dist/footage/draft-overlays.d.ts +6 -0
  17. package/dist/footage/draft-overlays.d.ts.map +1 -1
  18. package/dist/footage/draft-overlays.js +194 -9
  19. package/dist/footage/draft-overlays.js.map +1 -1
  20. package/dist/footage/draft.d.ts +21 -2
  21. package/dist/footage/draft.d.ts.map +1 -1
  22. package/dist/footage/draft.js +70 -31
  23. package/dist/footage/draft.js.map +1 -1
  24. package/dist/footage/drawn-transitions.d.ts +63 -0
  25. package/dist/footage/drawn-transitions.d.ts.map +1 -0
  26. package/dist/footage/drawn-transitions.js +177 -0
  27. package/dist/footage/drawn-transitions.js.map +1 -0
  28. package/dist/footage/edl.d.ts +39 -0
  29. package/dist/footage/edl.d.ts.map +1 -1
  30. package/dist/footage/edl.js +48 -1
  31. package/dist/footage/edl.js.map +1 -1
  32. package/dist/footage/film.d.ts +4 -3
  33. package/dist/footage/film.d.ts.map +1 -1
  34. package/dist/footage/film.js +3 -2
  35. package/dist/footage/film.js.map +1 -1
  36. package/dist/footage/hand-font.d.ts +16 -0
  37. package/dist/footage/hand-font.d.ts.map +1 -0
  38. package/dist/footage/hand-font.js +43 -0
  39. package/dist/footage/hand-font.js.map +1 -0
  40. package/dist/footage/overlay-html.d.ts +1 -0
  41. package/dist/footage/overlay-html.d.ts.map +1 -1
  42. package/dist/footage/overlay-html.js +138 -9
  43. package/dist/footage/overlay-html.js.map +1 -1
  44. package/dist/footage/overlay-motion.d.ts +35 -0
  45. package/dist/footage/overlay-motion.d.ts.map +1 -1
  46. package/dist/footage/overlay-motion.js +45 -0
  47. package/dist/footage/overlay-motion.js.map +1 -1
  48. package/dist/footage/overlay-schema.d.ts +57 -8
  49. package/dist/footage/overlay-schema.d.ts.map +1 -1
  50. package/dist/footage/overlay-schema.js +87 -21
  51. package/dist/footage/overlay-schema.js.map +1 -1
  52. package/dist/footage/overlays.d.ts +127 -1
  53. package/dist/footage/overlays.d.ts.map +1 -1
  54. package/dist/footage/overlays.js +277 -12
  55. package/dist/footage/overlays.js.map +1 -1
  56. package/dist/footage/picture.d.ts +8 -2
  57. package/dist/footage/picture.d.ts.map +1 -1
  58. package/dist/footage/picture.js +41 -15
  59. package/dist/footage/picture.js.map +1 -1
  60. package/dist/footage/pipeline.d.ts.map +1 -1
  61. package/dist/footage/pipeline.js +7 -1
  62. package/dist/footage/pipeline.js.map +1 -1
  63. package/dist/footage/tools.d.ts +1 -1
  64. package/dist/footage/tools.d.ts.map +1 -1
  65. package/dist/footage/tools.js +1 -1
  66. package/dist/footage/tools.js.map +1 -1
  67. package/dist/index.d.ts +8 -5
  68. package/dist/index.d.ts.map +1 -1
  69. package/dist/index.js +8 -5
  70. package/dist/index.js.map +1 -1
  71. package/fonts/Caveat-SemiBold-Latin.ttf +0 -0
  72. package/fonts/LICENSE-Caveat.txt +93 -0
  73. package/fonts/README.md +14 -0
  74. package/package.json +1 -1
  75. package/schema/edl.schema.json +108 -13
  76. package/schema/marketing.schema.json +10 -2
  77. package/src/config/schema.ts +1 -1
  78. package/src/footage/camera.ts +129 -0
  79. package/src/footage/compose.ts +42 -11
  80. package/src/footage/draft-overlays.ts +223 -7
  81. package/src/footage/draft.ts +83 -32
  82. package/src/footage/drawn-transitions.ts +214 -0
  83. package/src/footage/edl.ts +45 -1
  84. package/src/footage/film.ts +3 -2
  85. package/src/footage/hand-font.ts +47 -0
  86. package/src/footage/overlay-html.ts +145 -8
  87. package/src/footage/overlay-motion.ts +49 -0
  88. package/src/footage/overlay-schema.ts +100 -23
  89. package/src/footage/overlays.ts +332 -15
  90. package/src/footage/picture.ts +48 -17
  91. package/src/footage/pipeline.ts +7 -1
  92. package/src/footage/tools.ts +1 -1
  93. package/src/index.ts +56 -0
@@ -1,9 +1,15 @@
1
1
  import { getCornerRadiusPx, type BrandStyle, type CornerRadius } from "./brand-style.js";
2
2
  import { getDraftBoxEvents } from "./draft-boxes.js";
3
3
  import { toAssColor } from "./draft-color.js";
4
+ import { HAND_FONT, getHandFontAssSize } from "./hand-font.js";
4
5
  import { getCounterSeconds, getOverlayColors, getPlaceCardTimes, getTypingTimes, type OverlayColors } from "./overlay-html.js";
5
6
  import {
7
+ DROP_LETTER_SECONDS,
8
+ NOTE_GROW_FROM_SCALE,
9
+ NOTE_GROW_SECONDS,
10
+ NOTE_TICK_SECONDS,
6
11
  OVERLAY_EASES,
12
+ getDropLetterTimes,
7
13
  PIN_DROP_SECONDS,
8
14
  PIN_DROP_SHARE,
9
15
  UNDERLINE_EM,
@@ -16,6 +22,7 @@ import {
16
22
  } from "./overlay-motion.js";
17
23
  import type { OverlayEntrance } from "./overlay-schema.js";
18
24
  import {
25
+ NOTE_LINE_HEIGHT,
19
26
  OVERLAY_FONT_ROLES,
20
27
  OVERLAY_LINE_HEIGHT,
21
28
  OVERLAY_LIST_LINE_HEIGHT,
@@ -27,6 +34,12 @@ import {
27
34
  getDrawnOverlayCard,
28
35
  getListCardsByItem,
29
36
  getListItemTimes,
37
+ getNoteCentre,
38
+ getNoteColors,
39
+ getNotePaperPoints,
40
+ getNoteTextBox,
41
+ getNoteTickPoints,
42
+ getNoteWordsByLine,
30
43
  getOverlayPadding,
31
44
  getPlaceCardPinRow,
32
45
  getPlaceCardPinSize,
@@ -374,6 +387,73 @@ function getWipePanelEvent(overlay: Pick<ResolvedOverlay, "start">, drawing: str
374
387
  return [`Dialogue: 3,${toAssTime(overlay.start)},${toAssTime(overlay.start + motion.entrance.seconds)},OverlayShape,,0,0,0,,{\\an7\\pos(0,0)${tags}\\1c${toTagColor(accent)}\\p1}${drawing}{\\p0}`];
375
388
  }
376
389
 
390
+ /** The same motion with no entrance of its own: a part whose letters or words come in by themselves. */
391
+ function getPlainMotion(motion: DraftMotion): DraftMotion {
392
+ return { ...motion, name: "none", entrance: { kind: "none" } };
393
+ }
394
+
395
+ /**
396
+ * A dropped text as one line of ASS: each letter transparent until its second (`times`, from `getDropLetterTimes`),
397
+ * then fading in over half a fall. libass moves whole events only, so the draft shows the letters arriving on their
398
+ * times without the fall the render draws.
399
+ */
400
+ export function getDropText(text: string, times: readonly number[], eventStart: number): string {
401
+ const fade = toMs(DROP_LETTER_SECONDS / 2);
402
+ return [...toAssText(text)]
403
+ .map((char, index) => {
404
+ if (char.trim() === "") return char;
405
+ const from = toMs((times[index] ?? eventStart) - eventStart);
406
+ return `{\\alpha&HFF&\\t(${from},${from + fade},\\alpha&H00&)}${char}`;
407
+ })
408
+ .join("");
409
+ }
410
+
411
+ /** A highlight mark's padding round its text and its corner, in font sizes (as the render's `.ov-mark`). */
412
+ const MARK_PADDING_EM = { x: 0.22, y: 0.04 } as const;
413
+ const MARK_RADIUS_EM = 0.14;
414
+
415
+ /**
416
+ * A highlight backdrop's marks under one line of text (`style.backdrop` highlight): a tight rounded box in the card
417
+ * colour, its width the text shown so far (each typed letter widens it, as the render's box grows), anchored where
418
+ * the text is (`x` its left, middle or right edge, `top` its top).
419
+ */
420
+ function getBackdropMarkEvents(input: {
421
+ text: string;
422
+ x: number;
423
+ align: "left" | "center" | "right";
424
+ top: number;
425
+ fontSize: number;
426
+ colour: string;
427
+ motion: DraftMotion;
428
+ span: { start: number; end: number };
429
+ typing: number | null;
430
+ /** When the line starts typing, if not at the span's start (a second line of a title). */
431
+ typeFrom?: number;
432
+ }): string[] {
433
+ const { fontSize, span } = input;
434
+ const pad = { x: fontSize * MARK_PADDING_EM.x, y: fontSize * MARK_PADDING_EM.y };
435
+ const height = fontSize * OVERLAY_LINE_HEIGHT + 2 * pad.y;
436
+ const boxFor = (shown: string): OverlayBox => {
437
+ const width = estimateTextWidth(shown, fontSize) + 2 * pad.x;
438
+ const left = input.align === "left" ? input.x - pad.x : input.align === "right" ? input.x + pad.x - width : input.x - width / 2;
439
+ return { left, top: input.top - pad.y, width, height };
440
+ };
441
+ const clean = toAssText(input.text);
442
+ const steps =
443
+ input.typing === null
444
+ ? [{ from: span.start, to: span.end, shown: clean }]
445
+ : getTypingTimes(input.typeFrom ?? span.start, clean, input.typing).map((at, index, times) => ({ from: Math.min(at, span.end), to: Math.min(times[index + 1] ?? span.end, span.end), shown: [...clean].slice(0, index + 1).join("").trimEnd() }));
446
+ const visible = steps.filter((step) => step.to > step.from && step.shown.length > 0);
447
+ return visible.map((step, index) =>
448
+ getShapeEvent({ start: step.from, end: step.to }, getRoundedRectDrawing(boxFor(step.shown), fontSize * MARK_RADIUS_EM), input.colour, input.motion, 3, {
449
+ start: step.from,
450
+ end: step.to,
451
+ isFirst: index === 0,
452
+ isLast: index === visible.length - 1,
453
+ }),
454
+ );
455
+ }
456
+
377
457
  /** A keyword's underline: an accent bar under its text, drawn from the left once the keyword is in. */
378
458
  function getUnderlineEvent(overlay: Extract<ResolvedOverlay, { kind: "keyword" }>, card: OverlayBox, colour: string, motion: DraftMotion): string[] {
379
459
  if (overlay.underline !== true) return [];
@@ -403,19 +483,24 @@ function getSideTextEvents(overlay: Extract<ResolvedOverlay, { kind: "keyword" |
403
483
  // A side text always has a card: only a punch_in has none.
404
484
  const card = getDrawnOverlayCard(overlay) as OverlayBox;
405
485
  const { x: padX, y: padY } = getOverlayPadding(overlay);
406
- const isRight = side === "right";
407
- const x = isRight ? card.left + card.width - padX : card.left + padX;
486
+ const isCentred = overlay.kind === "keyword" && overlay.isCentred === true;
487
+ const isRight = !isCentred && side === "right";
488
+ const x = isCentred ? card.left + card.width / 2 : isRight ? card.left + card.width - padX : card.left + padX;
408
489
  const isFoot = overlay.kind === "lower_third";
409
490
  const y = isFoot ? card.top + card.height - padY : card.top + padY;
410
- // \an: 7 top left, 9 top right, 1 bottom left, 3 bottom right.
411
- const align = isFoot ? (isRight ? 3 : 1) : isRight ? 9 : 7;
491
+ // \an: 7 top left, 8 top centre, 9 top right, 1 bottom left, 3 bottom right.
492
+ const align = isFoot ? (isRight ? 3 : 1) : isCentred ? 8 : isRight ? 9 : 7;
412
493
  const motion = getDraftMotion(overlay, overlay.entrance === null || overlay.entrance === "type" ? "fade" : overlay.entrance, card, context);
413
494
  const span = { start: overlay.start, end: overlay.end };
414
495
  const tags = `\\an${align}\\fs${fontSize}${getTextTags(overlay, colors, context, OVERLAY_FONT_ROLES[overlay.kind])}`;
415
496
  const text = (pos: OverlayPoint, steps: TextStep[], own = motion) => getTextEvents({ layer: 4, style: "OverlayPlain", pos, tags, steps, motion: own });
416
- const shape = getCardShapeEvents(overlay, card, fontSize, colors, motion, context);
497
+ const isMarked = overlay.kind === "keyword" && overlay.backdrop === "highlight";
498
+ const shape = isMarked
499
+ ? getBackdropMarkEvents({ text: overlay.text, x, align: isCentred ? "center" : isRight ? "right" : "left", top: y, fontSize, colour: colors.background, motion, span, typing: overlay.typing })
500
+ : getCardShapeEvents(overlay, card, fontSize, colors, motion, context);
501
+ if (overlay.entrance === "drop") return [...shape, ...text({ x, y }, [{ from: span.start, to: span.end, text: getDropText(overlay.text, getDropLetterTimes(span.start, overlay.text), span.start) }], getPlainMotion(motion))];
417
502
  // A keyword or a lower third types in only when its entrance says so.
418
- const steps = overlay.entrance === null ? [{ from: span.start, to: span.end, text: toAssText(overlay.text) }] : getTypedSteps(overlay.text, span, overlay.typing);
503
+ const steps = overlay.entrance === null ? [{ from: span.start, to: span.end, text: toAssText(overlay.text) }] : getTypedSteps(overlay.text, span, overlay.typing, isCentred);
419
504
  return [...shape, ...text({ x, y }, steps), ...(overlay.kind === "keyword" ? getUnderlineEvent(overlay, card, colors.accent, motion) : [])];
420
505
  }
421
506
 
@@ -549,7 +634,8 @@ function getCardEvents(overlay: CardOverlay, context: DraftContext): string[] {
549
634
  const name = overlay.entrance === null || overlay.entrance === "type" ? (overlay.typing !== null ? "fade" : DEFAULT_ENTRANCES[overlay.kind]) : overlay.entrance;
550
635
  const motion = getDraftMotion(overlay, name, box, context);
551
636
  const span = { start: overlay.start, end: overlay.end };
552
- const events = getCardShapeEvents(overlay, box, fontSize, colors, motion, context);
637
+ const isMarked = overlay.kind === "hook_title" && overlay.backdrop === "highlight";
638
+ const events = isMarked ? [] : getCardShapeEvents(overlay, box, fontSize, colors, motion, context);
553
639
  const { x: padX, y: padY } = getOverlayPadding(overlay);
554
640
  const centerX = box.left + box.width / 2;
555
641
  const tagsFor = (role: OverlayFontRole) => getTextTags(overlay, colors, context, role);
@@ -581,6 +667,25 @@ function getCardEvents(overlay: CardOverlay, context: DraftContext): string[] {
581
667
  const lineHeight = overlay.kind === "hook_title" ? OVERLAY_LINE_HEIGHT : OVERLAY_TITLE_LINE_HEIGHT;
582
668
  const titleMotion = times.title > span.start ? withFadeEntrance(motion) : motion;
583
669
  let typedBefore = 0;
670
+ if (overlay.kind === "hook_title" && (isMarked || overlay.entrance === "drop")) {
671
+ const letters = getDropLetterTimes(span.start, overlay.lines.join(""));
672
+ overlay.lines.forEach((line) => {
673
+ const lineStart = overlay.typing === null ? span.start : span.start + typedBefore / overlay.typing;
674
+ if (isMarked) {
675
+ const align = isLeft ? "left" : "center";
676
+ events.push(...getBackdropMarkEvents({ text: line, x: lineX, align, top: y, fontSize, colour: colors.background, motion, span, typing: overlay.typing, typeFrom: lineStart }));
677
+ }
678
+ const steps =
679
+ overlay.entrance === "drop"
680
+ ? [{ from: span.start, to: span.end, text: getDropText(line, letters.slice(typedBefore, typedBefore + [...line].length), span.start) }]
681
+ : getTypedSteps(line, { start: lineStart, end: span.end }, overlay.typing, !isLeft);
682
+ const isQuiet = overlay.entrance === "drop" || (!isLeft && overlay.typing !== null);
683
+ events.push(...text({ x: lineX, y }, lineAlign, fontSize, "heading", isLeft && overlay.entrance !== "drop" ? steps.map((step, index) => (index === 0 ? { ...step, from: span.start } : step)) : steps, isQuiet ? plain : motion));
684
+ typedBefore += [...line].length;
685
+ y += fontSize * lineHeight;
686
+ });
687
+ return events;
688
+ }
584
689
  overlay.lines.forEach((line) => {
585
690
  // The lines type one after the other, as the render's characters do; a left line holds its place transparent
586
691
  // from the start, a centred one shows its typed part only (`getTypedSteps`).
@@ -649,6 +754,115 @@ function getMarkEvents(overlay: Extract<ResolvedOverlay, { kind: "arrow" | "high
649
754
  return [`Dialogue: 3,${at},OverlayShape,,0,0,0,,{\\an7\\pos(0,0)${fade}\\1a&HFF&\\3c${accent}\\bord${stroke}\\p1}${shape}{\\p0}`];
650
755
  }
651
756
 
757
+ /** A polygon as an ASS drawing. */
758
+ function getPolygonDrawing(points: readonly OverlayPoint[]): string {
759
+ const [first, ...rest] = points;
760
+ if (first === undefined) return "";
761
+ return `m ${r0(first.x)} ${r0(first.y)} l ${rest.map((point) => `${r0(point.x)} ${r0(point.y)}`).join(" ")}`;
762
+ }
763
+
764
+ /** A stroke along `points` `width` px wide as an ASS drawing: one quad per segment and a square cap at each joint. */
765
+ function getStrokeDrawing(points: readonly OverlayPoint[], width: number): string {
766
+ const half = width / 2;
767
+ const parts: string[] = [];
768
+ points.slice(1).forEach((to, index) => {
769
+ const from = points[index] as OverlayPoint;
770
+ const length = Math.hypot(to.x - from.x, to.y - from.y) || 1;
771
+ const n = { x: (-(to.y - from.y) / length) * half, y: ((to.x - from.x) / length) * half };
772
+ const u = { x: ((to.x - from.x) / length) * half, y: ((to.y - from.y) / length) * half };
773
+ parts.push(getPolygonDrawing([
774
+ { x: from.x - u.x + n.x, y: from.y - u.y + n.y },
775
+ { x: to.x + u.x + n.x, y: to.y + u.y + n.y },
776
+ { x: to.x + u.x - n.x, y: to.y + u.y - n.y },
777
+ { x: from.x - u.x - n.x, y: from.y - u.y - n.y },
778
+ ]));
779
+ });
780
+ return parts.join(" ");
781
+ }
782
+
783
+ /**
784
+ * A note: its paper's torn outline and a soft shadow (layer 3), turned by its tilt about its middle (`\org`, `\frz`);
785
+ * a card's handwritten words each fading in on its said second, a strip's capitals typed in after it grows; the tick
786
+ * drawn from the left after the last word (layer 4). A strip's grow is the same `NOTE_GROW_FROM_SCALE` to full size.
787
+ */
788
+ function getNoteEvents(overlay: Extract<ResolvedOverlay, { kind: "note" }>, context: DraftContext): string[] {
789
+ const colors = getNoteColors(overlay);
790
+ const centre = getNoteCentre(overlay);
791
+ const turn = `\\org(${r0(centre.x)},${r0(centre.y)})\\frz${overlay.tilt}`;
792
+ const isStrip = overlay.noteStyle === "strip";
793
+ const frame = { width: 1080 * context.scale, height: 1920 * context.scale };
794
+ const easing = overlay.easing ?? "smooth";
795
+ const grow: OverlayEntranceMotion = { kind: "tween", from: { opacity: 1, scale: NOTE_GROW_FROM_SCALE, y: 0, blur: 0 }, seconds: NOTE_GROW_SECONDS, ease: "power2.out" };
796
+ const name = overlay.entrance ?? (isStrip ? "pop" : "none");
797
+ const motion: DraftMotion = {
798
+ name,
799
+ entrance: isStrip && overlay.entrance === null ? grow : getEntranceMotion(name, easing, frame),
800
+ exit: getExitMotion({ exit: overlay.exit ?? "auto", entrance: overlay.entrance ?? "fade", easing, frame }),
801
+ card: overlay.box,
802
+ scale: context.scale,
803
+ isSnappy: easing === "snappy",
804
+ isCardMoved: name === "pop",
805
+ };
806
+ const at = { isFirst: true, isLast: true, ms: toMs(overlay.end - overlay.start) };
807
+ const shapeTags = getMotionTags(motion, { ...at, pos: { x: 0, y: 0 }, part: "card" });
808
+ const time = `${toAssTime(overlay.start)},${toAssTime(overlay.end)}`;
809
+ const paper = getPolygonDrawing(getNotePaperPoints(overlay));
810
+ const shadowOffset = r0(6 * context.scale);
811
+ const shadow = getPolygonDrawing(getNotePaperPoints({ ...overlay, box: { ...overlay.box, top: overlay.box.top + shadowOffset } }));
812
+ const events = [
813
+ `Dialogue: 3,${time},OverlayShape,,0,0,0,,{\\an7${shapeTags.position}${shapeTags.rest}${turn}\\blur${r0(10 * context.scale)}\\1c&H000000&\\1a&HB0&\\p1}${shadow}{\\p0}`,
814
+ `Dialogue: 3,${time},OverlayShape,,0,0,0,,{\\an7${shapeTags.position}${shapeTags.rest}${turn}\\1c${toTagColor(colors.paper)}\\p1}${paper}{\\p0}`,
815
+ ];
816
+ const textBox = getNoteTextBox(overlay);
817
+ const lineHeight = overlay.fontSize * NOTE_LINE_HEIGHT;
818
+ const font = isStrip ? `${context.fonts.heading === undefined ? "" : `\\fn${context.fonts.heading}`}\\b1` : `\\fn${HAND_FONT.family}\\b0`;
819
+ const textMotion = getPlainMotion(motion);
820
+ // libass sizes the hand font by its ascent and descent: its \\fs is scaled so the letters match the render's.
821
+ const assSize = isStrip ? overlay.fontSize : getHandFontAssSize(overlay.fontSize);
822
+ const tags = `\\an7\\fs${assSize}${font}\\1c${toTagColor(colors.ink)}${turn}`;
823
+ getNoteWordsByLine(overlay).forEach((words, index) => {
824
+ const pos = { x: textBox.left, y: textBox.top + index * lineHeight };
825
+ const line = overlay.lines[index] as string;
826
+ const span = { start: overlay.start, end: overlay.end };
827
+ if (isStrip) {
828
+ const before = overlay.lines.slice(0, index).join("").length;
829
+ const typing = overlay.typing ?? 14;
830
+ const steps = getTypedSteps(line, { start: overlay.start + before / typing, end: overlay.end }, typing).map((step, stepIndex) => (stepIndex === 0 ? { ...step, from: overlay.start } : step));
831
+ events.push(...getTextEvents({ layer: 4, style: "OverlayPlain", pos, tags, steps, motion: textMotion }));
832
+ return;
833
+ }
834
+ const fade = 100;
835
+ const shown = words.map((word) => `{\\alpha&HFF&\\t(${toMs(word.at - span.start)},${toMs(word.at - span.start) + fade},\\alpha&H00&)}${toAssText(word.text)}`).join(" ");
836
+ events.push(...getTextEvents({ layer: 4, style: "OverlayPlain", pos, tags, steps: [{ from: span.start, to: span.end, text: shown }], motion: textMotion }));
837
+ });
838
+ if (overlay.tickAt !== null) {
839
+ const points = getNoteTickPoints(overlay);
840
+ const xs = points.map((point) => point.x);
841
+ const ys = points.map((point) => point.y);
842
+ const room = overlay.fontSize * 0.2;
843
+ const clip = { x0: r0(Math.min(...xs) - room), y0: r0(Math.min(...ys) - room), x1: r0(Math.max(...xs) + room), y1: r0(Math.max(...ys) + room) };
844
+ const draw = `${toClip({ ...clip, x1: clip.x0 })}\\t(0,${toMs(NOTE_TICK_SECONDS)},${toClip(clip)})`;
845
+ const fade = motion.exit.kind === "none" ? "" : `\\fad(0,${FADE_OUT_MS})`;
846
+ events.push(`Dialogue: 4,${toAssTime(overlay.tickAt)},${toAssTime(overlay.end)},OverlayShape,,0,0,0,,{\\an7\\pos(0,0)${fade}${draw}${turn}\\1c${toTagColor(colors.tick)}\\p1}${getStrokeDrawing(points, overlay.fontSize * 0.12)}{\\p0}`);
847
+ }
848
+ return events;
849
+ }
850
+
851
+ /** An end word: one big handwritten line at the top, no card, white with a soft shadow, its letters dropping in (or its own entrance). */
852
+ function getEndWordEvents(overlay: Extract<ResolvedOverlay, { kind: "end_word" }>, context: DraftContext): string[] {
853
+ const name = overlay.entrance ?? "drop";
854
+ const motion = getDraftMotion(overlay, name, overlay.box, context);
855
+ const colour = overlay.colors.text ?? "#ffffff";
856
+ const tags = `\\an8\\fs${getHandFontAssSize(overlay.fontSize)}\\fn${HAND_FONT.family}\\b0\\1c${toTagColor(colour)}\\shad${r0(3 * context.scale)}\\4c&H000000&\\4a&H90&`;
857
+ const pos = { x: overlay.box.left + overlay.box.width / 2, y: overlay.box.top };
858
+ const span = { start: overlay.start, end: overlay.end };
859
+ if (name === "drop") {
860
+ const text = getDropText(overlay.text, getDropLetterTimes(span.start, overlay.text), span.start);
861
+ return getTextEvents({ layer: 4, style: "OverlayPlain", pos, tags, steps: [{ from: span.start, to: span.end, text }], motion: getPlainMotion(motion) });
862
+ }
863
+ return getTextEvents({ layer: 4, style: "OverlayPlain", pos, tags, steps: [{ from: span.start, to: span.end, text: toAssText(overlay.text) }], motion });
864
+ }
865
+
652
866
  /**
653
867
  * The overlays as ASS events, layers 3 and 4. `fonts` names the heading and interface families where they are not the
654
868
  * styles' own (the captions' font); `locale` groups a counter's number as the render does.
@@ -664,6 +878,8 @@ export function buildDraftOverlayEvents(
664
878
  if (overlay.kind === "punch_in") return [];
665
879
  if (overlay.kind === "arrow" || overlay.kind === "highlight") return getMarkEvents(overlay, context);
666
880
  if (overlay.kind === "keyword" || overlay.kind === "lower_third" || overlay.kind === "list") return getSideTextEvents(overlay, context);
881
+ if (overlay.kind === "note") return getNoteEvents(overlay, context);
882
+ if (overlay.kind === "end_word") return getEndWordEvents(overlay, context);
667
883
  return getCardEvents(overlay, context);
668
884
  });
669
885
  }
@@ -8,14 +8,17 @@ 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
10
  import { getCaptionChunkLayouts, getCaptionSpans, getFootageCaptionChunks, getFootageCaptionLayout, isSameCaptionPlace, type CaptionWordsFilm } from "./captions.js";
11
- import { getSegmentScales, getSegmentZoomEases } from "./compose.js";
11
+ import { getCameraMoveFrames, getCameraOrigin, getCameraScaleExpression, type CameraAnchor, type EdlCamera } from "./camera.js";
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";
12
14
  import { toAssColor } from "./draft-color.js";
13
15
  import { buildDraftOverlayEvents, getDraftOverlayStyles, getRoundedRectDrawing } from "./draft-overlays.js";
14
16
  import { getCaptionCornerRadius, getCornerRadiusPx, getStylePadding, type BrandStyle } from "./brand-style.js";
15
17
  import { getDraftBoxEvents } from "./draft-boxes.js";
16
18
  import { createDraftTextMeasure, wrapDraftLine, type DraftTextMeasure } from "./draft-text-width.js";
17
19
  import { CAPTION_PILL_PADDING } from "../compose/timeline.js";
18
- import { estimateTextWidth } from "./overlays.js";
20
+ import { estimateTextWidth, isHandFontNeeded } from "./overlays.js";
21
+ import { HAND_FONT } from "./hand-font.js";
19
22
  import type { OverlayColors } from "./overlay-html.js";
20
23
  import { resolveEdlOverlays, type OverlayFontRole, type ResolvedOverlay } from "./overlays.js";
21
24
  import { chooseFootageDraftFont } from "./draft-font.js";
@@ -66,8 +69,6 @@ export const FOOTAGE_DRAFT_FONT = {
66
69
 
67
70
  /** How far a segment marked `kenburns` zooms when the film's `kenBurnsPercent` is 0, as in the render. */
68
71
  const HAND_KEN_BURNS_PERCENT = 4;
69
- /** The point a zoom keeps still, as the render's `transform-origin: 50% 42%`. */
70
- const ZOOM_ORIGIN = { x: 0.5, y: 0.42 } as const;
71
72
  const DRAFT_CRF = 28;
72
73
  const DRAFT_AUDIO_BITRATE = "128k";
73
74
 
@@ -473,6 +474,13 @@ export interface DraftSegmentPlan {
473
474
  start: number;
474
475
  /** The cross-fade from the segment before, in seconds; 0 for a plain cut. */
475
476
  fade: number;
477
+ /**
478
+ * The drawn transition from the segment before (`whip`, `card`, `paper`) and its frames, over which the outgoing
479
+ * segment plays on under this one as under a fade; null for any other cut, or a segment too short for it.
480
+ */
481
+ drawn: { kind: DrawnTransition; frames: number } | null;
482
+ /** Whether the segment starts on a `stutter`: `STUTTER_FRAMES` frames at the full frame, then `scale`. */
483
+ isStutter: boolean;
476
484
  /** The zoom the segment starts at (`getSegmentScales`). */
477
485
  scale: number;
478
486
  /** The zoom it ends at: above `scale` for a `kenburns` segment, `scale` otherwise. */
@@ -481,6 +489,10 @@ export interface DraftSegmentPlan {
481
489
  startScale: number;
482
490
  /** The frames the zoom eases over (`getSegmentZoomEases`); 0: the segment starts at `scale`. */
483
491
  easeFrames: number;
492
+ /** The segment's camera (`EdlCamera`) and the frames its move takes; null: the film's own zoom (`scale`, `endScale`). */
493
+ camera: { camera: EdlCamera; frames: number } | null;
494
+ /** The point the segment's zooms keep still: its camera's anchor, else the render's `transform-origin: 50% 42%`. */
495
+ origin: CameraAnchor;
484
496
  /**
485
497
  * The EDL's `punch_in` overlays in this segment, in frames from its start: each multiplies the zoom by up to `scale`,
486
498
  * rising over `ease` frames from `from` and falling over the last `ease` of its `frames` (linear, the render eases).
@@ -489,28 +501,41 @@ export interface DraftSegmentPlan {
489
501
  }
490
502
 
491
503
  /**
492
- * How each segment plays in the draft. A `fade` cut lasts the film's `fadeFrames` (clamped to the incoming segment, so
493
- * the cross-fade never outlasts it) and the outgoing segment runs on under it, as in the render.
504
+ * How each segment plays in the draft. A `fade` cut lasts its own `fadeFrames` or the film's (clamped to the incoming
505
+ * segment, so the cross-fade never outlasts it) and the outgoing segment runs on under it, as in the render.
494
506
  */
495
507
  export function planFootageDraft(film: Pick<FootageFilm, "edit">, edl: Edl, overlays: readonly ResolvedOverlay[] = []): DraftSegmentPlan[] {
496
508
  const edit = getFootageEdit(film);
497
- const fadeSeconds = r3(edit.fadeFrames / FOOTAGE_FPS);
498
509
  const kenBurnsScale = 1 + (edit.kenBurnsPercent > 0 ? edit.kenBurnsPercent : HAND_KEN_BURNS_PERCENT) / 100;
499
510
  const scales = getSegmentScales(edl, edit.zoomPercent);
500
511
  const eases = getSegmentZoomEases(edl, edit);
501
512
  const starts = getSegmentStarts(edl);
502
- const fades = edl.segments.map((segment, index) => (segment.transition === "fade" && index > 0 ? r3(Math.min(fadeSeconds, segment.end - segment.start)) : 0));
513
+ const fades = edl.segments.map((segment, index) => r3(Math.min(getSegmentFadeFrames(edl, index, edit) / FOOTAGE_FPS, segment.end - segment.start)));
514
+ // A drawn transition only on a segment longer than its frames (the EDL check refuses a shorter one).
515
+ const drawn = edl.segments.map((segment, index) =>
516
+ index > 0 && isDrawnTransition(segment.transition) && Math.round((segment.end - segment.start) * FOOTAGE_FPS) > DRAWN_TRANSITION_FRAMES[segment.transition]
517
+ ? { kind: segment.transition, frames: DRAWN_TRANSITION_FRAMES[segment.transition] }
518
+ : null,
519
+ );
520
+ const overlaps = edl.segments.map((_, index) => {
521
+ const own = drawn[index];
522
+ return own === null || own === undefined ? (fades[index] as number) : r3(own.frames / FOOTAGE_FPS);
523
+ });
503
524
  return edl.segments.map((segment, index) => {
504
525
  const scale = scales[index] as number;
505
526
  return {
506
527
  length: r3(segment.end - segment.start),
507
- seconds: r3(segment.end - segment.start + (fades[index + 1] ?? 0)),
528
+ seconds: r3(segment.end - segment.start + (overlaps[index + 1] ?? 0)),
508
529
  start: starts[index] as number,
509
530
  fade: fades[index] as number,
531
+ drawn: drawn[index] ?? null,
532
+ isStutter: segment.transition === "stutter",
510
533
  scale,
511
- endScale: segment.motion === "kenburns" ? r4(scale * kenBurnsScale) : scale,
534
+ endScale: segment.camera !== undefined ? segment.camera.to : segment.motion === "kenburns" ? r4(scale * kenBurnsScale) : scale,
512
535
  startScale: (eases[index] as number) > 0 ? (scales[index - 1] as number) : scale,
513
536
  easeFrames: eases[index] as number,
537
+ camera: segment.camera === undefined ? null : { camera: segment.camera, frames: getCameraMoveFrames(segment.camera, segment.end - segment.start) },
538
+ origin: getCameraOrigin(segment.camera),
514
539
  punches: overlays.flatMap((overlay) =>
515
540
  overlay.kind === "punch_in" && overlay.segment === index
516
541
  ? [
@@ -528,40 +553,60 @@ export function planFootageDraft(film: Pick<FootageFilm, "edit">, edl: Edl, over
528
553
  }
529
554
 
530
555
  /**
531
- * The filters that zoom a segment's picture and scale it to the draft: a crop for a still zoom, `zoompan` for Ken Burns
532
- * and for an eased zoom cut (the render's `power1.out`: `1 - (1 - t)^2`).
556
+ * The filters that zoom a segment's picture and scale it to the draft: a crop for a still zoom, `zoompan` for Ken Burns,
557
+ * a camera's move and an eased zoom cut (the render's `power1.out`: `1 - (1 - t)^2`), each about the segment's origin.
533
558
  */
534
559
  function buildPictureFilters(plan: DraftSegmentPlan, draft: Frame): string[] {
535
560
  const size = `${draft.width}:${draft.height}`;
561
+ const { origin } = plan;
536
562
  const zoompan = (zoom: string): string =>
537
- `zoompan=z='${zoom}':x='(iw-iw/zoom)*${ZOOM_ORIGIN.x}':y='(ih-ih/zoom)*${ZOOM_ORIGIN.y}':d=1:s=${draft.width}x${draft.height}:fps=${FOOTAGE_FPS}`;
538
- if (plan.punches.length > 0) {
539
- // The segment's own zoom (an eased cut, Ken Burns or still) times each punch-in's rise, hold and fall.
540
- const frames = Math.max(1, Math.round(plan.length * FOOTAGE_FPS));
541
- const own =
542
- plan.easeFrames > 0
543
- ? `${plan.startScale}+(${r4(plan.scale - plan.startScale)})*(1-pow(1-min(on/${plan.easeFrames},1),2))`
563
+ `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}`;
564
+ // The zoom runs over the segment's own length, as the render's tween does, and holds through a fade's tail.
565
+ const frames = Math.max(1, Math.round(plan.length * FOOTAGE_FPS));
566
+ // A stutter: the full frame for its first frames, then its tight framing (it has no move and no punch-in).
567
+ if (plan.isStutter) return [zoompan(`if(lt(on,${STUTTER_FRAMES}),1,${plan.scale})`)];
568
+ const own =
569
+ plan.easeFrames > 0
570
+ ? `${plan.startScale}+(${r4(plan.scale - plan.startScale)})*(1-pow(1-min(on/${plan.easeFrames},1),2))`
571
+ : plan.camera !== null && plan.endScale !== plan.scale
572
+ ? getCameraScaleExpression(plan.camera.camera, plan.camera.frames)
544
573
  : plan.endScale !== plan.scale
545
574
  ? `${plan.scale}+${r4(plan.endScale - plan.scale)}*min(on/${frames},1)`
546
- : `${plan.scale}`;
575
+ : null;
576
+ if (plan.punches.length > 0) {
577
+ // The segment's own zoom (an eased cut, a camera, Ken Burns or still) times each punch-in's rise, hold and fall.
547
578
  const lifts = plan.punches.map((punch) => `${r4(punch.scale - 1)}*max(0,min(min(1,(on-${punch.from})/${punch.ease}),(${punch.from + punch.frames}-on)/${punch.ease}))`);
548
- return [zoompan(`(${own})*(1+${lifts.join("+")})`)];
549
- }
550
- if (plan.easeFrames > 0) {
551
- return [zoompan(`${plan.startScale}+(${r4(plan.scale - plan.startScale)})*(1-pow(1-min(on/${plan.easeFrames},1),2))`)];
552
- }
553
- if (plan.endScale !== plan.scale) {
554
- // The zoom runs over the segment's own length, as the render's tween does, and holds through a fade's tail.
555
- const frames = Math.max(1, Math.round(plan.length * FOOTAGE_FPS));
556
- const zoom = `${plan.scale}+${r4(plan.endScale - plan.scale)}*min(on/${frames},1)`;
557
- return [zoompan(zoom)];
579
+ return [zoompan(`(${own ?? String(plan.scale)})*(1+${lifts.join("+")})`)];
558
580
  }
581
+ if (own !== null) return [zoompan(own)];
559
582
  if (plan.scale !== 1) {
560
- return [`crop=iw/${plan.scale}:ih/${plan.scale}:(iw-iw/${plan.scale})*${ZOOM_ORIGIN.x}:(ih-ih/${plan.scale})*${ZOOM_ORIGIN.y}`, `scale=${size}`];
583
+ return [`crop=iw/${plan.scale}:ih/${plan.scale}:(iw-iw/${plan.scale})*${origin.x}:(ih-ih/${plan.scale})*${origin.y}`, `scale=${size}`];
561
584
  }
562
585
  return [`scale=${size}`];
563
586
  }
564
587
 
588
+ /**
589
+ * A drawn transition in the draft: the cut so far is split where the incoming segment starts, its tail (the outgoing
590
+ * segment playing on) blended with the incoming head as the render's picture blends them, and the rest of the
591
+ * incoming segment follows.
592
+ */
593
+ function buildDrawnJoin(input: { joined: string; incoming: string; output: string; plan: DraftSegmentPlan; drawn: { kind: DrawnTransition; frames: number }; frame: Frame; index: number }): string[] {
594
+ const { joined, incoming, output, drawn, index } = input;
595
+ const at = Math.round(input.plan.start * FOOTAGE_FPS);
596
+ const p = `d${String(index)}`;
597
+ return [
598
+ `[${joined}]split[${p}a][${p}b]`,
599
+ `[${p}a]trim=end_frame=${String(at)},setpts=PTS-STARTPTS,${FRAME_TIMING}[${p}head]`,
600
+ `[${p}b]trim=start_frame=${String(at)}:end_frame=${String(at + drawn.frames)},setpts=PTS-STARTPTS,${FRAME_TIMING}[${p}tail]`,
601
+ `[${incoming}]split[${p}c][${p}d]`,
602
+ `[${p}c]trim=end_frame=${String(drawn.frames)},setpts=PTS-STARTPTS,${FRAME_TIMING}[${p}in]`,
603
+ `[${p}d]trim=start_frame=${String(drawn.frames)},setpts=PTS-STARTPTS,${FRAME_TIMING}[${p}rest]`,
604
+ ...buildDrawnTransitionFilters({ kind: drawn.kind, outgoing: `${p}tail`, incoming: `${p}in`, output: `${p}blend`, frame: input.frame, prefix: `${p}t` }),
605
+ // concat changes the time base; a later xfade needs both of its inputs on the segments' own.
606
+ `[${p}head][${p}blend][${p}rest]concat=n=3:v=1:a=0,settb=1/${FOOTAGE_FPS},fps=${FOOTAGE_FPS}[${output}]`,
607
+ ];
608
+ }
609
+
565
610
  /**
566
611
  * The ffmpeg arguments of the draft: each segment read from its own seek into its clip, zoomed and scaled to the
567
612
  * draft's width, joined by `xfade` at `fade` cuts and `concat` at the others, the captions burned in (`ass`), the
@@ -601,6 +646,11 @@ export function buildFootageDraftArgs(input: FootageDraftArgsInput): string[] {
601
646
  plans.forEach((plan, index) => {
602
647
  if (index === 0) return;
603
648
  const label = `j${index}`;
649
+ if (plan.drawn !== null) {
650
+ parts.push(...buildDrawnJoin({ joined, incoming: `v${index}`, output: label, plan, drawn: plan.drawn, frame: draft, index }));
651
+ joined = label;
652
+ return;
653
+ }
604
654
  parts.push(
605
655
  plan.fade > 0
606
656
  ? `[${joined}][v${index}]xfade=transition=fade:duration=${plan.fade}:offset=${plan.start}[${label}]`
@@ -803,7 +853,8 @@ async function runRenderFootageDraft(
803
853
  if (captions !== null) {
804
854
  writeFileSync(join(draftDir, "captions.ass"), captions);
805
855
  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)));
856
+ const handFont = isHandFontNeeded(overlays) ? [HAND_FONT.file] : [];
857
+ for (const file of new Set([font.file, ...Object.values(roleFonts).map((chosen) => chosen.file), ...handFont])) copyFileSync(file, join(draftDir, "fonts", basename(file)));
807
858
  if (brandFont === null && options.brand?.fonts.body != null) {
808
859
  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
860
  }