@softure-ai/marketing-kit 0.32.0 → 0.34.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 (52) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/README.md +21 -0
  3. package/dist/footage/camera.d.ts +67 -0
  4. package/dist/footage/camera.d.ts.map +1 -0
  5. package/dist/footage/camera.js +89 -0
  6. package/dist/footage/camera.js.map +1 -0
  7. package/dist/footage/compose.d.ts +6 -1
  8. package/dist/footage/compose.d.ts.map +1 -1
  9. package/dist/footage/compose.js +31 -9
  10. package/dist/footage/compose.js.map +1 -1
  11. package/dist/footage/draft-overlays.d.ts.map +1 -1
  12. package/dist/footage/draft-overlays.js +103 -27
  13. package/dist/footage/draft-overlays.js.map +1 -1
  14. package/dist/footage/draft.d.ts +10 -2
  15. package/dist/footage/draft.d.ts.map +1 -1
  16. package/dist/footage/draft.js +25 -28
  17. package/dist/footage/draft.js.map +1 -1
  18. package/dist/footage/edl.d.ts +28 -0
  19. package/dist/footage/edl.d.ts.map +1 -1
  20. package/dist/footage/edl.js +24 -0
  21. package/dist/footage/edl.js.map +1 -1
  22. package/dist/footage/overlay-html.d.ts.map +1 -1
  23. package/dist/footage/overlay-html.js +81 -22
  24. package/dist/footage/overlay-html.js.map +1 -1
  25. package/dist/footage/overlay-schema.d.ts +23 -2
  26. package/dist/footage/overlay-schema.d.ts.map +1 -1
  27. package/dist/footage/overlay-schema.js +28 -3
  28. package/dist/footage/overlay-schema.js.map +1 -1
  29. package/dist/footage/overlays.d.ts +26 -1
  30. package/dist/footage/overlays.d.ts.map +1 -1
  31. package/dist/footage/overlays.js +116 -14
  32. package/dist/footage/overlays.js.map +1 -1
  33. package/dist/footage/picture.d.ts +3 -0
  34. package/dist/footage/picture.d.ts.map +1 -1
  35. package/dist/footage/picture.js +15 -11
  36. package/dist/footage/picture.js.map +1 -1
  37. package/dist/index.d.ts +5 -4
  38. package/dist/index.d.ts.map +1 -1
  39. package/dist/index.js +5 -4
  40. package/dist/index.js.map +1 -1
  41. package/package.json +1 -1
  42. package/schema/edl.schema.json +79 -2
  43. package/src/footage/camera.ts +129 -0
  44. package/src/footage/compose.ts +30 -10
  45. package/src/footage/draft-overlays.ts +123 -26
  46. package/src/footage/draft.ts +29 -29
  47. package/src/footage/edl.ts +24 -0
  48. package/src/footage/overlay-html.ts +85 -22
  49. package/src/footage/overlay-schema.ts +40 -4
  50. package/src/footage/overlays.ts +149 -15
  51. package/src/footage/picture.ts +17 -11
  52. package/src/index.ts +29 -0
@@ -41,6 +41,11 @@ export const OVERLAY_ALIGNS = ["center", "left"] as const;
41
41
 
42
42
  export type OverlayAlign = (typeof OVERLAY_ALIGNS)[number];
43
43
 
44
+ /** Where a keyword's card sits across the room it may take: on the left, in the middle or on the right. */
45
+ export const OVERLAY_KEYWORD_ALIGNS = ["left", "center", "right"] as const;
46
+
47
+ export type OverlayKeywordAlign = (typeof OVERLAY_KEYWORD_ALIGNS)[number];
48
+
44
49
  /** The kinds whose lines take an `align`: the two stacked title cards. */
45
50
  export const OVERLAY_ALIGNED_KINDS: readonly OverlayKind[] = ["hook_title", "place_card"];
46
51
 
@@ -74,6 +79,15 @@ export const OVERLAY_PINS = ["none", "static", "drop"] as const;
74
79
 
75
80
  export type OverlayPin = (typeof OVERLAY_PINS)[number];
76
81
 
82
+ /**
83
+ * How a list draws its points: `stack` (one centred card, its points one under another, the card growing as each one
84
+ * comes in), `chips` (each point its own small card, side by side in one centred row, entering in turn from the left)
85
+ * or `auto` (chips when every point fits one row at the list's size, else the stack). Without it: `stack`.
86
+ */
87
+ export const OVERLAY_LIST_LAYOUTS = ["stack", "chips", "auto"] as const;
88
+
89
+ export type OverlayListLayout = (typeof OVERLAY_LIST_LAYOUTS)[number];
90
+
77
91
  /** The longest a place card's subtitle waits after its title, in seconds. */
78
92
  export const MAX_OVERLAY_SUBTITLE_DELAY = 0.6;
79
93
 
@@ -142,8 +156,11 @@ export interface EdlOverlayStyle {
142
156
  colors?: EdlOverlayColors;
143
157
  /** Its card's corner in place of the brand style's (`BrandStyle.cornerRadius`); not on a punch_in, arrow or highlight. */
144
158
  corner_radius?: CornerRadius;
145
- /** How a hook title's or a place card's lines sit in the card (`center` without it). */
146
- align?: OverlayAlign;
159
+ /**
160
+ * How a hook title's or a place card's lines sit in the card (`center` or `left`, `center` without it), or where a
161
+ * keyword's card sits across its room (`left`, `center` or `right`, in place of `side`).
162
+ */
163
+ align?: OverlayKeywordAlign;
147
164
  /** A place card's subtitle size: `s`, `m` (about 55 % of the title, the default) or `l`. */
148
165
  subtitle_size?: OverlaySize;
149
166
  /** How it leaves (`auto` without it: mirrors the entrance). */
@@ -152,6 +169,8 @@ export interface EdlOverlayStyle {
152
169
  easing?: OverlayEasing;
153
170
  /** A list's points come in one by one (on their `item_words` when given, else spaced automatically). */
154
171
  stagger?: boolean;
172
+ /** How a list draws its points (`stack` without it). */
173
+ list_layout?: OverlayListLayout;
155
174
  /** Seconds a place card's subtitle waits after its title (0 to `MAX_OVERLAY_SUBTITLE_DELAY`). */
156
175
  subtitle_delay?: number;
157
176
  /** A place card's accent pin above its title. */
@@ -322,11 +341,17 @@ function checkOverlayStyle(overlay: EdlOverlay, issue: (path: string[], message:
322
341
  }
323
342
  if (style.typing_speed !== undefined && !isTypedOverlay(overlay)) issue(["style", "typing_speed"], "only a typed entrance or a search bar has a typing speed");
324
343
  if (style.corner_radius !== undefined && (kind === "punch_in" || kind === "arrow" || kind === "highlight")) issue(["style", "corner_radius"], `${article(kind)} draws no card; leave corner_radius out`);
325
- if (style.align !== undefined && !OVERLAY_ALIGNED_KINDS.includes(kind)) issue(["style", "align"], "only a hook_title or a place_card aligns its lines; leave align out");
344
+ if (style.align !== undefined) {
345
+ if (kind === "keyword") {
346
+ if (style.side !== undefined) issue(["style", "align"], "give a keyword align or side, not both");
347
+ } else if (!OVERLAY_ALIGNED_KINDS.includes(kind)) issue(["style", "align"], "only a hook_title, a place_card or a keyword takes align; leave it out");
348
+ else if (!(OVERLAY_ALIGNS as readonly string[]).includes(style.align)) issue(["style", "align"], `${article(kind)} aligns its lines ${OVERLAY_ALIGNS.join(" or ")}`);
349
+ }
326
350
  if (style.subtitle_size !== undefined && kind !== "place_card") issue(["style", "subtitle_size"], "only a place_card has a subtitle; leave subtitle_size out");
327
351
  if (style.subtitle_delay !== undefined && kind !== "place_card") issue(["style", "subtitle_delay"], "only a place_card has a subtitle; leave subtitle_delay out");
328
352
  if (style.pin !== undefined && kind !== "place_card") issue(["style", "pin"], "only a place_card draws a pin; leave pin out");
329
353
  if (style.stagger !== undefined && kind !== "list") issue(["style", "stagger"], "only a list has points to stagger; leave stagger out");
354
+ if (style.list_layout !== undefined && kind !== "list") issue(["style", "list_layout"], "only a list lays out points; leave list_layout out");
330
355
  if (style.underline !== undefined && kind !== "keyword") issue(["style", "underline"], "only a keyword is underlined; leave underline out");
331
356
  if ((style.exit !== undefined || style.easing !== undefined) && kind === "punch_in") issue(["style", style.exit === undefined ? "easing" : "exit"], "a punch_in eases the picture itself; leave exit and easing out");
332
357
  if (style.colors === undefined) return;
@@ -439,9 +464,20 @@ export const overlaySchema = z
439
464
  .enum(CORNER_RADII)
440
465
  .optional()
441
466
  .describe("The card's corner: none, s, m, l or pill; the brand style's without it (no punch_in, arrow or highlight)."),
442
- align: z.enum(OVERLAY_ALIGNS).optional().describe("center (the default) or left: how a hook_title's or a place_card's lines sit in their card."),
467
+ align: z
468
+ .enum(OVERLAY_KEYWORD_ALIGNS)
469
+ .optional()
470
+ .describe(
471
+ "center (the default) or left: how a hook_title's or a place_card's lines sit in their card; left, center or right: where a keyword's card sits across its room (in place of side).",
472
+ ),
443
473
  subtitle_size: z.enum(OVERLAY_SIZES).optional().describe("s, m (the default, about 55 % of the title) or l: a place_card's subtitle size."),
444
474
  stagger: z.boolean().optional().describe("A list only: its points come in one by one (on item_words when given, else spaced automatically)."),
475
+ list_layout: z
476
+ .enum(OVERLAY_LIST_LAYOUTS)
477
+ .optional()
478
+ .describe(
479
+ "A list only: stack (the default: one centred card growing as each point comes in), chips (each point its own small card in one centred row, entering in turn from the left) or auto (chips when they fit one row, else stack).",
480
+ ),
445
481
  subtitle_delay: z
446
482
  .number()
447
483
  .min(0)
@@ -14,10 +14,12 @@ import {
14
14
  type OverlayEntrance,
15
15
  type OverlayExit,
16
16
  type OverlayKind,
17
+ type OverlayListLayout,
17
18
  type OverlayPosition,
18
19
  type OverlaySide,
19
20
  type OverlaySize,
20
21
  } from "./overlay-schema.js";
22
+ import { isCameraMoving, isSameCamera } from "./camera.js";
21
23
  import { getSegmentZoomEases } from "./compose.js";
22
24
  import { normalizeWord } from "./words.js";
23
25
  import { getListItemStarts } from "./overlay-motion.js";
@@ -61,6 +63,8 @@ const MAX_TITLE_SHRINKS = 3;
61
63
  /** A text overlay's line height and its box's padding, in font sizes. */
62
64
  export const OVERLAY_LINE_HEIGHT = 1.15;
63
65
  export const OVERLAY_LIST_LINE_HEIGHT = 1.4;
66
+ /** The room between two chips of a list's row, in font sizes. */
67
+ export const LIST_CHIP_GAP_EM = 0.3;
64
68
  /** A place card title's line height, tighter for its big type. */
65
69
  export const OVERLAY_TITLE_LINE_HEIGHT = 1.05;
66
70
  export const OVERLAY_PADDING_EM = { x: 0.6, y: 0.35 } as const;
@@ -144,9 +148,29 @@ type Drawn = OverlayBase & OverlayLook;
144
148
  */
145
149
  export type ResolvedOverlay =
146
150
  | (OverlayBase & { kind: "punch_in"; scale: number; ease: number })
147
- | (Drawn & { kind: "keyword"; text: string; fontSize: number; side: OverlaySide; box: OverlayBox; underline?: boolean })
151
+ | (Drawn & {
152
+ kind: "keyword";
153
+ text: string;
154
+ fontSize: number;
155
+ side: OverlaySide;
156
+ box: OverlayBox;
157
+ underline?: boolean;
158
+ /** Its card sits in the middle of `box`, its text centred (`style.align` center); absent: on its side. */
159
+ isCentred?: boolean;
160
+ })
148
161
  | (Drawn & { kind: "lower_third"; text: string; fontSize: number; side: OverlaySide; box: OverlayBox })
149
- | (Drawn & { kind: "list"; items: string[]; fontSize: number; side: OverlaySide; box: OverlayBox; itemStarts?: number[] })
162
+ | (Drawn & {
163
+ kind: "list";
164
+ items: string[];
165
+ fontSize: number;
166
+ side: OverlaySide;
167
+ box: OverlayBox;
168
+ itemStarts?: number[];
169
+ /** Its card sits in the middle of `box` with its lines centred (a stack without `style.side`); absent: on its side. */
170
+ isCentred?: boolean;
171
+ /** Each point's own card in one row (`style.list_layout` chips, or auto when they fit); absent: one stacked card. */
172
+ chips?: OverlayBox[];
173
+ })
150
174
  | (Drawn & { kind: "arrow"; from: OverlayPoint; to: OverlayPoint })
151
175
  | (Drawn & { kind: "highlight"; rect: OverlayBox })
152
176
  | (Drawn & { kind: "hook_title"; lines: string[]; place: string | null; fontSize: number; placeFontSize: number; align?: OverlayAlign; box: OverlayBox })
@@ -285,9 +309,13 @@ export function getOverlayBounds(overlay: ResolvedOverlay): OverlayBox | null {
285
309
 
286
310
  type SideTextOverlay = Extract<ResolvedOverlay, { kind: "keyword" | "lower_third" | "list" }>;
287
311
 
288
- /** A keyword's, a lower third's or a list's lines as the draft draws them: a list's points with their bullets. */
312
+ /**
313
+ * A keyword's, a lower third's or a list's lines as the draft draws them: a list's points with their bullets on a list
314
+ * on its side; a centred stack and chips draw their points without bullets.
315
+ */
289
316
  export function getSideTextLines(overlay: SideTextOverlay): string[] {
290
- const lines = overlay.kind === "list" ? overlay.items.map((item) => `• ${item}`) : [overlay.text];
317
+ const hasBullets = overlay.kind === "list" && overlay.isCentred !== true && overlay.chips === undefined;
318
+ const lines = overlay.kind === "list" ? overlay.items.map((item) => (hasBullets ? `• ${item}` : item)) : [overlay.text];
291
319
  return lines.map((line) => line.replace(/\s+/g, " ").trim());
292
320
  }
293
321
 
@@ -299,11 +327,53 @@ export function getSideTextLines(overlay: SideTextOverlay): string[] {
299
327
  */
300
328
  export function getDrawnOverlayCard(overlay: ResolvedOverlay): OverlayBox | null {
301
329
  if (overlay.kind !== "keyword" && overlay.kind !== "lower_third" && overlay.kind !== "list") return getOverlayBounds(overlay);
330
+ if (overlay.kind === "list" && overlay.chips !== undefined) return getBoxesUnion(overlay.chips);
331
+ return getSideTextCard(overlay, getSideTextLines(overlay), overlay.box.height);
332
+ }
333
+
334
+ /** The card of a side text fitted to `lines`, `height` tall from the box's top: on its side, or in the box's middle (a centred list or keyword). */
335
+ function getSideTextCard(overlay: SideTextOverlay, lines: readonly string[], height: number): OverlayBox {
302
336
  const { box, fontSize, side } = overlay;
303
337
  const padX = getOverlayPadding(overlay).x;
304
- const textWidth = Math.max(0, ...getSideTextLines(overlay).map((line) => estimateTextWidth(line, fontSize)));
338
+ const textWidth = Math.max(0, ...lines.map((line) => estimateTextWidth(line, fontSize)));
305
339
  const width = Math.min(box.width, Math.ceil(textWidth + 2 * padX));
306
- return { left: side === "right" ? box.left + box.width - width : box.left, top: box.top, width, height: box.height };
340
+ const isCentred = (overlay.kind === "list" || overlay.kind === "keyword") && overlay.isCentred === true;
341
+ const left = isCentred ? box.left + Math.round((box.width - width) / 2) : side === "right" ? box.left + box.width - width : box.left;
342
+ return { left, top: box.top, width, height };
343
+ }
344
+
345
+ /** The smallest box round every box of a non-empty list. */
346
+ function getBoxesUnion(boxes: readonly OverlayBox[]): OverlayBox {
347
+ const left = Math.min(...boxes.map((box) => box.left));
348
+ const top = Math.min(...boxes.map((box) => box.top));
349
+ const right = Math.max(...boxes.map((box) => box.left + box.width));
350
+ const bottom = Math.max(...boxes.map((box) => box.top + box.height));
351
+ return { left, top, width: right - left, height: bottom - top };
352
+ }
353
+
354
+ /**
355
+ * A list's drawn boxes after each point has come in (RV-144 of an adopting app): `cards[i]` is what shows once points
356
+ * 0 to i are in. A stack's card grows with each point, fitted to the points in so far (one line taller, as wide as the
357
+ * widest), so it never stands sized for the whole list nor empty: its first point comes in with it. Chips add one
358
+ * card at a time, each in its final place (`overlay.chips`), so the row is centred once complete and nothing already
359
+ * shown moves. Every entry holds one box per drawn card.
360
+ */
361
+ export function getListCardsByItem(overlay: Extract<ResolvedOverlay, { kind: "list" }>): OverlayBox[][] {
362
+ if (overlay.chips !== undefined) {
363
+ const chips = overlay.chips;
364
+ return chips.map((_chip, index) => chips.slice(0, index + 1));
365
+ }
366
+ const lines = getSideTextLines(overlay);
367
+ const padY = getOverlayPadding(overlay).y;
368
+ return lines.map((_line, index) => {
369
+ const height = index === lines.length - 1 ? overlay.box.height : Math.ceil((index + 1) * overlay.fontSize * OVERLAY_LIST_LINE_HEIGHT + 2 * padY);
370
+ return [getSideTextCard(overlay, lines.slice(0, index + 1), height)];
371
+ });
372
+ }
373
+
374
+ /** The film seconds each point of a list comes in at: its own (`itemStarts`), the first with the card; else all with the card. */
375
+ export function getListItemTimes(overlay: Extract<ResolvedOverlay, { kind: "list" }>): number[] {
376
+ return overlay.items.map((_item, index) => (index === 0 ? overlay.start : (overlay.itemStarts?.[index] ?? overlay.start)));
307
377
  }
308
378
 
309
379
  /**
@@ -318,6 +388,7 @@ export function findShotBreak(edl: Pick<Edl, "segments">, index: number): string
318
388
  if (segment.clip !== previous.clip) return `segment "${segment.id}" plays another clip`;
319
389
  if (segment.transition !== "cut") return `segment "${segment.id}" starts on a ${segment.transition}, not a plain cut`;
320
390
  if (segment.motion === "kenburns" || previous.motion === "kenburns") return `a Ken Burns zoom at segment "${segment.id}"`;
391
+ if (isCameraMoving(segment.camera) || isCameraMoving(previous.camera) || !isSameCamera(segment.camera, previous.camera)) return `a camera move or a new framing at segment "${segment.id}"`;
321
392
  if (segment.caption?.bottom !== previous.caption?.bottom || segment.caption?.top !== previous.caption?.top) return `segment "${segment.id}" moves the captions`;
322
393
  return null;
323
394
  }
@@ -394,13 +465,18 @@ export function resolveEdlOverlays(input: ResolveOverlaysInput): ResolvedOverlay
394
465
  return;
395
466
  }
396
467
  const times = overlay.item_at ?? (overlay.item_words === undefined ? undefined : said.map((word) => (word as { start: number }).start));
397
- placed.overlay.itemStarts = getListItemStarts({ start, end, count: placed.overlay.items.length, ...(times === undefined ? {} : { words: times }) });
468
+ // The first point comes in with the card, so the card never stands empty (RV-144 of an adopting app).
469
+ placed.overlay.itemStarts = getListItemStarts({ start, end, count: placed.overlay.items.length, ...(times === undefined ? {} : { words: times }) }).map((at, item) => (item === 0 ? start : at));
398
470
  }
399
471
  if (placed.overlay.kind === "punch_in") {
400
472
  if (edl.segments[segment]?.motion === "kenburns") {
401
473
  problems.push(`${at}: segment "${segmentId}" has a Ken Burns zoom, which owns the picture's scale; put the punch-in on a still segment`);
402
474
  return;
403
475
  }
476
+ if (edl.segments[segment]?.camera !== undefined) {
477
+ problems.push(`${at}: segment "${segmentId}" has a camera (a move or a framing), which owns the picture's scale; put the punch-in on a segment without one`);
478
+ return;
479
+ }
404
480
  const easeEnd = r3(segmentStart + (eases[segment] ?? 0) / FOOTAGE_FPS);
405
481
  if (start < easeEnd) {
406
482
  problems.push(`${at}: starts at ${start} s, inside the zoom cut's ease of segment "${segmentId}" (until ${easeEnd} s); start it later`);
@@ -537,12 +613,19 @@ function placeMark(overlay: EdlOverlay, drawn: Drawn, place: Placement): Placed
537
613
  function placeSideText(overlay: EdlOverlay & { kind: "keyword" | "lower_third" | "list" }, drawn: Drawn, place: Placement): Placed {
538
614
  const { zone, frame } = place;
539
615
  const scale = frame.width / 1080;
540
- const side = overlay.style?.side ?? (overlay.kind === "keyword" ? "right" : "left");
616
+ const align = overlay.kind === "keyword" ? overlay.style?.align : undefined;
617
+ // A keyword's align left or right is its side; center puts its card in the middle (`isCentred`).
618
+ const side = align === "left" || align === "right" ? align : (overlay.style?.side ?? (overlay.kind === "keyword" ? "right" : "left"));
541
619
  const fontSize = Math.round(OVERLAY_FONT_SIZES[overlay.kind][overlay.style?.size ?? "m"] * scale);
542
- const padY = getOverlayPadding({ fontSize, padScale: place.padScale }).y;
620
+ const pad = getOverlayPadding({ fontSize, padScale: place.padScale });
621
+ const margin = Math.round(OVERLAY_MARGIN * scale);
622
+ const room = frame.width - zone.left - zone.right - 2 * margin;
623
+ const chips = overlay.kind === "list" ? getListChipLayout({ items: overlay.items ?? [], layout: overlay.style?.list_layout ?? "stack", fontSize, padScale: place.padScale, room }) : null;
624
+ if (chips !== null && !chips.ok) return chips;
625
+ const row = chips?.row ?? null;
543
626
  const lines = overlay.kind === "list" ? (overlay.items ?? []).length : 1;
544
627
  const lineHeight = overlay.kind === "list" ? OVERLAY_LIST_LINE_HEIGHT : OVERLAY_LINE_HEIGHT;
545
- const height = Math.ceil(lines * fontSize * lineHeight + 2 * padY);
628
+ const height = row === null ? Math.ceil(lines * fontSize * lineHeight + 2 * pad.y) : row.height;
546
629
  const region = getTextRegion(place);
547
630
  // Without a position, each kind's own place: the lower third on the captions' room, the keyword in the middle, the list high.
548
631
  const position = overlay.style?.position ?? (overlay.kind === "lower_third" ? "bottom" : overlay.kind === "keyword" ? "middle" : null);
@@ -550,12 +633,62 @@ function placeSideText(overlay: EdlOverlay & { kind: "keyword" | "lower_third" |
550
633
  if (top < region.top || top + height > region.bottom) {
551
634
  return { ok: false, error: `the ${overlay.kind.replace("_", " ")} (${height} px tall) does not fit between the platform safe zone and the captions; use a smaller size or fewer points` };
552
635
  }
553
- const margin = Math.round(OVERLAY_MARGIN * scale);
554
- const box = { left: zone.left + margin, top, width: frame.width - zone.left - zone.right - 2 * margin, height };
555
- if (overlay.kind === "list") return { ok: true, overlay: { ...drawn, kind: "list", items: overlay.items ?? [], fontSize, side, box } };
636
+ const box = { left: zone.left + margin, top, width: room, height };
637
+ if (overlay.kind === "list") {
638
+ const layout = row === null ? (overlay.style?.side === undefined ? { isCentred: true } : {}) : { chips: placeChipRow(row, box) };
639
+ // A row of chips may be drawn smaller than the list's size, to fit one row.
640
+ return { ok: true, overlay: { ...drawn, kind: "list", items: overlay.items ?? [], fontSize: row?.fontSize ?? fontSize, side, box, ...layout } };
641
+ }
556
642
  const fields = { text: overlay.text ?? "", fontSize, side, box };
557
643
  if (overlay.kind === "lower_third") return { ok: true, overlay: { ...drawn, kind: "lower_third", ...fields } };
558
- return { ok: true, overlay: { ...drawn, kind: "keyword", ...fields, ...(overlay.style?.underline === true ? { underline: true } : {}) } };
644
+ return {
645
+ ok: true,
646
+ overlay: { ...drawn, kind: "keyword", ...fields, ...(overlay.style?.underline === true ? { underline: true } : {}), ...(align === "center" ? { isCentred: true } : {}) },
647
+ };
648
+ }
649
+
650
+ /** A list's chips before they are placed: their type size, each one's width, their common height, the row's width with its gaps. */
651
+ interface ChipRow {
652
+ fontSize: number;
653
+ widths: number[];
654
+ height: number;
655
+ gap: number;
656
+ width: number;
657
+ }
658
+
659
+ /** A row of chips at one type size. */
660
+ function measureChipRow(items: readonly string[], fontSize: number, padScale: number): ChipRow {
661
+ const pad = getOverlayPadding({ fontSize, padScale });
662
+ const widths = items.map((item) => Math.ceil(estimateTextWidth(item, fontSize) + 2 * pad.x));
663
+ const gap = Math.round(fontSize * LIST_CHIP_GAP_EM);
664
+ const width = widths.reduce((sum, chip) => sum + chip, 0) + gap * Math.max(0, widths.length - 1);
665
+ return { fontSize, widths, height: Math.ceil(fontSize * OVERLAY_LINE_HEIGHT + 2 * pad.y), gap, width };
666
+ }
667
+
668
+ /**
669
+ * Whether a list draws as chips and their row (null: the stack), or why it cannot. A row wider than `room` is tried
670
+ * smaller, as a title is (by `OVERLAY_TITLE_SHRINK`, at most `MAX_TITLE_SHRINKS` times); one that never fits is refused
671
+ * on `chips`, and `auto` falls back to the stack at the list's own size. `stack` never draws chips.
672
+ */
673
+ function getListChipLayout(input: { items: readonly string[]; layout: OverlayListLayout; fontSize: number; padScale: number; room: number }): { ok: true; row: ChipRow | null } | { ok: false; error: string } {
674
+ const { items, layout, room } = input;
675
+ if (layout === "stack") return { ok: true, row: null };
676
+ const own = measureChipRow(items, input.fontSize, input.padScale);
677
+ for (let shrink = 0, row = own; shrink <= MAX_TITLE_SHRINKS; shrink++, row = measureChipRow(items, Math.round(row.fontSize * OVERLAY_TITLE_SHRINK), input.padScale)) {
678
+ if (row.width <= room) return { ok: true, row };
679
+ }
680
+ if (layout === "auto") return { ok: true, row: null };
681
+ return { ok: false, error: `the list's points as chips (${own.width} px) do not fit one row (${room} px) even at a smaller size; use list_layout stack or auto, or shorter points` };
682
+ }
683
+
684
+ /** The chips of a row in their final places: centred in `box`, left to right in the points' order. */
685
+ function placeChipRow(row: ChipRow, box: OverlayBox): OverlayBox[] {
686
+ let left = box.left + Math.round((box.width - row.width) / 2);
687
+ return row.widths.map((width) => {
688
+ const chip = { left, top: box.top, width, height: row.height };
689
+ left += width + row.gap;
690
+ return chip;
691
+ });
559
692
  }
560
693
 
561
694
  type CardKind = "hook_title" | "search_bar" | "place_card" | "counter" | "date_stamp";
@@ -679,7 +812,8 @@ function measureTitle(overlay: EdlOverlay & { kind: "hook_title" | "place_card"
679
812
  // The hook title's place label carries a pin about one label line wide before it.
680
813
  const secondWidth = second === null ? 0 : estimateTextWidth(second, secondSize) + (isHook ? Math.round(secondSize * 1.1) : 0);
681
814
  if (secondWidth > room) return tooWide(metrics, isHook ? "place label" : "subtitle");
682
- const align = overlay.style?.align ?? "center";
815
+ // A title's align is center or left (the schema refuses right on it).
816
+ const align: OverlayAlign = overlay.style?.align === "left" ? "left" : "center";
683
817
  const pin = !isHook && overlay.style?.pin !== undefined && overlay.style.pin !== "none" ? overlay.style.pin : undefined;
684
818
  const delay = !isHook && second !== null && overlay.style?.subtitle_delay !== undefined && overlay.style.subtitle_delay > 0 ? overlay.style.subtitle_delay : undefined;
685
819
  return {
@@ -1,4 +1,5 @@
1
- import { getSegmentScales } from "./compose.js";
1
+ import { CAMERA_ORIGIN, getCameraOrigin, type CameraAnchor } from "./camera.js";
2
+ import { getSegmentFadeFrames, getSegmentScales } from "./compose.js";
2
3
  import { getEdlDuration, getSegmentStarts, type Edl } from "./edl.js";
3
4
  import { getFootageEdit, type FootageFilm } from "./film.js";
4
5
  import { FOOTAGE_FPS, getThreadArgs, type Frame, type NormalizeEncoder } from "./normalize.js";
@@ -15,14 +16,13 @@ import { FOOTAGE_FPS, getThreadArgs, type Frame, type NormalizeEncoder } from ".
15
16
  * the composition's video.
16
17
  */
17
18
 
18
- /** The point a zoom keeps still, as the composition's `transform-origin: 50% 42%`. */
19
- const ZOOM_ORIGIN = { x: 0.5, y: 0.42 } as const;
20
19
  /** How far a segment marked `kenburns` zooms when the film's `kenBurnsPercent` is 0, as in the composition. */
21
20
  const HAND_KEN_BURNS_PERCENT = 4;
22
21
  const PICTURE_CRF = 18;
23
22
  const DEFAULT_PICTURE_PRESET = "veryfast";
24
23
 
25
24
  const r3 = (value: number): number => Math.round(value * 1000) / 1000 || 0;
25
+ const r4 = (value: number): number => Math.round(value * 10000) / 10000 || 0;
26
26
 
27
27
  /** The outgoing segment's tail under a cross-fade. */
28
28
  export interface PictureFadeTail {
@@ -32,6 +32,8 @@ export interface PictureFadeTail {
32
32
  frames: number;
33
33
  /** The zoom the outgoing segment ends on, held through the fade. */
34
34
  scale: number;
35
+ /** The point that zoom keeps still: the outgoing segment's camera anchor; absent: the composition's origin. */
36
+ origin?: CameraAnchor;
35
37
  }
36
38
 
37
39
  /** One segment's piece of the picture. */
@@ -64,13 +66,17 @@ export function planFootagePicture(film: Pick<FootageFilm, "edit">, edl: Edl): P
64
66
  const nextStart = starts[index + 1];
65
67
  const frames = Math.max(1, (nextStart === undefined ? lastFrame : toFrame(nextStart)) - frame);
66
68
  const previous = edl.segments[index - 1];
67
- const fadeFrames = segment.transition === "fade" ? Math.min(frames, edit.fadeFrames) : 0;
69
+ const fadeFrames = Math.min(frames, getSegmentFadeFrames(edl, index, edit));
68
70
  let fade: PictureFadeTail | null = null;
69
71
  if (previous !== undefined && fadeFrames > 0) {
70
72
  const previousScale = scales[index - 1] as number;
71
- // The outgoing segment's Ken Burns tween ends at its end; its tail holds the zoom it reached.
72
- const scale = previous.motion === "kenburns" ? Math.round(previousScale * kenBurnsScale * 10000) / 10000 : previousScale;
73
- fade = { clip: previous.clip, start: r3(previous.end), frames: fadeFrames, scale };
73
+ // The outgoing segment's Ken Burns tween or camera move ends by its end; its tail holds the zoom it reached.
74
+ const reached = previous.camera !== undefined ? previous.camera.to : previous.motion === "kenburns" ? r4(previousScale * kenBurnsScale) : previousScale;
75
+ // The composition zooms the whole picture to the incoming camera's start during the fade, so a camera's tail is
76
+ // baked at what is left of its zoom (never below the full frame: a fade into a tighter camera is a hard cut's job).
77
+ const isCamera = previous.camera !== undefined || segment.camera !== undefined;
78
+ const scale = isCamera ? r4(Math.max(1, reached / (scales[index] as number))) : reached;
79
+ fade = { clip: previous.clip, start: r3(previous.end), frames: fadeFrames, scale, origin: getCameraOrigin(previous.camera) };
74
80
  }
75
81
  return { clip: segment.clip, start: r3(segment.start), frame, frames, fade };
76
82
  });
@@ -102,12 +108,12 @@ function fitStream(frames: number): string[] {
102
108
  }
103
109
 
104
110
  /**
105
- * A crop to `scale` about the zoom origin and back to the clip's `frame`; nothing at scale 1. The crop rounds, so
111
+ * A crop to `scale` about `origin` and back to the clip's `frame`; nothing at scale 1. The crop rounds, so
106
112
  * scaling it by the factor could come back a pixel or two short of the incoming clip, which `xfade` refuses (#1057).
107
113
  */
108
- function zoomFilters(scale: number, frame: Frame): string[] {
114
+ function zoomFilters(scale: number, frame: Frame, origin: CameraAnchor): string[] {
109
115
  if (scale === 1) return [];
110
- return [`crop=iw/${scale}:ih/${scale}:(iw-iw/${scale})*${ZOOM_ORIGIN.x}:(ih-ih/${scale})*${ZOOM_ORIGIN.y}`, `scale=${frame.width}:${frame.height}`];
116
+ return [`crop=iw/${scale}:ih/${scale}:(iw-iw/${scale})*${origin.x}:(ih-ih/${scale})*${origin.y}`, `scale=${frame.width}:${frame.height}`];
111
117
  }
112
118
 
113
119
  export interface PicturePieceArgsInput {
@@ -136,7 +142,7 @@ export function buildPicturePieceArgs(input: PicturePieceArgsInput): string[] {
136
142
  if (piece.fade !== null) {
137
143
  const { fade } = piece;
138
144
  inputs.push(...threads.output, "-ss", String(fade.start), "-t", seconds(fade.frames), "-i", getClip(fade.clip));
139
- const tail = [...zoomFilters(fade.scale, input.frame), ...fitStream(fade.frames)];
145
+ const tail = [...zoomFilters(fade.scale, input.frame, fade.origin ?? CAMERA_ORIGIN), ...fitStream(fade.frames)];
140
146
  graph = [
141
147
  `[0:v]${fitStream(piece.frames).join(",")}[incoming]`,
142
148
  `[1:v]${tail.join(",")}[outgoing]`,
package/src/index.ts CHANGED
@@ -94,11 +94,13 @@ export {
94
94
  MIN_OVERLAY_TYPING_SPEED,
95
95
  OVERLAY_ALIGNED_KINDS,
96
96
  OVERLAY_ALIGNS,
97
+ OVERLAY_KEYWORD_ALIGNS,
97
98
  OVERLAY_EASINGS,
98
99
  OVERLAY_ENTRANCES,
99
100
  OVERLAY_ENTRANCES_BY_KIND,
100
101
  OVERLAY_EXITS,
101
102
  OVERLAY_PINS,
103
+ OVERLAY_LIST_LAYOUTS,
102
104
  MAX_OVERLAY_SUBTITLE_DELAY,
103
105
  OVERLAY_KINDS,
104
106
  OVERLAY_POSITIONS,
@@ -113,10 +115,12 @@ export {
113
115
  type EdlOverlayStyle,
114
116
  type EdlOverlayWord,
115
117
  type OverlayAlign,
118
+ type OverlayKeywordAlign,
116
119
  type OverlayEasing,
117
120
  type OverlayEntrance,
118
121
  type OverlayExit,
119
122
  type OverlayKind,
123
+ type OverlayListLayout,
120
124
  type OverlayPin,
121
125
  type OverlayPosition,
122
126
  type OverlaySide,
@@ -154,7 +158,10 @@ export {
154
158
  PUNCH_IN_SCALES,
155
159
  findShotBreak,
156
160
  formatOverlayNumber,
161
+ LIST_CHIP_GAP_EM,
157
162
  getDrawnOverlayCard,
163
+ getListCardsByItem,
164
+ getListItemTimes,
158
165
  getOverlayBounds,
159
166
  getOverlayPadding,
160
167
  getPlaceCardPinRow,
@@ -530,7 +537,28 @@ export {
530
537
  type EdlClip,
531
538
  type EdlSegment,
532
539
  type SegmentMotion,
540
+ MAX_FADE_FRAMES,
541
+ MIN_FADE_FRAMES,
533
542
  } from "./footage/edl.js";
543
+ export {
544
+ CAMERA_EASES,
545
+ CAMERA_ORIGIN,
546
+ MAX_CAMERA_SCALE,
547
+ cameraSchema,
548
+ describeCamera,
549
+ getCameraGsapEase,
550
+ getCameraMoveFrames,
551
+ getCameraMoveSeconds,
552
+ getCameraOrigin,
553
+ getCameraScaleAt,
554
+ getCameraScaleExpression,
555
+ isCameraMoving,
556
+ isSameCamera,
557
+ toTransformOrigin,
558
+ type CameraAnchor,
559
+ type CameraEase,
560
+ type EdlCamera,
561
+ } from "./footage/camera.js";
534
562
  export { findRetakes, splitFilmSentences, splitSentences, type RetakeKind, type RetakeSuggestion, type Sentence } from "./footage/sentences.js";
535
563
  export {
536
564
  CAPTION_SAFE_ZONES,
@@ -573,6 +601,7 @@ export {
573
601
  getFootageFilmSeconds,
574
602
  getFootageSfxCues,
575
603
  getLogoCardBox,
604
+ getSegmentFadeFrames,
576
605
  getSegmentScales,
577
606
  type FootageComposeAssets,
578
607
  type FootageComposeInput,