@softure-ai/marketing-kit 0.23.0 → 0.25.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 +29 -0
  2. package/README.md +23 -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 +21 -4
  12. package/dist/footage/draft-overlays.d.ts.map +1 -1
  13. package/dist/footage/draft-overlays.js +242 -36
  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 +121 -16
  32. package/dist/footage/overlays.d.ts.map +1 -1
  33. package/dist/footage/overlays.js +323 -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 +291 -37
  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 +387 -55
  57. package/src/footage/pipeline.ts +8 -3
  58. package/src/index.ts +27 -0
  59. package/src/render/render.ts +3 -2
@@ -121,7 +121,7 @@
121
121
  "description": "The kept parts of the clips, in film order."
122
122
  },
123
123
  "overlays": {
124
- "description": "Small graphics and emphasis zooms placed on a word of the transcript (at_word) or a film second (at), one at a time, each inside one segment: punch_in, keyword, lower_third, list, arrow, highlight. Without it, none.",
124
+ "description": "Small graphics and emphasis zooms placed on a word of the transcript (at_word) or a film second (at), one at a time, each inside one segment: punch_in, keyword, lower_third, list, arrow, highlight, search_bar, place_card, counter, date_stamp; and a hook_title at the top, which may stay across cuts beside the others. Without it, none.",
125
125
  "maxItems": 40,
126
126
  "type": "array",
127
127
  "items": {
@@ -135,9 +135,14 @@
135
135
  "lower_third",
136
136
  "list",
137
137
  "arrow",
138
- "highlight"
138
+ "highlight",
139
+ "hook_title",
140
+ "search_bar",
141
+ "place_card",
142
+ "counter",
143
+ "date_stamp"
139
144
  ],
140
- "description": "punch_in (an emphasis zoom on a word), keyword, lower_third, list, arrow or highlight."
145
+ "description": "punch_in (an emphasis zoom on a word), keyword, lower_third, list, arrow, highlight, hook_title, search_bar, place_card, counter or date_stamp."
141
146
  },
142
147
  "at_word": {
143
148
  "description": "The transcript word the overlay starts on (its start after the cut); give this or at.",
@@ -168,11 +173,11 @@
168
173
  "duration": {
169
174
  "type": "number",
170
175
  "minimum": 1,
171
- "maximum": 8,
172
- "description": "Seconds on screen (1-8)."
176
+ "maximum": 180,
177
+ "description": "Seconds on screen (1-8; a hook_title up to 180)."
173
178
  },
174
179
  "text": {
175
- "description": "The keyword (up to 24 characters) or the lower third (up to 40).",
180
+ "description": "The text: keyword (up to 24 characters), lower_third (40), hook_title (64, one or two lines), search_bar (40), place_card title (28) or date_stamp (24).",
176
181
  "type": "string",
177
182
  "minLength": 1
178
183
  },
@@ -218,8 +223,38 @@
218
223
  ],
219
224
  "additionalProperties": false
220
225
  },
226
+ "place": {
227
+ "description": "A hook_title's place label above it (drawn with a pin) or a date_stamp's place, e.g. \"Hanoi, Vietnam\" (up to 40 characters).",
228
+ "type": "string",
229
+ "minLength": 1,
230
+ "maxLength": 40
231
+ },
232
+ "subtitle": {
233
+ "description": "A place_card's one-line subtitle (up to 40 characters).",
234
+ "type": "string",
235
+ "minLength": 1,
236
+ "maxLength": 40
237
+ },
238
+ "value": {
239
+ "description": "The number a counter counts up to (at most two decimals).",
240
+ "type": "number",
241
+ "minimum": 0,
242
+ "maximum": 999999999
243
+ },
244
+ "from": {
245
+ "description": "The number a counter counts from (0 by default), below its value.",
246
+ "type": "number",
247
+ "minimum": 0,
248
+ "maximum": 999999999
249
+ },
250
+ "unit": {
251
+ "description": "A counter's unit after the number, e.g. km (up to 12 characters).",
252
+ "type": "string",
253
+ "minLength": 1,
254
+ "maxLength": 12
255
+ },
221
256
  "style": {
222
- "description": "The overlay's size step and side; colours and fonts are the brand's.",
257
+ "description": "The overlay's look: size, side, position, entrance, typing speed and colours; fonts are the brand's.",
223
258
  "type": "object",
224
259
  "properties": {
225
260
  "size": {
@@ -232,12 +267,59 @@
232
267
  ]
233
268
  },
234
269
  "side": {
235
- "description": "The side a keyword, lower third or list sits on.",
270
+ "description": "The side a keyword, lower third, list or date stamp sits on.",
236
271
  "type": "string",
237
272
  "enum": [
238
273
  "left",
239
274
  "right"
240
275
  ]
276
+ },
277
+ "position": {
278
+ "description": "top, middle or bottom of the room above the captions: keyword, search_bar, place_card, counter (any), lower_third (top or bottom), list (top or middle).",
279
+ "type": "string",
280
+ "enum": [
281
+ "top",
282
+ "middle",
283
+ "bottom"
284
+ ]
285
+ },
286
+ "entrance": {
287
+ "description": "fade, slide, type (text typed in letter by letter) or none; without it the kind's own. Never a bounce or a pop.",
288
+ "type": "string",
289
+ "enum": [
290
+ "fade",
291
+ "slide",
292
+ "type",
293
+ "none"
294
+ ]
295
+ },
296
+ "typing_speed": {
297
+ "description": "Characters per second of a typed entrance or a search bar (4-40, 14 by default).",
298
+ "type": "number",
299
+ "minimum": 4,
300
+ "maximum": 40
301
+ },
302
+ "colors": {
303
+ "description": "The overlay's own colours in place of the brand's.",
304
+ "type": "object",
305
+ "properties": {
306
+ "card": {
307
+ "description": "The card's colour (#rrggbb); the brand's background without it.",
308
+ "type": "string",
309
+ "pattern": "^#[0-9a-fA-F]{6}$"
310
+ },
311
+ "text": {
312
+ "description": "The text's colour; the brand's foreground without it.",
313
+ "type": "string",
314
+ "pattern": "^#[0-9a-fA-F]{6}$"
315
+ },
316
+ "accent": {
317
+ "description": "The accent (dot, pin, magnifier, arrow, marker); the brand's accent without it.",
318
+ "type": "string",
319
+ "pattern": "^#[0-9a-fA-F]{6}$"
320
+ }
321
+ },
322
+ "additionalProperties": false
241
323
  }
242
324
  },
243
325
  "additionalProperties": false
@@ -258,17 +258,26 @@ function findMissingInFamily(font: BrandFont | null, texts: string[], read: (pat
258
258
 
259
259
  /**
260
260
  * Glyphs the film's fonts lack: the body font against the captions and the end card's url and note, the heading font
261
- * (the body font without one) against the brand name and the headline. Empty when every letter is drawn.
261
+ * (the body font without one) against the brand name, the headline and the heading overlays' texts, and the interface
262
+ * font (the body font without one) against the interface overlays' texts. Empty when every letter is drawn.
262
263
  */
263
264
  export function findMissingCaptionGlyphs(
264
- input: { fonts: { heading: BrandFont | null; body: BrandFont | null }; captions: string[]; endCard: { headline: string; url: string; note: string } | null; brandName: string },
265
+ input: {
266
+ fonts: { heading: BrandFont | null; body: BrandFont | null; interface?: BrandFont | null };
267
+ captions: string[];
268
+ /** The overlays' texts by the font that draws them (`getOverlayTextsByRole`). */
269
+ overlays?: { heading: string[]; interface: string[] };
270
+ endCard: { headline: string; url: string; note: string } | null;
271
+ brandName: string;
272
+ },
265
273
  read: (path: string) => Buffer = readFileSync,
266
274
  ): MissingCaptionGlyphs[] {
267
275
  const { fonts, endCard } = input;
268
276
  const body = findMissingInFamily(fonts.body, [...input.captions, ...(endCard === null ? [] : [endCard.url, endCard.note])], read);
269
- const headingTexts = endCard === null ? [] : [input.brandName, endCard.headline];
277
+ const headingTexts = [...(endCard === null ? [] : [input.brandName, endCard.headline]), ...(input.overlays?.heading ?? [])];
270
278
  const heading = findMissingInFamily(fonts.heading ?? fonts.body, headingTexts, read);
271
- const missing = [body, heading].filter((entry): entry is MissingCaptionGlyphs => entry !== null);
279
+ const ui = findMissingInFamily(fonts.interface ?? fonts.body, input.overlays?.interface ?? [], read);
280
+ const missing = [body, heading, ui].filter((entry): entry is MissingCaptionGlyphs => entry !== null);
272
281
  // One family serving both roles is reported once.
273
282
  const merged = new Map<string, Set<string>>();
274
283
  for (const entry of missing) merged.set(entry.font, new Set([...(merged.get(entry.font) ?? []), ...entry.characters]));
@@ -75,7 +75,8 @@ export interface FootageComposeInput {
75
75
  /** The end card's headline size. */
76
76
  headlineSize: number;
77
77
  colors: BrandColors;
78
- fonts: { heading: ComposeFont | null; body: ComposeFont | null };
78
+ /** The heading font (titles, keywords, numbers), the body font (captions) and the interface font (labels, lists); null falls back to the body font. */
79
+ fonts: { heading: ComposeFont | null; body: ComposeFont | null; interface?: ComposeFont | null };
79
80
  assets: FootageComposeAssets;
80
81
  brandName: string;
81
82
  locale: string;
@@ -276,8 +277,9 @@ export function composeFootage(input: FootageComposeInput): string {
276
277
 
277
278
  const bodyFont = fontStack(fonts.body, "sans-serif");
278
279
  const headingFont = fonts.heading === null ? bodyFont : fontStack(fonts.heading, "sans-serif");
279
- const faces = [...fontFaces(fonts.body), ...fontFaces(fonts.heading)];
280
- const overlayMarkup = getOverlayMarkup(overlays, { colors: c, headingFont, frame });
280
+ const interfaceFont = fonts.interface == null ? bodyFont : fontStack(fonts.interface, "sans-serif");
281
+ const faces = [...fontFaces(fonts.body), ...fontFaces(fonts.heading), ...fontFaces(fonts.interface ?? null)];
282
+ const overlayMarkup = getOverlayMarkup(overlays, { colors: c, headingFont, interfaceFont, locale: input.locale, frame });
281
283
 
282
284
  return assertLocalReferences(`<!doctype html>
283
285
  <html lang="${escapeHtml(input.locale)}">
@@ -1,32 +1,58 @@
1
1
  import { toAssColor } from "./draft-color.js";
2
- import type { OverlayColors } from "./overlay-html.js";
3
- import { OVERLAY_PADDING_EM, type OverlayPoint, type ResolvedOverlay } from "./overlays.js";
2
+ import { getCounterSeconds, getOverlayColors, getTypingTimes, type OverlayColors } from "./overlay-html.js";
3
+ import {
4
+ OVERLAY_FONT_ROLES,
5
+ OVERLAY_LINE_HEIGHT,
6
+ OVERLAY_LIST_LINE_HEIGHT,
7
+ OVERLAY_PADDING_EM,
8
+ OVERLAY_TITLE_LINE_HEIGHT,
9
+ SEARCH_BAR_ICON_EM,
10
+ SEARCH_BAR_PADDING_EM,
11
+ estimateTextWidth,
12
+ formatOverlayNumber,
13
+ getDrawnOverlayCard,
14
+ getSideTextLines,
15
+ type OverlayBox,
16
+ type OverlayFontRole,
17
+ type OverlayPoint,
18
+ type ResolvedOverlay,
19
+ } from "./overlays.js";
4
20
 
5
21
  /**
6
22
  * The draft's overlays as ASS (issue #1200): the same places and times as the render, simplified. Text overlays are
7
- * cards of the brand's background (libass's opaque box) with the text in its foreground; an arrow is a straight shaft
8
- * and head in the accent; a highlight the accent's outline round its rectangle. A `punch_in` is drawn by the picture's
9
- * zoom (`buildPictureFilters`), not here. They sit on layers 3 and up, over the captions' 0 to 2.
23
+ * drawn rounded cards of the brand's background, fitted to their text, with the text in its foreground; an
24
+ * arrow is a straight shaft and head in the accent; a highlight the accent's outline round its rectangle; a pin and a
25
+ * magnifier are drawings in the accent. A typed text shows letter by letter (the rest transparent, so its card keeps
26
+ * its size), a counter steps up to its value every tenth of a second, a slide moves up into place. A `punch_in` is drawn
27
+ * by the picture's zoom (`buildPictureFilters`), not here. They sit on layers 3 and 4, over the captions' 0 to 2.
10
28
  */
11
29
 
12
30
  /** An arrow's or a highlight's stroke and the arrow head's length, in px of a 1080 px wide frame (as the render). */
13
31
  const STROKE_WIDTH = 10;
14
32
  const ARROW_HEAD = 46;
15
- const FADE = "\\fad(150,250)";
33
+ const FADE_IN_MS = 150;
34
+ const FADE_OUT_MS = 250;
35
+ const FADE = `\\fad(${FADE_IN_MS},${FADE_OUT_MS})`;
36
+ /** How far a slide starts below its place, in px of a 1080 px wide frame, and how long it takes. */
37
+ const SLIDE_PX = 28;
38
+ const SLIDE_MS = 300;
39
+ /** A counter's step in the draft, in seconds. */
40
+ const COUNT_STEP = 0.1;
41
+ /** A transparent primary colour: the typed text not shown yet. */
42
+ const HIDDEN = "{\\1a&HFF&}";
16
43
 
17
44
  const r0 = (value: number): number => Math.round(value);
18
45
 
19
46
  /** An ASS colour for an override tag (`&HBBGGRR&`). */
20
47
  const toTagColor = (hex: string): string => `${toAssColor(hex).replace(/^&H../, "&H")}&`;
21
48
 
22
- /** The two styles the overlays use: `Overlay` (text on an opaque card) and `OverlayShape` (drawings). */
49
+ /** The two styles the overlays use: `OverlayShape` (drawings: cards, marks, pins) and `OverlayPlain` (text over them). */
23
50
  export function getDraftOverlayStyles(family: string, colors: OverlayColors): string[] {
24
- const card = toAssColor(colors.background);
25
51
  const text = toAssColor(colors.foreground);
26
52
  const accent = toAssColor(colors.accent);
27
53
  return [
28
- `Style: Overlay,${family},48,${text},${text},${card},${card},-1,0,0,0,100,100,0,0,3,16,0,7,0,0,0,1`,
29
54
  `Style: OverlayShape,${family},48,${accent},${accent},${accent},${accent},0,0,0,0,100,100,0,0,1,0,0,7,0,0,0,1`,
55
+ `Style: OverlayPlain,${family},48,${text},${text},${text},${text},-1,0,0,0,100,100,0,0,1,0,0,7,0,0,0,1`,
30
56
  ];
31
57
  }
32
58
 
@@ -57,35 +83,263 @@ export function getArrowDrawing(from: OverlayPoint, to: OverlayPoint, scale: num
57
83
  return `${shaft} ${tip}`;
58
84
  }
59
85
 
60
- /** The overlays as ASS events, layer 3 and up. */
61
- export function buildDraftOverlayEvents(overlays: readonly ResolvedOverlay[], colors: OverlayColors, frame: { width: number; height: number }): string[] {
62
- const scale = frame.width / 1080;
63
- const accent = toTagColor(colors.accent);
64
- return overlays.flatMap((overlay) => {
65
- const at = `${toAssTime(overlay.start)},${toAssTime(overlay.end)}`;
66
- if (overlay.kind === "punch_in") return [];
67
- if (overlay.kind === "arrow") {
68
- return [`Dialogue: 3,${at},OverlayShape,,0,0,0,,{\\an7\\pos(0,0)${FADE}\\p1}${getArrowDrawing(overlay.from, overlay.to, scale)}{\\p0}`];
86
+ /** A rounded rectangle as an ASS drawing: straight sides and quarter-circle corners of radius `radius` (bezier). */
87
+ export function getRoundedRectDrawing(box: { left: number; top: number; width: number; height: number }, radius: number): string {
88
+ const r = Math.min(radius, box.width / 2, box.height / 2);
89
+ const k = r * 0.4477; // 1 - 0.5523, the bezier handle of a quarter circle
90
+ const [x0, y0, x1, y1] = [box.left, box.top, box.left + box.width, box.top + box.height];
91
+ const p = (x: number, y: number) => `${r0(x)} ${r0(y)}`;
92
+ return [
93
+ `m ${p(x0 + r, y0)} l ${p(x1 - r, y0)}`,
94
+ `b ${p(x1 - k, y0)} ${p(x1, y0 + k)} ${p(x1, y0 + r)} l ${p(x1, y1 - r)}`,
95
+ `b ${p(x1, y1 - k)} ${p(x1 - k, y1)} ${p(x1 - r, y1)} l ${p(x0 + r, y1)}`,
96
+ `b ${p(x0 + k, y1)} ${p(x0, y1 - k)} ${p(x0, y1 - r)} l ${p(x0, y0 + r)}`,
97
+ `b ${p(x0, y0 + k)} ${p(x0 + k, y0)} ${p(x0 + r, y0)}`,
98
+ ].join(" ");
99
+ }
100
+
101
+ /** A circle as an ASS drawing (four bezier quarters), clockwise, or the other way round to cut a hole. */
102
+ function getCircleDrawing(center: OverlayPoint, radius: number, isReversed = false): string {
103
+ const k = radius * 0.5523;
104
+ const p = (x: number, y: number) => `${r0(center.x + x)} ${r0(center.y + y)}`;
105
+ const turn = isReversed ? -1 : 1;
106
+ return `m ${p(0, -radius)} b ${p(turn * k, -radius)} ${p(turn * radius, -k)} ${p(turn * radius, 0)} b ${p(turn * radius, k)} ${p(turn * k, radius)} ${p(0, radius)} b ${p(-turn * k, radius)} ${p(-turn * radius, k)} ${p(-turn * radius, 0)} b ${p(-turn * radius, -k)} ${p(-turn * k, -radius)} ${p(0, -radius)}`;
107
+ }
108
+
109
+ /** A map pin `size` px tall with its top left at `at`: a drop, its hole cut by drawing it the other way round. */
110
+ export function getPinDrawing(at: OverlayPoint, size: number): string {
111
+ const s = size / 24;
112
+ const p = (x: number, y: number) => `${r0(at.x + x * s)} ${r0(at.y + y * s)}`;
113
+ const drop = `m ${p(12, 22.5)} b ${p(9, 19)} ${p(4.25, 13.5)} ${p(4.25, 9.1)} b ${p(4.25, 4.9)} ${p(7.7, 1.5)} ${p(12, 1.5)} b ${p(16.3, 1.5)} ${p(19.75, 4.9)} ${p(19.75, 9.1)} b ${p(19.75, 13.5)} ${p(15, 19)} ${p(12, 22.5)}`;
114
+ const hole = `m ${p(12, 6.1)} b ${p(10.3, 6.1)} ${p(9, 7.4)} ${p(9, 9.1)} b ${p(9, 10.8)} ${p(10.3, 12.1)} ${p(12, 12.1)} b ${p(13.7, 12.1)} ${p(15, 10.8)} ${p(15, 9.1)} b ${p(15, 7.4)} ${p(13.7, 6.1)} ${p(12, 6.1)}`;
115
+ return `${drop} ${hole}`;
116
+ }
117
+
118
+ /** A magnifier `size` px wide with its top left at `at`: a ring and a handle. */
119
+ export function getGlassDrawing(at: OverlayPoint, size: number): string {
120
+ const s = size / 24;
121
+ const center = { x: at.x + 10 * s, y: at.y + 10 * s };
122
+ const ring = `${getCircleDrawing(center, 7.9 * s)} ${getCircleDrawing(center, 5.3 * s, true)}`;
123
+ const half = 1.3 * s;
124
+ const p = (x: number, y: number) => `${r0(at.x + x * s)} ${r0(at.y + y * s)}`;
125
+ const handle = `m ${p(15 - half, 15 + half)} l ${p(15 + half, 15 - half)} ${p(21 + half, 21 - half)} ${p(21 - half, 21 + half)}`;
126
+ return `${ring} ${handle}`;
127
+ }
128
+
129
+ interface DraftContext {
130
+ brand: OverlayColors;
131
+ scale: number;
132
+ locale: string;
133
+ /** The font family per role, when it is not the styles' own. */
134
+ fonts: Partial<Record<OverlayFontRole, string>>;
135
+ }
136
+
137
+ /** One stretch of an overlay's text: what shows from `from` to `to`, and its tags. */
138
+ interface TextStep {
139
+ from: number;
140
+ to: number;
141
+ text: string;
142
+ }
143
+
144
+ /** The entrance and exit tags of a run of events: the first fades or slides in, the last fades out. */
145
+ function getMotionTags(entrance: "fade" | "slide" | "none", isFirst: boolean, isLast: boolean, slide: { x: number; y: number; dy: number } | null): string {
146
+ const fadeIn = isFirst && entrance !== "none" ? FADE_IN_MS : 0;
147
+ const fadeOut = isLast ? FADE_OUT_MS : 0;
148
+ const fade = fadeIn === 0 && fadeOut === 0 ? "" : `\\fad(${fadeIn},${fadeOut})`;
149
+ const move = isFirst && entrance === "slide" && slide !== null ? `\\move(${r0(slide.x)},${r0(slide.y + slide.dy)},${r0(slide.x)},${r0(slide.y)},0,${SLIDE_MS})` : "";
150
+ return `${move}${fade}`;
151
+ }
152
+
153
+ /** Text events for a run of steps, positioned at `pos` with `tags`, the entrance on the first and the fade out on the last. */
154
+ function getTextEvents(input: { layer: number; style: string; pos: OverlayPoint; tags: string; steps: TextStep[]; entrance: "fade" | "slide" | "none"; slidePx: number }): string[] {
155
+ return input.steps.map((step, index) => {
156
+ const motion = getMotionTags(input.entrance, index === 0, index === input.steps.length - 1, { x: input.pos.x, y: input.pos.y, dy: input.slidePx });
157
+ const pos = motion.includes("\\move") ? "" : `\\pos(${r0(input.pos.x)},${r0(input.pos.y)})`;
158
+ return `Dialogue: ${input.layer},${toAssTime(step.from)},${toAssTime(step.to)},${input.style},,0,0,0,,{${input.tags}${pos}${motion}}${step.text}`;
159
+ });
160
+ }
161
+
162
+ /** The steps of a text that types in letter by letter (the rest transparent), or one step showing it all. */
163
+ function getTypedSteps(text: string, span: { start: number; end: number }, typing: number | null): TextStep[] {
164
+ const clean = toAssText(text);
165
+ if (typing === null || clean.length === 0) return [{ from: span.start, to: span.end, text: clean }];
166
+ const chars = [...clean];
167
+ const times = getTypingTimes(span.start, clean, typing).map((time) => Math.min(time, span.end));
168
+ const steps: TextStep[] = [{ from: span.start, to: times[0] as number, text: `${HIDDEN}${clean}` }];
169
+ times.forEach((time, index) => {
170
+ const shown = chars.slice(0, index + 1).join("");
171
+ const rest = chars.slice(index + 1).join("");
172
+ steps.push({ from: time, to: times[index + 1] ?? span.end, text: rest.length === 0 ? shown : `${shown}${HIDDEN}${rest}` });
173
+ });
174
+ return steps.filter((step) => step.to > step.from);
175
+ }
176
+
177
+ /** The colour and font override tags of an overlay's text: only what differs from the style. */
178
+ function getTextTags(overlay: ResolvedOverlay, colors: OverlayColors, context: DraftContext, role: OverlayFontRole): string {
179
+ if (overlay.kind === "punch_in") return "";
180
+ const own = overlay.colors;
181
+ const font = context.fonts[role];
182
+ return [
183
+ font === undefined ? "" : `\\fn${font}`,
184
+ own.text === undefined ? "" : `\\1c${toTagColor(colors.foreground)}`,
185
+ ].join("");
186
+ }
187
+
188
+ /** The corner radius of a keyword's, a lower third's or a list's card: the render's `.ov-card` (0.42 em). */
189
+ function getSideCardRadius(fontSize: number): number {
190
+ return fontSize * 0.42;
191
+ }
192
+
193
+ /**
194
+ * A keyword, a lower third or a list: a drawn rounded card fitted to its text (`getDrawnOverlayCard`) on layer 3 and
195
+ * its text on layer 4, inset by the card's padding on its side (a lower third from its foot).
196
+ */
197
+ function getSideTextEvents(overlay: Extract<ResolvedOverlay, { kind: "keyword" | "lower_third" | "list" }>, context: DraftContext): string[] {
198
+ const colors = getOverlayColors(overlay, context.brand);
199
+ const { fontSize, side } = overlay;
200
+ // A side text always has a card: only a punch_in has none.
201
+ const card = getDrawnOverlayCard(overlay) as OverlayBox;
202
+ const padX = r0(fontSize * OVERLAY_PADDING_EM.x);
203
+ const padY = r0(fontSize * OVERLAY_PADDING_EM.y);
204
+ const isRight = side === "right";
205
+ const x = isRight ? card.left + card.width - padX : card.left + padX;
206
+ const isFoot = overlay.kind === "lower_third";
207
+ const y = isFoot ? card.top + card.height - padY : card.top + padY;
208
+ // \an: 7 top left, 9 top right, 1 bottom left, 3 bottom right.
209
+ const align = isFoot ? (isRight ? 3 : 1) : isRight ? 9 : 7;
210
+ const entrance = overlay.entrance === null || overlay.entrance === "type" ? "fade" : overlay.entrance;
211
+ const span = { start: overlay.start, end: overlay.end };
212
+ const tags = `\\an${align}\\fs${fontSize}${getTextTags(overlay, colors, context, OVERLAY_FONT_ROLES[overlay.kind])}`;
213
+ const text = (pos: OverlayPoint, steps: TextStep[]) => getTextEvents({ layer: 4, style: "OverlayPlain", pos, tags, steps, entrance, slidePx: SLIDE_PX * context.scale });
214
+ const shape = getShapeEvent(overlay, getRoundedRectDrawing(card, getSideCardRadius(fontSize)), colors.background, entrance, context.scale);
215
+ if (overlay.kind === "list") {
216
+ // One event per point, on the render's line height (libass's own line spacing is tighter), all shown at once.
217
+ const step = fontSize * OVERLAY_LIST_LINE_HEIGHT;
218
+ const lead = (step - fontSize * OVERLAY_LINE_HEIGHT) / 2;
219
+ return [shape, ...getSideTextLines(overlay).flatMap((line, index) => text({ x, y: y + lead + index * step }, [{ from: span.start, to: span.end, text: toAssText(line) }]))];
220
+ }
221
+ // A keyword or a lower third types in only when its entrance says so.
222
+ return [shape, ...text({ x, y }, overlay.entrance === null ? [{ from: span.start, to: span.end, text: toAssText(overlay.text) }] : getTypedSteps(overlay.text, span, overlay.typing))];
223
+ }
224
+
225
+ type CardOverlay = Extract<ResolvedOverlay, { kind: "hook_title" | "search_bar" | "place_card" | "counter" | "date_stamp" }>;
226
+
227
+ /** Each card's own entrance when the overlay names none (a typed card fades its card in). */
228
+ const DEFAULT_ENTRANCES = { hook_title: "slide", search_bar: "fade", place_card: "slide", counter: "fade", date_stamp: "fade" } as const;
229
+
230
+ /** A drawing event in the overlay's card colour (or accent), with the overlay's entrance. */
231
+ function getShapeEvent(overlay: Pick<ResolvedOverlay, "start" | "end">, drawing: string, colour: string, entrance: "fade" | "slide" | "none", scale: number): string {
232
+ const motion = getMotionTags(entrance, true, true, { x: 0, y: 0, dy: SLIDE_PX * scale });
233
+ const pos = motion.includes("\\move") ? "" : "\\pos(0,0)";
234
+ return `Dialogue: 3,${toAssTime(overlay.start)},${toAssTime(overlay.end)},OverlayShape,,0,0,0,,{\\an7${pos}${motion}\\1c${toTagColor(colour)}\\p1}${drawing}{\\p0}`;
235
+ }
236
+
237
+ /** A hook title, a search bar, a place card, a counter or a date stamp: a drawn rounded card and its text on layer 4. */
238
+ function getCardEvents(overlay: CardOverlay, context: DraftContext): string[] {
239
+ const colors = getOverlayColors(overlay, context.brand);
240
+ const { box, fontSize } = overlay;
241
+ const entrance = overlay.entrance === null || overlay.entrance === "type" ? (overlay.typing !== null ? "fade" : DEFAULT_ENTRANCES[overlay.kind]) : overlay.entrance;
242
+ const slidePx = SLIDE_PX * context.scale;
243
+ const span = { start: overlay.start, end: overlay.end };
244
+ const radius = overlay.kind === "search_bar" ? box.height / 2 : fontSize * 0.42;
245
+ const events = [getShapeEvent(overlay, getRoundedRectDrawing(box, radius), colors.background, entrance, context.scale)];
246
+ const padX = r0(fontSize * OVERLAY_PADDING_EM.x);
247
+ const padY = r0(fontSize * OVERLAY_PADDING_EM.y);
248
+ const centerX = box.left + box.width / 2;
249
+ const tagsFor = (role: OverlayFontRole) => getTextTags(overlay, colors, context, role);
250
+ const text = (pos: OverlayPoint, align: number, size: number, role: OverlayFontRole, steps: TextStep[]) =>
251
+ getTextEvents({ layer: 4, style: "OverlayPlain", pos, tags: `\\an${align}\\fs${r0(size)}${tagsFor(role)}`, steps, entrance, slidePx });
252
+ if (overlay.kind === "hook_title" || overlay.kind === "place_card") {
253
+ let y = box.top + padY;
254
+ if (overlay.kind === "hook_title" && overlay.place !== null) {
255
+ const size = overlay.placeFontSize;
256
+ const pin = Math.round(size * 1.05);
257
+ const rowWidth = pin + Math.round(size * 0.25) + estimateTextWidth(overlay.place, size);
258
+ const rowLeft = centerX - rowWidth / 2;
259
+ events.push(getShapeEvent(overlay, getPinDrawing({ x: rowLeft, y: y + (size * OVERLAY_LINE_HEIGHT - pin) / 2 }, pin), colors.accent, entrance, context.scale).replace("Dialogue: 3,", "Dialogue: 4,"));
260
+ events.push(...text({ x: rowLeft + pin + Math.round(size * 0.25), y }, 7, size, OVERLAY_FONT_ROLES.date_stamp, [{ from: span.start, to: span.end, text: toAssText(overlay.place) }]));
261
+ y += size * 1.3 + fontSize * 0.12;
262
+ }
263
+ const lineHeight = overlay.kind === "hook_title" ? OVERLAY_LINE_HEIGHT : OVERLAY_TITLE_LINE_HEIGHT;
264
+ let typedBefore = 0;
265
+ overlay.lines.forEach((line) => {
266
+ // The lines type one after the other, as the render's characters do.
267
+ const lineStart = overlay.typing === null ? span.start : span.start + typedBefore / overlay.typing;
268
+ events.push(...text({ x: centerX, y }, 8, fontSize, "heading", getTypedSteps(line, { start: lineStart, end: span.end }, overlay.typing).map((step, index) => (index === 0 ? { ...step, from: span.start } : step))));
269
+ typedBefore += [...line].length;
270
+ y += fontSize * lineHeight;
271
+ });
272
+ if (overlay.kind === "place_card" && overlay.subtitle !== null) {
273
+ events.push(...text({ x: centerX, y: y + fontSize * 0.12 }, 8, overlay.subtitleFontSize, "interface", [{ from: span.start, to: span.end, text: toAssText(overlay.subtitle) }]));
69
274
  }
70
- if (overlay.kind === "highlight") {
71
- // libass grows a drawing's border outwards only: the shape is inset by half the stroke and bordered by all of
72
- // it, so the stroke straddles the rectangle's edge as the render's SVG stroke does.
73
- const stroke = r0(STROKE_WIDTH * scale);
74
- const half = stroke / 2;
75
- const [left, top] = [overlay.rect.left + half, overlay.rect.top + half];
76
- const [right, bottom] = [overlay.rect.left + overlay.rect.width - half, overlay.rect.top + overlay.rect.height - half];
77
- const shape = `m ${r0(left)} ${r0(top)} l ${r0(right)} ${r0(top)} ${r0(right)} ${r0(bottom)} ${r0(left)} ${r0(bottom)}`;
78
- return [`Dialogue: 3,${at},OverlayShape,,0,0,0,,{\\an7\\pos(0,0)${FADE}\\1a&HFF&\\3c${accent}\\bord${stroke}\\p1}${shape}{\\p0}`];
275
+ return events;
276
+ }
277
+ if (overlay.kind === "search_bar") {
278
+ const searchPadX = r0(fontSize * SEARCH_BAR_PADDING_EM.x);
279
+ const middle = box.top + box.height / 2;
280
+ events.push(getShapeEvent(overlay, getGlassDrawing({ x: box.left + searchPadX, y: middle - fontSize / 2 }, fontSize), colors.accent, entrance, context.scale).replace("Dialogue: 3,", "Dialogue: 4,"));
281
+ events.push(...text({ x: box.left + searchPadX + Math.round(fontSize * SEARCH_BAR_ICON_EM), y: middle }, 4, fontSize, "interface", getTypedSteps(overlay.text, span, overlay.typing)));
282
+ return events;
283
+ }
284
+ if (overlay.kind === "counter") {
285
+ const unit = overlay.unit === null ? "" : `{\\fs${overlay.unitFontSize}} ${toAssText(overlay.unit)}`;
286
+ const count = getCounterSeconds(overlay);
287
+ const steps: TextStep[] = [];
288
+ const ticks = Math.max(1, Math.round(count.duration / COUNT_STEP));
289
+ const show = (value: number) => `${formatOverlayNumber(value, overlay.decimals, context.locale)}${unit}`;
290
+ steps.push({ from: span.start, to: count.start, text: show(overlay.from) });
291
+ for (let tick = 1; tick <= ticks; tick++) {
292
+ const progress = tick / ticks;
293
+ // power2.out, as the render's tween eases.
294
+ const eased = 1 - (1 - progress) ** 2;
295
+ const value = overlay.from + (overlay.value - overlay.from) * eased;
296
+ steps.push({ from: count.start + (tick - 1) * COUNT_STEP, to: tick === ticks ? span.end : count.start + tick * COUNT_STEP, text: show(value) });
79
297
  }
80
- const { box, fontSize, side } = overlay;
81
- const pad = r0(fontSize * OVERLAY_PADDING_EM.y);
82
- const isRight = side === "right";
83
- const x = isRight ? box.left + box.width - pad : box.left + pad;
84
- const isFoot = overlay.kind === "lower_third";
85
- const y = isFoot ? box.top + box.height - pad : box.top + pad;
86
- // \an: 7 top left, 9 top right, 1 bottom left, 3 bottom right.
87
- const align = isFoot ? (isRight ? 3 : 1) : isRight ? 9 : 7;
88
- const text = overlay.kind === "list" ? overlay.items.map((item) => `• ${toAssText(item)}`).join("\\N") : toAssText(overlay.text);
89
- return [`Dialogue: 3,${at},Overlay,,0,0,0,,{\\an${align}\\pos(${r0(x)},${r0(y)})\\fs${fontSize}\\bord${pad}${FADE}}${text}`];
298
+ return [...events, ...text({ x: centerX, y: box.top + box.height / 2 }, 5, fontSize, "heading", steps.filter((step) => step.to > step.from))];
299
+ }
300
+ const isRight = overlay.side === "right";
301
+ const x = isRight ? box.left + box.width - padX : box.left + padX;
302
+ events.push(...text({ x, y: box.top + padY }, isRight ? 9 : 7, fontSize, "interface", getTypedSteps(overlay.text, span, overlay.typing)));
303
+ if (overlay.place !== null) {
304
+ events.push(...text({ x, y: box.top + padY + fontSize * OVERLAY_LINE_HEIGHT }, isRight ? 9 : 7, overlay.placeFontSize, "interface", [{ from: span.start, to: span.end, text: toAssText(overlay.place) }]));
305
+ }
306
+ return events;
307
+ }
308
+
309
+ /** An arrow or a highlight in its accent. */
310
+ function getMarkEvents(overlay: Extract<ResolvedOverlay, { kind: "arrow" | "highlight" }>, context: DraftContext): string[] {
311
+ const at = `${toAssTime(overlay.start)},${toAssTime(overlay.end)}`;
312
+ const accent = toTagColor(getOverlayColors(overlay, context.brand).accent);
313
+ const fade = overlay.entrance === "none" ? `\\fad(0,${FADE_OUT_MS})` : FADE;
314
+ const colour = overlay.colors.accent === undefined ? "" : `\\1c${accent}`;
315
+ if (overlay.kind === "arrow") {
316
+ return [`Dialogue: 3,${at},OverlayShape,,0,0,0,,{\\an7\\pos(0,0)${fade}${colour}\\p1}${getArrowDrawing(overlay.from, overlay.to, context.scale)}{\\p0}`];
317
+ }
318
+ // libass grows a drawing's border outwards only: the shape is inset by half the stroke and bordered by all of
319
+ // it, so the stroke straddles the rectangle's edge as the render's SVG stroke does.
320
+ const stroke = r0(STROKE_WIDTH * context.scale);
321
+ const half = stroke / 2;
322
+ const [left, top] = [overlay.rect.left + half, overlay.rect.top + half];
323
+ const [right, bottom] = [overlay.rect.left + overlay.rect.width - half, overlay.rect.top + overlay.rect.height - half];
324
+ const shape = `m ${r0(left)} ${r0(top)} l ${r0(right)} ${r0(top)} ${r0(right)} ${r0(bottom)} ${r0(left)} ${r0(bottom)}`;
325
+ return [`Dialogue: 3,${at},OverlayShape,,0,0,0,,{\\an7\\pos(0,0)${fade}\\1a&HFF&\\3c${accent}\\bord${stroke}\\p1}${shape}{\\p0}`];
326
+ }
327
+
328
+ /**
329
+ * The overlays as ASS events, layers 3 and 4. `fonts` names the heading and interface families where they are not the
330
+ * styles' own (the captions' font); `locale` groups a counter's number as the render does.
331
+ */
332
+ export function buildDraftOverlayEvents(
333
+ overlays: readonly ResolvedOverlay[],
334
+ colors: OverlayColors,
335
+ frame: { width: number; height: number },
336
+ options: { fonts?: Partial<Record<OverlayFontRole, string>>; locale?: string } = {},
337
+ ): string[] {
338
+ const context: DraftContext = { brand: colors, scale: frame.width / 1080, locale: options.locale ?? "en-US", fonts: options.fonts ?? {} };
339
+ return overlays.flatMap((overlay) => {
340
+ if (overlay.kind === "punch_in") return [];
341
+ if (overlay.kind === "arrow" || overlay.kind === "highlight") return getMarkEvents(overlay, context);
342
+ if (overlay.kind === "keyword" || overlay.kind === "lower_third" || overlay.kind === "list") return getSideTextEvents(overlay, context);
343
+ return getCardEvents(overlay, context);
90
344
  });
91
345
  }
@@ -12,7 +12,7 @@ import { getSegmentScales, getSegmentZoomEases } from "./compose.js";
12
12
  import { toAssColor } from "./draft-color.js";
13
13
  import { buildDraftOverlayEvents, getDraftOverlayStyles } from "./draft-overlays.js";
14
14
  import type { OverlayColors } from "./overlay-html.js";
15
- import { resolveEdlOverlays, type ResolvedOverlay } from "./overlays.js";
15
+ import { resolveEdlOverlays, type OverlayFontRole, type ResolvedOverlay } from "./overlays.js";
16
16
  import { chooseFootageDraftFont } from "./draft-font.js";
17
17
  import { getEdlDuration, getSegmentStarts, remapWords, type Edl } from "./edl.js";
18
18
  import { declickSpeech, describeDeclick, type DeclickReport } from "./declick.js";
@@ -134,6 +134,10 @@ export interface FootageDraftCaptionsInput {
134
134
  overlays?: ResolvedOverlay[];
135
135
  /** The overlays' card, text and accent colours; default `FOOTAGE_DRAFT_OVERLAY_COLORS`. */
136
136
  overlayColors?: OverlayColors;
137
+ /** The overlays' heading and interface font families where they are not `fontFamily` (as the font files name them). */
138
+ overlayFonts?: Partial<Record<OverlayFontRole, string>>;
139
+ /** How a counter groups its number (BCP 47); default `en-US`. */
140
+ locale?: string;
137
141
  }
138
142
 
139
143
  /** The pieces of a `highlight` chunk's span: cut wherever a word lights up or goes out (in centiseconds), with the words lit in each. */
@@ -279,7 +283,10 @@ export function buildFootageDraftCaptions(input: FootageDraftCaptionsInput): str
279
283
  "[Events]",
280
284
  "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
281
285
  ...events,
282
- ...buildDraftOverlayEvents(overlays, input.overlayColors ?? FOOTAGE_DRAFT_OVERLAY_COLORS, input.frame),
286
+ ...buildDraftOverlayEvents(overlays, input.overlayColors ?? FOOTAGE_DRAFT_OVERLAY_COLORS, input.frame, {
287
+ ...(input.overlayFonts === undefined ? {} : { fonts: input.overlayFonts }),
288
+ ...(input.locale === undefined ? {} : { locale: input.locale }),
289
+ }),
283
290
  "",
284
291
  ].join("\n");
285
292
  }
@@ -519,7 +526,7 @@ export interface RenderFootageDraftOptions extends Pick<FootageRunOptions, "buil
519
526
  * OpenType file; DejaVu Sans when it has none) and its caption colours. Without it, DejaVu Sans and
520
527
  * `FOOTAGE_DRAFT_CAPTION_COLORS`.
521
528
  */
522
- brand?: { colors: FootageDraftCaptionColors & Partial<OverlayColors>; fonts: Pick<FootageBrand["fonts"], "body"> };
529
+ brand?: { colors: FootageDraftCaptionColors & Partial<OverlayColors>; fonts: Pick<FootageBrand["fonts"], "body"> & Partial<Pick<FootageBrand["fonts"], "heading" | "interface">>; locale?: string };
523
530
  /**
524
531
  * ffmpeg's threads for the draft's decoders, filter graph and encoder (`buildFootageDraftArgs`); by default ffmpeg's
525
532
  * own choice, which follows the host's cores. Set it from a CPU-limited container's quota.
@@ -633,6 +640,13 @@ async function runRenderFootageDraft(
633
640
  : FOOTAGE_DRAFT_OVERLAY_COLORS;
634
641
  const brandFont = chooseFootageDraftFont(options.brand?.fonts.body ?? null);
635
642
  const font = brandFont ?? FOOTAGE_DRAFT_FONT;
643
+ // The overlays' heading and interface fonts, where the brand has a TrueType or OpenType file for them.
644
+ const roleFonts = Object.fromEntries(
645
+ (["heading", "interface"] as const).flatMap((role) => {
646
+ const chosen = overlays.length === 0 ? null : chooseFootageDraftFont(options.brand?.fonts[role] ?? null);
647
+ return chosen === null || chosen.family === font.family ? [] : [[role, chosen]];
648
+ }),
649
+ ) as Partial<Record<OverlayFontRole, { family: string; file: string }>>;
636
650
  const captions = buildFootageDraftCaptions({
637
651
  film,
638
652
  edl,
@@ -642,11 +656,13 @@ async function runRenderFootageDraft(
642
656
  fontFamily: font.family,
643
657
  ...(options.brand === undefined ? {} : { colors: options.brand.colors }),
644
658
  ...(overlays.length === 0 ? {} : { overlays, overlayColors }),
659
+ ...(Object.keys(roleFonts).length === 0 ? {} : { overlayFonts: Object.fromEntries(Object.entries(roleFonts).map(([role, chosen]) => [role, chosen.family])) }),
660
+ ...(options.brand?.locale === undefined ? {} : { locale: options.brand.locale }),
645
661
  });
646
662
  if (captions !== null) {
647
663
  writeFileSync(join(draftDir, "captions.ass"), captions);
648
664
  mkdirSync(join(draftDir, "fonts"));
649
- copyFileSync(font.file, join(draftDir, "fonts", basename(font.file)));
665
+ for (const file of new Set([font.file, ...Object.values(roleFonts).map((chosen) => chosen.file)])) copyFileSync(file, join(draftDir, "fonts", basename(file)));
650
666
  if (brandFont === null && options.brand?.fonts.body != null) {
651
667
  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}.`);
652
668
  }
@@ -109,7 +109,7 @@ export const edlSchema = z
109
109
  .max(40)
110
110
  .optional()
111
111
  .describe(
112
- "Small graphics and emphasis zooms placed on a word of the transcript (at_word) or a film second (at), one at a time, each inside one segment: punch_in, keyword, lower_third, list, arrow, highlight. Without it, none.",
112
+ "Small graphics and emphasis zooms placed on a word of the transcript (at_word) or a film second (at), one at a time, each inside one segment: punch_in, keyword, lower_third, list, arrow, highlight, search_bar, place_card, counter, date_stamp; and a hook_title at the top, which may stay across cuts beside the others. Without it, none.",
113
113
  ),
114
114
  })
115
115
  .describe("The edit decision list of a footage film (edl.json).");