@softure-ai/marketing-kit 0.22.0 → 0.24.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 (135) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +21 -1
  3. package/dist/cli/failure.d.ts.map +1 -1
  4. package/dist/cli/failure.js.map +1 -1
  5. package/dist/cli/films.js.map +1 -1
  6. package/dist/cli/main.js.map +1 -1
  7. package/dist/cli/options.d.ts.map +1 -1
  8. package/dist/compose/timeline.d.ts +22 -1
  9. package/dist/compose/timeline.d.ts.map +1 -1
  10. package/dist/compose/timeline.js +52 -14
  11. package/dist/compose/timeline.js.map +1 -1
  12. package/dist/config/actions-schema.d.ts +85 -85
  13. package/dist/config/actions-schema.d.ts.map +1 -1
  14. package/dist/config/colors.d.ts +24 -2
  15. package/dist/config/colors.d.ts.map +1 -1
  16. package/dist/config/config.d.ts.map +1 -1
  17. package/dist/config/config.js +3 -0
  18. package/dist/config/config.js.map +1 -1
  19. package/dist/config/placeholders.d.ts.map +1 -1
  20. package/dist/config/placeholders.js.map +1 -1
  21. package/dist/config/schema.d.ts +469 -466
  22. package/dist/config/schema.d.ts.map +1 -1
  23. package/dist/config/schema.js +15 -0
  24. package/dist/config/schema.js.map +1 -1
  25. package/dist/config/shot-steps.d.ts +96 -96
  26. package/dist/film.d.ts.map +1 -1
  27. package/dist/footage/audio.js.map +1 -1
  28. package/dist/footage/captions.d.ts +22 -6
  29. package/dist/footage/captions.d.ts.map +1 -1
  30. package/dist/footage/captions.js +24 -14
  31. package/dist/footage/captions.js.map +1 -1
  32. package/dist/footage/clip-sound.d.ts.map +1 -1
  33. package/dist/footage/clip-sound.js.map +1 -1
  34. package/dist/footage/compose.d.ts +2 -0
  35. package/dist/footage/compose.d.ts.map +1 -1
  36. package/dist/footage/compose.js +3 -2
  37. package/dist/footage/compose.js.map +1 -1
  38. package/dist/footage/cuts.d.ts.map +1 -1
  39. package/dist/footage/cuts.js.map +1 -1
  40. package/dist/footage/declick.d.ts.map +1 -1
  41. package/dist/footage/disk.js.map +1 -1
  42. package/dist/footage/draft-font.js.map +1 -1
  43. package/dist/footage/draft-overlays.d.ts +24 -4
  44. package/dist/footage/draft-overlays.d.ts.map +1 -1
  45. package/dist/footage/draft-overlays.js +232 -34
  46. package/dist/footage/draft-overlays.js.map +1 -1
  47. package/dist/footage/draft.d.ts +7 -2
  48. package/dist/footage/draft.d.ts.map +1 -1
  49. package/dist/footage/draft.js +13 -2
  50. package/dist/footage/draft.js.map +1 -1
  51. package/dist/footage/edl.d.ts +46 -19
  52. package/dist/footage/edl.d.ts.map +1 -1
  53. package/dist/footage/edl.js +1 -1
  54. package/dist/footage/edl.js.map +1 -1
  55. package/dist/footage/elevenlabs.d.ts.map +1 -1
  56. package/dist/footage/failure.js.map +1 -1
  57. package/dist/footage/fake.js.map +1 -1
  58. package/dist/footage/ffmpeg-failure.d.ts.map +1 -1
  59. package/dist/footage/ffmpeg-failure.js.map +1 -1
  60. package/dist/footage/film.d.ts +9 -0
  61. package/dist/footage/film.d.ts.map +1 -1
  62. package/dist/footage/film.js.map +1 -1
  63. package/dist/footage/hyperframes-capture.d.ts.map +1 -1
  64. package/dist/footage/keyterms.d.ts.map +1 -1
  65. package/dist/footage/loudness.d.ts.map +1 -1
  66. package/dist/footage/loudness.js.map +1 -1
  67. package/dist/footage/mouth-clicks.d.ts.map +1 -1
  68. package/dist/footage/normalize.d.ts.map +1 -1
  69. package/dist/footage/normalize.js.map +1 -1
  70. package/dist/footage/overlay-html.d.ts +21 -1
  71. package/dist/footage/overlay-html.d.ts.map +1 -1
  72. package/dist/footage/overlay-html.js +217 -56
  73. package/dist/footage/overlay-html.js.map +1 -1
  74. package/dist/footage/overlay-schema.d.ts +104 -12
  75. package/dist/footage/overlay-schema.d.ts.map +1 -1
  76. package/dist/footage/overlay-schema.js +215 -45
  77. package/dist/footage/overlay-schema.js.map +1 -1
  78. package/dist/footage/overlays.d.ts +109 -16
  79. package/dist/footage/overlays.d.ts.map +1 -1
  80. package/dist/footage/overlays.js +303 -52
  81. package/dist/footage/overlays.js.map +1 -1
  82. package/dist/footage/paid.d.ts.map +1 -1
  83. package/dist/footage/pipeline.d.ts +5 -0
  84. package/dist/footage/pipeline.d.ts.map +1 -1
  85. package/dist/footage/pipeline.js +3 -2
  86. package/dist/footage/pipeline.js.map +1 -1
  87. package/dist/footage/probe.js.map +1 -1
  88. package/dist/footage/process.js.map +1 -1
  89. package/dist/footage/publish.js.map +1 -1
  90. package/dist/footage/render.js.map +1 -1
  91. package/dist/footage/sound-analysis.d.ts.map +1 -1
  92. package/dist/footage/speech-ranges.js.map +1 -1
  93. package/dist/footage/tonemap-lut.d.ts.map +1 -1
  94. package/dist/footage/tonemap-lut.js.map +1 -1
  95. package/dist/footage/tools.d.ts.map +1 -1
  96. package/dist/footage/tools.js.map +1 -1
  97. package/dist/index.d.ts +3 -3
  98. package/dist/index.d.ts.map +1 -1
  99. package/dist/index.js +3 -3
  100. package/dist/index.js.map +1 -1
  101. package/dist/messages/en.d.ts.map +1 -1
  102. package/dist/messages/index.js.map +1 -1
  103. package/dist/og/font-file.d.ts.map +1 -1
  104. package/dist/og/fonts.d.ts.map +1 -1
  105. package/dist/og/fonts.js.map +1 -1
  106. package/dist/og/photo-cover.d.ts.map +1 -1
  107. package/dist/og/result.d.ts.map +1 -1
  108. package/dist/og/templates/schemas.d.ts.map +1 -1
  109. package/dist/platforms.d.ts.map +1 -1
  110. package/dist/render/hyperframes.js.map +1 -1
  111. package/dist/render/render.d.ts +4 -1
  112. package/dist/render/render.d.ts.map +1 -1
  113. package/dist/render/render.js +2 -1
  114. package/dist/render/render.js.map +1 -1
  115. package/dist/screenshot/gates.d.ts.map +1 -1
  116. package/dist/voice/fake.js.map +1 -1
  117. package/dist/voice/provider.d.ts.map +1 -1
  118. package/package.json +2 -2
  119. package/schema/edl.schema.json +90 -8
  120. package/schema/marketing.schema.json +18 -0
  121. package/src/compose/timeline.ts +62 -13
  122. package/src/config/config.ts +3 -0
  123. package/src/config/schema.ts +15 -0
  124. package/src/footage/captions.ts +39 -16
  125. package/src/footage/compose.ts +5 -3
  126. package/src/footage/draft-overlays.ts +276 -35
  127. package/src/footage/draft.ts +20 -4
  128. package/src/footage/edl.ts +1 -1
  129. package/src/footage/film.ts +9 -0
  130. package/src/footage/overlay-html.ts +239 -59
  131. package/src/footage/overlay-schema.ts +245 -40
  132. package/src/footage/overlays.ts +364 -55
  133. package/src/footage/pipeline.ts +8 -3
  134. package/src/index.ts +28 -0
  135. package/src/render/render.ts +3 -2
@@ -8,10 +8,14 @@ import { z } from "zod";
8
8
 
9
9
  /**
10
10
  * `punch_in`: an emphasis zoom of the picture on a word, eased in and back out. `keyword`: one word or number beside
11
- * the subject. `lower_third`: a place or a name above the captions. `list`: 2 to 4 short points. `arrow`: points at
12
- * `anchor` in the frame. `highlight`: marks the `anchor` rectangle of the frame.
11
+ * the subject. `lower_third`: a place or a name above the captions (or at the top). `list`: 2 to 4 short points.
12
+ * `arrow`: points at `anchor` in the frame. `highlight`: marks the `anchor` rectangle of the frame. `hook_title`: the
13
+ * hook's question or title at the top of the frame, one or two lines, with an optional place label (a drawn pin and
14
+ * "City, Country") above it; it may stay across cuts. `search_bar`: a rounded search field whose text types in.
15
+ * `place_card`: a big place title with a one-line subtitle. `counter`: a number with a unit counting up to its value.
16
+ * `date_stamp`: a day or a date with a place, small, in a corner of the top band.
13
17
  */
14
- export const OVERLAY_KINDS = ["punch_in", "keyword", "lower_third", "list", "arrow", "highlight"] as const;
18
+ export const OVERLAY_KINDS = ["punch_in", "keyword", "lower_third", "list", "arrow", "highlight", "hook_title", "search_bar", "place_card", "counter", "date_stamp"] as const;
15
19
 
16
20
  export type OverlayKind = (typeof OVERLAY_KINDS)[number];
17
21
 
@@ -25,16 +29,52 @@ export const OVERLAY_SIDES = ["left", "right"] as const;
25
29
 
26
30
  export type OverlaySide = (typeof OVERLAY_SIDES)[number];
27
31
 
32
+ /** The band of the text region an overlay sits in (`OVERLAY_POSITIONS_BY_KIND` says which a kind takes). */
33
+ export const OVERLAY_POSITIONS = ["top", "middle", "bottom"] as const;
34
+
35
+ export type OverlayPosition = (typeof OVERLAY_POSITIONS)[number];
36
+
37
+ /**
38
+ * How an overlay enters: `fade` in place, `slide` up into place, `type` letter by letter (text kinds), `none` (it is
39
+ * simply there). Without one, the kind's own entrance. Never a bounce or a pop: the reel stays natural.
40
+ */
41
+ export const OVERLAY_ENTRANCES = ["fade", "slide", "type", "none"] as const;
42
+
43
+ export type OverlayEntrance = (typeof OVERLAY_ENTRANCES)[number];
44
+
28
45
  /** The shortest an overlay stays on screen: shorter does not read. */
29
46
  export const MIN_OVERLAY_SECONDS = 1;
30
- /** The longest an overlay stays on screen. */
47
+ /** The longest an overlay stays on screen (a `hook_title` may stay up to `MAX_HOOK_TITLE_SECONDS`). */
31
48
  export const MAX_OVERLAY_SECONDS = 8;
49
+ /** The longest a `hook_title` stays on screen: up to a whole short film. */
50
+ export const MAX_HOOK_TITLE_SECONDS = 180;
32
51
  /** The longest `keyword` text. */
33
52
  export const MAX_OVERLAY_KEYWORD_LENGTH = 24;
34
53
  /** The longest `lower_third` text. */
35
54
  export const MAX_OVERLAY_LOWER_THIRD_LENGTH = 40;
36
55
  /** The longest point of a `list`. */
37
56
  export const MAX_OVERLAY_LIST_ITEM_LENGTH = 32;
57
+ /** The longest `hook_title` text (one or two lines). */
58
+ export const MAX_OVERLAY_HOOK_TITLE_LENGTH = 64;
59
+ /** The longest place label (`hook_title`, `date_stamp`). */
60
+ export const MAX_OVERLAY_PLACE_LENGTH = 40;
61
+ /** The longest `search_bar` query. */
62
+ export const MAX_OVERLAY_SEARCH_LENGTH = 40;
63
+ /** The longest `place_card` title. */
64
+ export const MAX_OVERLAY_PLACE_TITLE_LENGTH = 28;
65
+ /** The longest `place_card` subtitle. */
66
+ export const MAX_OVERLAY_SUBTITLE_LENGTH = 40;
67
+ /** The longest `date_stamp` text. */
68
+ export const MAX_OVERLAY_DATE_LENGTH = 24;
69
+ /** The longest `counter` unit. */
70
+ export const MAX_OVERLAY_UNIT_LENGTH = 12;
71
+ /** The largest `counter` value. */
72
+ export const MAX_OVERLAY_COUNTER_VALUE = 999_999_999;
73
+ /** The `type` entrance's and the search bar's typing speed bounds, in characters per second. */
74
+ export const MIN_OVERLAY_TYPING_SPEED = 4;
75
+ export const MAX_OVERLAY_TYPING_SPEED = 40;
76
+ /** The typing speed without a `typing_speed`, in characters per second. */
77
+ export const DEFAULT_OVERLAY_TYPING_SPEED = 14;
38
78
 
39
79
  /** A word of the film's transcript: the `occurrence`-th word (1 first) that reads `text`, compared like fillers are. */
40
80
  export interface EdlOverlayWord {
@@ -50,9 +90,21 @@ export interface EdlOverlayAnchor {
50
90
  height?: number;
51
91
  }
52
92
 
93
+ /** An overlay's own colours (`#rrggbb`), each one in place of the brand's: its card, its text, its accent. */
94
+ export interface EdlOverlayColors {
95
+ card?: string;
96
+ text?: string;
97
+ accent?: string;
98
+ }
99
+
53
100
  export interface EdlOverlayStyle {
54
101
  size?: OverlaySize;
55
102
  side?: OverlaySide;
103
+ position?: OverlayPosition;
104
+ entrance?: OverlayEntrance;
105
+ /** Characters per second of the `type` entrance and the search bar's query. */
106
+ typing_speed?: number;
107
+ colors?: EdlOverlayColors;
56
108
  }
57
109
 
58
110
  export interface EdlOverlay {
@@ -61,34 +113,160 @@ export interface EdlOverlay {
61
113
  at_word?: EdlOverlayWord;
62
114
  /** The film second it starts at; give this or `at_word`. */
63
115
  at?: number;
64
- /** Seconds on screen (`MIN_OVERLAY_SECONDS` to `MAX_OVERLAY_SECONDS`). */
116
+ /** Seconds on screen (`MIN_OVERLAY_SECONDS` to `MAX_OVERLAY_SECONDS`; a `hook_title` up to `MAX_HOOK_TITLE_SECONDS`). */
65
117
  duration: number;
66
- /** The `keyword` or the `lower_third` text. */
118
+ /** The text of a `keyword`, `lower_third`, `hook_title`, `search_bar`, `place_card` (its title) or `date_stamp`. */
67
119
  text?: string;
68
120
  /** The `list` points (2 to 4). */
69
121
  items?: string[];
70
122
  /** The `arrow` point or the `highlight` rectangle. */
71
123
  anchor?: EdlOverlayAnchor;
124
+ /** The place label of a `hook_title` (with a pin) or a `date_stamp`. */
125
+ place?: string;
126
+ /** The `place_card`'s one-line subtitle. */
127
+ subtitle?: string;
128
+ /** The number a `counter` counts up to, with at most two decimals. */
129
+ value?: number;
130
+ /** The number a `counter` counts from (0 by default), below its `value`. */
131
+ from?: number;
132
+ /** The `counter`'s unit after the number (km, days, a currency). */
133
+ unit?: string;
72
134
  style?: EdlOverlayStyle;
73
135
  }
74
136
 
75
- /** What each kind needs and refuses: its text, its points or its anchor. */
76
- const KIND_FIELDS: Record<OverlayKind, { text: boolean; items: boolean; anchor: "none" | "point" | "rect" }> = {
77
- punch_in: { text: false, items: false, anchor: "none" },
78
- keyword: { text: true, items: false, anchor: "none" },
79
- lower_third: { text: true, items: false, anchor: "none" },
80
- list: { text: false, items: true, anchor: "none" },
81
- arrow: { text: false, items: false, anchor: "point" },
82
- highlight: { text: false, items: false, anchor: "rect" },
137
+ type FieldRule = "required" | "optional" | "none";
138
+
139
+ interface KindFields {
140
+ text: FieldRule;
141
+ items: boolean;
142
+ anchor: "none" | "point" | "rect";
143
+ place: boolean;
144
+ subtitle: boolean;
145
+ counter: boolean;
146
+ }
147
+
148
+ const NO_FIELDS: KindFields = { text: "none", items: false, anchor: "none", place: false, subtitle: false, counter: false };
149
+ const TEXT_ONLY: KindFields = { ...NO_FIELDS, text: "required" };
150
+
151
+ /** What each kind needs, takes and refuses. */
152
+ const KIND_FIELDS: Record<OverlayKind, KindFields> = {
153
+ punch_in: NO_FIELDS,
154
+ keyword: TEXT_ONLY,
155
+ lower_third: TEXT_ONLY,
156
+ list: { ...NO_FIELDS, items: true },
157
+ arrow: { ...NO_FIELDS, anchor: "point" },
158
+ highlight: { ...NO_FIELDS, anchor: "rect" },
159
+ hook_title: { ...TEXT_ONLY, place: true },
160
+ search_bar: TEXT_ONLY,
161
+ place_card: { ...TEXT_ONLY, subtitle: true },
162
+ counter: { ...NO_FIELDS, counter: true },
163
+ date_stamp: { ...TEXT_ONLY, place: true },
164
+ };
165
+
166
+ const TEXT_LIMITS: Partial<Record<OverlayKind, number>> = {
167
+ keyword: MAX_OVERLAY_KEYWORD_LENGTH,
168
+ lower_third: MAX_OVERLAY_LOWER_THIRD_LENGTH,
169
+ hook_title: MAX_OVERLAY_HOOK_TITLE_LENGTH,
170
+ search_bar: MAX_OVERLAY_SEARCH_LENGTH,
171
+ place_card: MAX_OVERLAY_PLACE_TITLE_LENGTH,
172
+ date_stamp: MAX_OVERLAY_DATE_LENGTH,
83
173
  };
84
174
 
85
- const TEXT_LIMITS: Partial<Record<OverlayKind, number>> = { keyword: MAX_OVERLAY_KEYWORD_LENGTH, lower_third: MAX_OVERLAY_LOWER_THIRD_LENGTH };
175
+ /** The kinds that take a side. */
176
+ export const OVERLAY_SIDED_KINDS: readonly OverlayKind[] = ["keyword", "lower_third", "list", "date_stamp"];
177
+
178
+ /** The positions a kind may take (none: its place is fixed). */
179
+ export const OVERLAY_POSITIONS_BY_KIND: Partial<Record<OverlayKind, readonly OverlayPosition[]>> = {
180
+ keyword: ["top", "middle", "bottom"],
181
+ lower_third: ["top", "bottom"],
182
+ list: ["top", "middle"],
183
+ search_bar: ["top", "middle", "bottom"],
184
+ place_card: ["top", "middle", "bottom"],
185
+ counter: ["top", "middle", "bottom"],
186
+ };
187
+
188
+ const TEXT_ENTRANCES: readonly OverlayEntrance[] = ["fade", "slide", "type", "none"];
189
+ const BLOCK_ENTRANCES: readonly OverlayEntrance[] = ["fade", "slide", "none"];
190
+
191
+ /** The entrances a kind may take (none listed: it takes no entrance). */
192
+ export const OVERLAY_ENTRANCES_BY_KIND: Record<OverlayKind, readonly OverlayEntrance[]> = {
193
+ punch_in: [],
194
+ keyword: TEXT_ENTRANCES,
195
+ lower_third: TEXT_ENTRANCES,
196
+ list: BLOCK_ENTRANCES,
197
+ arrow: ["fade", "none"],
198
+ highlight: ["fade", "none"],
199
+ hook_title: TEXT_ENTRANCES,
200
+ search_bar: TEXT_ENTRANCES,
201
+ place_card: TEXT_ENTRANCES,
202
+ counter: BLOCK_ENTRANCES,
203
+ date_stamp: TEXT_ENTRANCES,
204
+ };
205
+
206
+ /** Whether an overlay types its text in: the `type` entrance, or a search bar without another entrance. */
207
+ export function isTypedOverlay(overlay: Pick<EdlOverlay, "kind" | "style">): boolean {
208
+ const entrance = overlay.style?.entrance;
209
+ return entrance === "type" || (overlay.kind === "search_bar" && entrance === undefined);
210
+ }
86
211
 
87
212
  const overlayText = z.string().trim().min(1, "is empty");
213
+ const hexColor = z.string().regex(/^#[0-9a-fA-F]{6}$/, "is not a #rrggbb colour");
214
+ const article = (kind: OverlayKind): string => (/^[aeiou]/.test(kind) ? `an ${kind}` : `a ${kind}`);
215
+ const hasTwoDecimals = (value: number): boolean => Math.abs(Math.round(value * 100) - value * 100) < 1e-6;
216
+ const counterNumber = z.number().min(0).max(MAX_OVERLAY_COUNTER_VALUE).refine(hasTwoDecimals, "has more than two decimals");
217
+
218
+ /** Every issue of one overlay's fields against its kind. */
219
+ function checkOverlayFields(overlay: EdlOverlay, issue: (path: string[], message: string) => void): void {
220
+ const { kind } = overlay;
221
+ const fields = KIND_FIELDS[kind];
222
+ if ((overlay.at_word === undefined) === (overlay.at === undefined)) issue([], "needs exactly one of at_word and at");
223
+ if (kind !== "hook_title" && overlay.duration > MAX_OVERLAY_SECONDS) issue(["duration"], `${article(kind)} stays at most ${MAX_OVERLAY_SECONDS} s (only a hook_title stays longer)`);
224
+ if (fields.text === "required" && overlay.text === undefined) issue(["text"], `${article(kind)} needs its text`);
225
+ if (fields.text === "none" && overlay.text !== undefined) issue(["text"], `${article(kind)} draws no text; leave it out`);
226
+ const limit = TEXT_LIMITS[kind];
227
+ if (limit !== undefined && overlay.text !== undefined && overlay.text.length > limit) issue(["text"], `is longer than ${limit} characters`);
228
+ if (fields.items && overlay.items === undefined) issue(["items"], "a list needs 2 to 4 points");
229
+ if (!fields.items && overlay.items !== undefined) issue(["items"], `${article(kind)} draws no points; leave them out`);
230
+ if (fields.anchor === "none" && overlay.anchor !== undefined) issue(["anchor"], `${article(kind)} has no anchor; leave it out`);
231
+ if (fields.anchor !== "none" && overlay.anchor === undefined) issue(["anchor"], `${article(kind)} needs its anchor`);
232
+ const isRect = overlay.anchor?.width !== undefined && overlay.anchor.height !== undefined;
233
+ if (fields.anchor === "rect" && overlay.anchor !== undefined && !isRect) issue(["anchor"], "a highlight needs the anchor's width and height");
234
+ if (fields.anchor === "point" && (overlay.anchor?.width !== undefined || overlay.anchor?.height !== undefined)) issue(["anchor"], "an arrow points at a point: leave width and height out");
235
+ if (!fields.place && overlay.place !== undefined) issue(["place"], `${article(kind)} has no place label; leave it out`);
236
+ if (!fields.subtitle && overlay.subtitle !== undefined) issue(["subtitle"], `${article(kind)} has no subtitle; leave it out`);
237
+ if (fields.counter && overlay.value === undefined) issue(["value"], "a counter needs its value");
238
+ if (!fields.counter) {
239
+ for (const key of ["value", "from", "unit"] as const) if (overlay[key] !== undefined) issue([key], `${article(kind)} counts nothing; leave ${key} out`);
240
+ }
241
+ if (overlay.value !== undefined && overlay.from !== undefined && overlay.from >= overlay.value) issue(["from"], "a counter counts up: from must be below value");
242
+ }
243
+
244
+ /** Every issue of one overlay's style knobs against its kind. */
245
+ function checkOverlayStyle(overlay: EdlOverlay, issue: (path: string[], message: string) => void): void {
246
+ const { kind, style } = overlay;
247
+ if (style === undefined) return;
248
+ if (style.side !== undefined && !OVERLAY_SIDED_KINDS.includes(kind)) issue(["style", "side"], `${article(kind)} has no side; leave it out`);
249
+ const positions = OVERLAY_POSITIONS_BY_KIND[kind];
250
+ if (style.position !== undefined && !(positions ?? []).includes(style.position)) {
251
+ issue(["style", "position"], positions === undefined ? `${article(kind)} has a fixed place; leave position out` : `${article(kind)} sits at ${positions.join(", ")}`);
252
+ }
253
+ const entrances = OVERLAY_ENTRANCES_BY_KIND[kind];
254
+ if (style.entrance !== undefined && !entrances.includes(style.entrance)) {
255
+ issue(["style", "entrance"], entrances.length === 0 ? `${article(kind)} has no entrance; leave it out` : `${article(kind)} enters by ${entrances.join(", ")}`);
256
+ }
257
+ if (style.typing_speed !== undefined && !isTypedOverlay(overlay)) issue(["style", "typing_speed"], "only a typed entrance or a search bar has a typing speed");
258
+ if (style.colors === undefined) return;
259
+ if (kind === "punch_in") issue(["style", "colors"], "a punch_in draws nothing to colour; leave colors out");
260
+ if ((kind === "arrow" || kind === "highlight") && (style.colors.card !== undefined || style.colors.text !== undefined)) {
261
+ issue(["style", "colors"], `${article(kind)} draws in its accent only; leave card and text out`);
262
+ }
263
+ }
88
264
 
89
265
  export const overlaySchema = z
90
266
  .strictObject({
91
- kind: z.enum(OVERLAY_KINDS).describe("punch_in (an emphasis zoom on a word), keyword, lower_third, list, arrow or highlight."),
267
+ kind: z
268
+ .enum(OVERLAY_KINDS)
269
+ .describe("punch_in (an emphasis zoom on a word), keyword, lower_third, list, arrow, highlight, hook_title, search_bar, place_card, counter or date_stamp."),
92
270
  at_word: z
93
271
  .strictObject({
94
272
  text: overlayText.describe("The word as the transcript has it; compared without case and punctuation."),
@@ -97,8 +275,16 @@ export const overlaySchema = z
97
275
  .optional()
98
276
  .describe("The transcript word the overlay starts on (its start after the cut); give this or at."),
99
277
  at: z.number().min(0).optional().describe("The film second the overlay starts at; give this or at_word."),
100
- duration: z.number().min(MIN_OVERLAY_SECONDS).max(MAX_OVERLAY_SECONDS).describe(`Seconds on screen (${MIN_OVERLAY_SECONDS}-${MAX_OVERLAY_SECONDS}).`),
101
- text: overlayText.optional().describe(`The keyword (up to ${MAX_OVERLAY_KEYWORD_LENGTH} characters) or the lower third (up to ${MAX_OVERLAY_LOWER_THIRD_LENGTH}).`),
278
+ duration: z
279
+ .number()
280
+ .min(MIN_OVERLAY_SECONDS)
281
+ .max(MAX_HOOK_TITLE_SECONDS)
282
+ .describe(`Seconds on screen (${MIN_OVERLAY_SECONDS}-${MAX_OVERLAY_SECONDS}; a hook_title up to ${MAX_HOOK_TITLE_SECONDS}).`),
283
+ text: overlayText
284
+ .optional()
285
+ .describe(
286
+ `The text: keyword (up to ${MAX_OVERLAY_KEYWORD_LENGTH} characters), lower_third (${MAX_OVERLAY_LOWER_THIRD_LENGTH}), hook_title (${MAX_OVERLAY_HOOK_TITLE_LENGTH}, one or two lines), search_bar (${MAX_OVERLAY_SEARCH_LENGTH}), place_card title (${MAX_OVERLAY_PLACE_TITLE_LENGTH}) or date_stamp (${MAX_OVERLAY_DATE_LENGTH}).`,
287
+ ),
102
288
  items: z
103
289
  .array(overlayText.max(MAX_OVERLAY_LIST_ITEM_LENGTH, `is longer than ${MAX_OVERLAY_LIST_ITEM_LENGTH} characters`))
104
290
  .min(2, "a list needs 2 to 4 points")
@@ -114,33 +300,52 @@ export const overlaySchema = z
114
300
  })
115
301
  .optional()
116
302
  .describe("The point an arrow points at, or the rectangle a highlight marks (x, y its top left), in px of the film's frame."),
303
+ place: overlayText
304
+ .max(MAX_OVERLAY_PLACE_LENGTH, `is longer than ${MAX_OVERLAY_PLACE_LENGTH} characters`)
305
+ .optional()
306
+ .describe(`A hook_title's place label above it (drawn with a pin) or a date_stamp's place, e.g. "Hanoi, Vietnam" (up to ${MAX_OVERLAY_PLACE_LENGTH} characters).`),
307
+ subtitle: overlayText
308
+ .max(MAX_OVERLAY_SUBTITLE_LENGTH, `is longer than ${MAX_OVERLAY_SUBTITLE_LENGTH} characters`)
309
+ .optional()
310
+ .describe(`A place_card's one-line subtitle (up to ${MAX_OVERLAY_SUBTITLE_LENGTH} characters).`),
311
+ value: counterNumber.optional().describe("The number a counter counts up to (at most two decimals)."),
312
+ from: counterNumber.optional().describe("The number a counter counts from (0 by default), below its value."),
313
+ unit: overlayText
314
+ .max(MAX_OVERLAY_UNIT_LENGTH, `is longer than ${MAX_OVERLAY_UNIT_LENGTH} characters`)
315
+ .optional()
316
+ .describe(`A counter's unit after the number, e.g. km (up to ${MAX_OVERLAY_UNIT_LENGTH} characters).`),
117
317
  style: z
118
318
  .strictObject({
119
319
  size: z.enum(OVERLAY_SIZES).optional().describe("s, m (the default) or l: the punch-in's zoom (108, 112, 115 %) or the type size."),
120
- side: z.enum(OVERLAY_SIDES).optional().describe("The side a keyword, lower third or list sits on."),
320
+ side: z.enum(OVERLAY_SIDES).optional().describe("The side a keyword, lower third, list or date stamp sits on."),
321
+ position: z
322
+ .enum(OVERLAY_POSITIONS)
323
+ .optional()
324
+ .describe("top, middle or bottom of the room above the captions: keyword, search_bar, place_card, counter (any), lower_third (top or bottom), list (top or middle)."),
325
+ entrance: z
326
+ .enum(OVERLAY_ENTRANCES)
327
+ .optional()
328
+ .describe("fade, slide, type (text typed in letter by letter) or none; without it the kind's own. Never a bounce or a pop."),
329
+ typing_speed: z
330
+ .number()
331
+ .min(MIN_OVERLAY_TYPING_SPEED)
332
+ .max(MAX_OVERLAY_TYPING_SPEED)
333
+ .optional()
334
+ .describe(`Characters per second of a typed entrance or a search bar (${MIN_OVERLAY_TYPING_SPEED}-${MAX_OVERLAY_TYPING_SPEED}, ${DEFAULT_OVERLAY_TYPING_SPEED} by default).`),
335
+ colors: z
336
+ .strictObject({
337
+ card: hexColor.optional().describe("The card's colour (#rrggbb); the brand's background without it."),
338
+ text: hexColor.optional().describe("The text's colour; the brand's foreground without it."),
339
+ accent: hexColor.optional().describe("The accent (dot, pin, magnifier, arrow, marker); the brand's accent without it."),
340
+ })
341
+ .optional()
342
+ .describe("The overlay's own colours in place of the brand's."),
121
343
  })
122
344
  .optional()
123
- .describe("The overlay's size step and side; colours and fonts are the brand's."),
345
+ .describe("The overlay's look: size, side, position, entrance, typing speed and colours; fonts are the brand's."),
124
346
  })
125
347
  .superRefine((overlay, context) => {
126
- const fields = KIND_FIELDS[overlay.kind];
127
- if ((overlay.at_word === undefined) === (overlay.at === undefined)) context.addIssue({ code: "custom", path: [], message: "needs exactly one of at_word and at" });
128
- if (fields.text && overlay.text === undefined) context.addIssue({ code: "custom", path: ["text"], message: `a ${overlay.kind} needs its text` });
129
- if (!fields.text && overlay.text !== undefined) context.addIssue({ code: "custom", path: ["text"], message: `a ${overlay.kind} draws no text; leave it out` });
130
- const limit = TEXT_LIMITS[overlay.kind];
131
- if (limit !== undefined && overlay.text !== undefined && overlay.text.length > limit) {
132
- context.addIssue({ code: "custom", path: ["text"], message: `is longer than ${limit} characters` });
133
- }
134
- if (fields.items && overlay.items === undefined) context.addIssue({ code: "custom", path: ["items"], message: "a list needs 2 to 4 points" });
135
- if (!fields.items && overlay.items !== undefined) context.addIssue({ code: "custom", path: ["items"], message: `a ${overlay.kind} draws no points; leave them out` });
136
- if (fields.anchor === "none" && overlay.anchor !== undefined) context.addIssue({ code: "custom", path: ["anchor"], message: `a ${overlay.kind} has no anchor; leave it out` });
137
- if (fields.anchor !== "none" && overlay.anchor === undefined) context.addIssue({ code: "custom", path: ["anchor"], message: `${overlay.kind === "arrow" ? "an arrow" : "a highlight"} needs its anchor` });
138
- const isRect = overlay.anchor?.width !== undefined && overlay.anchor.height !== undefined;
139
- if (fields.anchor === "rect" && overlay.anchor !== undefined && !isRect) context.addIssue({ code: "custom", path: ["anchor"], message: "a highlight needs the anchor's width and height" });
140
- if (fields.anchor === "point" && (overlay.anchor?.width !== undefined || overlay.anchor?.height !== undefined)) {
141
- context.addIssue({ code: "custom", path: ["anchor"], message: "an arrow points at a point: leave width and height out" });
142
- }
143
- if (overlay.kind !== "keyword" && overlay.kind !== "lower_third" && overlay.kind !== "list" && overlay.style?.side !== undefined) {
144
- context.addIssue({ code: "custom", path: ["style", "side"], message: `a ${overlay.kind} has no side; leave it out` });
145
- }
348
+ const issue = (path: string[], message: string) => context.addIssue({ code: "custom", path, message });
349
+ checkOverlayFields(overlay, issue);
350
+ checkOverlayStyle(overlay, issue);
146
351
  });