@softure-ai/marketing-kit 0.36.2 → 0.38.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.
@@ -89,6 +89,10 @@ export const OVERLAY_LINE_HEIGHT = 1.15;
89
89
  export const OVERLAY_LIST_LINE_HEIGHT = 1.4;
90
90
  /** The room between two chips of a list's row, in font sizes. */
91
91
  export const LIST_CHIP_GAP_EM = 0.3;
92
+ /** A chip's step badge before its point (a round accent mark with its number, a tick once the next point is in), in font sizes. */
93
+ export const LIST_CHIP_BADGE_EM = { size: 1.1, gap: 0.35 } as const;
94
+ /** How opaque a chip's point stays once the next point is in: it steps back, the newest point leads. */
95
+ export const LIST_CHIP_COVERED_OPACITY = 0.55;
92
96
  /** A place card title's line height, tighter for its big type. */
93
97
  export const OVERLAY_TITLE_LINE_HEIGHT = 1.05;
94
98
  export const OVERLAY_PADDING_EM = { x: 0.6, y: 0.35 } as const;
@@ -235,7 +239,8 @@ export type ResolvedOverlay =
235
239
  /** Its lines as drawn (a strip's in capitals). */
236
240
  lines: string[];
237
241
  fontSize: number;
238
- side: OverlaySide;
242
+ /** Its side, or `center` on the frame's axis (the default). */
243
+ side: OverlaySide | "center";
239
244
  /** Its paper, unturned; it is drawn turned by `tilt` degrees about its middle. */
240
245
  box: OverlayBox;
241
246
  tilt: number;
@@ -537,7 +542,9 @@ export function resolveEdlOverlays(input: ResolveOverlaysInput): ResolvedOverlay
537
542
  problems.push(`${at}: ${placed.error}`);
538
543
  return;
539
544
  }
540
- if (placed.overlay.kind === "list" && (overlay.style?.stagger === true || overlay.item_words !== undefined || overlay.item_at !== undefined)) {
545
+ // Chips always come in one by one, as a countdown of the points (RV-181 of an adopting app); a stack only when asked.
546
+ const isStaggered = overlay.style?.stagger === true || overlay.item_words !== undefined || overlay.item_at !== undefined;
547
+ if (placed.overlay.kind === "list" && (isStaggered || placed.overlay.chips !== undefined)) {
541
548
  const said = (overlay.item_words ?? []).map((word, item) => findWordStart(word, input.words, `item_words[${item}]`));
542
549
  const missing = said.flatMap((word) => (word.ok ? [] : [word.error]));
543
550
  if (missing.length > 0) {
@@ -644,6 +651,37 @@ function isInsideZone(place: Placement, point: OverlayPoint): boolean {
644
651
  return point.x >= zone.left && point.x <= frame.width - zone.right && point.y >= zone.top && point.y <= frame.height - zone.bottom;
645
652
  }
646
653
 
654
+ /**
655
+ * The left edge of a box `width` wide centred on the frame's vertical axis, as the captions are: the platform safe
656
+ * zone's sides differ (60 px on the left, up to 150 px on the right), so the middle of the zone sits left of the
657
+ * frame's middle (RV-180 of an adopting app). A box no wider than `getCentredSpan` is exactly centred; a wider one
658
+ * (a note, whose room is a share of the whole zone) is pushed inwards only as far as the zone needs.
659
+ */
660
+ export function getCentredLeft(place: Pick<Placement, "zone" | "frame">, width: number, margin: number): number {
661
+ const { zone, frame } = place;
662
+ const lowest = zone.left + margin;
663
+ const highest = frame.width - zone.right - margin - width;
664
+ return Math.round(Math.max(lowest, Math.min(highest, (frame.width - width) / 2)));
665
+ }
666
+
667
+ /** The widest box centred on the frame's axis that stays inside the safe zone: the wider side taken on both edges. */
668
+ function getCentredSpan(place: Pick<Placement, "zone" | "frame">, margin: number): { left: number; width: number } {
669
+ const side = Math.max(place.zone.left, place.zone.right) + margin;
670
+ return { left: side, width: place.frame.width - 2 * side };
671
+ }
672
+
673
+ /**
674
+ * A centred overlay measured so it can sit on the frame's axis: in the whole zone's width as before when it is no
675
+ * wider than the centred span, else again in the centred span (smaller or on more lines), and only when it cannot fit
676
+ * there either in the whole zone, as close to the axis as the zone allows. What fitted before still fits.
677
+ */
678
+ function measureCentred<T extends { ok: true } | { ok: false; error: string }>(input: { whole: number; centred: number; measure: (room: number) => T; getWidth: (result: T & { ok: true }) => number }): T {
679
+ const wide = input.measure(input.whole);
680
+ if (!wide.ok || input.getWidth(wide as T & { ok: true }) <= input.centred) return wide;
681
+ const narrow = input.measure(input.centred);
682
+ return narrow.ok ? narrow : wide;
683
+ }
684
+
647
685
  /** The top of a box `height` tall at a named position of the text region. */
648
686
  function getPositionTop(region: { top: number; bottom: number }, position: OverlayPosition, height: number): number {
649
687
  if (position === "top") return region.top;
@@ -746,9 +784,10 @@ function placeNote(overlay: EdlOverlay, drawn: Drawn, place: Placement): Placed
746
784
  if (top < region.top || top + height > region.bottom) {
747
785
  return { ok: false, error: `the note (${height} px tall) does not fit between the platform safe zone and the captions; use a smaller size or shorter text` };
748
786
  }
749
- const side = overlay.style?.side ?? "left";
750
- const left = side === "right" ? frame.width - zone.right - margin - width : zone.left + margin;
751
- const tilt = (side === "right" ? -1 : 1) * NOTE_TILT[noteStyle];
787
+ // Without a side the note sits on the frame's axis, leaning half as much (RV-182 of an adopting app).
788
+ const side = overlay.style?.side ?? "center";
789
+ const left = side === "center" ? getCentredLeft(place, width, margin) : side === "right" ? frame.width - zone.right - margin - width : zone.left + margin;
790
+ const tilt = side === "center" ? NOTE_TILT[noteStyle] / 2 : (side === "right" ? -1 : 1) * NOTE_TILT[noteStyle];
752
791
  return {
753
792
  ok: true,
754
793
  overlay: { ...drawn, kind: "note", noteStyle, lines, fontSize, side, box: { left, top, width, height }, tilt, tear: getTornEdge(text), wordTimes: null, tick: isTick, tickAt: null },
@@ -799,18 +838,28 @@ function placeEndWord(overlay: EdlOverlay, drawn: Drawn, place: Placement): Plac
799
838
  const { zone, frame } = place;
800
839
  const scale = frame.width / 1080;
801
840
  const margin = Math.round(OVERLAY_MARGIN * scale);
802
- const room = frame.width - zone.left - zone.right - 2 * margin;
803
841
  const text = (overlay.text ?? "").replace(/\s+/g, " ").trim();
804
- let fontSize = Math.round(OVERLAY_FONT_SIZES.end_word[overlay.style?.size ?? "m"] * scale);
805
- for (let shrink = 0; measureHandText(text, fontSize) > room; shrink++) {
806
- if (shrink === MAX_TITLE_SHRINKS) return { ok: false, error: "the end word is too wide for one line even at a smaller size; shorten it or use a smaller size" };
807
- fontSize = Math.round(fontSize * OVERLAY_TITLE_SHRINK);
808
- }
842
+ const own = Math.round(OVERLAY_FONT_SIZES.end_word[overlay.style?.size ?? "m"] * scale);
843
+ const fitted = measureCentred({
844
+ whole: frame.width - zone.left - zone.right - 2 * margin,
845
+ centred: getCentredSpan(place, margin).width,
846
+ measure: (room: number): { ok: true; fontSize: number } | { ok: false; error: string } => {
847
+ let fontSize = own;
848
+ for (let shrink = 0; measureHandText(text, fontSize) > room; shrink++) {
849
+ if (shrink === MAX_TITLE_SHRINKS) return { ok: false, error: "the end word is too wide for one line even at a smaller size; shorten it or use a smaller size" };
850
+ fontSize = Math.round(fontSize * OVERLAY_TITLE_SHRINK);
851
+ }
852
+ return { ok: true, fontSize };
853
+ },
854
+ getWidth: (result) => measureHandText(text, result.fontSize),
855
+ });
856
+ if (!fitted.ok) return fitted;
857
+ const { fontSize } = fitted;
809
858
  const width = measureHandText(text, fontSize);
810
859
  const height = Math.ceil(fontSize * OVERLAY_LINE_HEIGHT);
811
860
  const region = getTextRegion(place);
812
861
  if (region.top + height > region.bottom) return { ok: false, error: `the end word (${height} px tall) does not fit above the captions; use a smaller size` };
813
- const left = Math.round(zone.left + margin + (room - width) / 2);
862
+ const left = getCentredLeft(place, width, margin);
814
863
  return { ok: true, overlay: { ...drawn, kind: "end_word", text, fontSize, box: { left, top: region.top, width, height } } };
815
864
  }
816
865
 
@@ -851,7 +900,12 @@ function placeSideText(overlay: EdlOverlay & { kind: "keyword" | "lower_third" |
851
900
  const pad = getOverlayPadding({ fontSize, padScale: place.padScale });
852
901
  const margin = Math.round(OVERLAY_MARGIN * scale);
853
902
  const room = frame.width - zone.left - zone.right - 2 * margin;
854
- const chips = overlay.kind === "list" ? getListChipLayout({ items: overlay.items ?? [], layout: overlay.style?.list_layout ?? "stack", fontSize, padScale: place.padScale, room }) : null;
903
+ const chips = overlay.kind === "list" ? measureCentred({
904
+ whole: room,
905
+ centred: getCentredSpan(place, margin).width,
906
+ measure: (width: number) => getListChipLayout({ items: overlay.items ?? [], layout: overlay.style?.list_layout ?? "stack", fontSize, padScale: place.padScale, room: width }),
907
+ getWidth: (result) => result.row?.width ?? 0,
908
+ }) : null;
855
909
  if (chips !== null && !chips.ok) return chips;
856
910
  const row = chips?.row ?? null;
857
911
  const lines = overlay.kind === "list" ? (overlay.items ?? []).length : 1;
@@ -865,12 +919,15 @@ function placeSideText(overlay: EdlOverlay & { kind: "keyword" | "lower_third" |
865
919
  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` };
866
920
  }
867
921
  const box = { left: zone.left + margin, top, width: room, height };
922
+ // A centred card (a stack without a side, a keyword aligned center) sits in a box centred on the frame's axis.
923
+ const centred = { ...box, ...getCentredSpan(place, margin) };
868
924
  if (overlay.kind === "list") {
869
- const layout = row === null ? (overlay.style?.side === undefined ? { isCentred: true } : {}) : { chips: placeChipRow(row, box) };
925
+ const isCentred = row === null && overlay.style?.side === undefined;
926
+ const layout = row !== null ? { chips: placeChipRow(row, { ...box, left: getCentredLeft(place, row.width, margin), width: row.width }) } : isCentred ? { isCentred: true } : {};
870
927
  // A row of chips may be drawn smaller than the list's size, to fit one row.
871
- return { ok: true, overlay: { ...drawn, kind: "list", items: overlay.items ?? [], fontSize: row?.fontSize ?? fontSize, side, box, ...layout } };
928
+ return { ok: true, overlay: { ...drawn, kind: "list", items: overlay.items ?? [], fontSize: row?.fontSize ?? fontSize, side, box: isCentred ? centred : box, ...layout } };
872
929
  }
873
- const fields = { text: overlay.text ?? "", fontSize, side, box };
930
+ const fields = { text: overlay.text ?? "", fontSize, side, box: align === "center" ? centred : box };
874
931
  if (overlay.kind === "lower_third") return { ok: true, overlay: { ...drawn, kind: "lower_third", ...fields } };
875
932
  return {
876
933
  ok: true,
@@ -897,7 +954,9 @@ interface ChipRow {
897
954
  /** A row of chips at one type size. */
898
955
  function measureChipRow(items: readonly string[], fontSize: number, padScale: number): ChipRow {
899
956
  const pad = getOverlayPadding({ fontSize, padScale });
900
- const widths = items.map((item) => Math.ceil(estimateTextWidth(item, fontSize) + 2 * pad.x));
957
+ const badge = getChipBadgeSize(fontSize);
958
+ // The badge sits as far from the chip's left edge as from its top, so the left takes the vertical padding.
959
+ const widths = items.map((item) => Math.ceil(estimateTextWidth(item, fontSize) + pad.y + pad.x + badge.size + badge.gap));
901
960
  const gap = Math.round(fontSize * LIST_CHIP_GAP_EM);
902
961
  const width = widths.reduce((sum, chip) => sum + chip, 0) + gap * Math.max(0, widths.length - 1);
903
962
  return { fontSize, widths, height: Math.ceil(fontSize * OVERLAY_LINE_HEIGHT + 2 * pad.y), gap, width };
@@ -919,6 +978,46 @@ function getListChipLayout(input: { items: readonly string[]; layout: OverlayLis
919
978
  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` };
920
979
  }
921
980
 
981
+ /** A chip's step badge: its diameter and the room after it, in px. */
982
+ export function getChipBadgeSize(fontSize: number): { size: number; gap: number } {
983
+ return { size: Math.round(fontSize * LIST_CHIP_BADGE_EM.size), gap: Math.round(fontSize * LIST_CHIP_BADGE_EM.gap) };
984
+ }
985
+
986
+ /**
987
+ * A chip's parts (RV-181 of an adopting app): its step badge, a round mark on the chip's left, and the centre its point
988
+ * is written about, in the room after the badge.
989
+ */
990
+ export function getChipParts(chip: OverlayBox, overlay: { fontSize: number; padScale?: number }): { badge: { centre: OverlayPoint; radius: number }; textX: number } {
991
+ const pad = getOverlayPadding(overlay);
992
+ const badge = getChipBadgeSize(overlay.fontSize);
993
+ const radius = badge.size / 2;
994
+ const textLeft = chip.left + pad.y + badge.size + badge.gap;
995
+ return { badge: { centre: { x: chip.left + pad.y + radius, y: chip.top + chip.height / 2 }, radius }, textX: r1(textLeft + (chip.left + chip.width - pad.x - textLeft) / 2) };
996
+ }
997
+
998
+ /** The three points of the tick that takes a covered chip's number's place, inside its badge. */
999
+ export function getChipTickPoints(badge: { centre: OverlayPoint; radius: number }): OverlayPoint[] {
1000
+ const { centre, radius } = badge;
1001
+ return [
1002
+ { x: r1(centre.x - 0.42 * radius), y: r1(centre.y + 0.02 * radius) },
1003
+ { x: r1(centre.x - 0.1 * radius), y: r1(centre.y + 0.32 * radius) },
1004
+ { x: r1(centre.x + 0.44 * radius), y: r1(centre.y - 0.3 * radius) },
1005
+ ];
1006
+ }
1007
+
1008
+ /**
1009
+ * When each chip of a row is covered: the second the next point comes in, after which the chip steps back (its point
1010
+ * fainter, its number a tick) and the newest point leads, as a countdown does; null for the last chip, and for one
1011
+ * whose next point comes in with it or after the list has gone.
1012
+ */
1013
+ export function getChipCoveredTimes(overlay: Extract<ResolvedOverlay, { kind: "list" }>): (number | null)[] {
1014
+ const times = getListItemTimes(overlay);
1015
+ return times.map((at, index) => {
1016
+ const next = times[index + 1];
1017
+ return next !== undefined && next > at && next < overlay.end ? next : null;
1018
+ });
1019
+ }
1020
+
922
1021
  /** The chips of a row in their final places: centred in `box`, left to right in the points' order. */
923
1022
  function placeChipRow(row: ChipRow, box: OverlayBox): OverlayBox[] {
924
1023
  let left = box.left + Math.round((box.width - row.width) / 2);
@@ -1118,15 +1217,21 @@ function placeCard(overlay: EdlOverlay & { kind: CardKind }, drawn: Drawn, place
1118
1217
  const outer = frame.width - zone.left - zone.right - 2 * margin;
1119
1218
  const fontSize = Math.round(OVERLAY_FONT_SIZES[overlay.kind][overlay.style?.size ?? "m"] * scale);
1120
1219
  const pad = getOverlayPadding({ fontSize, padScale: place.padScale });
1121
- const metrics = { fontSize, pad, room: outer - 2 * pad.x, label: overlay.kind.replace("_", " "), scale };
1122
- const measured =
1123
- overlay.kind === "hook_title" || overlay.kind === "place_card"
1220
+ const measure = (room: number): CardResult => {
1221
+ const metrics = { fontSize, pad, room: room - 2 * pad.x, label: overlay.kind.replace("_", " "), scale };
1222
+ return overlay.kind === "hook_title" || overlay.kind === "place_card"
1124
1223
  ? measureTitle({ ...overlay, kind: overlay.kind }, metrics)
1125
1224
  : overlay.kind === "search_bar"
1126
1225
  ? measureSearchBar(overlay, metrics)
1127
1226
  : overlay.kind === "counter"
1128
1227
  ? measureCounter(overlay, metrics)
1129
1228
  : measureDateStamp(overlay, metrics);
1229
+ };
1230
+ // A date stamp sits on its side of the whole zone; every other card on the frame's axis.
1231
+ const measured =
1232
+ overlay.kind === "date_stamp"
1233
+ ? measure(outer)
1234
+ : measureCentred({ whole: outer, centred: getCentredSpan(place, margin).width, measure, getWidth: (result) => Math.ceil(result.content.width + 2 * pad.x) });
1130
1235
  if (!measured.ok) return measured;
1131
1236
  const { content } = measured;
1132
1237
  const width = Math.ceil(content.width + 2 * pad.x);
@@ -1134,10 +1239,10 @@ function placeCard(overlay: EdlOverlay & { kind: CardKind }, drawn: Drawn, place
1134
1239
  const region = getTextRegion(place);
1135
1240
  const top = getPositionTop(region, overlay.style?.position ?? CARD_POSITIONS[overlay.kind], height);
1136
1241
  if (top < region.top || top + height > region.bottom) {
1137
- return { ok: false, error: `the ${metrics.label} (${height} px tall) does not fit between the platform safe zone and the captions; use a smaller size or shorter text` };
1242
+ 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 shorter text` };
1138
1243
  }
1139
1244
  const left =
1140
- overlay.kind !== "date_stamp" ? Math.round(zone.left + margin + (outer - width) / 2) : content.fields.side === "right" ? frame.width - zone.right - margin - width : zone.left + margin;
1245
+ overlay.kind !== "date_stamp" ? getCentredLeft(place, width, margin) : content.fields.side === "right" ? frame.width - zone.right - margin - width : zone.left + margin;
1141
1246
  return { ok: true, overlay: { ...drawn, ...content.fields, box: { left, top, width, height } } as ResolvedOverlay };
1142
1247
  }
1143
1248
 
package/src/index.ts CHANGED
@@ -169,6 +169,13 @@ export {
169
169
  findShotBreak,
170
170
  formatOverlayNumber,
171
171
  LIST_CHIP_GAP_EM,
172
+ LIST_CHIP_BADGE_EM,
173
+ LIST_CHIP_COVERED_OPACITY,
174
+ getCentredLeft,
175
+ getChipBadgeSize,
176
+ getChipCoveredTimes,
177
+ getChipParts,
178
+ getChipTickPoints,
172
179
  getDrawnOverlayCard,
173
180
  getListCardsByItem,
174
181
  getListItemTimes,
@@ -678,13 +685,25 @@ export {
678
685
  FOOTAGE_DRAFT_WIDTH,
679
686
  buildFootageDraftArgs,
680
687
  buildFootageDraftCaptions,
688
+ buildFootageDraftJoinArgs,
689
+ buildFootageDraftPieceArgs,
690
+ estimateFootageDraftMemory,
691
+ FOOTAGE_DRAFT_ASSEMBLIES,
692
+ FOOTAGE_DRAFT_PIECE_SEGMENTS,
681
693
  getFootageDraftFrame,
682
694
  planFootageDraft,
695
+ planFootageDraftPieces,
683
696
  renderFootageDraft,
684
697
  toAssColor,
698
+ type DraftPiece,
685
699
  type DraftSegmentPlan,
686
700
  type FootageDraft,
687
701
  type FootageDraftArgsInput,
702
+ type FootageDraftAssembly,
703
+ type FootageDraftJoinArgsInput,
704
+ type FootageDraftMemory,
705
+ type FootageDraftMemoryInput,
706
+ type FootageDraftPieceArgsInput,
688
707
  type FootageDraftCaptionColors,
689
708
  type FootageDraftCaptionsInput,
690
709
  type FootageDraftMusic,