@softure-ai/marketing-kit 0.33.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 +23 -0
  2. package/README.md +13 -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 +6 -5
  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 +23 -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 +4 -1
  24. package/dist/footage/overlay-html.js.map +1 -1
  25. package/dist/footage/overlay-schema.d.ts +9 -2
  26. package/dist/footage/overlay-schema.d.ts.map +1 -1
  27. package/dist/footage/overlay-schema.js +16 -3
  28. package/dist/footage/overlay-schema.js.map +1 -1
  29. package/dist/footage/overlays.d.ts +2 -0
  30. package/dist/footage/overlays.d.ts.map +1 -1
  31. package/dist/footage/overlays.js +18 -5
  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 +4 -3
  38. package/dist/index.d.ts.map +1 -1
  39. package/dist/index.js +4 -3
  40. package/dist/index.js.map +1 -1
  41. package/package.json +1 -1
  42. package/schema/edl.schema.json +70 -2
  43. package/src/footage/camera.ts +129 -0
  44. package/src/footage/compose.ts +30 -10
  45. package/src/footage/draft-overlays.ts +6 -5
  46. package/src/footage/draft.ts +29 -29
  47. package/src/footage/edl.ts +24 -0
  48. package/src/footage/overlay-html.ts +4 -1
  49. package/src/footage/overlay-schema.ts +22 -4
  50. package/src/footage/overlays.ts +27 -6
  51. package/src/footage/picture.ts +17 -11
  52. package/src/index.ts +24 -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
 
@@ -151,8 +156,11 @@ export interface EdlOverlayStyle {
151
156
  colors?: EdlOverlayColors;
152
157
  /** Its card's corner in place of the brand style's (`BrandStyle.cornerRadius`); not on a punch_in, arrow or highlight. */
153
158
  corner_radius?: CornerRadius;
154
- /** How a hook title's or a place card's lines sit in the card (`center` without it). */
155
- 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;
156
164
  /** A place card's subtitle size: `s`, `m` (about 55 % of the title, the default) or `l`. */
157
165
  subtitle_size?: OverlaySize;
158
166
  /** How it leaves (`auto` without it: mirrors the entrance). */
@@ -333,7 +341,12 @@ function checkOverlayStyle(overlay: EdlOverlay, issue: (path: string[], message:
333
341
  }
334
342
  if (style.typing_speed !== undefined && !isTypedOverlay(overlay)) issue(["style", "typing_speed"], "only a typed entrance or a search bar has a typing speed");
335
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`);
336
- 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
+ }
337
350
  if (style.subtitle_size !== undefined && kind !== "place_card") issue(["style", "subtitle_size"], "only a place_card has a subtitle; leave subtitle_size out");
338
351
  if (style.subtitle_delay !== undefined && kind !== "place_card") issue(["style", "subtitle_delay"], "only a place_card has a subtitle; leave subtitle_delay out");
339
352
  if (style.pin !== undefined && kind !== "place_card") issue(["style", "pin"], "only a place_card draws a pin; leave pin out");
@@ -451,7 +464,12 @@ export const overlaySchema = z
451
464
  .enum(CORNER_RADII)
452
465
  .optional()
453
466
  .describe("The card's corner: none, s, m, l or pill; the brand style's without it (no punch_in, arrow or highlight)."),
454
- 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
+ ),
455
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."),
456
474
  stagger: z.boolean().optional().describe("A list only: its points come in one by one (on item_words when given, else spaced automatically)."),
457
475
  list_layout: z
@@ -19,6 +19,7 @@ import {
19
19
  type OverlaySide,
20
20
  type OverlaySize,
21
21
  } from "./overlay-schema.js";
22
+ import { isCameraMoving, isSameCamera } from "./camera.js";
22
23
  import { getSegmentZoomEases } from "./compose.js";
23
24
  import { normalizeWord } from "./words.js";
24
25
  import { getListItemStarts } from "./overlay-motion.js";
@@ -147,7 +148,16 @@ type Drawn = OverlayBase & OverlayLook;
147
148
  */
148
149
  export type ResolvedOverlay =
149
150
  | (OverlayBase & { kind: "punch_in"; scale: number; ease: number })
150
- | (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
+ })
151
161
  | (Drawn & { kind: "lower_third"; text: string; fontSize: number; side: OverlaySide; box: OverlayBox })
152
162
  | (Drawn & {
153
163
  kind: "list";
@@ -321,13 +331,13 @@ export function getDrawnOverlayCard(overlay: ResolvedOverlay): OverlayBox | null
321
331
  return getSideTextCard(overlay, getSideTextLines(overlay), overlay.box.height);
322
332
  }
323
333
 
324
- /** 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. */
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). */
325
335
  function getSideTextCard(overlay: SideTextOverlay, lines: readonly string[], height: number): OverlayBox {
326
336
  const { box, fontSize, side } = overlay;
327
337
  const padX = getOverlayPadding(overlay).x;
328
338
  const textWidth = Math.max(0, ...lines.map((line) => estimateTextWidth(line, fontSize)));
329
339
  const width = Math.min(box.width, Math.ceil(textWidth + 2 * padX));
330
- const isCentred = overlay.kind === "list" && overlay.isCentred === true;
340
+ const isCentred = (overlay.kind === "list" || overlay.kind === "keyword") && overlay.isCentred === true;
331
341
  const left = isCentred ? box.left + Math.round((box.width - width) / 2) : side === "right" ? box.left + box.width - width : box.left;
332
342
  return { left, top: box.top, width, height };
333
343
  }
@@ -378,6 +388,7 @@ export function findShotBreak(edl: Pick<Edl, "segments">, index: number): string
378
388
  if (segment.clip !== previous.clip) return `segment "${segment.id}" plays another clip`;
379
389
  if (segment.transition !== "cut") return `segment "${segment.id}" starts on a ${segment.transition}, not a plain cut`;
380
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}"`;
381
392
  if (segment.caption?.bottom !== previous.caption?.bottom || segment.caption?.top !== previous.caption?.top) return `segment "${segment.id}" moves the captions`;
382
393
  return null;
383
394
  }
@@ -462,6 +473,10 @@ export function resolveEdlOverlays(input: ResolveOverlaysInput): ResolvedOverlay
462
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`);
463
474
  return;
464
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
+ }
465
480
  const easeEnd = r3(segmentStart + (eases[segment] ?? 0) / FOOTAGE_FPS);
466
481
  if (start < easeEnd) {
467
482
  problems.push(`${at}: starts at ${start} s, inside the zoom cut's ease of segment "${segmentId}" (until ${easeEnd} s); start it later`);
@@ -598,7 +613,9 @@ function placeMark(overlay: EdlOverlay, drawn: Drawn, place: Placement): Placed
598
613
  function placeSideText(overlay: EdlOverlay & { kind: "keyword" | "lower_third" | "list" }, drawn: Drawn, place: Placement): Placed {
599
614
  const { zone, frame } = place;
600
615
  const scale = frame.width / 1080;
601
- 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"));
602
619
  const fontSize = Math.round(OVERLAY_FONT_SIZES[overlay.kind][overlay.style?.size ?? "m"] * scale);
603
620
  const pad = getOverlayPadding({ fontSize, padScale: place.padScale });
604
621
  const margin = Math.round(OVERLAY_MARGIN * scale);
@@ -624,7 +641,10 @@ function placeSideText(overlay: EdlOverlay & { kind: "keyword" | "lower_third" |
624
641
  }
625
642
  const fields = { text: overlay.text ?? "", fontSize, side, box };
626
643
  if (overlay.kind === "lower_third") return { ok: true, overlay: { ...drawn, kind: "lower_third", ...fields } };
627
- 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
+ };
628
648
  }
629
649
 
630
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. */
@@ -792,7 +812,8 @@ function measureTitle(overlay: EdlOverlay & { kind: "hook_title" | "place_card"
792
812
  // The hook title's place label carries a pin about one label line wide before it.
793
813
  const secondWidth = second === null ? 0 : estimateTextWidth(second, secondSize) + (isHook ? Math.round(secondSize * 1.1) : 0);
794
814
  if (secondWidth > room) return tooWide(metrics, isHook ? "place label" : "subtitle");
795
- 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";
796
817
  const pin = !isHook && overlay.style?.pin !== undefined && overlay.style.pin !== "none" ? overlay.style.pin : undefined;
797
818
  const delay = !isHook && second !== null && overlay.style?.subtitle_delay !== undefined && overlay.style.subtitle_delay > 0 ? overlay.style.subtitle_delay : undefined;
798
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,6 +94,7 @@ 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,
@@ -114,6 +115,7 @@ export {
114
115
  type EdlOverlayStyle,
115
116
  type EdlOverlayWord,
116
117
  type OverlayAlign,
118
+ type OverlayKeywordAlign,
117
119
  type OverlayEasing,
118
120
  type OverlayEntrance,
119
121
  type OverlayExit,
@@ -535,7 +537,28 @@ export {
535
537
  type EdlClip,
536
538
  type EdlSegment,
537
539
  type SegmentMotion,
540
+ MAX_FADE_FRAMES,
541
+ MIN_FADE_FRAMES,
538
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";
539
562
  export { findRetakes, splitFilmSentences, splitSentences, type RetakeKind, type RetakeSuggestion, type Sentence } from "./footage/sentences.js";
540
563
  export {
541
564
  CAPTION_SAFE_ZONES,
@@ -578,6 +601,7 @@ export {
578
601
  getFootageFilmSeconds,
579
602
  getFootageSfxCues,
580
603
  getLogoCardBox,
604
+ getSegmentFadeFrames,
581
605
  getSegmentScales,
582
606
  type FootageComposeAssets,
583
607
  type FootageComposeInput,