@softure-ai/marketing-kit 0.29.0 → 0.31.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 (40) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/README.md +15 -1
  3. package/dist/footage/draft-boxes.d.ts +3 -1
  4. package/dist/footage/draft-boxes.d.ts.map +1 -1
  5. package/dist/footage/draft-boxes.js +3 -2
  6. package/dist/footage/draft-boxes.js.map +1 -1
  7. package/dist/footage/draft-overlays.d.ts.map +1 -1
  8. package/dist/footage/draft-overlays.js +191 -41
  9. package/dist/footage/draft-overlays.js.map +1 -1
  10. package/dist/footage/edl.d.ts +27 -0
  11. package/dist/footage/edl.d.ts.map +1 -1
  12. package/dist/footage/overlay-html.d.ts +8 -0
  13. package/dist/footage/overlay-html.d.ts.map +1 -1
  14. package/dist/footage/overlay-html.js +127 -29
  15. package/dist/footage/overlay-html.js.map +1 -1
  16. package/dist/footage/overlay-motion.d.ts +107 -0
  17. package/dist/footage/overlay-motion.d.ts.map +1 -0
  18. package/dist/footage/overlay-motion.js +129 -0
  19. package/dist/footage/overlay-motion.js.map +1 -0
  20. package/dist/footage/overlay-schema.d.ts +63 -2
  21. package/dist/footage/overlay-schema.d.ts.map +1 -1
  22. package/dist/footage/overlay-schema.js +70 -5
  23. package/dist/footage/overlay-schema.js.map +1 -1
  24. package/dist/footage/overlays.d.ts +16 -1
  25. package/dist/footage/overlays.d.ts.map +1 -1
  26. package/dist/footage/overlays.js +43 -12
  27. package/dist/footage/overlays.js.map +1 -1
  28. package/dist/index.d.ts +3 -2
  29. package/dist/index.d.ts.map +1 -1
  30. package/dist/index.js +3 -2
  31. package/dist/index.js.map +1 -1
  32. package/package.json +1 -1
  33. package/schema/edl.schema.json +82 -1
  34. package/src/footage/draft-boxes.ts +7 -3
  35. package/src/footage/draft-overlays.ts +224 -42
  36. package/src/footage/overlay-html.ts +148 -27
  37. package/src/footage/overlay-motion.ts +157 -0
  38. package/src/footage/overlay-schema.ts +90 -5
  39. package/src/footage/overlays.ts +70 -16
  40. package/src/index.ts +22 -0
@@ -10,7 +10,9 @@ import {
10
10
  type EdlOverlay,
11
11
  type EdlOverlayColors,
12
12
  type OverlayAlign,
13
+ type OverlayEasing,
13
14
  type OverlayEntrance,
15
+ type OverlayExit,
14
16
  type OverlayKind,
15
17
  type OverlayPosition,
16
18
  type OverlaySide,
@@ -18,6 +20,7 @@ import {
18
20
  } from "./overlay-schema.js";
19
21
  import { getSegmentZoomEases } from "./compose.js";
20
22
  import { normalizeWord } from "./words.js";
23
+ import { getListItemStarts } from "./overlay-motion.js";
21
24
  import { STYLE_PADDING_SCALES, type BrandStyle, type CornerRadius } from "./brand-style.js";
22
25
 
23
26
  /**
@@ -127,6 +130,10 @@ export interface OverlayLook {
127
130
  cornerRadius?: CornerRadius | null;
128
131
  /** Its card's padding in `OVERLAY_PADDING_EM`s: the brand style's `padding` (`STYLE_PADDING_SCALES`); absent: 1. */
129
132
  padScale?: number;
133
+ /** How it leaves (`style.exit`); absent: `auto`, mirroring its entrance. */
134
+ exit?: OverlayExit;
135
+ /** The curve of its entrance and exit (`style.easing`); absent: `smooth`. */
136
+ easing?: OverlayEasing;
130
137
  }
131
138
 
132
139
  type Drawn = OverlayBase & OverlayLook;
@@ -137,14 +144,26 @@ type Drawn = OverlayBase & OverlayLook;
137
144
  */
138
145
  export type ResolvedOverlay =
139
146
  | (OverlayBase & { kind: "punch_in"; scale: number; ease: number })
140
- | (Drawn & { kind: "keyword"; text: string; fontSize: number; side: OverlaySide; box: OverlayBox })
147
+ | (Drawn & { kind: "keyword"; text: string; fontSize: number; side: OverlaySide; box: OverlayBox; underline?: boolean })
141
148
  | (Drawn & { kind: "lower_third"; text: string; fontSize: number; side: OverlaySide; box: OverlayBox })
142
- | (Drawn & { kind: "list"; items: string[]; fontSize: number; side: OverlaySide; box: OverlayBox })
149
+ | (Drawn & { kind: "list"; items: string[]; fontSize: number; side: OverlaySide; box: OverlayBox; itemStarts?: number[] })
143
150
  | (Drawn & { kind: "arrow"; from: OverlayPoint; to: OverlayPoint })
144
151
  | (Drawn & { kind: "highlight"; rect: OverlayBox })
145
152
  | (Drawn & { kind: "hook_title"; lines: string[]; place: string | null; fontSize: number; placeFontSize: number; align?: OverlayAlign; box: OverlayBox })
146
153
  | (Drawn & { kind: "search_bar"; text: string; fontSize: number; box: OverlayBox })
147
- | (Drawn & { kind: "place_card"; lines: string[]; subtitle: string | null; fontSize: number; subtitleFontSize: number; align?: OverlayAlign; box: OverlayBox })
154
+ | (Drawn & {
155
+ kind: "place_card";
156
+ lines: string[];
157
+ subtitle: string | null;
158
+ fontSize: number;
159
+ subtitleFontSize: number;
160
+ align?: OverlayAlign;
161
+ box: OverlayBox;
162
+ /** Its accent pin above the title (`style.pin`); absent: none. */
163
+ pin?: "static" | "drop";
164
+ /** Seconds its subtitle waits after its title (`style.subtitle_delay`); absent: none. */
165
+ subtitleDelay?: number;
166
+ })
148
167
  | (Drawn & { kind: "counter"; value: number; from: number; decimals: number; unit: string | null; fontSize: number; unitFontSize: number; box: OverlayBox })
149
168
  | (Drawn & { kind: "date_stamp"; text: string; place: string | null; fontSize: number; placeFontSize: number; side: OverlaySide; box: OverlayBox });
150
169
 
@@ -181,14 +200,18 @@ function getCaptionBand(input: ResolveOverlaysInput, segment: number): { top: nu
181
200
  /** The film second an overlay starts at, or the reason its word cannot be found. */
182
201
  function findOverlayStart(overlay: EdlOverlay, words: TimedWord[]): { ok: true; start: number } | { ok: false; error: string } {
183
202
  if (overlay.at !== undefined) return { ok: true, start: overlay.at };
184
- const wanted = overlay.at_word as NonNullable<EdlOverlay["at_word"]>;
203
+ return findWordStart(overlay.at_word as NonNullable<EdlOverlay["at_word"]>, words, "at_word");
204
+ }
205
+
206
+ /** The film second a word of the transcript starts at, or why it is not there (`field` names it in the reason). */
207
+ function findWordStart(wanted: NonNullable<EdlOverlay["at_word"]>, words: TimedWord[], field: string): { ok: true; start: number } | { ok: false; error: string } {
185
208
  const key = normalizeWord(wanted.text);
186
209
  const occurrence = wanted.occurrence ?? 1;
187
210
  const matches = words.filter((word) => normalizeWord(word.text) === key);
188
211
  const word = matches[occurrence - 1];
189
212
  if (word === undefined) {
190
213
  const said = matches.length === 0 ? "the film never says it" : `the film says it ${matches.length} time${matches.length === 1 ? "" : "s"}`;
191
- return { ok: false, error: `at_word: no word "${wanted.text}"${occurrence > 1 ? ` (occurrence ${occurrence})` : ""} in the cut; ${said}` };
214
+ return { ok: false, error: `${field}: no word "${wanted.text}"${occurrence > 1 ? ` (occurrence ${occurrence})` : ""} in the cut; ${said}` };
192
215
  }
193
216
  return { ok: true, start: word.start };
194
217
  }
@@ -353,6 +376,16 @@ export function resolveEdlOverlays(input: ResolveOverlaysInput): ResolvedOverlay
353
376
  problems.push(`${at}: ${placed.error}`);
354
377
  return;
355
378
  }
379
+ if (placed.overlay.kind === "list" && (overlay.style?.stagger === true || overlay.item_words !== undefined || overlay.item_at !== undefined)) {
380
+ const said = (overlay.item_words ?? []).map((word, item) => findWordStart(word, input.words, `item_words[${item}]`));
381
+ const missing = said.flatMap((word) => (word.ok ? [] : [word.error]));
382
+ if (missing.length > 0) {
383
+ problems.push(...missing.map((error) => `${at}.${error}`));
384
+ return;
385
+ }
386
+ const times = overlay.item_at ?? (overlay.item_words === undefined ? undefined : said.map((word) => (word as { start: number }).start));
387
+ placed.overlay.itemStarts = getListItemStarts({ start, end, count: placed.overlay.items.length, ...(times === undefined ? {} : { words: times }) });
388
+ }
356
389
  if (placed.overlay.kind === "punch_in") {
357
390
  if (edl.segments[segment]?.motion === "kenburns") {
358
391
  problems.push(`${at}: segment "${segmentId}" has a Ken Burns zoom, which owns the picture's scale; put the punch-in on a still segment`);
@@ -442,11 +475,14 @@ function getPositionTop(region: { top: number; bottom: number }, position: Overl
442
475
  }
443
476
 
444
477
  function getLook(overlay: EdlOverlay): OverlayLook {
478
+ const style = overlay.style ?? {};
445
479
  return {
446
- entrance: overlay.style?.entrance ?? null,
447
- typing: isTypedOverlay(overlay) ? (overlay.style?.typing_speed ?? DEFAULT_OVERLAY_TYPING_SPEED) : null,
448
- colors: { ...overlay.style?.colors },
449
- cornerRadius: overlay.style?.corner_radius ?? null,
480
+ entrance: style.entrance ?? null,
481
+ typing: isTypedOverlay(overlay) ? (style.typing_speed ?? DEFAULT_OVERLAY_TYPING_SPEED) : null,
482
+ colors: { ...style.colors },
483
+ cornerRadius: style.corner_radius ?? null,
484
+ ...(style.exit === undefined || style.exit === "auto" ? {} : { exit: style.exit }),
485
+ ...(style.easing === undefined || style.easing === "smooth" ? {} : { easing: style.easing }),
450
486
  };
451
487
  }
452
488
 
@@ -508,7 +544,8 @@ function placeSideText(overlay: EdlOverlay & { kind: "keyword" | "lower_third" |
508
544
  const box = { left: zone.left + margin, top, width: frame.width - zone.left - zone.right - 2 * margin, height };
509
545
  if (overlay.kind === "list") return { ok: true, overlay: { ...drawn, kind: "list", items: overlay.items ?? [], fontSize, side, box } };
510
546
  const fields = { text: overlay.text ?? "", fontSize, side, box };
511
- return { ok: true, overlay: overlay.kind === "keyword" ? { ...drawn, kind: "keyword", ...fields } : { ...drawn, kind: "lower_third", ...fields } };
547
+ if (overlay.kind === "lower_third") return { ok: true, overlay: { ...drawn, kind: "lower_third", ...fields } };
548
+ return { ok: true, overlay: { ...drawn, kind: "keyword", ...fields, ...(overlay.style?.underline === true ? { underline: true } : {}) } };
512
549
  }
513
550
 
514
551
  type CardKind = "hook_title" | "search_bar" | "place_card" | "counter" | "date_stamp";
@@ -584,22 +621,35 @@ type TitleOverlay = Extract<ResolvedOverlay, { kind: "hook_title" | "place_card"
584
621
  * its pin, the subtitle, each title line) and its height. Its card is this plus the padding, so the draft and the
585
622
  * render find the block's left edge and top inside the card from it whatever the title's fitted size.
586
623
  */
587
- export function getTitleContentSize(input: { kind: TitleOverlay["kind"]; lines: readonly string[]; fontSize: number; second: string | null; secondSize: number }): { width: number; height: number } {
624
+ export function getTitleContentSize(input: { kind: TitleOverlay["kind"]; lines: readonly string[]; fontSize: number; second: string | null; secondSize: number; pin?: boolean }): {
625
+ width: number;
626
+ height: number;
627
+ } {
588
628
  const { kind, lines, fontSize, second, secondSize } = input;
589
629
  const isHook = kind === "hook_title";
590
630
  const secondWidth = second === null ? 0 : estimateTextWidth(second, secondSize) + (isHook ? Math.round(secondSize * 1.1) : 0);
591
631
  const lineHeight = isHook ? OVERLAY_LINE_HEIGHT : OVERLAY_TITLE_LINE_HEIGHT;
592
632
  return {
593
- width: Math.max(secondWidth, ...lines.map((line) => estimateTextWidth(line, fontSize))),
594
- height: lines.length * fontSize * lineHeight + (second === null ? 0 : secondSize * 1.3 + fontSize * 0.12),
633
+ width: Math.max(secondWidth, input.pin === true ? getPlaceCardPinSize(fontSize) : 0, ...lines.map((line) => estimateTextWidth(line, fontSize))),
634
+ height: lines.length * fontSize * lineHeight + (second === null ? 0 : secondSize * 1.3 + fontSize * 0.12) + (input.pin === true ? getPlaceCardPinRow(fontSize) : 0),
595
635
  };
596
636
  }
597
637
 
638
+ /** A place card's pin height (and width), in px: half its title's size. */
639
+ export function getPlaceCardPinSize(fontSize: number): number {
640
+ return Math.round(fontSize * 0.5);
641
+ }
642
+
643
+ /** The row a place card's pin takes above its title: the pin and a small gap. */
644
+ export function getPlaceCardPinRow(fontSize: number): number {
645
+ return getPlaceCardPinSize(fontSize) + Math.round(fontSize * 0.1);
646
+ }
647
+
598
648
  /** A resolved title's text block inside its card: its left edge and top, in px of the frame. */
599
649
  export function getTitleContentBox(overlay: TitleOverlay): OverlayBox {
600
650
  const second = overlay.kind === "hook_title" ? overlay.place : overlay.subtitle;
601
651
  const secondSize = overlay.kind === "hook_title" ? overlay.placeFontSize : overlay.subtitleFontSize;
602
- const size = getTitleContentSize({ kind: overlay.kind, lines: overlay.lines, fontSize: overlay.fontSize, second, secondSize });
652
+ const size = getTitleContentSize({ kind: overlay.kind, lines: overlay.lines, fontSize: overlay.fontSize, second, secondSize, pin: overlay.kind === "place_card" && overlay.pin !== undefined });
603
653
  const { box } = overlay;
604
654
  return { left: box.left + (box.width - size.width) / 2, top: box.top + (box.height - size.height) / 2, width: size.width, height: size.height };
605
655
  }
@@ -620,11 +670,15 @@ function measureTitle(overlay: EdlOverlay & { kind: "hook_title" | "place_card"
620
670
  const secondWidth = second === null ? 0 : estimateTextWidth(second, secondSize) + (isHook ? Math.round(secondSize * 1.1) : 0);
621
671
  if (secondWidth > room) return tooWide(metrics, isHook ? "place label" : "subtitle");
622
672
  const align = overlay.style?.align ?? "center";
673
+ const pin = !isHook && overlay.style?.pin !== undefined && overlay.style.pin !== "none" ? overlay.style.pin : undefined;
674
+ const delay = !isHook && second !== null && overlay.style?.subtitle_delay !== undefined && overlay.style.subtitle_delay > 0 ? overlay.style.subtitle_delay : undefined;
623
675
  return {
624
676
  ok: true,
625
677
  content: {
626
- ...getTitleContentSize({ kind: overlay.kind, lines, fontSize, second, secondSize }),
627
- fields: isHook ? { kind: "hook_title", lines, place: second, fontSize, placeFontSize: secondSize, align } : { kind: "place_card", lines, subtitle: second, fontSize, subtitleFontSize: secondSize, align },
678
+ ...getTitleContentSize({ kind: overlay.kind, lines, fontSize, second, secondSize, pin: pin !== undefined }),
679
+ fields: isHook
680
+ ? { kind: "hook_title", lines, place: second, fontSize, placeFontSize: secondSize, align }
681
+ : { kind: "place_card", lines, subtitle: second, fontSize, subtitleFontSize: secondSize, align, ...(pin === undefined ? {} : { pin }), ...(delay === undefined ? {} : { subtitleDelay: delay }) },
628
682
  },
629
683
  };
630
684
  }
package/src/index.ts CHANGED
@@ -94,8 +94,12 @@ export {
94
94
  MIN_OVERLAY_TYPING_SPEED,
95
95
  OVERLAY_ALIGNED_KINDS,
96
96
  OVERLAY_ALIGNS,
97
+ OVERLAY_EASINGS,
97
98
  OVERLAY_ENTRANCES,
98
99
  OVERLAY_ENTRANCES_BY_KIND,
100
+ OVERLAY_EXITS,
101
+ OVERLAY_PINS,
102
+ MAX_OVERLAY_SUBTITLE_DELAY,
99
103
  OVERLAY_KINDS,
100
104
  OVERLAY_POSITIONS,
101
105
  OVERLAY_POSITIONS_BY_KIND,
@@ -109,8 +113,11 @@ export {
109
113
  type EdlOverlayStyle,
110
114
  type EdlOverlayWord,
111
115
  type OverlayAlign,
116
+ type OverlayEasing,
112
117
  type OverlayEntrance,
118
+ type OverlayExit,
113
119
  type OverlayKind,
120
+ type OverlayPin,
114
121
  type OverlayPosition,
115
122
  type OverlaySide,
116
123
  type OverlaySize,
@@ -150,6 +157,8 @@ export {
150
157
  getDrawnOverlayCard,
151
158
  getOverlayBounds,
152
159
  getOverlayPadding,
160
+ getPlaceCardPinRow,
161
+ getPlaceCardPinSize,
153
162
  getTitleContentBox,
154
163
  getTitleContentSize,
155
164
  wrapOverlayTitle,
@@ -164,6 +173,19 @@ export {
164
173
  type ResolvedOverlay,
165
174
  type ResolvedOverlaysResult,
166
175
  } from "./footage/overlays.js";
176
+ export {
177
+ OVERLAY_EASES,
178
+ POP_FROM_SCALE,
179
+ RISE_FROM_HEIGHT,
180
+ getEntranceMotion,
181
+ getEntranceScaleAt,
182
+ getExitMotion,
183
+ getListItemStarts,
184
+ type OverlayEase,
185
+ type OverlayEntranceMotion,
186
+ type OverlayExitMotion,
187
+ type OverlayMotionOffset,
188
+ } from "./footage/overlay-motion.js";
167
189
  export { resolveBrandColors, type BrandColorsResult } from "./config/brand.js";
168
190
  export { readCssColors } from "./config/css-colors.js";
169
191
  export { readDesignJsonColors } from "./config/design-json.js";