@softure-ai/marketing-kit 0.23.0 → 0.24.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 (59) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/README.md +17 -0
  3. package/dist/footage/captions.d.ts +8 -1
  4. package/dist/footage/captions.d.ts.map +1 -1
  5. package/dist/footage/captions.js +5 -3
  6. package/dist/footage/captions.js.map +1 -1
  7. package/dist/footage/compose.d.ts +2 -0
  8. package/dist/footage/compose.d.ts.map +1 -1
  9. package/dist/footage/compose.js +3 -2
  10. package/dist/footage/compose.js.map +1 -1
  11. package/dist/footage/draft-overlays.d.ts +24 -4
  12. package/dist/footage/draft-overlays.d.ts.map +1 -1
  13. package/dist/footage/draft-overlays.js +232 -34
  14. package/dist/footage/draft-overlays.js.map +1 -1
  15. package/dist/footage/draft.d.ts +7 -2
  16. package/dist/footage/draft.d.ts.map +1 -1
  17. package/dist/footage/draft.js +13 -2
  18. package/dist/footage/draft.js.map +1 -1
  19. package/dist/footage/edl.d.ts +27 -0
  20. package/dist/footage/edl.d.ts.map +1 -1
  21. package/dist/footage/edl.js +1 -1
  22. package/dist/footage/edl.js.map +1 -1
  23. package/dist/footage/overlay-html.d.ts +21 -1
  24. package/dist/footage/overlay-html.d.ts.map +1 -1
  25. package/dist/footage/overlay-html.js +217 -56
  26. package/dist/footage/overlay-html.js.map +1 -1
  27. package/dist/footage/overlay-schema.d.ts +98 -6
  28. package/dist/footage/overlay-schema.d.ts.map +1 -1
  29. package/dist/footage/overlay-schema.js +215 -45
  30. package/dist/footage/overlay-schema.js.map +1 -1
  31. package/dist/footage/overlays.d.ts +109 -16
  32. package/dist/footage/overlays.d.ts.map +1 -1
  33. package/dist/footage/overlays.js +303 -52
  34. package/dist/footage/overlays.js.map +1 -1
  35. package/dist/footage/pipeline.d.ts +5 -0
  36. package/dist/footage/pipeline.d.ts.map +1 -1
  37. package/dist/footage/pipeline.js +3 -2
  38. package/dist/footage/pipeline.js.map +1 -1
  39. package/dist/index.d.ts +2 -2
  40. package/dist/index.d.ts.map +1 -1
  41. package/dist/index.js +2 -2
  42. package/dist/index.js.map +1 -1
  43. package/dist/render/render.d.ts +4 -1
  44. package/dist/render/render.d.ts.map +1 -1
  45. package/dist/render/render.js +2 -1
  46. package/dist/render/render.js.map +1 -1
  47. package/package.json +1 -1
  48. package/schema/edl.schema.json +90 -8
  49. package/src/footage/captions.ts +13 -4
  50. package/src/footage/compose.ts +5 -3
  51. package/src/footage/draft-overlays.ts +276 -35
  52. package/src/footage/draft.ts +20 -4
  53. package/src/footage/edl.ts +1 -1
  54. package/src/footage/overlay-html.ts +239 -59
  55. package/src/footage/overlay-schema.ts +245 -40
  56. package/src/footage/overlays.ts +364 -55
  57. package/src/footage/pipeline.ts +8 -3
  58. package/src/index.ts +26 -0
  59. package/src/render/render.ts +3 -2
@@ -4,7 +4,17 @@ import { applySegmentCaption, CAPTION_SAFE_ZONES } from "./captions.js";
4
4
  import { getEdlDuration, getSegmentStarts, findSegmentAt, type Edl } from "./edl.js";
5
5
  import { getFootageEdit, type FootageFilm } from "./film.js";
6
6
  import { FOOTAGE_FPS } from "./normalize.js";
7
- import type { EdlOverlay, OverlaySide, OverlaySize } from "./overlay-schema.js";
7
+ import {
8
+ DEFAULT_OVERLAY_TYPING_SPEED,
9
+ isTypedOverlay,
10
+ type EdlOverlay,
11
+ type EdlOverlayColors,
12
+ type OverlayEntrance,
13
+ type OverlayKind,
14
+ type OverlayPosition,
15
+ type OverlaySide,
16
+ type OverlaySize,
17
+ } from "./overlay-schema.js";
8
18
  import { getSegmentZoomEases } from "./compose.js";
9
19
  import { normalizeWord } from "./words.js";
10
20
 
@@ -19,16 +29,37 @@ import { normalizeWord } from "./words.js";
19
29
  export const PUNCH_IN_SCALES: Record<OverlaySize, number> = { s: 1.08, m: 1.12, l: 1.15 };
20
30
  /** The `punch_in`'s ease into its zoom and back out, in seconds (shorter when the overlay is short). */
21
31
  export const PUNCH_IN_EASE_SECONDS = 0.35;
22
- /** A text overlay's type size in px of a 1080 px wide frame, by kind and size step. */
23
- export const OVERLAY_FONT_SIZES: Record<"keyword" | "lower_third" | "list", Record<OverlaySize, number>> = {
32
+
33
+ /** The kinds drawn with text: every kind but `punch_in`, `arrow` and `highlight`. */
34
+ export type TextOverlayKind = Exclude<OverlayKind, "punch_in" | "arrow" | "highlight">;
35
+
36
+ /** A text overlay's main type size in px of a 1080 px wide frame, by kind and size step. */
37
+ export const OVERLAY_FONT_SIZES: Record<TextOverlayKind, Record<OverlaySize, number>> = {
24
38
  keyword: { s: 64, m: 84, l: 108 },
25
39
  lower_third: { s: 44, m: 52, l: 60 },
26
40
  list: { s: 40, m: 48, l: 56 },
41
+ hook_title: { s: 52, m: 64, l: 76 },
42
+ search_bar: { s: 36, m: 42, l: 50 },
43
+ place_card: { s: 72, m: 92, l: 112 },
44
+ counter: { s: 84, m: 108, l: 132 },
45
+ date_stamp: { s: 30, m: 36, l: 44 },
27
46
  };
47
+ /** A second line's type size in main font sizes: the hook title's place label, the subtitle, the unit, the stamp's place. */
48
+ export const OVERLAY_SECONDARY_SCALE = { hook_title: 0.55, place_card: 0.42, counter: 0.5, date_stamp: 0.78 } as const;
28
49
  /** A text overlay's line height and its box's padding, in font sizes. */
29
50
  export const OVERLAY_LINE_HEIGHT = 1.15;
30
51
  export const OVERLAY_LIST_LINE_HEIGHT = 1.4;
52
+ /** A place card title's line height, tighter for its big type. */
53
+ export const OVERLAY_TITLE_LINE_HEIGHT = 1.05;
31
54
  export const OVERLAY_PADDING_EM = { x: 0.6, y: 0.35 } as const;
55
+ /** The search field's padding round its query, in font sizes (its height is the line plus twice this). */
56
+ export const SEARCH_BAR_PADDING_EM = { x: 0.7, y: 0.55 } as const;
57
+ /** The room the search field's magnifier and its gap take before the query, in font sizes. */
58
+ export const SEARCH_BAR_ICON_EM = 1.5;
59
+ /** The average advance of a bold Latin letter, in font sizes: how wide a line is estimated before it is drawn. */
60
+ export const OVERLAY_CHAR_EM = 0.56;
61
+ /** The most lines a hook title or a place card's title wraps to. */
62
+ export const MAX_OVERLAY_TITLE_LINES = 2;
32
63
  /** The room kept between an overlay and the safe zone's edge or the captions, in px. */
33
64
  export const OVERLAY_MARGIN = 24;
34
65
  /** How far an arrow's tail sits from the point it points at, in px. */
@@ -38,6 +69,21 @@ const MIN_HIGHLIGHT_SIDE = 40;
38
69
  /** The safe zone of a frame that is not a 1080×1920 vertical: 80 px on every side. */
39
70
  const DEFAULT_SAFE_MARGIN = 80;
40
71
 
72
+ /** The brand font a text overlay is drawn in: `heading` for titles and numbers, `interface` for labels and lists. */
73
+ export type OverlayFontRole = "heading" | "interface";
74
+
75
+ /** Each text kind's font role (the hook title's place label and a place card's subtitle are interface text). */
76
+ export const OVERLAY_FONT_ROLES: Record<TextOverlayKind, OverlayFontRole> = {
77
+ keyword: "heading",
78
+ hook_title: "heading",
79
+ place_card: "heading",
80
+ counter: "heading",
81
+ lower_third: "interface",
82
+ list: "interface",
83
+ search_bar: "interface",
84
+ date_stamp: "interface",
85
+ };
86
+
41
87
  /** A box in the film's frame, in px. */
42
88
  export interface OverlayBox {
43
89
  left: number;
@@ -57,17 +103,37 @@ interface OverlayBase {
57
103
  /** Film seconds. */
58
104
  start: number;
59
105
  end: number;
60
- /** The segment it plays in. */
106
+ /** The segment it starts in. */
61
107
  segment: number;
62
108
  }
63
109
 
64
- /** A text overlay's box: `left` and `top` of its outer edge, its width the most it may take (it shrinks to its text). */
110
+ /** How a drawn overlay looks besides its place: its entrance (null: the kind's own), typing speed and own colours. */
111
+ export interface OverlayLook {
112
+ entrance: OverlayEntrance | null;
113
+ /** Characters per second when it types its text in, else null. */
114
+ typing: number | null;
115
+ /** Its own colours in place of the brand's (empty: the brand's). */
116
+ colors: EdlOverlayColors;
117
+ }
118
+
119
+ type Drawn = OverlayBase & OverlayLook;
120
+
121
+ /**
122
+ * A text overlay's box: for `keyword`, `lower_third` and `list`, `left` and `top` of its outer edge and the most it
123
+ * may take (it shrinks to its text); for the others, the box its card takes.
124
+ */
65
125
  export type ResolvedOverlay =
66
126
  | (OverlayBase & { kind: "punch_in"; scale: number; ease: number })
67
- | (OverlayBase & { kind: "keyword" | "lower_third"; text: string; fontSize: number; side: OverlaySide; box: OverlayBox })
68
- | (OverlayBase & { kind: "list"; items: string[]; fontSize: number; side: OverlaySide; box: OverlayBox })
69
- | (OverlayBase & { kind: "arrow"; from: OverlayPoint; to: OverlayPoint })
70
- | (OverlayBase & { kind: "highlight"; rect: OverlayBox });
127
+ | (Drawn & { kind: "keyword"; text: string; fontSize: number; side: OverlaySide; box: OverlayBox })
128
+ | (Drawn & { kind: "lower_third"; text: string; fontSize: number; side: OverlaySide; box: OverlayBox })
129
+ | (Drawn & { kind: "list"; items: string[]; fontSize: number; side: OverlaySide; box: OverlayBox })
130
+ | (Drawn & { kind: "arrow"; from: OverlayPoint; to: OverlayPoint })
131
+ | (Drawn & { kind: "highlight"; rect: OverlayBox })
132
+ | (Drawn & { kind: "hook_title"; lines: string[]; place: string | null; fontSize: number; placeFontSize: number; box: OverlayBox })
133
+ | (Drawn & { kind: "search_bar"; text: string; fontSize: number; box: OverlayBox })
134
+ | (Drawn & { kind: "place_card"; lines: string[]; subtitle: string | null; fontSize: number; subtitleFontSize: number; box: OverlayBox })
135
+ | (Drawn & { kind: "counter"; value: number; from: number; decimals: number; unit: string | null; fontSize: number; unitFontSize: number; box: OverlayBox })
136
+ | (Drawn & { kind: "date_stamp"; text: string; place: string | null; fontSize: number; placeFontSize: number; side: OverlaySide; box: OverlayBox });
71
137
 
72
138
  export type ResolvedOverlaysResult = { ok: true; overlays: ResolvedOverlay[] } | { ok: false; problems: string[] };
73
139
 
@@ -115,12 +181,61 @@ function findOverlayStart(overlay: EdlOverlay, words: TimedWord[]): { ok: true;
115
181
  const r1 = (value: number): number => Math.round(value * 10) / 10;
116
182
  const r3 = (value: number): number => Math.round(value * 1000) / 1000 || 0;
117
183
 
184
+ /** The estimated width of a line of text at a font size, in px (`OVERLAY_CHAR_EM` a letter). */
185
+ export function estimateTextWidth(text: string, fontSize: number): number {
186
+ return Math.ceil([...text].length * OVERLAY_CHAR_EM * fontSize - 1e-6);
187
+ }
188
+
189
+ /** Text broken into lines at spaces so each fits `width` at `fontSize` by the estimate; a word longer than a line stands alone. */
190
+ export function wrapOverlayText(text: string, fontSize: number, width: number): string[] {
191
+ const lines: string[] = [];
192
+ for (const word of text.split(/\s+/).filter((part) => part.length > 0)) {
193
+ const last = lines[lines.length - 1];
194
+ if (last !== undefined && estimateTextWidth(`${last} ${word}`, fontSize) <= width) lines[lines.length - 1] = `${last} ${word}`;
195
+ else lines.push(word);
196
+ }
197
+ return lines;
198
+ }
199
+
200
+ /** The decimals a number is written with: 0, 1 or 2. */
201
+ function countDecimals(number: number): number {
202
+ if (Number.isInteger(number)) return 0;
203
+ return Number.isInteger(Math.round(number * 100) / 10) ? 1 : 2;
204
+ }
205
+
206
+ /** The number of decimals a counter shows: the most of its value's and its start's (at most two). */
207
+ export function getCounterDecimals(value: number, from: number): number {
208
+ return Math.max(countDecimals(value), countDecimals(from));
209
+ }
210
+
211
+ /** A counter's number as the film shows it, grouped as `locale` writes numbers, with plain spaces for the group gaps. */
212
+ export function formatOverlayNumber(value: number, decimals: number, locale: string): string {
213
+ return new Intl.NumberFormat(locale, { minimumFractionDigits: decimals, maximumFractionDigits: decimals }).format(value).replace(/[\u00a0\u202f]/g, " ");
214
+ }
215
+
216
+ /** Whether two boxes share any px. */
217
+ function isOverlapping(a: OverlayBox, b: OverlayBox): boolean {
218
+ return a.left < b.left + b.width && b.left < a.left + a.width && a.top < b.top + b.height && b.top < a.top + a.height;
219
+ }
220
+
221
+ /** The box a drawn overlay takes in the frame, or null for a `punch_in` (it draws nothing). */
222
+ export function getOverlayBounds(overlay: ResolvedOverlay): OverlayBox | null {
223
+ if (overlay.kind === "punch_in") return null;
224
+ if (overlay.kind === "highlight") return overlay.rect;
225
+ if (overlay.kind === "arrow") {
226
+ const [left, top] = [Math.min(overlay.from.x, overlay.to.x), Math.min(overlay.from.y, overlay.to.y)];
227
+ return { left, top, width: Math.max(overlay.from.x, overlay.to.x) - left, height: Math.max(overlay.from.y, overlay.to.y) - top };
228
+ }
229
+ return overlay.box;
230
+ }
231
+
118
232
  /**
119
233
  * The overlays of an EDL resolved to film time and placed, or every reason one cannot be drawn: its word is not said,
120
- * it is too short or runs past the cut or into the next segment, two overlap, two start closer than
121
- * `overlayMinSpacing`, a text overlay does not fit between the safe zone and the captions, an anchor leaves the safe
122
- * zone or sits on the captions, or a `punch_in` falls on a `kenburns` segment or inside a zoom cut's ease. An EDL
123
- * without overlays resolves to none.
234
+ * it is too short or runs past the cut or into the next segment (a `hook_title` may stay across cuts), two overlap,
235
+ * two start closer than `overlayMinSpacing`, a text overlay does not fit between the safe zone and the captions, an
236
+ * anchor leaves the safe zone or sits on the captions, or a `punch_in` falls on a `kenburns` segment or inside a zoom
237
+ * cut's ease. A `hook_title` lives in the top band: it does not count against one overlay at a time or the spacing,
238
+ * but nothing drawn while it shows may sit on it. An EDL without overlays resolves to none.
124
239
  */
125
240
  export function resolveEdlOverlays(input: ResolveOverlaysInput): ResolvedOverlaysResult {
126
241
  const overlays = input.edl.overlays ?? [];
@@ -149,7 +264,7 @@ export function resolveEdlOverlays(input: ResolveOverlaysInput): ResolvedOverlay
149
264
  const segmentStart = starts[segment] as number;
150
265
  const segmentEnd = r3(segmentStart + ((edl.segments[segment]?.end ?? 0) - (edl.segments[segment]?.start ?? 0)));
151
266
  const segmentId = edl.segments[segment]?.id ?? "";
152
- if (end > segmentEnd + 0.01) {
267
+ if (overlay.kind !== "hook_title" && end > segmentEnd + 0.01) {
153
268
  problems.push(`${at}: runs ${r1(end - segmentEnd)} s past the cut at ${segmentEnd} s; keep it inside segment "${segmentId}" (${segmentStart}-${segmentEnd} s) or shorten it`);
154
269
  return;
155
270
  }
@@ -173,9 +288,21 @@ export function resolveEdlOverlays(input: ResolveOverlaysInput): ResolvedOverlay
173
288
  resolved.push(placed.overlay);
174
289
  });
175
290
  const ordered = [...resolved].sort((a, b) => a.start - b.start);
176
- const spacing = film.overlayMinSpacing ?? 0;
177
- ordered.forEach((overlay, place) => {
178
- const previous = ordered[place - 1];
291
+ problems.push(...findTimingProblems(ordered, film.overlayMinSpacing ?? 0));
292
+ return problems.length > 0 ? { ok: false, problems } : { ok: true, overlays: ordered };
293
+ }
294
+
295
+ /** Whether two overlays are on screen at the same time. */
296
+ function isConcurrent(a: ResolvedOverlay, b: ResolvedOverlay): boolean {
297
+ return a.start < b.end - 0.001 && b.start < a.end - 0.001;
298
+ }
299
+
300
+ /** Two overlays on screen at once, two too close, two hook titles at once, or a drawing on a hook title while it shows. */
301
+ function findTimingProblems(ordered: readonly ResolvedOverlay[], spacing: number): string[] {
302
+ const problems: string[] = [];
303
+ const counted = ordered.filter((overlay) => overlay.kind !== "hook_title");
304
+ counted.forEach((overlay, place) => {
305
+ const previous = counted[place - 1];
179
306
  if (previous === undefined) return;
180
307
  if (overlay.start < previous.end - 0.001) {
181
308
  problems.push(`overlays[${overlay.index}]: starts at ${overlay.start} s while overlays[${previous.index}] is on screen (until ${previous.end} s); one overlay at a time`);
@@ -183,7 +310,20 @@ export function resolveEdlOverlays(input: ResolveOverlaysInput): ResolvedOverlay
183
310
  problems.push(`overlays[${overlay.index}]: starts ${r1(overlay.start - previous.start)} s after overlays[${previous.index}]; the film keeps overlays ${spacing} s apart (overlayMinSpacing)`);
184
311
  }
185
312
  });
186
- return problems.length > 0 ? { ok: false, problems } : { ok: true, overlays: ordered };
313
+ const titles = ordered.filter((overlay) => overlay.kind === "hook_title");
314
+ titles.forEach((title, place) => {
315
+ const previous = titles[place - 1];
316
+ if (previous !== undefined && isConcurrent(title, previous)) {
317
+ problems.push(`overlays[${title.index}]: starts at ${title.start} s while the hook title overlays[${previous.index}] is on screen (until ${previous.end} s); one hook title at a time`);
318
+ }
319
+ const titleBox = title.box;
320
+ for (const other of counted) {
321
+ const bounds = getOverlayBounds(other);
322
+ if (bounds === null || !isConcurrent(title, other) || !isOverlapping(bounds, titleBox)) continue;
323
+ problems.push(`overlays[${other.index}]: the ${other.kind.replace("_", " ")} would sit on the hook title overlays[${title.index}] (on screen until ${title.end} s); move it lower or start it after the title`);
324
+ }
325
+ });
326
+ return problems;
187
327
  }
188
328
 
189
329
  interface Placement {
@@ -213,60 +353,229 @@ function isInsideZone(place: Placement, point: OverlayPoint): boolean {
213
353
  return point.x >= zone.left && point.x <= frame.width - zone.right && point.y >= zone.top && point.y <= frame.height - zone.bottom;
214
354
  }
215
355
 
356
+ /** The top of a box `height` tall at a named position of the text region. */
357
+ function getPositionTop(region: { top: number; bottom: number }, position: OverlayPosition, height: number): number {
358
+ if (position === "top") return region.top;
359
+ if (position === "bottom") return region.bottom - height;
360
+ return Math.round(region.top + (region.bottom - region.top) * 0.4 - height / 2);
361
+ }
362
+
363
+ function getLook(overlay: EdlOverlay): OverlayLook {
364
+ return {
365
+ entrance: overlay.style?.entrance ?? null,
366
+ typing: isTypedOverlay(overlay) ? (overlay.style?.typing_speed ?? DEFAULT_OVERLAY_TYPING_SPEED) : null,
367
+ colors: { ...overlay.style?.colors },
368
+ };
369
+ }
370
+
216
371
  function placeOverlay(overlay: EdlOverlay, base: OverlayBase, place: Placement): Placed {
217
- const size = overlay.style?.size ?? "m";
218
372
  if (overlay.kind === "punch_in") {
219
373
  const ease = r3(Math.min(PUNCH_IN_EASE_SECONDS, (base.end - base.start) / 2));
220
- return { ok: true, overlay: { ...base, kind: "punch_in", scale: PUNCH_IN_SCALES[size], ease } };
374
+ return { ok: true, overlay: { ...base, kind: "punch_in", scale: PUNCH_IN_SCALES[overlay.style?.size ?? "m"], ease } };
221
375
  }
376
+ const drawn = { ...base, ...getLook(overlay) };
377
+ if (overlay.kind === "arrow" || overlay.kind === "highlight") return placeMark(overlay, drawn, place);
378
+ if (overlay.kind === "keyword" || overlay.kind === "lower_third" || overlay.kind === "list") return placeSideText({ ...overlay, kind: overlay.kind }, drawn, place);
379
+ return placeCard({ ...overlay, kind: overlay.kind }, drawn, place);
380
+ }
381
+
382
+ /** An arrow's tail and point, or a highlight's rectangle. */
383
+ function placeMark(overlay: EdlOverlay, drawn: Drawn, place: Placement): Placed {
222
384
  const { zone, frame } = place;
223
385
  const scale = frame.width / 1080;
224
- if (overlay.kind === "arrow" || overlay.kind === "highlight") {
225
- const anchor = overlay.anchor as NonNullable<EdlOverlay["anchor"]>;
226
- if (overlay.kind === "arrow") {
227
- const to = { x: anchor.x, y: anchor.y };
228
- if (!isInsideZone(place, to)) return { ok: false, error: `the arrow's point (${to.x}, ${to.y}) is outside the platform safe zone` };
229
- if (isOnCaptions(place, to.y, to.y)) return { ok: false, error: `the arrow's point (${to.x}, ${to.y}) sits on the captions` };
230
- const clampX = (x: number) => Math.min(frame.width - zone.right, Math.max(zone.left, x));
231
- const clampY = (y: number) => Math.min(frame.height - zone.bottom, Math.max(zone.top, y));
232
- const dx = Math.round(ARROW_REACH.x * scale);
233
- const dy = Math.round(ARROW_REACH.y * scale);
234
- // The tail sits towards the frame's middle and above the point (below it near the top), so the arrow reads inward.
235
- const from = { x: clampX(to.x > frame.width / 2 ? to.x - dx : to.x + dx), y: clampY(to.y - dy >= zone.top ? to.y - dy : to.y + dy) };
236
- if (isOnCaptions(place, Math.min(from.y, to.y), Math.max(from.y, to.y))) return { ok: false, error: "the arrow would cross the captions; point at something further from them" };
237
- return { ok: true, overlay: { ...base, kind: "arrow", from, to } };
238
- }
239
- const rect = { left: anchor.x, top: anchor.y, width: anchor.width ?? 0, height: anchor.height ?? 0 };
240
- if (rect.width < MIN_HIGHLIGHT_SIDE || rect.height < MIN_HIGHLIGHT_SIDE) return { ok: false, error: `the highlight is smaller than ${MIN_HIGHLIGHT_SIDE}×${MIN_HIGHLIGHT_SIDE} px` };
241
- const corner = { x: rect.left + rect.width, y: rect.top + rect.height };
242
- if (!isInsideZone(place, { x: rect.left, y: rect.top }) || !isInsideZone(place, corner)) return { ok: false, error: "the highlight reaches outside the platform safe zone" };
243
- if (isOnCaptions(place, rect.top, corner.y)) return { ok: false, error: "the highlight overlaps the captions" };
244
- return { ok: true, overlay: { ...base, kind: "highlight", rect } };
386
+ const anchor = overlay.anchor as NonNullable<EdlOverlay["anchor"]>;
387
+ if (overlay.kind === "arrow") {
388
+ const to = { x: anchor.x, y: anchor.y };
389
+ if (!isInsideZone(place, to)) return { ok: false, error: `the arrow's point (${to.x}, ${to.y}) is outside the platform safe zone` };
390
+ if (isOnCaptions(place, to.y, to.y)) return { ok: false, error: `the arrow's point (${to.x}, ${to.y}) sits on the captions` };
391
+ const clampX = (x: number) => Math.min(frame.width - zone.right, Math.max(zone.left, x));
392
+ const clampY = (y: number) => Math.min(frame.height - zone.bottom, Math.max(zone.top, y));
393
+ const dx = Math.round(ARROW_REACH.x * scale);
394
+ const dy = Math.round(ARROW_REACH.y * scale);
395
+ // The tail sits towards the frame's middle and above the point (below it near the top), so the arrow reads inward.
396
+ const from = { x: clampX(to.x > frame.width / 2 ? to.x - dx : to.x + dx), y: clampY(to.y - dy >= zone.top ? to.y - dy : to.y + dy) };
397
+ if (isOnCaptions(place, Math.min(from.y, to.y), Math.max(from.y, to.y))) return { ok: false, error: "the arrow would cross the captions; point at something further from them" };
398
+ return { ok: true, overlay: { ...drawn, kind: "arrow", from, to } };
245
399
  }
400
+ const rect = { left: anchor.x, top: anchor.y, width: anchor.width ?? 0, height: anchor.height ?? 0 };
401
+ if (rect.width < MIN_HIGHLIGHT_SIDE || rect.height < MIN_HIGHLIGHT_SIDE) return { ok: false, error: `the highlight is smaller than ${MIN_HIGHLIGHT_SIDE}×${MIN_HIGHLIGHT_SIDE} px` };
402
+ const corner = { x: rect.left + rect.width, y: rect.top + rect.height };
403
+ if (!isInsideZone(place, { x: rect.left, y: rect.top }) || !isInsideZone(place, corner)) return { ok: false, error: "the highlight reaches outside the platform safe zone" };
404
+ if (isOnCaptions(place, rect.top, corner.y)) return { ok: false, error: "the highlight overlaps the captions" };
405
+ return { ok: true, overlay: { ...drawn, kind: "highlight", rect } };
406
+ }
407
+
408
+ /** A keyword, a lower third or a list: a card on one side, its box the whole width it may take. */
409
+ function placeSideText(overlay: EdlOverlay & { kind: "keyword" | "lower_third" | "list" }, drawn: Drawn, place: Placement): Placed {
410
+ const { zone, frame } = place;
411
+ const scale = frame.width / 1080;
246
412
  const side = overlay.style?.side ?? (overlay.kind === "keyword" ? "right" : "left");
247
- const fontSize = Math.round(OVERLAY_FONT_SIZES[overlay.kind][size] * scale);
413
+ const fontSize = Math.round(OVERLAY_FONT_SIZES[overlay.kind][overlay.style?.size ?? "m"] * scale);
248
414
  const padY = Math.round(fontSize * OVERLAY_PADDING_EM.y);
249
415
  const lines = overlay.kind === "list" ? (overlay.items ?? []).length : 1;
250
416
  const lineHeight = overlay.kind === "list" ? OVERLAY_LIST_LINE_HEIGHT : OVERLAY_LINE_HEIGHT;
251
417
  const height = Math.ceil(lines * fontSize * lineHeight + 2 * padY);
252
418
  const region = getTextRegion(place);
253
- const regionHeight = region.bottom - region.top;
254
- const margin = Math.round(OVERLAY_MARGIN * scale);
255
- const top =
256
- overlay.kind === "lower_third"
257
- ? region.bottom - height
258
- : overlay.kind === "keyword"
259
- ? Math.round(region.top + regionHeight * 0.4 - height / 2)
260
- : Math.round(region.top + regionHeight * 0.15);
419
+ // Without a position, each kind's own place: the lower third on the captions' room, the keyword in the middle, the list high.
420
+ const position = overlay.style?.position ?? (overlay.kind === "lower_third" ? "bottom" : overlay.kind === "keyword" ? "middle" : null);
421
+ const top = position === null ? Math.round(region.top + (region.bottom - region.top) * 0.15) : getPositionTop(region, position, height);
261
422
  if (top < region.top || top + height > region.bottom) {
262
423
  return { ok: false, error: `the ${overlay.kind.replace("_", " ")} (${height} px tall) does not fit between the platform safe zone and the captions; use a smaller size or fewer points` };
263
424
  }
425
+ const margin = Math.round(OVERLAY_MARGIN * scale);
264
426
  const box = { left: zone.left + margin, top, width: frame.width - zone.left - zone.right - 2 * margin, height };
265
- if (overlay.kind === "list") return { ok: true, overlay: { ...base, kind: "list", items: overlay.items ?? [], fontSize, side, box } };
266
- return { ok: true, overlay: { ...base, kind: overlay.kind, text: overlay.text ?? "", fontSize, side, box } };
427
+ if (overlay.kind === "list") return { ok: true, overlay: { ...drawn, kind: "list", items: overlay.items ?? [], fontSize, side, box } };
428
+ const fields = { text: overlay.text ?? "", fontSize, side, box };
429
+ return { ok: true, overlay: overlay.kind === "keyword" ? { ...drawn, kind: "keyword", ...fields } : { ...drawn, kind: "lower_third", ...fields } };
430
+ }
431
+
432
+ type CardKind = "hook_title" | "search_bar" | "place_card" | "counter" | "date_stamp";
433
+
434
+ /** The default position of each card. */
435
+ const CARD_POSITIONS: Record<CardKind, OverlayPosition> = { hook_title: "top", search_bar: "middle", place_card: "middle", counter: "middle", date_stamp: "top" };
436
+
437
+ interface CardContent {
438
+ /** The card's content box without its padding, in px. */
439
+ width: number;
440
+ height: number;
441
+ /** The overlay's own fields. */
442
+ fields: Record<string, unknown>;
443
+ }
444
+
445
+ type CardResult = { ok: true; content: CardContent } | { ok: false; error: string };
446
+
447
+ interface CardMetrics {
448
+ fontSize: number;
449
+ pad: { x: number; y: number };
450
+ /** The widest the content may be, in px. */
451
+ room: number;
452
+ label: string;
453
+ }
454
+
455
+ const tooWide = (metrics: CardMetrics, what: string): CardResult => ({ ok: false, error: `the ${metrics.label}'s ${what} is too wide for one line; shorten it or use a smaller size` });
456
+
457
+ /** A hook title's or a place card's lines and second line. */
458
+ function measureTitle(overlay: EdlOverlay & { kind: "hook_title" | "place_card" }, metrics: CardMetrics): CardResult {
459
+ const { fontSize, room, label } = metrics;
460
+ const lines = wrapOverlayText(overlay.text ?? "", fontSize, room);
461
+ if (lines.length > MAX_OVERLAY_TITLE_LINES || lines.some((line) => estimateTextWidth(line, fontSize) > room)) {
462
+ return { ok: false, error: `the ${label} takes more than ${MAX_OVERLAY_TITLE_LINES} lines; shorten it or use a smaller size` };
463
+ }
464
+ const isHook = overlay.kind === "hook_title";
465
+ const second = (isHook ? overlay.place : overlay.subtitle) ?? null;
466
+ const secondSize = Math.round(fontSize * OVERLAY_SECONDARY_SCALE[overlay.kind]);
467
+ // The hook title's place label carries a pin about one label line wide before it.
468
+ const secondWidth = second === null ? 0 : estimateTextWidth(second, secondSize) + (isHook ? Math.round(secondSize * 1.1) : 0);
469
+ if (secondWidth > room) return tooWide(metrics, isHook ? "place label" : "subtitle");
470
+ const lineHeight = isHook ? OVERLAY_LINE_HEIGHT : OVERLAY_TITLE_LINE_HEIGHT;
471
+ return {
472
+ ok: true,
473
+ content: {
474
+ width: Math.max(secondWidth, ...lines.map((line) => estimateTextWidth(line, fontSize))),
475
+ height: lines.length * fontSize * lineHeight + (second === null ? 0 : secondSize * 1.3 + fontSize * 0.12),
476
+ fields: isHook ? { kind: "hook_title", lines, place: second, fontSize, placeFontSize: secondSize } : { kind: "place_card", lines, subtitle: second, fontSize, subtitleFontSize: secondSize },
477
+ },
478
+ };
479
+ }
480
+
481
+ /** A search field: wide whatever its query (a search field, not a pill round a word), its query on one line. */
482
+ function measureSearchBar(overlay: EdlOverlay, metrics: CardMetrics): CardResult {
483
+ const { fontSize, pad, room } = metrics;
484
+ const text = overlay.text ?? "";
485
+ const searchPad = { x: Math.round(fontSize * SEARCH_BAR_PADDING_EM.x), y: Math.round(fontSize * SEARCH_BAR_PADDING_EM.y) };
486
+ const width = Math.round(fontSize * SEARCH_BAR_ICON_EM) + estimateTextWidth(text, fontSize) + 2 * searchPad.x;
487
+ if (width > room + 2 * pad.x) return tooWide(metrics, "query");
488
+ const fieldWidth = Math.max(Math.round((room + 2 * pad.x) * 0.82), width);
489
+ const height = Math.ceil(fontSize * OVERLAY_LINE_HEIGHT + 2 * searchPad.y);
490
+ return { ok: true, content: { width: fieldWidth - 2 * pad.x, height: height - 2 * pad.y, fields: { kind: "search_bar", text, fontSize } } };
491
+ }
492
+
493
+ /** A counter: its widest number (the final value, grouped as en-US groups, as widely as any locale) and its unit. */
494
+ function measureCounter(overlay: EdlOverlay, metrics: CardMetrics): CardResult {
495
+ const { fontSize, room } = metrics;
496
+ const value = overlay.value ?? 0;
497
+ const from = overlay.from ?? 0;
498
+ const decimals = getCounterDecimals(value, from);
499
+ const unit = overlay.unit ?? null;
500
+ const unitSize = Math.round(fontSize * OVERLAY_SECONDARY_SCALE.counter);
501
+ const width = estimateTextWidth(formatOverlayNumber(value, decimals, "en-US"), fontSize) + (unit === null ? 0 : Math.round(unitSize * 0.3) + estimateTextWidth(unit, unitSize));
502
+ if (width > room) return tooWide(metrics, "number");
503
+ return { ok: true, content: { width, height: fontSize * 1.1, fields: { kind: "counter", value, from, decimals, unit, fontSize, unitFontSize: unitSize } } };
504
+ }
505
+
506
+ /** A date stamp: its day or date, and its place on a second line. */
507
+ function measureDateStamp(overlay: EdlOverlay, metrics: CardMetrics): CardResult {
508
+ const { fontSize, room } = metrics;
509
+ const text = overlay.text ?? "";
510
+ const place = overlay.place ?? null;
511
+ const placeSize = Math.round(fontSize * OVERLAY_SECONDARY_SCALE.date_stamp);
512
+ const textWidth = estimateTextWidth(text, fontSize);
513
+ const placeWidth = place === null ? 0 : estimateTextWidth(place, placeSize);
514
+ if (textWidth > room) return tooWide(metrics, "text");
515
+ if (placeWidth > room) return tooWide(metrics, "place");
516
+ return {
517
+ ok: true,
518
+ content: {
519
+ width: Math.max(textWidth, placeWidth),
520
+ height: fontSize * OVERLAY_LINE_HEIGHT + (place === null ? 0 : placeSize * 1.25),
521
+ fields: { kind: "date_stamp", text, place, fontSize, placeFontSize: placeSize, side: overlay.style?.side ?? "left" },
522
+ },
523
+ };
524
+ }
525
+
526
+ /** A hook title, a search bar, a place card, a counter or a date stamp: a card sized to its estimated content. */
527
+ function placeCard(overlay: EdlOverlay & { kind: CardKind }, drawn: Drawn, place: Placement): Placed {
528
+ const { zone, frame } = place;
529
+ const scale = frame.width / 1080;
530
+ const margin = Math.round(OVERLAY_MARGIN * scale);
531
+ const outer = frame.width - zone.left - zone.right - 2 * margin;
532
+ const fontSize = Math.round(OVERLAY_FONT_SIZES[overlay.kind][overlay.style?.size ?? "m"] * scale);
533
+ const pad = { x: Math.round(fontSize * OVERLAY_PADDING_EM.x), y: Math.round(fontSize * OVERLAY_PADDING_EM.y) };
534
+ const metrics = { fontSize, pad, room: outer - 2 * pad.x, label: overlay.kind.replace("_", " ") };
535
+ const measured =
536
+ overlay.kind === "hook_title" || overlay.kind === "place_card"
537
+ ? measureTitle({ ...overlay, kind: overlay.kind }, metrics)
538
+ : overlay.kind === "search_bar"
539
+ ? measureSearchBar(overlay, metrics)
540
+ : overlay.kind === "counter"
541
+ ? measureCounter(overlay, metrics)
542
+ : measureDateStamp(overlay, metrics);
543
+ if (!measured.ok) return measured;
544
+ const { content } = measured;
545
+ const width = Math.ceil(content.width + 2 * pad.x);
546
+ const height = Math.ceil(content.height + 2 * pad.y);
547
+ const region = getTextRegion(place);
548
+ const top = getPositionTop(region, overlay.style?.position ?? CARD_POSITIONS[overlay.kind], height);
549
+ if (top < region.top || top + height > region.bottom) {
550
+ return { ok: false, error: `the ${metrics.label} (${height} px tall) does not fit between the platform safe zone and the captions; use a smaller size or shorter text` };
551
+ }
552
+ const left =
553
+ overlay.kind !== "date_stamp" ? Math.round(zone.left + margin + (outer - width) / 2) : content.fields.side === "right" ? frame.width - zone.right - margin - width : zone.left + margin;
554
+ return { ok: true, overlay: { ...drawn, ...content.fields, box: { left, top, width, height } } as ResolvedOverlay };
555
+ }
556
+
557
+ /** The texts the overlays draw, by the brand font that draws them, for the glyph check. */
558
+ export function getOverlayTextsByRole(overlays: readonly ResolvedOverlay[], locale = "en-US"): Record<OverlayFontRole, string[]> {
559
+ const texts: Record<OverlayFontRole, string[]> = { heading: [], interface: [] };
560
+ for (const overlay of overlays) {
561
+ if (overlay.kind === "keyword" || overlay.kind === "lower_third" || overlay.kind === "search_bar") texts[OVERLAY_FONT_ROLES[overlay.kind]].push(overlay.text);
562
+ else if (overlay.kind === "list") texts.interface.push(...overlay.items);
563
+ else if (overlay.kind === "hook_title" || overlay.kind === "place_card") {
564
+ texts.heading.push(...overlay.lines);
565
+ const second = overlay.kind === "hook_title" ? overlay.place : overlay.subtitle;
566
+ if (second !== null) texts.interface.push(second);
567
+ } else if (overlay.kind === "counter") {
568
+ // Every digit shows while it counts.
569
+ texts.heading.push(formatOverlayNumber(overlay.value, overlay.decimals, locale), "0123456789", ...(overlay.unit === null ? [] : [overlay.unit]));
570
+ } else if (overlay.kind === "date_stamp") {
571
+ texts.interface.push(overlay.text, ...(overlay.place === null ? [] : [overlay.place]));
572
+ }
573
+ }
574
+ return texts;
267
575
  }
268
576
 
269
- /** The texts the overlays draw, for the glyph check. */
270
- export function getOverlayTexts(overlays: readonly ResolvedOverlay[]): string[] {
271
- return overlays.flatMap((overlay) => (overlay.kind === "keyword" || overlay.kind === "lower_third" ? [overlay.text] : overlay.kind === "list" ? overlay.items : []));
577
+ /** The texts the overlays draw, every role together. */
578
+ export function getOverlayTexts(overlays: readonly ResolvedOverlay[], locale = "en-US"): string[] {
579
+ const texts = getOverlayTextsByRole(overlays, locale);
580
+ return [...texts.heading, ...texts.interface];
272
581
  }
@@ -16,7 +16,7 @@ import { prepareClipSounds, type SpeechPeaks, type SpeechPreGain } from "./clip-
16
16
  import { readCachedTranscript, writeCacheFile, writeTranscript } from "./cache.js";
17
17
  import { composeFootage, getFootageFilmSeconds, getFootageSfxCues } from "./compose.js";
18
18
  import { getCaptionHighlight } from "./caption-highlight.js";
19
- import { getOverlayTexts, resolveEdlOverlays } from "./overlays.js";
19
+ import { getOverlayTextsByRole, resolveEdlOverlays } from "./overlays.js";
20
20
  import { findMissingCaptionGlyphs, getCaptionBounds, getFootageCaptionLayout } from "./captions.js";
21
21
  import { err, getProviderFootageFailure, ok, type FootageResult } from "./failure.js";
22
22
  import { findLowDiskProblems, getFreeBytes, getRenderTempDir, type FreeBytesReader } from "./disk.js";
@@ -115,7 +115,11 @@ export interface FootageBrand {
115
115
  /** BCP 47, e.g. `en-US`. */
116
116
  locale: string;
117
117
  colors: BrandColors;
118
- fonts: { heading: BrandFont | null; body: BrandFont | null };
118
+ /**
119
+ * The heading font (titles, keywords, numbers, the end card), the body font (captions) and the interface font
120
+ * (labels, lists, the search query, the date stamp); an absent or null interface font falls back to the body font.
121
+ */
122
+ fonts: { heading: BrandFont | null; body: BrandFont | null; interface?: BrandFont | null };
119
123
  logo: string | null;
120
124
  }
121
125
 
@@ -849,7 +853,8 @@ async function runRenderFootage(
849
853
  const layout = { ...base, caption: getFootageCaptionLayout(film, options.layout ?? {}) };
850
854
  const missing = findMissingCaptionGlyphs({
851
855
  fonts: options.brand.fonts,
852
- captions: [...(film.captions ? words.map((word) => word.text) : []), ...getOverlayTexts(overlays.overlays)],
856
+ captions: film.captions ? words.map((word) => word.text) : [],
857
+ overlays: getOverlayTextsByRole(overlays.overlays, options.brand.locale),
853
858
  endCard: getEndCardTexts(film.endCard),
854
859
  brandName: options.brand.name,
855
860
  });
package/src/index.ts CHANGED
@@ -71,30 +71,56 @@ export {
71
71
  type CaptionHighlightResult,
72
72
  } from "./footage/caption-highlight.js";
73
73
  export {
74
+ DEFAULT_OVERLAY_TYPING_SPEED,
75
+ MAX_HOOK_TITLE_SECONDS,
76
+ MAX_OVERLAY_COUNTER_VALUE,
77
+ MAX_OVERLAY_DATE_LENGTH,
78
+ MAX_OVERLAY_HOOK_TITLE_LENGTH,
74
79
  MAX_OVERLAY_KEYWORD_LENGTH,
75
80
  MAX_OVERLAY_LIST_ITEM_LENGTH,
76
81
  MAX_OVERLAY_LOWER_THIRD_LENGTH,
82
+ MAX_OVERLAY_PLACE_LENGTH,
83
+ MAX_OVERLAY_PLACE_TITLE_LENGTH,
84
+ MAX_OVERLAY_SEARCH_LENGTH,
77
85
  MAX_OVERLAY_SECONDS,
86
+ MAX_OVERLAY_SUBTITLE_LENGTH,
87
+ MAX_OVERLAY_TYPING_SPEED,
88
+ MAX_OVERLAY_UNIT_LENGTH,
78
89
  MIN_OVERLAY_SECONDS,
90
+ MIN_OVERLAY_TYPING_SPEED,
91
+ OVERLAY_ENTRANCES,
92
+ OVERLAY_ENTRANCES_BY_KIND,
79
93
  OVERLAY_KINDS,
94
+ OVERLAY_POSITIONS,
95
+ OVERLAY_POSITIONS_BY_KIND,
96
+ OVERLAY_SIDED_KINDS,
80
97
  OVERLAY_SIDES,
81
98
  OVERLAY_SIZES,
99
+ isTypedOverlay,
82
100
  type EdlOverlay,
83
101
  type EdlOverlayAnchor,
102
+ type EdlOverlayColors,
84
103
  type EdlOverlayStyle,
85
104
  type EdlOverlayWord,
105
+ type OverlayEntrance,
86
106
  type OverlayKind,
107
+ type OverlayPosition,
87
108
  type OverlaySide,
88
109
  type OverlaySize,
89
110
  } from "./footage/overlay-schema.js";
90
111
  export {
112
+ OVERLAY_FONT_ROLES,
91
113
  OVERLAY_FONT_SIZES,
92
114
  PUNCH_IN_EASE_SECONDS,
93
115
  PUNCH_IN_SCALES,
116
+ formatOverlayNumber,
117
+ getOverlayBounds,
94
118
  getOverlaySafeZone,
95
119
  getOverlayTexts,
120
+ getOverlayTextsByRole,
96
121
  resolveEdlOverlays,
97
122
  type OverlayBox,
123
+ type OverlayFontRole,
98
124
  type OverlayPoint,
99
125
  type ResolveOverlaysInput,
100
126
  type ResolvedOverlay,
@@ -47,7 +47,7 @@ function run(command: string, args: string[]): void {
47
47
  }
48
48
 
49
49
  /** Copies each font file as `<n>.<ext>`: two files with one name cannot overwrite each other, and the name is safe inside url("…"). */
50
- export function copyFonts(fonts: RenderInput["fonts"], dir: string): { heading: ComposeFont | null; body: ComposeFont | null } {
50
+ export function copyFonts(fonts: RenderInput["fonts"] & { interface?: BrandFont | null }, dir: string): { heading: ComposeFont | null; body: ComposeFont | null; interface?: ComposeFont | null } {
51
51
  rmSync(dir, { recursive: true, force: true });
52
52
  mkdirSync(dir, { recursive: true });
53
53
  let count = 0;
@@ -64,7 +64,8 @@ export function copyFonts(fonts: RenderInput["fonts"], dir: string): { heading:
64
64
  }),
65
65
  };
66
66
  };
67
- return { body: copy(fonts.body), heading: copy(fonts.heading) };
67
+ const copied = { body: copy(fonts.body), heading: copy(fonts.heading) };
68
+ return fonts.interface === undefined ? copied : { ...copied, interface: copy(fonts.interface) };
68
69
  }
69
70
 
70
71
  function getFramePath(dir: string, index: number): string {