@softure-ai/marketing-kit 0.21.1 → 0.22.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 (108) hide show
  1. package/CHANGELOG.md +31 -0
  2. package/NOTICE +11 -0
  3. package/README.md +35 -4
  4. package/dist/config/actions-schema.d.ts +35 -35
  5. package/dist/config/brand.d.ts.map +1 -1
  6. package/dist/config/brand.js +22 -1
  7. package/dist/config/brand.js.map +1 -1
  8. package/dist/config/colors.d.ts +12 -2
  9. package/dist/config/colors.d.ts.map +1 -1
  10. package/dist/config/colors.js +32 -0
  11. package/dist/config/colors.js.map +1 -1
  12. package/dist/config/config.d.ts.map +1 -1
  13. package/dist/config/config.js +2 -0
  14. package/dist/config/config.js.map +1 -1
  15. package/dist/config/schema.d.ts +181 -172
  16. package/dist/config/schema.d.ts.map +1 -1
  17. package/dist/config/schema.js +16 -4
  18. package/dist/config/schema.js.map +1 -1
  19. package/dist/config/shot-steps.d.ts +40 -40
  20. package/dist/footage/caption-highlight.d.ts +44 -0
  21. package/dist/footage/caption-highlight.d.ts.map +1 -0
  22. package/dist/footage/caption-highlight.js +29 -0
  23. package/dist/footage/caption-highlight.js.map +1 -0
  24. package/dist/footage/compose.d.ts +3 -0
  25. package/dist/footage/compose.d.ts.map +1 -1
  26. package/dist/footage/compose.js +33 -6
  27. package/dist/footage/compose.js.map +1 -1
  28. package/dist/footage/draft-color.d.ts +6 -0
  29. package/dist/footage/draft-color.d.ts.map +1 -0
  30. package/dist/footage/draft-color.js +14 -0
  31. package/dist/footage/draft-color.js.map +1 -0
  32. package/dist/footage/draft-overlays.d.ts +12 -0
  33. package/dist/footage/draft-overlays.d.ts.map +1 -0
  34. package/dist/footage/draft-overlays.js +83 -0
  35. package/dist/footage/draft-overlays.js.map +1 -0
  36. package/dist/footage/draft.d.ts +27 -9
  37. package/dist/footage/draft.d.ts.map +1 -1
  38. package/dist/footage/draft.js +99 -37
  39. package/dist/footage/draft.js.map +1 -1
  40. package/dist/footage/edl.d.ts +41 -0
  41. package/dist/footage/edl.d.ts.map +1 -1
  42. package/dist/footage/edl.js +10 -0
  43. package/dist/footage/edl.js.map +1 -1
  44. package/dist/footage/film.d.ts +14 -0
  45. package/dist/footage/film.d.ts.map +1 -1
  46. package/dist/footage/film.js +2 -0
  47. package/dist/footage/film.js.map +1 -1
  48. package/dist/footage/isolate-ranges.js +1 -1
  49. package/dist/footage/isolate-ranges.js.map +1 -1
  50. package/dist/footage/overlay-html.d.ts +29 -0
  51. package/dist/footage/overlay-html.d.ts.map +1 -0
  52. package/dist/footage/overlay-html.js +112 -0
  53. package/dist/footage/overlay-html.js.map +1 -0
  54. package/dist/footage/overlay-schema.d.ts +97 -0
  55. package/dist/footage/overlay-schema.d.ts.map +1 -0
  56. package/dist/footage/overlay-schema.js +104 -0
  57. package/dist/footage/overlay-schema.js.map +1 -0
  58. package/dist/footage/overlays.d.ts +112 -0
  59. package/dist/footage/overlays.d.ts.map +1 -0
  60. package/dist/footage/overlays.js +222 -0
  61. package/dist/footage/overlays.js.map +1 -0
  62. package/dist/footage/pipeline.d.ts.map +1 -1
  63. package/dist/footage/pipeline.js +10 -1
  64. package/dist/footage/pipeline.js.map +1 -1
  65. package/dist/footage/speech-ranges.d.ts +8 -3
  66. package/dist/footage/speech-ranges.d.ts.map +1 -1
  67. package/dist/footage/speech-ranges.js +7 -4
  68. package/dist/footage/speech-ranges.js.map +1 -1
  69. package/dist/index.d.ts +6 -3
  70. package/dist/index.d.ts.map +1 -1
  71. package/dist/index.js +6 -3
  72. package/dist/index.js.map +1 -1
  73. package/dist/og/index.d.ts +1 -1
  74. package/dist/og/index.d.ts.map +1 -1
  75. package/dist/og/index.js +1 -1
  76. package/dist/og/index.js.map +1 -1
  77. package/dist/og/photo-cover.d.ts +18 -1
  78. package/dist/og/photo-cover.d.ts.map +1 -1
  79. package/dist/og/photo-cover.js +56 -28
  80. package/dist/og/photo-cover.js.map +1 -1
  81. package/dist/render/hyperframes.d.ts +1 -1
  82. package/dist/render/hyperframes.d.ts.map +1 -1
  83. package/dist/render/hyperframes.js +1 -1
  84. package/dist/render/hyperframes.js.map +1 -1
  85. package/package.json +3 -2
  86. package/schema/edl.schema.json +130 -0
  87. package/schema/marketing.schema.json +33 -0
  88. package/src/config/brand.ts +20 -1
  89. package/src/config/colors.ts +39 -2
  90. package/src/config/config.ts +2 -0
  91. package/src/config/schema.ts +19 -7
  92. package/src/footage/caption-highlight.ts +52 -0
  93. package/src/footage/compose.ts +40 -6
  94. package/src/footage/draft-color.ts +12 -0
  95. package/src/footage/draft-overlays.ts +91 -0
  96. package/src/footage/draft.ts +117 -39
  97. package/src/footage/edl.ts +17 -0
  98. package/src/footage/film.ts +16 -0
  99. package/src/footage/isolate-ranges.ts +1 -1
  100. package/src/footage/overlay-html.ts +127 -0
  101. package/src/footage/overlay-schema.ts +146 -0
  102. package/src/footage/overlays.ts +272 -0
  103. package/src/footage/pipeline.ts +8 -1
  104. package/src/footage/speech-ranges.ts +8 -5
  105. package/src/index.ts +56 -1
  106. package/src/og/index.ts +2 -0
  107. package/src/og/photo-cover.ts +83 -33
  108. package/src/render/hyperframes.ts +1 -1
@@ -4,6 +4,7 @@ import type { ComposeFont } from "../compose/compose.js";
4
4
  import { assertLocalReferences, escapeHtml, fontFaces, fontStack } from "../compose/html.js";
5
5
  import { CAPTION_LINE_HEIGHT, getCaptionPillCss, getCaptionPositionCss, type CaptionLayout } from "../compose/timeline.js";
6
6
  import type { TimedWord } from "../voice/voiceover.js";
7
+ import { CAPTION_HIGHLIGHT_BOX_PADDING_EM, CAPTION_HIGHLIGHT_BOX_RADIUS, CAPTION_HIGHLIGHT_SECONDS, getCaptionHighlight } from "./caption-highlight.js";
7
8
  import { CAPTION_SAFE_ZONES, getCaptionChunkLayouts, getCaptionSpans, getFootageCaptionChunks, isSameCaptionPlace, type CaptionSpan } from "./captions.js";
8
9
  import { getEdlDuration, getSegmentStarts, type Edl } from "./edl.js";
9
10
  import {
@@ -18,6 +19,8 @@ import {
18
19
  type LogoFootageEndCard,
19
20
  } from "./film.js";
20
21
  import { FOOTAGE_FPS } from "./normalize.js";
22
+ import { getOverlayMarkup } from "./overlay-html.js";
23
+ import type { ResolvedOverlay } from "./overlays.js";
21
24
 
22
25
  const r3 = (value: number): number => Math.round(value * 1000) / 1000 || 0;
23
26
 
@@ -76,6 +79,8 @@ export interface FootageComposeInput {
76
79
  assets: FootageComposeAssets;
77
80
  brandName: string;
78
81
  locale: string;
82
+ /** The EDL's overlays, resolved (`resolveEdlOverlays`); absent or empty: none, and the composition is as without them. */
83
+ overlays?: ResolvedOverlay[];
79
84
  }
80
85
 
81
86
  /** The film's length: the cut plus the end card (`getEndCardSeconds`). */
@@ -189,8 +194,26 @@ export function composeFootage(input: FootageComposeInput): string {
189
194
  }
190
195
  });
191
196
 
197
+ // --- Overlays: the punch-in zooms the segment's picture (eased in, held, eased back), the others are clips of their own ---
198
+ const overlays = input.overlays ?? [];
199
+ for (const overlay of overlays) {
200
+ if (overlay.kind !== "punch_in") continue;
201
+ const target = picture === undefined ? `#seg${overlay.segment}` : "#picture";
202
+ const base = scales[overlay.segment] as number;
203
+ const peak = r3(base * overlay.scale);
204
+ tweens.push(
205
+ `tl.fromTo("${target}", { scale: ${base} }, { scale: ${peak}, duration: ${overlay.ease}, ease: "sine.inOut", immediateRender: false }, ${overlay.start});`,
206
+ `tl.fromTo("${target}", { scale: ${peak} }, { scale: ${base}, duration: ${overlay.ease}, ease: "sine.inOut", immediateRender: false }, ${r3(overlay.end - overlay.ease)});`,
207
+ );
208
+ }
209
+
192
210
  // --- Captions: plain phrases, or the pill that lights each word ---
193
211
  const isHighlight = film.captionStyle === "highlight";
212
+ const highlight = isHighlight ? getCaptionHighlight(film, c) : ({ ok: true, look: { style: "text", color: c.captionHighlight } } as const);
213
+ // The pipeline refuses such a film before it composes; reaching here is a bug.
214
+ if (!highlight.ok) throw new Error(`composeFootage: ${highlight.error}`);
215
+ const look = highlight.look;
216
+ const isBox = isHighlight && look.style === "box";
194
217
  const caption = getFootageCaptionChunks(film, words);
195
218
  const spans = getCaptionSpans(caption, cutEnd);
196
219
  const boxes = getCaptionChunkLayouts(caption, edl, captionBox);
@@ -201,7 +224,7 @@ export function composeFootage(input: FootageComposeInput): string {
201
224
  // A chunk in a segment's own box overrides the shared rule's anchor; one in the film's box is written as before.
202
225
  const style = isSameCaptionPlace(place, captionBox) ? "" : ` style="${place.bottom === undefined ? `bottom:auto;top:${place.top}px` : `top:auto;bottom:${place.bottom}px`}"`;
203
226
  const box = isHighlight
204
- ? `<p class="pill">${chunk.words.map((w, j) => `<span id="cw${i}_${j}">${escapeHtml(w.text)}</span>`).join(" ")}</p>`
227
+ ? `<p class="pill">${chunk.words.map((w, j) => `<span id="cw${i}_${j}">${isBox ? `<i class="hl" id="cb${i}_${j}"></i>` : ""}${escapeHtml(w.text)}</span>`).join(" ")}</p>`
205
228
  : `<p class="phrase">${escapeHtml(chunk.words.map((w) => w.text).join(" "))}</p>`;
206
229
  return `<div id="cap${i}" class="clip caption" data-start="${start}" data-duration="${r3(stop - start)}"${style}>${box}</div>`;
207
230
  })
@@ -254,6 +277,7 @@ export function composeFootage(input: FootageComposeInput): string {
254
277
  const bodyFont = fontStack(fonts.body, "sans-serif");
255
278
  const headingFont = fonts.heading === null ? bodyFont : fontStack(fonts.heading, "sans-serif");
256
279
  const faces = [...fontFaces(fonts.body), ...fontFaces(fonts.heading)];
280
+ const overlayMarkup = getOverlayMarkup(overlays, { colors: c, headingFont, frame });
257
281
 
258
282
  return assertLocalReferences(`<!doctype html>
259
283
  <html lang="${escapeHtml(input.locale)}">
@@ -272,7 +296,10 @@ html,body{width:${frame.width}px;height:${frame.height}px;overflow:hidden;backgr
272
296
  .caption{position:absolute;left:${captionBox.left}px;right:${captionBox.right}px;${getCaptionPositionCss(captionBox)};display:flex;justify-content:center}
273
297
  .pill{${getCaptionPillCss(captionBox.fontSize)};border-radius:22px;background:${c.captionBackground};box-shadow:0 14px 44px rgba(0,0,0,.5);color:${c.captionText}}
274
298
  .pill span{display:inline-block}
275
- .phrase{font-weight:650;font-size:${captionBox.fontSize}px;line-height:${CAPTION_LINE_HEIGHT};letter-spacing:-.01em;text-align:center;color:#fff;text-shadow:0 2px 6px rgba(0,0,0,.55),0 0 18px rgba(0,0,0,.35)}
299
+ ${isBox ? `.pill{position:relative;z-index:0}
300
+ .pill span{position:relative}
301
+ .hl{position:absolute;top:0;bottom:0;left:-${CAPTION_HIGHLIGHT_BOX_PADDING_EM}em;right:-${CAPTION_HIGHLIGHT_BOX_PADDING_EM}em;z-index:-1;border-radius:${CAPTION_HIGHLIGHT_BOX_RADIUS}px;background:${look.box};opacity:0}
302
+ ` : ""}.phrase{font-weight:650;font-size:${captionBox.fontSize}px;line-height:${CAPTION_LINE_HEIGHT};letter-spacing:-.01em;text-align:center;color:#fff;text-shadow:0 2px 6px rgba(0,0,0,.55),0 0 18px rgba(0,0,0,.35)}
276
303
  .endcard{position:absolute;inset:0;display:flex;flex-direction:column;justify-content:center;align-items:center;padding:0 80px;text-align:center}
277
304
  .brand{display:flex;justify-content:center;align-items:center;gap:18px;font-family:${headingFont};font-size:46px}
278
305
  .logo{height:60px;width:auto}
@@ -285,13 +312,13 @@ html,body{width:${frame.width}px;height:${frame.height}px;overflow:hidden;backgr
285
312
  .mark.vector{width:min(100%,${LOGO_CARD_MARK.width}px);height:${LOGO_CARD_MARK.height}px;object-fit:contain}
286
313
  .markname{font-family:${headingFont};font-weight:600;font-size:96px;letter-spacing:-.02em}
287
314
  .logoline{font-family:${headingFont};font-weight:600;font-size:${LOGO_CARD_LINE_SIZE}px;line-height:1.15;letter-spacing:-.01em}
288
- </style>
315
+ ${overlayMarkup.css.map((rule) => `${rule}\n`).join("")}</style>
289
316
  </head>
290
317
  <body>
291
318
  <div id="root" data-composition-id="${COMPOSITION_ID}" data-start="0" data-duration="${end}" data-width="${frame.width}" data-height="${frame.height}">
292
319
  ${segments.join("\n ")}
293
320
  ${endCardHtml}
294
- ${captionHtml}
321
+ ${overlayMarkup.html.map((element) => `${element}\n `).join("")}${captionHtml}
295
322
  ${audio}
296
323
  </div>
297
324
  ${captionFit}<script>
@@ -300,9 +327,16 @@ ${tweens.join("\n")}
300
327
  const captions = ${JSON.stringify(isHighlight ? caption.map((chunk) => chunk.words.map((w) => w.start)) : [])};
301
328
  captions.forEach((words, i) => {
302
329
  tl.fromTo("#cap" + i + " .pill", { y: 14, opacity: 0 }, { y: 0, opacity: 1, duration: 0.16, ease: "power3.out" }, Math.max(0, words[0] - 0.05));
303
- words.forEach((t, j) => tl.fromTo("#cw" + i + "_" + j, { color: "${c.captionText}" }, { color: "${c.captionHighlight}", duration: 0.06, immediateRender: false }, t).to("#cw" + i + "_" + j, { color: "${c.captionText}", duration: 0.2 }, t + 0.32));
330
+ ${
331
+ look.style === "box"
332
+ ? ` words.forEach((t, j) => {
333
+ tl.fromTo("#cb" + i + "_" + j, { opacity: 0 }, { opacity: 1, duration: 0.06, immediateRender: false }, t).to("#cb" + i + "_" + j, { opacity: 0, duration: 0.2 }, t + ${CAPTION_HIGHLIGHT_SECONDS});
334
+ tl.fromTo("#cw" + i + "_" + j, { color: "${c.captionText}" }, { color: "${look.text}", duration: 0.06, immediateRender: false }, t).to("#cw" + i + "_" + j, { color: "${c.captionText}", duration: 0.2 }, t + ${CAPTION_HIGHLIGHT_SECONDS});
335
+ });`
336
+ : ` words.forEach((t, j) => tl.fromTo("#cw" + i + "_" + j, { color: "${c.captionText}" }, { color: "${look.color}", duration: 0.06, immediateRender: false }, t).to("#cw" + i + "_" + j, { color: "${c.captionText}", duration: 0.2 }, t + 0.32));`
337
+ }
304
338
  });
305
- ${endCardTweens.join("\n")}
339
+ ${overlayMarkup.tweens.map((tween) => `${tween}\n`).join("")}${endCardTweens.join("\n")}
306
340
  tl.set({}, {}, ${end});
307
341
  window.__timelines = window.__timelines || {};
308
342
  window.__timelines["${COMPOSITION_ID}"] = tl;
@@ -0,0 +1,12 @@
1
+ /**
2
+ * A hex colour (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`) as an ASS colour, `&HAABBGGRR&`-style without the closing
3
+ * `&`: ASS writes blue first and counts alpha the other way round (00 is opaque).
4
+ */
5
+ export function toAssColor(hex: string): string {
6
+ const digits = hex.replace(/^#/, "");
7
+ const full = digits.length <= 4 ? [...digits].map((digit) => digit + digit).join("") : digits;
8
+ if (!/^(?:[0-9a-f]{6}|[0-9a-f]{8})$/i.test(full)) throw new Error(`Not a hex colour: "${hex}".`);
9
+ const pair = (index: number): string => full.slice(index, index + 2).toUpperCase();
10
+ const alpha = full.length === 8 ? (255 - parseInt(full.slice(6, 8), 16)).toString(16).padStart(2, "0").toUpperCase() : "00";
11
+ return `&H${alpha}${pair(4)}${pair(2)}${pair(0)}`;
12
+ }
@@ -0,0 +1,91 @@
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";
4
+
5
+ /**
6
+ * 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.
10
+ */
11
+
12
+ /** 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
+ const STROKE_WIDTH = 10;
14
+ const ARROW_HEAD = 46;
15
+ const FADE = "\\fad(150,250)";
16
+
17
+ const r0 = (value: number): number => Math.round(value);
18
+
19
+ /** An ASS colour for an override tag (`&HBBGGRR&`). */
20
+ const toTagColor = (hex: string): string => `${toAssColor(hex).replace(/^&H../, "&H")}&`;
21
+
22
+ /** The two styles the overlays use: `Overlay` (text on an opaque card) and `OverlayShape` (drawings). */
23
+ export function getDraftOverlayStyles(family: string, colors: OverlayColors): string[] {
24
+ const card = toAssColor(colors.background);
25
+ const text = toAssColor(colors.foreground);
26
+ const accent = toAssColor(colors.accent);
27
+ 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
+ `Style: OverlayShape,${family},48,${accent},${accent},${accent},${accent},0,0,0,0,100,100,0,0,1,0,0,7,0,0,0,1`,
30
+ ];
31
+ }
32
+
33
+ /** An ASS time: `H:MM:SS.cc`. */
34
+ function toAssTime(seconds: number): string {
35
+ const centiseconds = Math.max(0, Math.round(seconds * 100));
36
+ const pad = (value: number): string => String(value).padStart(2, "0");
37
+ return `${Math.floor(centiseconds / 360000)}:${pad(Math.floor((centiseconds % 360000) / 6000))}:${pad(Math.floor((centiseconds % 6000) / 100))}.${pad(centiseconds % 100)}`;
38
+ }
39
+
40
+ /** Overlay text as ASS dialogue: braces and backslashes would read as tags. */
41
+ function toAssText(text: string): string {
42
+ return text.replace(/\\/g, "/").replace(/\{/g, "(").replace(/\}/g, ")").replace(/\s+/g, " ").trim();
43
+ }
44
+
45
+ /** A straight arrow from `from` to `to` as an ASS drawing: the shaft's quad and the head's triangle. */
46
+ export function getArrowDrawing(from: OverlayPoint, to: OverlayPoint, scale: number): string {
47
+ const length = Math.hypot(to.x - from.x, to.y - from.y) || 1;
48
+ const u = { x: (to.x - from.x) / length, y: (to.y - from.y) / length };
49
+ const n = { x: -u.y, y: u.x };
50
+ const half = (STROKE_WIDTH * scale) / 2;
51
+ const head = ARROW_HEAD * scale;
52
+ const base = { x: to.x - u.x * head, y: to.y - u.y * head };
53
+ const p = (x: number, y: number) => `${r0(x)} ${r0(y)}`;
54
+ const shaft = `m ${p(from.x + n.x * half, from.y + n.y * half)} l ${p(base.x + n.x * half, base.y + n.y * half)} ${p(base.x - n.x * half, base.y - n.y * half)} ${p(from.x - n.x * half, from.y - n.y * half)}`;
55
+ const wing = head * 0.6;
56
+ const tip = `m ${p(to.x, to.y)} l ${p(base.x + n.x * wing, base.y + n.y * wing)} ${p(base.x - n.x * wing, base.y - n.y * wing)}`;
57
+ return `${shaft} ${tip}`;
58
+ }
59
+
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}`];
69
+ }
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}`];
79
+ }
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}`];
90
+ });
91
+ }
@@ -6,8 +6,13 @@ import type { CaptionLayout, LayoutOverride } from "../compose/timeline.js";
6
6
  import type { BrandColors } from "../config/colors.js";
7
7
  import { err, ok } from "./failure.js";
8
8
  import type { TimedWord } from "../voice/voiceover.js";
9
+ import { CAPTION_HIGHLIGHT_BOX_PADDING_EM, CAPTION_HIGHLIGHT_SECONDS, getCaptionHighlight, type CaptionHighlightLook } from "./caption-highlight.js";
9
10
  import { getCaptionChunkLayouts, getCaptionSpans, getFootageCaptionChunks, getFootageCaptionLayout, isSameCaptionPlace, type CaptionWordsFilm } from "./captions.js";
10
11
  import { getSegmentScales, getSegmentZoomEases } from "./compose.js";
12
+ import { toAssColor } from "./draft-color.js";
13
+ import { buildDraftOverlayEvents, getDraftOverlayStyles } from "./draft-overlays.js";
14
+ import type { OverlayColors } from "./overlay-html.js";
15
+ import { resolveEdlOverlays, type ResolvedOverlay } from "./overlays.js";
11
16
  import { chooseFootageDraftFont } from "./draft-font.js";
12
17
  import { getEdlDuration, getSegmentStarts, remapWords, type Edl } from "./edl.js";
13
18
  import { declickSpeech, describeDeclick, type DeclickReport } from "./declick.js";
@@ -43,6 +48,8 @@ import { buildMusicArgs, buildSpeechArgs, getSpeechCutOptions } from "./render.j
43
48
  * before the paid render.
44
49
  */
45
50
 
51
+ export { toAssColor } from "./draft-color.js";
52
+
46
53
  /** The draft's default width: 540 makes a 540×960 draft of a 9:16 film. */
47
54
  export const FOOTAGE_DRAFT_WIDTH = 540;
48
55
 
@@ -60,9 +67,17 @@ const DRAFT_CRF = 28;
60
67
  const DRAFT_AUDIO_BITRATE = "128k";
61
68
 
62
69
  /** The caption colours of a `highlight` draft made without a brand. */
63
- export const FOOTAGE_DRAFT_CAPTION_COLORS = { captionBackground: "#111111", captionText: "#ffffff", captionHighlight: "#ffd400" } as const;
70
+ export const FOOTAGE_DRAFT_CAPTION_COLORS = {
71
+ captionBackground: "#111111",
72
+ captionText: "#ffffff",
73
+ captionHighlight: "#ffd400",
74
+ captionHighlightBox: "#ffd400",
75
+ captionHighlightText: "#111111",
76
+ } as const;
77
+ /** The overlays' colours in a draft made without a brand. */
78
+ export const FOOTAGE_DRAFT_OVERLAY_COLORS: OverlayColors = { background: "#111111", foreground: "#ffffff", accent: "#ffd400" };
64
79
  /** How long the render keeps a spoken word lit in the `highlight` pill. */
65
- const HIGHLIGHT_SECONDS = 0.32;
80
+ const HIGHLIGHT_SECONDS = CAPTION_HIGHLIGHT_SECONDS;
66
81
  /** The pill's padding around its text (`CAPTION_PILL_PADDING.y`): the opaque box's border in the film's frame. */
67
82
  const HIGHLIGHT_BOX_PADDING = 16;
68
83
 
@@ -85,19 +100,6 @@ function toAssTime(seconds: number): string {
85
100
  return `${hours}:${pad(minutes)}:${pad(secs)}.${pad(centiseconds % 100)}`;
86
101
  }
87
102
 
88
- /**
89
- * A hex colour (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`) as an ASS colour, `&HAABBGGRR&`-style without the closing
90
- * `&`: ASS writes blue first and counts alpha the other way round (00 is opaque).
91
- */
92
- export function toAssColor(hex: string): string {
93
- const digits = hex.replace(/^#/, "");
94
- const full = digits.length <= 4 ? [...digits].map((digit) => digit + digit).join("") : digits;
95
- if (!/^(?:[0-9a-f]{6}|[0-9a-f]{8})$/i.test(full)) throw new Error(`Not a hex colour: "${hex}".`);
96
- const pair = (index: number): string => full.slice(index, index + 2).toUpperCase();
97
- const alpha = full.length === 8 ? (255 - parseInt(full.slice(6, 8), 16)).toString(16).padStart(2, "0").toUpperCase() : "00";
98
- return `&H${alpha}${pair(4)}${pair(2)}${pair(0)}`;
99
- }
100
-
101
103
  /**
102
104
  * Caption text as ASS dialogue: override braces and backslashes would be read as tags, line breaks end the line. A
103
105
  * no-break space (U+00A0) becomes ASS's hard space `\h`, which libass never breaks a line at, as the render's HTML.
@@ -113,10 +115,10 @@ function toAssText(text: string): string {
113
115
  }
114
116
 
115
117
  /** The caption colours the draft paints with (`BrandColors`). */
116
- export type FootageDraftCaptionColors = Pick<BrandColors, "captionBackground" | "captionText" | "captionHighlight">;
118
+ export type FootageDraftCaptionColors = Pick<BrandColors, "captionBackground" | "captionText" | "captionHighlight" | "captionHighlightBox" | "captionHighlightText">;
117
119
 
118
120
  export interface FootageDraftCaptionsInput {
119
- film: Pick<FootageFilm, "captions" | "captionStyle"> & CaptionWordsFilm;
121
+ film: Pick<FootageFilm, "captions" | "captionStyle" | "captionHighlightStyle"> & CaptionWordsFilm;
120
122
  edl: Edl;
121
123
  /** The film's words in film time (`remapWords`). */
122
124
  words: TimedWord[];
@@ -128,6 +130,19 @@ export interface FootageDraftCaptionsInput {
128
130
  fontFamily?: string;
129
131
  /** The `highlight` pill's colours; default `FOOTAGE_DRAFT_CAPTION_COLORS`. A `phrase` caption is white, as in the render. */
130
132
  colors?: FootageDraftCaptionColors;
133
+ /** The EDL's overlays, resolved (`resolveEdlOverlays`), drawn over the captions' layers; absent: none. */
134
+ overlays?: ResolvedOverlay[];
135
+ /** The overlays' card, text and accent colours; default `FOOTAGE_DRAFT_OVERLAY_COLORS`. */
136
+ overlayColors?: OverlayColors;
137
+ }
138
+
139
+ /** 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. */
140
+ function getHighlightPieces(chunk: { words: TimedWord[] }, span: { start: number; end: number }): { from: number; to: number; lit: boolean[] }[] {
141
+ const cs = (seconds: number): number => Math.round(seconds * 100);
142
+ const [from, to] = [cs(span.start), cs(span.end)];
143
+ const lights = chunk.words.map((word) => ({ on: cs(word.start), off: cs(word.start + HIGHLIGHT_SECONDS) }));
144
+ const cuts = [...new Set([from, to, ...lights.flatMap((light) => [light.on, light.off])])].filter((at) => at >= from && at <= to).sort((a, b) => a - b);
145
+ return cuts.slice(0, -1).map((at, index) => ({ from: at, to: cuts[index + 1] as number, lit: lights.map((light) => light.on <= at && at < light.off) }));
131
146
  }
132
147
 
133
148
  /**
@@ -135,23 +150,36 @@ export interface FootageDraftCaptionsInput {
135
150
  * with the words lit then in `highlight` (a word stays lit for the render's 0.32 s from its start).
136
151
  */
137
152
  function buildHighlightEvents(chunk: { words: TimedWord[] }, span: { start: number; end: number }, colors: { text: string; highlight: string }, styleName: string): string[] {
138
- const cs = (seconds: number): number => Math.round(seconds * 100);
139
- const [from, to] = [cs(span.start), cs(span.end)];
140
- const lights = chunk.words.map((word) => ({ on: cs(word.start), off: cs(word.start + HIGHLIGHT_SECONDS) }));
141
- const cuts = [...new Set([from, to, ...lights.flatMap((light) => [light.on, light.off])])].filter((at) => at >= from && at <= to).sort((a, b) => a - b);
142
- const events: string[] = [];
143
- cuts.slice(0, -1).forEach((at, index) => {
144
- const next = cuts[index + 1] as number;
145
- const text = chunk.words
146
- .map((word, wordIndex) => {
147
- const light = lights[wordIndex] as { on: number; off: number };
148
- const shown = toAssText(word.text);
149
- return light.on <= at && at < light.off ? `{\\1c${colors.highlight}&}${shown}{\\1c${colors.text}&}` : shown;
150
- })
151
- .join(" ");
152
- events.push(`Dialogue: 0,${toAssTime(at / 100)},${toAssTime(next / 100)},${styleName},,0,0,0,,${text}`);
153
+ return getHighlightPieces(chunk, span).map((piece) => {
154
+ const text = chunk.words.map((word, wordIndex) => (piece.lit[wordIndex] === true ? `{\\1c${colors.highlight}&}${toAssText(word.text)}{\\1c${colors.text}&}` : toAssText(word.text))).join(" ");
155
+ return `Dialogue: 0,${toAssTime(piece.from / 100)},${toAssTime(piece.to / 100)},${styleName},,0,0,0,,${text}`;
153
156
  });
154
- return events;
157
+ }
158
+
159
+ /**
160
+ * A `box` highlight chunk as ASS events (issue #1199), three layers per piece of its span. libass draws a
161
+ * `BorderStyle 3` box per glyph, in each glyph's own `\3c` and `\3a`, so the layers share one layout: 0 is the pill
162
+ * (its text hidden), 1 the lit word's box (every other glyph's box transparent, grown by `boxPadding` instead of the
163
+ * pill's), 2 the text alone (no box) with the lit word in its box text colour.
164
+ */
165
+ function buildHighlightBoxEvents(chunk: { words: TimedWord[] }, span: { start: number; end: number }, colors: { text: string; box: string; boxText: string }, boxPadding: number, styleName: string): string[] {
166
+ return getHighlightPieces(chunk, span).flatMap((piece) => {
167
+ const at = `${toAssTime(piece.from / 100)},${toAssTime(piece.to / 100)},${styleName},,0,0,0,,`;
168
+ const shown = chunk.words.map((word) => toAssText(word.text));
169
+ const pill = `{\\1a&HFF&}${shown.join(" ")}`;
170
+ const box = `{\\1a&HFF&\\bord${boxPadding}\\3a&HFF&}${shown.map((text, index) => (piece.lit[index] === true ? `{\\3c${colors.box}&\\3a&H00&}${text}{\\3a&HFF&}` : text)).join(" ")}`;
171
+ const text = `{\\3a&HFF&\\4a&HFF&}${shown.map((word, index) => (piece.lit[index] === true ? `{\\1c${colors.boxText}&}${word}{\\1c${colors.text}&}` : word)).join(" ")}`;
172
+ const isLit = piece.lit.some((lit) => lit);
173
+ return [`Dialogue: 0,${at}${pill}`, ...(isLit ? [`Dialogue: 1,${at}${box}`] : []), `Dialogue: 2,${at}${text}`];
174
+ });
175
+ }
176
+
177
+ /** The highlight look the draft draws: `text` for a `phrase` film; a `box` film without its colours is an input error. */
178
+ function getDraftHighlightLook(film: Pick<FootageFilm, "captionStyle" | "captionHighlightStyle">, colors: FootageDraftCaptionColors): CaptionHighlightLook {
179
+ if (film.captionStyle !== "highlight") return { style: "text", color: colors.captionHighlight };
180
+ const highlight = getCaptionHighlight(film, colors);
181
+ if (!highlight.ok) throw new Error(`buildFootageDraftCaptions: ${highlight.error}`);
182
+ return highlight.look;
155
183
  }
156
184
 
157
185
  /**
@@ -163,10 +191,11 @@ function buildHighlightEvents(chunk: { words: TimedWord[] }, span: { start: numb
163
191
  * captions or nothing is said.
164
192
  */
165
193
  export function buildFootageDraftCaptions(input: FootageDraftCaptionsInput): string | null {
166
- if (!input.film.captions) return null;
194
+ const overlays = input.overlays ?? [];
167
195
  const isHighlight = input.film.captionStyle === "highlight";
168
- const chunks = getFootageCaptionChunks(input.film, input.words);
169
- if (chunks.length === 0) return null;
196
+ // No chunks without captions (`getFootageCaptionChunks`): then only the overlays, if any, make the file.
197
+ const chunks = input.film.captions ? getFootageCaptionChunks(input.film, input.words) : [];
198
+ if (chunks.length === 0 && overlays.length === 0) return null;
170
199
  const spans = getCaptionSpans(chunks, getEdlDuration(input.edl));
171
200
  const { caption, frame } = input;
172
201
  const family = (input.fontFamily ?? FOOTAGE_DRAFT_FONT.family).replace(/,/g, " ");
@@ -223,9 +252,13 @@ export function buildFootageDraftCaptions(input: FootageDraftCaptionsInput): str
223
252
  return `Caption${index + 2}`;
224
253
  });
225
254
  const highlight = { text: text.replace(/^&H../, "&H"), highlight: toAssColor(colors.captionHighlight).replace(/^&H../, "&H") };
255
+ const lit = getDraftHighlightLook(input.film, colors);
256
+ const boxColors = lit.style === "box" ? { text: highlight.text, box: toAssColor(lit.box).replace(/^&H../, "&H"), boxText: toAssColor(lit.text).replace(/^&H../, "&H") } : null;
257
+ const boxPadding = Math.max(1, Math.round(caption.fontSize * CAPTION_HIGHLIGHT_BOX_PADDING_EM));
226
258
  const events = chunks.flatMap((chunk, index) => {
227
259
  const span = spans[index] as { start: number; end: number };
228
260
  const styleName = styleNames[index] ?? "Caption";
261
+ if (isHighlight && boxColors !== null) return buildHighlightBoxEvents(chunk, span, boxColors, boxPadding, styleName);
229
262
  if (isHighlight) return buildHighlightEvents(chunk, span, highlight, styleName);
230
263
  const line = toAssText(chunk.words.map((word) => word.text).join(" "));
231
264
  return [`Dialogue: 0,${toAssTime(span.start)},${toAssTime(span.end)},${styleName},,0,0,0,,${line}`];
@@ -241,10 +274,12 @@ export function buildFootageDraftCaptions(input: FootageDraftCaptionsInput): str
241
274
  "[V4+ Styles]",
242
275
  "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding",
243
276
  ...styles.map((style) => `Style: ${style}`),
277
+ ...(overlays.length === 0 ? [] : getDraftOverlayStyles(family, input.overlayColors ?? FOOTAGE_DRAFT_OVERLAY_COLORS)),
244
278
  "",
245
279
  "[Events]",
246
280
  "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
247
281
  ...events,
282
+ ...buildDraftOverlayEvents(overlays, input.overlayColors ?? FOOTAGE_DRAFT_OVERLAY_COLORS, input.frame),
248
283
  "",
249
284
  ].join("\n");
250
285
  }
@@ -269,6 +304,8 @@ export interface FootageDraftArgsInput {
269
304
  width?: number;
270
305
  /** The ASS captions file (`buildFootageDraftCaptions`), or null for none. */
271
306
  captions: string | null;
307
+ /** The EDL's resolved overlays: their `punch_in` zooms are drawn into the picture (the rest is in the ASS file). */
308
+ overlays?: readonly ResolvedOverlay[];
272
309
  /** The folder libass loads the captions' font from, or null for the system's fonts. */
273
310
  fontsDir: string | null;
274
311
  output: string;
@@ -297,13 +334,18 @@ export interface DraftSegmentPlan {
297
334
  startScale: number;
298
335
  /** The frames the zoom eases over (`getSegmentZoomEases`); 0: the segment starts at `scale`. */
299
336
  easeFrames: number;
337
+ /**
338
+ * The EDL's `punch_in` overlays in this segment, in frames from its start: each multiplies the zoom by up to `scale`,
339
+ * rising over `ease` frames from `from` and falling over the last `ease` of its `frames` (linear, the render eases).
340
+ */
341
+ punches: { from: number; frames: number; ease: number; scale: number }[];
300
342
  }
301
343
 
302
344
  /**
303
345
  * How each segment plays in the draft. A `fade` cut lasts the film's `fadeFrames` (clamped to the incoming segment, so
304
346
  * the cross-fade never outlasts it) and the outgoing segment runs on under it, as in the render.
305
347
  */
306
- export function planFootageDraft(film: Pick<FootageFilm, "edit">, edl: Edl): DraftSegmentPlan[] {
348
+ export function planFootageDraft(film: Pick<FootageFilm, "edit">, edl: Edl, overlays: readonly ResolvedOverlay[] = []): DraftSegmentPlan[] {
307
349
  const edit = getFootageEdit(film);
308
350
  const fadeSeconds = r3(edit.fadeFrames / FOOTAGE_FPS);
309
351
  const kenBurnsScale = 1 + (edit.kenBurnsPercent > 0 ? edit.kenBurnsPercent : HAND_KEN_BURNS_PERCENT) / 100;
@@ -322,6 +364,18 @@ export function planFootageDraft(film: Pick<FootageFilm, "edit">, edl: Edl): Dra
322
364
  endScale: segment.motion === "kenburns" ? r4(scale * kenBurnsScale) : scale,
323
365
  startScale: (eases[index] as number) > 0 ? (scales[index - 1] as number) : scale,
324
366
  easeFrames: eases[index] as number,
367
+ punches: overlays.flatMap((overlay) =>
368
+ overlay.kind === "punch_in" && overlay.segment === index
369
+ ? [
370
+ {
371
+ from: Math.round((overlay.start - (starts[index] as number)) * FOOTAGE_FPS),
372
+ frames: Math.round((overlay.end - overlay.start) * FOOTAGE_FPS),
373
+ ease: Math.max(1, Math.round(overlay.ease * FOOTAGE_FPS)),
374
+ scale: overlay.scale,
375
+ },
376
+ ]
377
+ : [],
378
+ ),
325
379
  };
326
380
  });
327
381
  }
@@ -334,6 +388,18 @@ function buildPictureFilters(plan: DraftSegmentPlan, draft: Frame): string[] {
334
388
  const size = `${draft.width}:${draft.height}`;
335
389
  const zoompan = (zoom: string): string =>
336
390
  `zoompan=z='${zoom}':x='(iw-iw/zoom)*${ZOOM_ORIGIN.x}':y='(ih-ih/zoom)*${ZOOM_ORIGIN.y}':d=1:s=${draft.width}x${draft.height}:fps=${FOOTAGE_FPS}`;
391
+ if (plan.punches.length > 0) {
392
+ // The segment's own zoom (an eased cut, Ken Burns or still) times each punch-in's rise, hold and fall.
393
+ const frames = Math.max(1, Math.round(plan.length * FOOTAGE_FPS));
394
+ const own =
395
+ plan.easeFrames > 0
396
+ ? `${plan.startScale}+(${r4(plan.scale - plan.startScale)})*(1-pow(1-min(on/${plan.easeFrames},1),2))`
397
+ : plan.endScale !== plan.scale
398
+ ? `${plan.scale}+${r4(plan.endScale - plan.scale)}*min(on/${frames},1)`
399
+ : `${plan.scale}`;
400
+ const lifts = plan.punches.map((punch) => `${r4(punch.scale - 1)}*max(0,min(min(1,(on-${punch.from})/${punch.ease}),(${punch.from + punch.frames}-on)/${punch.ease}))`);
401
+ return [zoompan(`(${own})*(1+${lifts.join("+")})`)];
402
+ }
337
403
  if (plan.easeFrames > 0) {
338
404
  return [zoompan(`${plan.startScale}+(${r4(plan.scale - plan.startScale)})*(1-pow(1-min(on/${plan.easeFrames},1),2))`)];
339
405
  }
@@ -358,7 +424,7 @@ function buildPictureFilters(plan: DraftSegmentPlan, draft: Frame): string[] {
358
424
  export function buildFootageDraftArgs(input: FootageDraftArgsInput): string[] {
359
425
  const { edl } = input;
360
426
  const draft = getFootageDraftFrame(input.frame, input.width);
361
- const plans = planFootageDraft(input.film, edl);
427
+ const plans = planFootageDraft(input.film, edl, input.overlays ?? []);
362
428
  const threads = getThreadArgs(input.threads, "draft.threads");
363
429
  const inputs: string[] = [];
364
430
  const parts: string[] = [];
@@ -453,7 +519,7 @@ export interface RenderFootageDraftOptions extends Pick<FootageRunOptions, "buil
453
519
  * OpenType file; DejaVu Sans when it has none) and its caption colours. Without it, DejaVu Sans and
454
520
  * `FOOTAGE_DRAFT_CAPTION_COLORS`.
455
521
  */
456
- brand?: { colors: FootageDraftCaptionColors; fonts: Pick<FootageBrand["fonts"], "body"> };
522
+ brand?: { colors: FootageDraftCaptionColors & Partial<OverlayColors>; fonts: Pick<FootageBrand["fonts"], "body"> };
457
523
  /**
458
524
  * ffmpeg's threads for the draft's decoders, filter graph and encoder (`buildFootageDraftArgs`); by default ffmpeg's
459
525
  * own choice, which follows the host's cores. Set it from a CPU-limited container's quota.
@@ -528,6 +594,8 @@ async function runRenderFootageDraft(
528
594
  ): Promise<FootageResult<FootageDraft>> {
529
595
  const { log, signal } = options;
530
596
  const aborting = signal === undefined ? {} : { signal };
597
+ const highlight = film.captions && film.captionStyle === "highlight" ? getCaptionHighlight(film, options.brand?.colors ?? FOOTAGE_DRAFT_CAPTION_COLORS) : null;
598
+ if (highlight !== null && !highlight.ok) return err(`footage film ${film.id}: ${highlight.error}`, { kind: "input" });
531
599
  const seconds = getEdlDuration(edl);
532
600
  const music = await findDraftMusic(film, edl, clips, options);
533
601
  if (!music.ok) return music;
@@ -555,6 +623,14 @@ async function runRenderFootageDraft(
555
623
  const { rawSpeechFile, declickedFile, speechFile } = getSpeechChainFiles(draftDir, { isDeclick: declickLevel !== "off", isLoudness: loudness !== null });
556
624
  const words = remapWords(edl, transcript.words, film.cut.fillers);
557
625
  const frame = getFrame(film);
626
+ const resolved = resolveEdlOverlays({ film, edl, words, frame, caption: getFootageCaptionLayout(film, options.layout ?? {}) });
627
+ if (!resolved.ok) return err(`footage film ${film.id}: the EDL's overlays cannot be drawn: ${resolved.problems.join("; ")}`, { kind: "input" });
628
+ const overlays = resolved.overlays;
629
+ const brandColors = options.brand?.colors;
630
+ const overlayColors =
631
+ brandColors?.background !== undefined && brandColors.foreground !== undefined && brandColors.accent !== undefined
632
+ ? { background: brandColors.background, foreground: brandColors.foreground, accent: brandColors.accent }
633
+ : FOOTAGE_DRAFT_OVERLAY_COLORS;
558
634
  const brandFont = chooseFootageDraftFont(options.brand?.fonts.body ?? null);
559
635
  const font = brandFont ?? FOOTAGE_DRAFT_FONT;
560
636
  const captions = buildFootageDraftCaptions({
@@ -565,6 +641,7 @@ async function runRenderFootageDraft(
565
641
  frame,
566
642
  fontFamily: font.family,
567
643
  ...(options.brand === undefined ? {} : { colors: options.brand.colors }),
644
+ ...(overlays.length === 0 ? {} : { overlays, overlayColors }),
568
645
  });
569
646
  if (captions !== null) {
570
647
  writeFileSync(join(draftDir, "captions.ass"), captions);
@@ -628,6 +705,7 @@ async function runRenderFootageDraft(
628
705
  ...(options.width === undefined ? {} : { width: options.width }),
629
706
  ...(options.threads === undefined ? {} : { threads: options.threads }),
630
707
  captions: captions === null ? null : "captions.ass",
708
+ ...(overlays.length === 0 ? {} : { overlays }),
631
709
  fontsDir: captions === null ? null : "fonts",
632
710
  output,
633
711
  });
@@ -1,6 +1,7 @@
1
1
  import { z } from "zod";
2
2
 
3
3
  import type { TimedWord } from "../voice/voiceover.js";
4
+ import { overlaySchema, type EdlOverlay } from "./overlay-schema.js";
4
5
  import { CUT_TRANSITIONS, type ClipRole, type CutOptions, type CutTransition, type FootageTransitions } from "./film.js";
5
6
  import { splitFilmSentences, type Sentence } from "./sentences.js";
6
7
  import { isFiller } from "./words.js";
@@ -57,6 +58,11 @@ export interface Edl {
57
58
  version: 2;
58
59
  film: string;
59
60
  segments: EdlSegment[];
61
+ /**
62
+ * Small graphics and emphasis zooms on words of the transcript (`overlays.ts`, issue #1200); absent or empty: none,
63
+ * and the film is drawn as without the field.
64
+ */
65
+ overlays?: EdlOverlay[];
60
66
  }
61
67
 
62
68
  const SEGMENT_ID_PATTERN = /^[A-Za-z0-9._-]+$/;
@@ -98,6 +104,13 @@ export const edlSchema = z
98
104
  )
99
105
  .min(1, "the cut needs at least one segment")
100
106
  .describe("The kept parts of the clips, in film order."),
107
+ overlays: z
108
+ .array(overlaySchema)
109
+ .max(40)
110
+ .optional()
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.",
113
+ ),
101
114
  })
102
115
  .describe("The edit decision list of a footage film (edl.json).");
103
116
 
@@ -371,6 +384,10 @@ export function diffEdl(before: Edl, after: Edl): string[] {
371
384
  if (previous === undefined || isSameCaption(previous.caption, segment.caption)) continue;
372
385
  lines.push(isMovedCaption(segment.caption) ? `${segment.id} captions moved` : `${segment.id} captions back in the film's box`);
373
386
  }
387
+ const [overlaysBefore, overlaysAfter] = [before.overlays ?? [], after.overlays ?? []];
388
+ if (JSON.stringify(overlaysBefore) !== JSON.stringify(overlaysAfter)) {
389
+ lines.push(`overlays: ${overlaysAfter.map((overlay) => overlay.kind.replace("_", " ")).join(", ") || "none"} (was ${overlaysBefore.length})`);
390
+ }
374
391
  for (const segment of after.segments) {
375
392
  const was = old.get(segment.id)?.audio;
376
393
  const { audio } = segment;
@@ -125,6 +125,12 @@ export interface FootageFilm {
125
125
  captions: boolean;
126
126
  /** `phrase` (the default): 2-6 words of plain text with a soft shadow; `highlight`: a pill that lights each word as it is said. */
127
127
  captionStyle?: CaptionStyle;
128
+ /**
129
+ * How a `highlight` caption lights the word being said: `text` (the default) colours its text `captionHighlight`;
130
+ * `box` puts it on a rounded box of `captionHighlightBox` with its text in `captionHighlightText` (both brand colours
131
+ * then required). Ignored by `phrase` captions.
132
+ */
133
+ captionHighlightStyle?: CaptionHighlightStyle;
128
134
  /** Places the 9:16 caption box inside a platform's safe zone (`CAPTION_SAFE_ZONES`); absent: the layout as it is. */
129
135
  captionPreset?: CaptionPreset;
130
136
  /**
@@ -138,6 +144,11 @@ export interface FootageFilm {
138
144
  * empty: numbers only.
139
145
  */
140
146
  captionKeepWithNext?: string[];
147
+ /**
148
+ * The least time between the starts of two EDL overlays, in seconds (the app's own budget, e.g. 8 for one in about
149
+ * 8 s); absent: only one overlay at a time.
150
+ */
151
+ overlayMinSpacing?: number;
141
152
  /** The cut's look: zoom size, fade length, Ken Burns, the end card's whoosh. Absent fields take `DEFAULT_EDIT`. */
142
153
  edit?: Partial<FootageEdit>;
143
154
  /** The closing card after the last segment (`FootageEndCard`); null: the film ends with its last segment. */
@@ -259,6 +270,11 @@ export const CAPTION_STYLES = ["phrase", "highlight"] as const;
259
270
 
260
271
  export type CaptionStyle = (typeof CAPTION_STYLES)[number];
261
272
 
273
+ /** How a `highlight` caption lights the word being said: its text colour, or a box behind it (issue #1199). */
274
+ export const CAPTION_HIGHLIGHT_STYLES = ["text", "box"] as const;
275
+
276
+ export type CaptionHighlightStyle = (typeof CAPTION_HIGHLIGHT_STYLES)[number];
277
+
262
278
  /** The smallest a caption line limit shrinks a card's font to, as a share of the caption box's size. */
263
279
  export const CAPTION_MIN_FONT_SCALE = 0.7;
264
280
 
@@ -203,7 +203,7 @@ async function runIsolateSpeechRanges(
203
203
  mkdirSync(workDir, { recursive: true });
204
204
  // The provider sees the clip's id and the range as the file name.
205
205
  const input = join(workDir, `${range.clip}.${String(range.startMs)}-${String(range.endMs)}.wav`);
206
- await runFfmpeg(`Cutting ${describeRange(range)} for voice isolation`, buildRangeAudioArgs(getSound(clip), range, input), { ...aborting, output: input });
206
+ await runFfmpeg(`Cutting ${describeRange(range)} for voice isolation`, buildRangeAudioArgs(getSound(clip), range, input, options.speechPeaks === undefined ? {} : { peaks: options.speechPeaks }), { ...aborting, output: input });
207
207
  signal?.throwIfAborted();
208
208
  log(`voice isolation (${providers.isolation.id}): ${describeRange(range)}, ${units.toFixed(1)} s.`);
209
209
  const answer = await isolateWithRetries({