@softure-ai/marketing-kit 0.29.0 → 0.32.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/CHANGELOG.md +36 -0
  2. package/README.md +18 -2
  3. package/dist/footage/captions.d.ts +9 -2
  4. package/dist/footage/captions.d.ts.map +1 -1
  5. package/dist/footage/captions.js +20 -4
  6. package/dist/footage/captions.js.map +1 -1
  7. package/dist/footage/draft-boxes.d.ts +3 -1
  8. package/dist/footage/draft-boxes.d.ts.map +1 -1
  9. package/dist/footage/draft-boxes.js +3 -2
  10. package/dist/footage/draft-boxes.js.map +1 -1
  11. package/dist/footage/draft-overlays.d.ts.map +1 -1
  12. package/dist/footage/draft-overlays.js +191 -41
  13. package/dist/footage/draft-overlays.js.map +1 -1
  14. package/dist/footage/edl.d.ts +46 -0
  15. package/dist/footage/edl.d.ts.map +1 -1
  16. package/dist/footage/edl.js +39 -0
  17. package/dist/footage/edl.js.map +1 -1
  18. package/dist/footage/overlay-html.d.ts +8 -0
  19. package/dist/footage/overlay-html.d.ts.map +1 -1
  20. package/dist/footage/overlay-html.js +127 -29
  21. package/dist/footage/overlay-html.js.map +1 -1
  22. package/dist/footage/overlay-motion.d.ts +107 -0
  23. package/dist/footage/overlay-motion.d.ts.map +1 -0
  24. package/dist/footage/overlay-motion.js +129 -0
  25. package/dist/footage/overlay-motion.js.map +1 -0
  26. package/dist/footage/overlay-schema.d.ts +63 -2
  27. package/dist/footage/overlay-schema.d.ts.map +1 -1
  28. package/dist/footage/overlay-schema.js +70 -5
  29. package/dist/footage/overlay-schema.js.map +1 -1
  30. package/dist/footage/overlays.d.ts +16 -1
  31. package/dist/footage/overlays.d.ts.map +1 -1
  32. package/dist/footage/overlays.js +60 -20
  33. package/dist/footage/overlays.js.map +1 -1
  34. package/dist/index.d.ts +5 -4
  35. package/dist/index.d.ts.map +1 -1
  36. package/dist/index.js +5 -4
  37. package/dist/index.js.map +1 -1
  38. package/package.json +1 -1
  39. package/schema/edl.schema.json +117 -1
  40. package/src/footage/captions.ts +21 -5
  41. package/src/footage/draft-boxes.ts +7 -3
  42. package/src/footage/draft-overlays.ts +224 -42
  43. package/src/footage/edl.ts +51 -0
  44. package/src/footage/overlay-html.ts +148 -27
  45. package/src/footage/overlay-motion.ts +157 -0
  46. package/src/footage/overlay-schema.ts +90 -5
  47. package/src/footage/overlays.ts +87 -23
  48. package/src/index.ts +25 -0
@@ -1,7 +1,20 @@
1
1
  import { getCornerRadiusPx, type BrandStyle, type CornerRadius } from "./brand-style.js";
2
2
  import { getDraftBoxEvents } from "./draft-boxes.js";
3
3
  import { toAssColor } from "./draft-color.js";
4
- import { getCounterSeconds, getOverlayColors, getTypingTimes, type OverlayColors } from "./overlay-html.js";
4
+ import { getCounterSeconds, getOverlayColors, getPlaceCardTimes, getTypingTimes, type OverlayColors } from "./overlay-html.js";
5
+ import {
6
+ OVERLAY_EASES,
7
+ PIN_DROP_SECONDS,
8
+ PIN_DROP_SHARE,
9
+ UNDERLINE_EM,
10
+ UNDERLINE_SECONDS,
11
+ getEntranceMotion,
12
+ getExitMotion,
13
+ getWipeHalves,
14
+ type OverlayEntranceMotion,
15
+ type OverlayExitMotion,
16
+ } from "./overlay-motion.js";
17
+ import type { OverlayEntrance } from "./overlay-schema.js";
5
18
  import {
6
19
  OVERLAY_FONT_ROLES,
7
20
  OVERLAY_LINE_HEIGHT,
@@ -13,6 +26,8 @@ import {
13
26
  formatOverlayNumber,
14
27
  getDrawnOverlayCard,
15
28
  getOverlayPadding,
29
+ getPlaceCardPinRow,
30
+ getPlaceCardPinSize,
16
31
  getSideTextLines,
17
32
  getTitleContentBox,
18
33
  type OverlayBox,
@@ -155,21 +170,123 @@ interface TextStep {
155
170
  text: string;
156
171
  }
157
172
 
158
- /** The entrance and exit tags of a run of events: the first fades or slides in, the last fades out. */
159
- function getMotionTags(entrance: "fade" | "slide" | "none", isFirst: boolean, isLast: boolean, slide: { x: number; y: number; dy: number } | null): string {
160
- const fadeIn = isFirst && entrance !== "none" ? FADE_IN_MS : 0;
161
- const fadeOut = isLast ? FADE_OUT_MS : 0;
173
+ /** How one overlay moves in the draft: its entrance and exit (`overlay-motion.ts`) and the card they scale about and wipe over. */
174
+ interface DraftMotion {
175
+ /** The entrance it shows (the kind's own already chosen when the overlay names none). */
176
+ name: OverlayEntrance;
177
+ entrance: OverlayEntranceMotion;
178
+ exit: OverlayExitMotion;
179
+ /** The card a pop scales about and a wipe reveals. */
180
+ card: OverlayBox;
181
+ /** The frame's width / 1080. */
182
+ scale: number;
183
+ isSnappy: boolean;
184
+ /** Whether the card's entrance moves it (slide, rise, pop): then no part moves on the way out, so they stay together. */
185
+ isCardMoved: boolean;
186
+ }
187
+
188
+ /** An overlay's draft motion with its entrance `name` (already the kind's own when it names none). */
189
+ function getDraftMotion(overlay: Exclude<ResolvedOverlay, { kind: "punch_in" }>, name: OverlayEntrance, card: OverlayBox, context: DraftContext): DraftMotion {
190
+ const easing = overlay.easing ?? "smooth";
191
+ const frame = { width: 1080 * context.scale, height: 1920 * context.scale };
192
+ return {
193
+ name,
194
+ entrance: getEntranceMotion(name, easing, frame),
195
+ exit: getExitMotion({ exit: overlay.exit ?? "auto", entrance: overlay.entrance, easing, frame }),
196
+ card,
197
+ scale: context.scale,
198
+ isSnappy: easing === "snappy",
199
+ isCardMoved: name === "slide" || name === "rise" || name === "pop",
200
+ };
201
+ }
202
+
203
+ /** The same motion entering by a plain fade: a part that comes in after its card (a delayed subtitle, a staggered point). */
204
+ function withFadeEntrance(motion: DraftMotion): DraftMotion {
205
+ return { ...motion, name: "fade", entrance: getEntranceMotion("fade", "smooth", { width: 1080, height: 1920 }) };
206
+ }
207
+
208
+ /** Which part of an overlay an event draws: its card (and drawings on it), its text, or a wipe's accent panel. */
209
+ type DraftPart = "card" | "text";
210
+
211
+ /** The rectangle a wipe clips to, round the card with room for its shadow and border. */
212
+ function getWipeClip(motion: DraftMotion): { x0: number; y0: number; x1: number; y1: number } {
213
+ const room = 24 * motion.scale;
214
+ const { card } = motion;
215
+ return { x0: r0(card.left - room / 4), y0: r0(card.top - room), x1: r0(card.left + card.width + room / 4), y1: r0(card.top + card.height + room) };
216
+ }
217
+
218
+ const toClip = (box: { x0: number; y0: number; x1: number; y1: number }): string => `\\clip(${box.x0},${box.y0},${box.x1},${box.y1})`;
219
+ const toMs = (seconds: number): number => Math.max(0, Math.round(seconds * 1000));
220
+
221
+ /**
222
+ * The position and motion tags of one event of a run: the first takes the entrance (a fade, a slide or a rise moving up
223
+ * into place, a pop growing about the card's middle, a wipe's clip), the last the exit (a fade, a move down, a wipe
224
+ * off to the right). libass scales about an event's position, so a pop moves the position with the scale (both linear)
225
+ * to keep the card's middle still. `pos` is the event's position, (0, 0) for a drawing.
226
+ */
227
+ function getMotionTags(motion: DraftMotion, input: { isFirst: boolean; isLast: boolean; pos: OverlayPoint; ms: number; part: DraftPart }): { position: string; rest: string } {
228
+ const { entrance, exit } = motion;
229
+ const { pos, ms } = input;
230
+ let move: string | null = null;
231
+ const tags: string[] = [];
232
+ let fadeIn = 0;
233
+ if (input.isFirst && entrance.kind === "tween") {
234
+ const enterMs = toMs(entrance.seconds);
235
+ fadeIn = motion.name === "fade" || motion.name === "slide" || motion.name === "type" ? FADE_IN_MS : r0(enterMs * 0.7);
236
+ if (motion.name === "slide") move = `\\move(${r0(pos.x)},${r0(pos.y + SLIDE_PX * motion.scale)},${r0(pos.x)},${r0(pos.y)},0,${SLIDE_MS})`;
237
+ if (entrance.from.y > 0 && motion.name !== "slide") move = `\\move(${r0(pos.x)},${r0(pos.y + entrance.from.y)},${r0(pos.x)},${r0(pos.y)},0,${enterMs})`;
238
+ if (entrance.from.scale < 1) {
239
+ const s = entrance.from.scale;
240
+ const centre = { x: motion.card.left + motion.card.width / 2, y: motion.card.top + motion.card.height / 2 };
241
+ move = `\\move(${r0(centre.x + s * (pos.x - centre.x))},${r0(centre.y + s * (pos.y - centre.y))},${r0(pos.x)},${r0(pos.y)},0,${enterMs})`;
242
+ const percent = Math.round(s * 100);
243
+ tags.push(`\\fscx${percent}\\fscy${percent}\\t(0,${enterMs},\\fscx100\\fscy100)`);
244
+ }
245
+ }
246
+ const clip = getWipeClip(motion);
247
+ if (input.isFirst && entrance.kind === "wipe") {
248
+ const halves = getWipeHalves(entrance.seconds);
249
+ const [grow, reveal] = [toMs(halves.grow), toMs(halves.reveal)];
250
+ const closed = toClip({ ...clip, x1: clip.x0 });
251
+ tags.push(input.part === "card" ? `${closed}\\t(0,${grow},${toClip(clip)})` : `${closed}\\t(${grow},${grow + reveal},${toClip(clip)})`);
252
+ }
253
+ let fadeOut = 0;
254
+ if (input.isLast && exit.kind !== "none") {
255
+ if (exit.kind === "wipe") {
256
+ const exitMs = toMs(exit.seconds);
257
+ if (!(input.isFirst && entrance.kind === "wipe")) tags.push(toClip(clip));
258
+ tags.push(`\\t(${Math.max(0, ms - exitMs)},${ms},${toClip({ ...clip, x0: clip.x1 })})`);
259
+ } else {
260
+ fadeOut = motion.isSnappy ? r0(FADE_OUT_MS * 0.7) : FADE_OUT_MS;
261
+ if (exit.kind === "tween" && exit.from.y > 0 && !motion.isCardMoved) {
262
+ const exitMs = toMs(exit.seconds);
263
+ move = `\\move(${r0(pos.x)},${r0(pos.y)},${r0(pos.x)},${r0(pos.y + exit.from.y)},${Math.max(0, ms - exitMs)},${ms})`;
264
+ }
265
+ }
266
+ }
162
267
  const fade = fadeIn === 0 && fadeOut === 0 ? "" : `\\fad(${fadeIn},${fadeOut})`;
163
- 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})` : "";
164
- return `${move}${fade}`;
268
+ return { position: move ?? `\\pos(${r0(pos.x)},${r0(pos.y)})`, rest: `${fade}${tags.join("")}` };
269
+ }
270
+
271
+ /** A blur entrance's and exit's tags for an event whose own blur is `own`: from blurred to its own, from its own to blurred. */
272
+ function getBlurTags(motion: DraftMotion, input: { isFirst: boolean; isLast: boolean; ms: number }, own: number): string {
273
+ const tags: string[] = [];
274
+ if (input.isFirst && motion.entrance.kind === "tween" && motion.entrance.from.blur > 0) {
275
+ tags.push(`\\blur${Math.max(own, r0(motion.entrance.from.blur / 2))}\\t(0,${toMs(motion.entrance.seconds)},\\blur${own})`);
276
+ }
277
+ if (input.isLast && motion.exit.kind === "tween" && motion.exit.from.blur > 0) {
278
+ const exitMs = toMs(motion.exit.seconds);
279
+ tags.push(`\\t(${Math.max(0, input.ms - exitMs)},${input.ms},\\blur${Math.max(own, r0(motion.exit.from.blur / 2))})`);
280
+ }
281
+ return tags.join("");
165
282
  }
166
283
 
167
- /** Text events for a run of steps, positioned at `pos` with `tags`, the entrance on the first and the fade out on the last. */
168
- function getTextEvents(input: { layer: number; style: string; pos: OverlayPoint; tags: string; steps: TextStep[]; entrance: "fade" | "slide" | "none"; slidePx: number }): string[] {
284
+ /** Text events for a run of steps, positioned at `pos` with `tags`, the entrance on the first and the exit on the last. */
285
+ function getTextEvents(input: { layer: number; style: string; pos: OverlayPoint; tags: string; steps: TextStep[]; motion: DraftMotion }): string[] {
169
286
  return input.steps.map((step, index) => {
170
- const motion = getMotionTags(input.entrance, index === 0, index === input.steps.length - 1, { x: input.pos.x, y: input.pos.y, dy: input.slidePx });
171
- const pos = motion.includes("\\move") ? "" : `\\pos(${r0(input.pos.x)},${r0(input.pos.y)})`;
172
- return `Dialogue: ${input.layer},${toAssTime(step.from)},${toAssTime(step.to)},${input.style},,0,0,0,,{${input.tags}${pos}${motion}}${step.text}`;
287
+ const at = { isFirst: index === 0, isLast: index === input.steps.length - 1, ms: toMs(step.to - step.from) };
288
+ const { position, rest } = getMotionTags(input.motion, { ...at, pos: input.pos, part: "text" });
289
+ return `Dialogue: ${input.layer},${toAssTime(step.from)},${toAssTime(step.to)},${input.style},,0,0,0,,{${input.tags}${position}${rest}${getBlurTags(input.motion, at, 0)}}${step.text}`;
173
290
  });
174
291
  }
175
292
 
@@ -210,13 +327,18 @@ function getOwnCardRadius(overlay: Pick<ResolvedOverlay, "kind">, box: { height:
210
327
  }
211
328
 
212
329
  /**
213
- * A card's drawn box on layer 3 with the overlay's entrance: one fill without a brand style, else the style's shadow,
214
- * fill and border (`getDraftBoxEvents`), at the brand style's corner or the overlay's own (`getDraftCardRadius`).
330
+ * A card's drawn box on layer 3 with the overlay's motion: one fill without a brand style, else the style's shadow,
331
+ * fill and border (`getDraftBoxEvents`), at the brand style's corner or the overlay's own (`getDraftCardRadius`); a
332
+ * wipe's accent panel over it.
215
333
  */
216
- function getCardShapeEvents(overlay: ResolvedOverlay, box: OverlayBox, fontSize: number, colors: { background: string; accent: string }, entrance: "fade" | "slide" | "none", context: DraftContext): string[] {
334
+ function getCardShapeEvents(overlay: Exclude<ResolvedOverlay, { kind: "punch_in" }>, box: OverlayBox, fontSize: number, colors: { background: string; accent: string }, motion: DraftMotion, context: DraftContext): string[] {
217
335
  const radius = getDraftCardRadius(overlay, box, context, getOwnCardRadius(overlay, box, fontSize));
218
- if (context.style === undefined) return [getShapeEvent(overlay, getRoundedRectDrawing(box, radius), colors.background, entrance, context.scale)];
219
- return getDraftBoxEvents({
336
+ const drawing = getRoundedRectDrawing(box, radius);
337
+ const panel = getWipePanelEvent(overlay, drawing, colors.accent, motion);
338
+ if (context.style === undefined) return [getShapeEvent(overlay, drawing, colors.background, motion), ...panel];
339
+ const at = { isFirst: true, isLast: true, ms: toMs(overlay.end - overlay.start) };
340
+ const { position, rest } = getMotionTags(motion, { ...at, pos: { x: 0, y: 0 }, part: "card" });
341
+ const events = getDraftBoxEvents({
220
342
  layer: 3,
221
343
  at: `${toAssTime(overlay.start)},${toAssTime(overlay.end)}`,
222
344
  styleName: "OverlayShape",
@@ -226,13 +348,43 @@ function getCardShapeEvents(overlay: ResolvedOverlay, box: OverlayBox, fontSize:
226
348
  accent: colors.accent,
227
349
  style: context.style,
228
350
  scale: context.scale,
229
- motion: getMotionTags(entrance, true, true, { x: 0, y: 0, dy: SLIDE_PX * context.scale }),
351
+ motion: `${position.startsWith("\\move") ? position : ""}${rest}`,
352
+ blurTags: (own) => getBlurTags(motion, at, own),
230
353
  });
354
+ return [...events, ...panel];
355
+ }
356
+
357
+ /** A wipe's accent panel: it grows over the card from the left, then slides off to the right, revealing the card and its text. */
358
+ function getWipePanelEvent(overlay: Pick<ResolvedOverlay, "start">, drawing: string, accent: string, motion: DraftMotion): string[] {
359
+ if (motion.entrance.kind !== "wipe") return [];
360
+ const halves = getWipeHalves(motion.entrance.seconds);
361
+ const [grow, reveal] = [toMs(halves.grow), toMs(halves.reveal)];
362
+ const clip = getWipeClip(motion);
363
+ const tags = `${toClip({ ...clip, x1: clip.x0 })}\\t(0,${grow},${toClip(clip)})\\t(${grow},${grow + reveal},${toClip({ ...clip, x0: clip.x1 })})`;
364
+ return [`Dialogue: 3,${toAssTime(overlay.start)},${toAssTime(overlay.start + motion.entrance.seconds)},OverlayShape,,0,0,0,,{\\an7\\pos(0,0)${tags}\\1c${toTagColor(accent)}\\p1}${drawing}{\\p0}`];
365
+ }
366
+
367
+ /** A keyword's underline: an accent bar under its text, drawn from the left once the keyword is in. */
368
+ function getUnderlineEvent(overlay: Extract<ResolvedOverlay, { kind: "keyword" }>, card: OverlayBox, colour: string, motion: DraftMotion): string[] {
369
+ if (overlay.underline !== true) return [];
370
+ const pad = getOverlayPadding(overlay);
371
+ const height = Math.max(2, r0(overlay.fontSize * UNDERLINE_EM.height));
372
+ const bar = { left: card.left + pad.x, top: card.top + card.height - pad.y + r0(overlay.fontSize * UNDERLINE_EM.gap), width: card.width - 2 * pad.x, height };
373
+ const after = motion.entrance.kind === "none" ? 0 : motion.entrance.seconds;
374
+ const from = Math.min(overlay.end, overlay.start + after);
375
+ const drawMs = toMs(UNDERLINE_SECONDS);
376
+ const x0 = r0(bar.left);
377
+ const clip = `\\clip(${x0},${r0(bar.top - 4)},${x0},${r0(bar.top + bar.height + 4)})\\t(0,${drawMs},\\clip(${x0},${r0(bar.top - 4)},${r0(bar.left + bar.width)},${r0(bar.top + bar.height + 4)}))`;
378
+ const fade = motion.exit.kind === "none" ? "" : `\\fad(0,${motion.isSnappy ? r0(FADE_OUT_MS * 0.7) : FADE_OUT_MS})`;
379
+ // Under a wipe off, the bar leaves as the wipe starts: it is not clipped with the card.
380
+ const until = motion.exit.kind === "wipe" ? Math.max(from, overlay.end - motion.exit.seconds) : overlay.end;
381
+ return [`Dialogue: 4,${toAssTime(from)},${toAssTime(until)},OverlayShape,,0,0,0,,{\\an7\\pos(0,0)${fade}${clip}\\1c${toTagColor(colour)}\\p1}${getRoundedRectDrawing(bar, height / 2)}{\\p0}`];
231
382
  }
232
383
 
233
384
  /**
234
385
  * A keyword, a lower third or a list: a drawn rounded card fitted to its text (`getDrawnOverlayCard`) on layer 3 and
235
- * its text on layer 4, inset by the card's padding on its side (a lower third from its foot).
386
+ * its text on layer 4, inset by the card's padding on its side (a lower third from its foot). A staggered list's points
387
+ * come in one by one; a keyword's underline is drawn once it is in.
236
388
  */
237
389
  function getSideTextEvents(overlay: Extract<ResolvedOverlay, { kind: "keyword" | "lower_third" | "list" }>, context: DraftContext): string[] {
238
390
  const colors = getOverlayColors(overlay, context.brand);
@@ -246,19 +398,27 @@ function getSideTextEvents(overlay: Extract<ResolvedOverlay, { kind: "keyword" |
246
398
  const y = isFoot ? card.top + card.height - padY : card.top + padY;
247
399
  // \an: 7 top left, 9 top right, 1 bottom left, 3 bottom right.
248
400
  const align = isFoot ? (isRight ? 3 : 1) : isRight ? 9 : 7;
249
- const entrance = overlay.entrance === null || overlay.entrance === "type" ? "fade" : overlay.entrance;
401
+ const motion = getDraftMotion(overlay, overlay.entrance === null || overlay.entrance === "type" ? "fade" : overlay.entrance, card, context);
250
402
  const span = { start: overlay.start, end: overlay.end };
251
403
  const tags = `\\an${align}\\fs${fontSize}${getTextTags(overlay, colors, context, OVERLAY_FONT_ROLES[overlay.kind])}`;
252
- const text = (pos: OverlayPoint, steps: TextStep[]) => getTextEvents({ layer: 4, style: "OverlayPlain", pos, tags, steps, entrance, slidePx: SLIDE_PX * context.scale });
253
- const shape = getCardShapeEvents(overlay, card, fontSize, colors, entrance, context);
404
+ const text = (pos: OverlayPoint, steps: TextStep[], own = motion) => getTextEvents({ layer: 4, style: "OverlayPlain", pos, tags, steps, motion: own });
405
+ const shape = getCardShapeEvents(overlay, card, fontSize, colors, motion, context);
254
406
  if (overlay.kind === "list") {
255
- // One event per point, on the render's line height (libass's own line spacing is tighter), all shown at once.
407
+ // One event per point, on the render's line height (libass's own line spacing is tighter); a staggered point from its second.
256
408
  const step = fontSize * OVERLAY_LIST_LINE_HEIGHT;
257
409
  const lead = (step - fontSize * OVERLAY_LINE_HEIGHT) / 2;
258
- return [...shape, ...getSideTextLines(overlay).flatMap((line, index) => text({ x, y: y + lead + index * step }, [{ from: span.start, to: span.end, text: toAssText(line) }]))];
410
+ return [
411
+ ...shape,
412
+ ...getSideTextLines(overlay).flatMap((line, index) => {
413
+ const from = overlay.itemStarts?.[index];
414
+ const pos = { x, y: y + lead + index * step };
415
+ return from === undefined ? text(pos, [{ from: span.start, to: span.end, text: toAssText(line) }]) : text(pos, [{ from, to: span.end, text: toAssText(line) }], withFadeEntrance(motion));
416
+ }),
417
+ ];
259
418
  }
260
419
  // A keyword or a lower third types in only when its entrance says so.
261
- return [...shape, ...text({ x, y }, overlay.entrance === null ? [{ from: span.start, to: span.end, text: toAssText(overlay.text) }] : getTypedSteps(overlay.text, span, overlay.typing))];
420
+ const steps = overlay.entrance === null ? [{ from: span.start, to: span.end, text: toAssText(overlay.text) }] : getTypedSteps(overlay.text, span, overlay.typing);
421
+ return [...shape, ...text({ x, y }, steps), ...(overlay.kind === "keyword" ? getUnderlineEvent(overlay, card, colors.accent, motion) : [])];
262
422
  }
263
423
 
264
424
  type CardOverlay = Extract<ResolvedOverlay, { kind: "hook_title" | "search_bar" | "place_card" | "counter" | "date_stamp" }>;
@@ -266,26 +426,40 @@ type CardOverlay = Extract<ResolvedOverlay, { kind: "hook_title" | "search_bar"
266
426
  /** Each card's own entrance when the overlay names none (a typed card fades its card in). */
267
427
  const DEFAULT_ENTRANCES = { hook_title: "slide", search_bar: "fade", place_card: "slide", counter: "fade", date_stamp: "fade" } as const;
268
428
 
269
- /** A drawing event in the overlay's card colour (or accent), with the overlay's entrance. */
270
- function getShapeEvent(overlay: Pick<ResolvedOverlay, "start" | "end">, drawing: string, colour: string, entrance: "fade" | "slide" | "none", scale: number): string {
271
- const motion = getMotionTags(entrance, true, true, { x: 0, y: 0, dy: SLIDE_PX * scale });
272
- const pos = motion.includes("\\move") ? "" : "\\pos(0,0)";
273
- return `Dialogue: 3,${toAssTime(overlay.start)},${toAssTime(overlay.end)},OverlayShape,,0,0,0,,{\\an7${pos}${motion}\\1c${toTagColor(colour)}\\p1}${drawing}{\\p0}`;
429
+ /** A drawing event in the overlay's card colour (or accent), with the overlay's motion. */
430
+ function getShapeEvent(overlay: Pick<ResolvedOverlay, "start" | "end">, drawing: string, colour: string, motion: DraftMotion, layer = 3): string {
431
+ const at = { isFirst: true, isLast: true, ms: toMs(overlay.end - overlay.start) };
432
+ const { position, rest } = getMotionTags(motion, { ...at, pos: { x: 0, y: 0 }, part: "card" });
433
+ return `Dialogue: ${layer},${toAssTime(overlay.start)},${toAssTime(overlay.end)},OverlayShape,,0,0,0,,{\\an7${position}${rest}${getBlurTags(motion, at, 0)}\\1c${toTagColor(colour)}\\p1}${drawing}{\\p0}`;
434
+ }
435
+
436
+ /** A place card's pin above its title: there with the card, or dropping a little onto its place. */
437
+ function getPinEvents(overlay: Extract<ResolvedOverlay, { kind: "place_card" }>, at: OverlayPoint, colour: string, motion: DraftMotion): string[] {
438
+ if (overlay.pin === undefined) return [];
439
+ const size = getPlaceCardPinSize(overlay.fontSize);
440
+ const drawing = getPinDrawing(at, size);
441
+ if (overlay.pin === "static") return [getShapeEvent(overlay, drawing, colour, motion, 4)];
442
+ const drop = r0(size * PIN_DROP_SHARE);
443
+ const fade = motion.exit.kind === "none" ? 0 : motion.isSnappy ? r0(FADE_OUT_MS * 0.7) : FADE_OUT_MS;
444
+ return [
445
+ `Dialogue: 4,${toAssTime(overlay.start)},${toAssTime(overlay.end)},OverlayShape,,0,0,0,,{\\an7\\move(0,${-drop},0,0,0,${toMs(PIN_DROP_SECONDS)})\\fad(${r0(toMs(PIN_DROP_SECONDS) * 0.6)},${fade})\\1c${toTagColor(colour)}\\p1}${drawing}{\\p0}`,
446
+ ];
274
447
  }
275
448
 
276
449
  /** 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. */
277
450
  function getCardEvents(overlay: CardOverlay, context: DraftContext): string[] {
278
451
  const colors = getOverlayColors(overlay, context.brand);
279
452
  const { box, fontSize } = overlay;
280
- const entrance = overlay.entrance === null || overlay.entrance === "type" ? (overlay.typing !== null ? "fade" : DEFAULT_ENTRANCES[overlay.kind]) : overlay.entrance;
281
- const slidePx = SLIDE_PX * context.scale;
453
+ const name = overlay.entrance === null || overlay.entrance === "type" ? (overlay.typing !== null ? "fade" : DEFAULT_ENTRANCES[overlay.kind]) : overlay.entrance;
454
+ const motion = getDraftMotion(overlay, name, box, context);
282
455
  const span = { start: overlay.start, end: overlay.end };
283
- const events = getCardShapeEvents(overlay, box, fontSize, colors, entrance, context);
456
+ const events = getCardShapeEvents(overlay, box, fontSize, colors, motion, context);
284
457
  const { x: padX, y: padY } = getOverlayPadding(overlay);
285
458
  const centerX = box.left + box.width / 2;
286
459
  const tagsFor = (role: OverlayFontRole) => getTextTags(overlay, colors, context, role);
287
- const text = (pos: OverlayPoint, align: number, size: number, role: OverlayFontRole, steps: TextStep[], own: "fade" | "slide" | "none" = entrance) =>
288
- getTextEvents({ layer: 4, style: "OverlayPlain", pos, tags: `\\an${align}\\fs${r0(size)}${tagsFor(role)}`, steps, entrance: own, slidePx });
460
+ const text = (pos: OverlayPoint, align: number, size: number, role: OverlayFontRole, steps: TextStep[], own: DraftMotion = motion) =>
461
+ getTextEvents({ layer: 4, style: "OverlayPlain", pos, tags: `\\an${align}\\fs${r0(size)}${tagsFor(role)}`, steps, motion: own });
462
+ const plain = { ...motion, name: "none" as const, entrance: { kind: "none" as const } };
289
463
  if (overlay.kind === "hook_title" || overlay.kind === "place_card") {
290
464
  // The text block sits in the card's middle; centred lines on its axis, left ones from its left edge (RV-131).
291
465
  const content = getTitleContentBox(overlay);
@@ -298,32 +472,40 @@ function getCardEvents(overlay: CardOverlay, context: DraftContext): string[] {
298
472
  const pin = Math.round(size * 1.05);
299
473
  const rowWidth = pin + Math.round(size * 0.25) + estimateTextWidth(overlay.place, size);
300
474
  const rowLeft = isLeft ? content.left : centerX - rowWidth / 2;
301
- 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,"));
475
+ events.push(getShapeEvent(overlay, getPinDrawing({ x: rowLeft, y: y + (size * OVERLAY_LINE_HEIGHT - pin) / 2 }, pin), colors.accent, motion, 4));
302
476
  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) }]));
303
477
  y += size * 1.3 + fontSize * 0.12;
304
478
  }
479
+ const times = overlay.kind === "place_card" ? getPlaceCardTimes(overlay) : { pin: null, title: span.start, subtitle: null };
480
+ if (overlay.kind === "place_card" && overlay.pin !== undefined) {
481
+ const size = getPlaceCardPinSize(fontSize);
482
+ events.push(...getPinEvents(overlay, { x: isLeft ? content.left : centerX - size / 2, y }, colors.accent, motion));
483
+ y += getPlaceCardPinRow(fontSize);
484
+ }
305
485
  const lineHeight = overlay.kind === "hook_title" ? OVERLAY_LINE_HEIGHT : OVERLAY_TITLE_LINE_HEIGHT;
486
+ const titleMotion = times.title > span.start ? withFadeEntrance(motion) : motion;
306
487
  let typedBefore = 0;
307
488
  overlay.lines.forEach((line) => {
308
489
  // The lines type one after the other, as the render's characters do; a left line holds its place transparent
309
490
  // from the start, a centred one shows its typed part only (`getTypedSteps`).
310
- const lineStart = overlay.typing === null ? span.start : span.start + typedBefore / overlay.typing;
491
+ const lineStart = overlay.typing === null ? times.title : span.start + typedBefore / overlay.typing;
311
492
  const steps = getTypedSteps(line, { start: lineStart, end: span.end }, overlay.typing, !isLeft);
312
493
  // A centred typed line has no hidden first step to carry the entrance: its letters appear as typed, as the render's.
313
494
  const isTypedCentre = !isLeft && overlay.typing !== null;
314
- events.push(...text({ x: lineX, y }, lineAlign, fontSize, "heading", isLeft ? steps.map((step, index) => (index === 0 ? { ...step, from: span.start } : step)) : steps, isTypedCentre ? "none" : entrance));
495
+ events.push(...text({ x: lineX, y }, lineAlign, fontSize, "heading", isLeft ? steps.map((step, index) => (index === 0 ? { ...step, from: span.start } : step)) : steps, isTypedCentre ? plain : titleMotion));
315
496
  typedBefore += [...line].length;
316
497
  y += fontSize * lineHeight;
317
498
  });
318
499
  if (overlay.kind === "place_card" && overlay.subtitle !== null) {
319
- events.push(...text({ x: lineX, y: y + fontSize * 0.12 }, lineAlign, overlay.subtitleFontSize, "interface", [{ from: span.start, to: span.end, text: toAssText(overlay.subtitle) }]));
500
+ const from = times.subtitle ?? span.start;
501
+ events.push(...text({ x: lineX, y: y + fontSize * 0.12 }, lineAlign, overlay.subtitleFontSize, "interface", [{ from, to: span.end, text: toAssText(overlay.subtitle) }], from > span.start ? withFadeEntrance(motion) : motion));
320
502
  }
321
503
  return events;
322
504
  }
323
505
  if (overlay.kind === "search_bar") {
324
506
  const searchPadX = r0(fontSize * SEARCH_BAR_PADDING_EM.x);
325
507
  const middle = box.top + box.height / 2;
326
- events.push(getShapeEvent(overlay, getGlassDrawing({ x: box.left + searchPadX, y: middle - fontSize / 2 }, fontSize), colors.accent, entrance, context.scale).replace("Dialogue: 3,", "Dialogue: 4,"));
508
+ events.push(getShapeEvent(overlay, getGlassDrawing({ x: box.left + searchPadX, y: middle - fontSize / 2 }, fontSize), colors.accent, motion, 4));
327
509
  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)));
328
510
  return events;
329
511
  }
@@ -336,8 +518,8 @@ function getCardEvents(overlay: CardOverlay, context: DraftContext): string[] {
336
518
  steps.push({ from: span.start, to: count.start, text: show(overlay.from) });
337
519
  for (let tick = 1; tick <= ticks; tick++) {
338
520
  const progress = tick / ticks;
339
- // power2.out, as the render's tween eases.
340
- const eased = 1 - (1 - progress) ** 2;
521
+ // power2.out, as the render's tween eases: the count slows down to its value.
522
+ const eased = OVERLAY_EASES["power2.out"](progress);
341
523
  const value = overlay.from + (overlay.value - overlay.from) * eased;
342
524
  steps.push({ from: count.start + (tick - 1) * COUNT_STEP, to: tick === ticks ? span.end : count.start + tick * COUNT_STEP, text: show(value) });
343
525
  }
@@ -38,6 +38,16 @@ export interface EdlCaption {
38
38
  top?: number;
39
39
  }
40
40
 
41
+ /**
42
+ * The caption box for a stretch of film time, over the segment's (`EdlCaption`): the caption chunks said between
43
+ * `from` and `to` (film seconds, `to` excluded) take it, so captions can clear something shown for part of a segment
44
+ * without splitting the cut. Px of the film's frame, as `EdlCaption`.
45
+ */
46
+ export interface EdlCaptionRange extends EdlCaption {
47
+ from: number;
48
+ to: number;
49
+ }
50
+
41
51
  export interface EdlSegment {
42
52
  /** Unique in the cut: `s<n>` (the sentence it starts with), `r<n>` (b-roll), `w<n>` (a talking clip without words). */
43
53
  id: string;
@@ -63,6 +73,8 @@ export interface Edl {
63
73
  * and the film is drawn as without the field.
64
74
  */
65
75
  overlays?: EdlOverlay[];
76
+ /** Caption boxes for stretches of film time, over the segments' own (`EdlCaptionRange`); absent or empty: none. */
77
+ captionRanges?: EdlCaptionRange[];
66
78
  }
67
79
 
68
80
  const SEGMENT_ID_PATTERN = /^[A-Za-z0-9._-]+$/;
@@ -111,6 +123,18 @@ export const edlSchema = z
111
123
  .describe(
112
124
  "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 shot (one segment, or segments of one clip joined by plain cuts, with no Ken Burns zoom and the same caption box; a punch_in 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
125
  ),
126
+ captionRanges: z
127
+ .array(
128
+ z.strictObject({
129
+ from: z.number().min(0).describe("Film second where the stretch starts."),
130
+ to: z.number().positive().describe("Film second where the stretch ends (excluded)."),
131
+ bottom: z.number().min(0).optional().describe("The caption box's foot, in px above the frame's foot; anchors the box by its foot and wins over top."),
132
+ top: z.number().min(0).optional().describe("The caption box's top, in px below the frame's top; used when bottom is absent."),
133
+ }),
134
+ )
135
+ .max(40)
136
+ .optional()
137
+ .describe("Moves the caption box for the captions said in a stretch of film time (from to to, in film seconds), over the segment's own caption; stretches never overlap. Without it, the segments' boxes."),
114
138
  })
115
139
  .describe("The edit decision list of a footage film (edl.json).");
116
140
 
@@ -288,6 +312,23 @@ export function validateEdl(edl: Edl, clips: Pick<EdlClip, "id" | "duration">[],
288
312
  const soundLength = r3(audio.end - audio.start);
289
313
  if (Math.abs(length - soundLength) > 0.05) problems.push(`${at}.audio: ${soundLength} s of sound for ${length} s of picture (end - start must match)`);
290
314
  });
315
+ problems.push(...findCaptionRangeProblems(edl, captionBounds));
316
+ return problems;
317
+ }
318
+
319
+ /** Caption ranges that are empty, run past the cut, overlap one another or (with `captionBounds`) leave the frame. */
320
+ function findCaptionRangeProblems(edl: Edl, captionBounds: EdlCaptionBounds | undefined): string[] {
321
+ const problems: string[] = [];
322
+ const duration = getEdlDuration(edl);
323
+ const ranges = edl.captionRanges ?? [];
324
+ ranges.forEach((range, index) => {
325
+ const at = `captionRanges[${index}]`;
326
+ if (range.to <= range.from) problems.push(`${at}: to (${range.to} s) must come after from (${range.from} s)`);
327
+ if (range.to > duration + 0.05) problems.push(`${at}.to: ${range.to} s is past the cut's end (${duration} s)`);
328
+ const other = ranges.findIndex((candidate, j) => j < index && candidate.from < range.to && range.from < candidate.to);
329
+ if (other !== -1) problems.push(`${at}: overlaps captionRanges[${other}] (${formatSpan({ start: range.from, end: range.to })})`);
330
+ if (captionBounds !== undefined) problems.push(...findCaptionProblems(at, range, captionBounds));
331
+ });
291
332
  return problems;
292
333
  }
293
334
 
@@ -384,6 +425,11 @@ export function diffEdl(before: Edl, after: Edl): string[] {
384
425
  if (previous === undefined || isSameCaption(previous.caption, segment.caption)) continue;
385
426
  lines.push(isMovedCaption(segment.caption) ? `${segment.id} captions moved` : `${segment.id} captions back in the film's box`);
386
427
  }
428
+ const [rangesBefore, rangesAfter] = [before.captionRanges ?? [], after.captionRanges ?? []];
429
+ if (JSON.stringify(rangesBefore) !== JSON.stringify(rangesAfter)) {
430
+ const spans = rangesAfter.map((range) => formatSpan({ start: range.from, end: range.to })).join(", ");
431
+ lines.push(rangesAfter.length === 0 ? "captions back in the segments' boxes" : `captions moved in ${spans}`);
432
+ }
387
433
  const [overlaysBefore, overlaysAfter] = [before.overlays ?? [], after.overlays ?? []];
388
434
  if (JSON.stringify(overlaysBefore) !== JSON.stringify(overlaysAfter)) {
389
435
  lines.push(`overlays: ${overlaysAfter.map((overlay) => overlay.kind.replace("_", " ")).join(", ") || "none"} (was ${overlaysBefore.length})`);
@@ -420,6 +466,11 @@ export function getEdlDuration(edl: Edl): number {
420
466
  * The index of the segment that plays at `time` (film seconds): the one whose span holds it; a time before the film
421
467
  * gives the first segment, one at or past the cut's end the last.
422
468
  */
469
+ /** The caption range that holds film second `time` (from it, before its end), or undefined. */
470
+ export function findCaptionRangeAt(edl: Pick<Edl, "captionRanges">, time: number): EdlCaptionRange | undefined {
471
+ return (edl.captionRanges ?? []).find((range) => range.from <= time && time < range.to);
472
+ }
473
+
423
474
  export function findSegmentAt(edl: Edl, time: number): number {
424
475
  const starts = getSegmentStarts(edl);
425
476
  let found = 0;