@softure-ai/marketing-kit 0.29.0 → 0.32.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 (48) hide show
  1. package/CHANGELOG.md +36 -0
  2. package/README.md +18 -2
  3. package/dist/footage/captions.d.ts +9 -2
  4. package/dist/footage/captions.d.ts.map +1 -1
  5. package/dist/footage/captions.js +20 -4
  6. package/dist/footage/captions.js.map +1 -1
  7. package/dist/footage/draft-boxes.d.ts +3 -1
  8. package/dist/footage/draft-boxes.d.ts.map +1 -1
  9. package/dist/footage/draft-boxes.js +3 -2
  10. package/dist/footage/draft-boxes.js.map +1 -1
  11. package/dist/footage/draft-overlays.d.ts.map +1 -1
  12. package/dist/footage/draft-overlays.js +191 -41
  13. package/dist/footage/draft-overlays.js.map +1 -1
  14. package/dist/footage/edl.d.ts +46 -0
  15. package/dist/footage/edl.d.ts.map +1 -1
  16. package/dist/footage/edl.js +39 -0
  17. package/dist/footage/edl.js.map +1 -1
  18. package/dist/footage/overlay-html.d.ts +8 -0
  19. package/dist/footage/overlay-html.d.ts.map +1 -1
  20. package/dist/footage/overlay-html.js +127 -29
  21. package/dist/footage/overlay-html.js.map +1 -1
  22. package/dist/footage/overlay-motion.d.ts +107 -0
  23. package/dist/footage/overlay-motion.d.ts.map +1 -0
  24. package/dist/footage/overlay-motion.js +129 -0
  25. package/dist/footage/overlay-motion.js.map +1 -0
  26. package/dist/footage/overlay-schema.d.ts +63 -2
  27. package/dist/footage/overlay-schema.d.ts.map +1 -1
  28. package/dist/footage/overlay-schema.js +70 -5
  29. package/dist/footage/overlay-schema.js.map +1 -1
  30. package/dist/footage/overlays.d.ts +16 -1
  31. package/dist/footage/overlays.d.ts.map +1 -1
  32. package/dist/footage/overlays.js +60 -20
  33. package/dist/footage/overlays.js.map +1 -1
  34. package/dist/index.d.ts +5 -4
  35. package/dist/index.d.ts.map +1 -1
  36. package/dist/index.js +5 -4
  37. package/dist/index.js.map +1 -1
  38. package/package.json +1 -1
  39. package/schema/edl.schema.json +117 -1
  40. package/src/footage/captions.ts +21 -5
  41. package/src/footage/draft-boxes.ts +7 -3
  42. package/src/footage/draft-overlays.ts +224 -42
  43. package/src/footage/edl.ts +51 -0
  44. package/src/footage/overlay-html.ts +148 -27
  45. package/src/footage/overlay-motion.ts +157 -0
  46. package/src/footage/overlay-schema.ts +90 -5
  47. package/src/footage/overlays.ts +87 -23
  48. package/src/index.ts +25 -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
 
@@ -168,27 +187,41 @@ export function getOverlaySafeZone(film: Pick<FootageFilm, "format" | "captionPr
168
187
  return { top: DEFAULT_SAFE_MARGIN, bottom: DEFAULT_SAFE_MARGIN, left: DEFAULT_SAFE_MARGIN, right: DEFAULT_SAFE_MARGIN };
169
188
  }
170
189
 
171
- /** The rows a caption card can take in a segment (its box moved by the segment's `caption`), or null without captions. */
172
- function getCaptionBand(input: ResolveOverlaysInput, segment: number): { top: number; bottom: number } | null {
190
+ /**
191
+ * The rows a caption card can take while an overlay shows, or null without captions: the box of the segment it starts
192
+ * in (moved by the segment's `caption`) and of every caption range on screen with it (`Edl.captionRanges`), as one band.
193
+ */
194
+ function getCaptionBand(input: ResolveOverlaysInput, at: { segment: number; start: number; end: number }): { top: number; bottom: number } | null {
173
195
  if (!input.film.captions) return null;
174
- const place = applySegmentCaption(input.caption, input.edl.segments[segment]?.caption);
175
196
  const lines = input.film.captionMaxLines ?? 2;
176
- const height = Math.ceil(lines * place.fontSize * CAPTION_LINE_HEIGHT + 2 * CAPTION_PILL_PADDING.y);
177
- if (place.bottom !== undefined) return { top: input.frame.height - place.bottom - height, bottom: input.frame.height - place.bottom };
178
- return { top: place.top, bottom: place.top + height };
197
+ const ranges = (input.edl.captionRanges ?? []).filter((range) => range.from < at.end && at.start < range.to);
198
+ const isWithinOneRange = ranges.some((range) => range.from <= at.start && at.end <= range.to);
199
+ const places = [
200
+ ...(isWithinOneRange ? [] : [applySegmentCaption(input.caption, input.edl.segments[at.segment]?.caption)]),
201
+ ...ranges.map((range) => applySegmentCaption(input.caption, { ...(range.bottom === undefined ? {} : { bottom: range.bottom }), ...(range.top === undefined ? {} : { top: range.top }) })),
202
+ ];
203
+ const bands = places.map((place) => {
204
+ const height = Math.ceil(lines * place.fontSize * CAPTION_LINE_HEIGHT + 2 * CAPTION_PILL_PADDING.y);
205
+ return place.bottom !== undefined ? { top: input.frame.height - place.bottom - height, bottom: input.frame.height - place.bottom } : { top: place.top, bottom: place.top + height };
206
+ });
207
+ return { top: Math.min(...bands.map((band) => band.top)), bottom: Math.max(...bands.map((band) => band.bottom)) };
179
208
  }
180
209
 
181
210
  /** The film second an overlay starts at, or the reason its word cannot be found. */
182
211
  function findOverlayStart(overlay: EdlOverlay, words: TimedWord[]): { ok: true; start: number } | { ok: false; error: string } {
183
212
  if (overlay.at !== undefined) return { ok: true, start: overlay.at };
184
- const wanted = overlay.at_word as NonNullable<EdlOverlay["at_word"]>;
213
+ return findWordStart(overlay.at_word as NonNullable<EdlOverlay["at_word"]>, words, "at_word");
214
+ }
215
+
216
+ /** The film second a word of the transcript starts at, or why it is not there (`field` names it in the reason). */
217
+ function findWordStart(wanted: NonNullable<EdlOverlay["at_word"]>, words: TimedWord[], field: string): { ok: true; start: number } | { ok: false; error: string } {
185
218
  const key = normalizeWord(wanted.text);
186
219
  const occurrence = wanted.occurrence ?? 1;
187
220
  const matches = words.filter((word) => normalizeWord(word.text) === key);
188
221
  const word = matches[occurrence - 1];
189
222
  if (word === undefined) {
190
223
  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}` };
224
+ return { ok: false, error: `${field}: no word "${wanted.text}"${occurrence > 1 ? ` (occurrence ${occurrence})` : ""} in the cut; ${said}` };
192
225
  }
193
226
  return { ok: true, start: word.start };
194
227
  }
@@ -348,11 +381,21 @@ export function resolveEdlOverlays(input: ResolveOverlaysInput): ResolvedOverlay
348
381
  }
349
382
  }
350
383
  const base = { index, start, end, segment };
351
- const placed = placeOverlay(overlay, base, { zone, frame, band: getCaptionBand(input, segment), padScale: STYLE_PADDING_SCALES[input.style?.padding ?? "m"] });
384
+ const placed = placeOverlay(overlay, base, { zone, frame, band: getCaptionBand(input, base), padScale: STYLE_PADDING_SCALES[input.style?.padding ?? "m"] });
352
385
  if (!placed.ok) {
353
386
  problems.push(`${at}: ${placed.error}`);
354
387
  return;
355
388
  }
389
+ if (placed.overlay.kind === "list" && (overlay.style?.stagger === true || overlay.item_words !== undefined || overlay.item_at !== undefined)) {
390
+ const said = (overlay.item_words ?? []).map((word, item) => findWordStart(word, input.words, `item_words[${item}]`));
391
+ const missing = said.flatMap((word) => (word.ok ? [] : [word.error]));
392
+ if (missing.length > 0) {
393
+ problems.push(...missing.map((error) => `${at}.${error}`));
394
+ return;
395
+ }
396
+ const times = overlay.item_at ?? (overlay.item_words === undefined ? undefined : said.map((word) => (word as { start: number }).start));
397
+ placed.overlay.itemStarts = getListItemStarts({ start, end, count: placed.overlay.items.length, ...(times === undefined ? {} : { words: times }) });
398
+ }
356
399
  if (placed.overlay.kind === "punch_in") {
357
400
  if (edl.segments[segment]?.motion === "kenburns") {
358
401
  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 +485,14 @@ function getPositionTop(region: { top: number; bottom: number }, position: Overl
442
485
  }
443
486
 
444
487
  function getLook(overlay: EdlOverlay): OverlayLook {
488
+ const style = overlay.style ?? {};
445
489
  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,
490
+ entrance: style.entrance ?? null,
491
+ typing: isTypedOverlay(overlay) ? (style.typing_speed ?? DEFAULT_OVERLAY_TYPING_SPEED) : null,
492
+ colors: { ...style.colors },
493
+ cornerRadius: style.corner_radius ?? null,
494
+ ...(style.exit === undefined || style.exit === "auto" ? {} : { exit: style.exit }),
495
+ ...(style.easing === undefined || style.easing === "smooth" ? {} : { easing: style.easing }),
450
496
  };
451
497
  }
452
498
 
@@ -508,7 +554,8 @@ function placeSideText(overlay: EdlOverlay & { kind: "keyword" | "lower_third" |
508
554
  const box = { left: zone.left + margin, top, width: frame.width - zone.left - zone.right - 2 * margin, height };
509
555
  if (overlay.kind === "list") return { ok: true, overlay: { ...drawn, kind: "list", items: overlay.items ?? [], fontSize, side, box } };
510
556
  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 } };
557
+ if (overlay.kind === "lower_third") return { ok: true, overlay: { ...drawn, kind: "lower_third", ...fields } };
558
+ return { ok: true, overlay: { ...drawn, kind: "keyword", ...fields, ...(overlay.style?.underline === true ? { underline: true } : {}) } };
512
559
  }
513
560
 
514
561
  type CardKind = "hook_title" | "search_bar" | "place_card" | "counter" | "date_stamp";
@@ -584,22 +631,35 @@ type TitleOverlay = Extract<ResolvedOverlay, { kind: "hook_title" | "place_card"
584
631
  * its pin, the subtitle, each title line) and its height. Its card is this plus the padding, so the draft and the
585
632
  * render find the block's left edge and top inside the card from it whatever the title's fitted size.
586
633
  */
587
- export function getTitleContentSize(input: { kind: TitleOverlay["kind"]; lines: readonly string[]; fontSize: number; second: string | null; secondSize: number }): { width: number; height: number } {
634
+ export function getTitleContentSize(input: { kind: TitleOverlay["kind"]; lines: readonly string[]; fontSize: number; second: string | null; secondSize: number; pin?: boolean }): {
635
+ width: number;
636
+ height: number;
637
+ } {
588
638
  const { kind, lines, fontSize, second, secondSize } = input;
589
639
  const isHook = kind === "hook_title";
590
640
  const secondWidth = second === null ? 0 : estimateTextWidth(second, secondSize) + (isHook ? Math.round(secondSize * 1.1) : 0);
591
641
  const lineHeight = isHook ? OVERLAY_LINE_HEIGHT : OVERLAY_TITLE_LINE_HEIGHT;
592
642
  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),
643
+ width: Math.max(secondWidth, input.pin === true ? getPlaceCardPinSize(fontSize) : 0, ...lines.map((line) => estimateTextWidth(line, fontSize))),
644
+ height: lines.length * fontSize * lineHeight + (second === null ? 0 : secondSize * 1.3 + fontSize * 0.12) + (input.pin === true ? getPlaceCardPinRow(fontSize) : 0),
595
645
  };
596
646
  }
597
647
 
648
+ /** A place card's pin height (and width), in px: half its title's size. */
649
+ export function getPlaceCardPinSize(fontSize: number): number {
650
+ return Math.round(fontSize * 0.5);
651
+ }
652
+
653
+ /** The row a place card's pin takes above its title: the pin and a small gap. */
654
+ export function getPlaceCardPinRow(fontSize: number): number {
655
+ return getPlaceCardPinSize(fontSize) + Math.round(fontSize * 0.1);
656
+ }
657
+
598
658
  /** A resolved title's text block inside its card: its left edge and top, in px of the frame. */
599
659
  export function getTitleContentBox(overlay: TitleOverlay): OverlayBox {
600
660
  const second = overlay.kind === "hook_title" ? overlay.place : overlay.subtitle;
601
661
  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 });
662
+ const size = getTitleContentSize({ kind: overlay.kind, lines: overlay.lines, fontSize: overlay.fontSize, second, secondSize, pin: overlay.kind === "place_card" && overlay.pin !== undefined });
603
663
  const { box } = overlay;
604
664
  return { left: box.left + (box.width - size.width) / 2, top: box.top + (box.height - size.height) / 2, width: size.width, height: size.height };
605
665
  }
@@ -620,11 +680,15 @@ function measureTitle(overlay: EdlOverlay & { kind: "hook_title" | "place_card"
620
680
  const secondWidth = second === null ? 0 : estimateTextWidth(second, secondSize) + (isHook ? Math.round(secondSize * 1.1) : 0);
621
681
  if (secondWidth > room) return tooWide(metrics, isHook ? "place label" : "subtitle");
622
682
  const align = overlay.style?.align ?? "center";
683
+ const pin = !isHook && overlay.style?.pin !== undefined && overlay.style.pin !== "none" ? overlay.style.pin : undefined;
684
+ const delay = !isHook && second !== null && overlay.style?.subtitle_delay !== undefined && overlay.style.subtitle_delay > 0 ? overlay.style.subtitle_delay : undefined;
623
685
  return {
624
686
  ok: true,
625
687
  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 },
688
+ ...getTitleContentSize({ kind: overlay.kind, lines, fontSize, second, secondSize, pin: pin !== undefined }),
689
+ fields: isHook
690
+ ? { kind: "hook_title", lines, place: second, fontSize, placeFontSize: secondSize, align }
691
+ : { kind: "place_card", lines, subtitle: second, fontSize, subtitleFontSize: secondSize, align, ...(pin === undefined ? {} : { pin }), ...(delay === undefined ? {} : { subtitleDelay: delay }) },
628
692
  },
629
693
  };
630
694
  }
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";
@@ -489,6 +511,7 @@ export {
489
511
  edlSchema,
490
512
  findEdlProblems,
491
513
  findSegmentAt,
514
+ findCaptionRangeAt,
492
515
  getEdlDuration,
493
516
  getEdlJsonSchema,
494
517
  getSegmentStarts,
@@ -502,6 +525,7 @@ export {
502
525
  type Edl,
503
526
  type EdlAudio,
504
527
  type EdlCaption,
528
+ type EdlCaptionRange,
505
529
  type EdlCaptionBounds,
506
530
  type EdlClip,
507
531
  type EdlSegment,
@@ -514,6 +538,7 @@ export {
514
538
  findMissingCaptionGlyphs,
515
539
  getCaptionBounds,
516
540
  getCaptionChunkLayouts,
541
+ getCaptionPlaceAt,
517
542
  getCaptionKeepsWithNext,
518
543
  getFootageCaptionChunks,
519
544
  getCaptionPresetLayout,