@softure-ai/marketing-kit 0.1.12 → 0.3.1

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 (118) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +109 -4
  3. package/dist/cli/footage.d.ts +6 -0
  4. package/dist/cli/footage.d.ts.map +1 -0
  5. package/dist/cli/footage.js +95 -0
  6. package/dist/cli/footage.js.map +1 -0
  7. package/dist/cli/main.js +21 -5
  8. package/dist/cli/main.js.map +1 -1
  9. package/dist/cli/options.d.ts +18 -3
  10. package/dist/cli/options.d.ts.map +1 -1
  11. package/dist/cli/options.js +41 -2
  12. package/dist/cli/options.js.map +1 -1
  13. package/dist/compose/compose.d.ts.map +1 -1
  14. package/dist/compose/compose.js +1 -22
  15. package/dist/compose/compose.js.map +1 -1
  16. package/dist/compose/html.d.ts +6 -0
  17. package/dist/compose/html.d.ts.map +1 -0
  18. package/dist/compose/html.js +24 -0
  19. package/dist/compose/html.js.map +1 -0
  20. package/dist/config/actions-schema.d.ts +14 -14
  21. package/dist/config/config.d.ts +19 -3
  22. package/dist/config/config.d.ts.map +1 -1
  23. package/dist/config/config.js +90 -2
  24. package/dist/config/config.js.map +1 -1
  25. package/dist/config/schema.d.ts +152 -70
  26. package/dist/config/schema.d.ts.map +1 -1
  27. package/dist/config/schema.js +140 -10
  28. package/dist/config/schema.js.map +1 -1
  29. package/dist/config/shot-steps.d.ts +16 -16
  30. package/dist/footage/cache.d.ts +23 -0
  31. package/dist/footage/cache.d.ts.map +1 -0
  32. package/dist/footage/cache.js +51 -0
  33. package/dist/footage/cache.js.map +1 -0
  34. package/dist/footage/compose.d.ts +50 -0
  35. package/dist/footage/compose.d.ts.map +1 -0
  36. package/dist/footage/compose.js +166 -0
  37. package/dist/footage/compose.js.map +1 -0
  38. package/dist/footage/edl.d.ts +83 -0
  39. package/dist/footage/edl.d.ts.map +1 -0
  40. package/dist/footage/edl.js +166 -0
  41. package/dist/footage/edl.js.map +1 -0
  42. package/dist/footage/elevenlabs.d.ts +31 -0
  43. package/dist/footage/elevenlabs.d.ts.map +1 -0
  44. package/dist/footage/elevenlabs.js +140 -0
  45. package/dist/footage/elevenlabs.js.map +1 -0
  46. package/dist/footage/fake.d.ts +38 -0
  47. package/dist/footage/fake.d.ts.map +1 -0
  48. package/dist/footage/fake.js +66 -0
  49. package/dist/footage/fake.js.map +1 -0
  50. package/dist/footage/film.d.ts +103 -0
  51. package/dist/footage/film.d.ts.map +1 -0
  52. package/dist/footage/film.js +29 -0
  53. package/dist/footage/film.js.map +1 -0
  54. package/dist/footage/music.d.ts +37 -0
  55. package/dist/footage/music.d.ts.map +1 -0
  56. package/dist/footage/music.js +63 -0
  57. package/dist/footage/music.js.map +1 -0
  58. package/dist/footage/normalize.d.ts +41 -0
  59. package/dist/footage/normalize.d.ts.map +1 -0
  60. package/dist/footage/normalize.js +114 -0
  61. package/dist/footage/normalize.js.map +1 -0
  62. package/dist/footage/pipeline.d.ts +105 -0
  63. package/dist/footage/pipeline.d.ts.map +1 -0
  64. package/dist/footage/pipeline.js +385 -0
  65. package/dist/footage/pipeline.js.map +1 -0
  66. package/dist/footage/probe.d.ts +64 -0
  67. package/dist/footage/probe.d.ts.map +1 -0
  68. package/dist/footage/probe.js +138 -0
  69. package/dist/footage/probe.js.map +1 -0
  70. package/dist/footage/providers.d.ts +61 -0
  71. package/dist/footage/providers.d.ts.map +1 -0
  72. package/dist/footage/providers.js +13 -0
  73. package/dist/footage/providers.js.map +1 -0
  74. package/dist/footage/render.d.ts +20 -0
  75. package/dist/footage/render.d.ts.map +1 -0
  76. package/dist/footage/render.js +76 -0
  77. package/dist/footage/render.js.map +1 -0
  78. package/dist/index.d.ts +14 -2
  79. package/dist/index.d.ts.map +1 -1
  80. package/dist/index.js +16 -3
  81. package/dist/index.js.map +1 -1
  82. package/dist/messages/index.d.ts +10 -22
  83. package/dist/messages/index.d.ts.map +1 -1
  84. package/dist/messages/index.js +8 -6
  85. package/dist/messages/index.js.map +1 -1
  86. package/dist/render/render.d.ts +6 -0
  87. package/dist/render/render.d.ts.map +1 -1
  88. package/dist/render/render.js +1 -1
  89. package/dist/render/render.js.map +1 -1
  90. package/package.json +1 -1
  91. package/schema/marketing.schema.json +339 -3
  92. package/src/cli/footage.ts +87 -0
  93. package/src/cli/main.ts +20 -5
  94. package/src/cli/options.ts +51 -4
  95. package/src/compose/compose.ts +1 -25
  96. package/src/compose/html.ts +28 -0
  97. package/src/config/config.ts +101 -5
  98. package/src/config/schema.ts +146 -12
  99. package/src/footage/cache.ts +66 -0
  100. package/src/footage/compose.ts +213 -0
  101. package/src/footage/edl.ts +204 -0
  102. package/src/footage/elevenlabs.ts +154 -0
  103. package/src/footage/fake.ts +92 -0
  104. package/src/footage/film.ts +111 -0
  105. package/src/footage/music.ts +86 -0
  106. package/src/footage/normalize.ts +133 -0
  107. package/src/footage/pipeline.ts +447 -0
  108. package/src/footage/probe.ts +172 -0
  109. package/src/footage/providers.ts +71 -0
  110. package/src/footage/render.ts +82 -0
  111. package/src/index.ts +110 -3
  112. package/src/messages/index.ts +16 -8
  113. package/src/render/render.ts +1 -1
  114. package/dist/messages/pl.d.ts +0 -3
  115. package/dist/messages/pl.d.ts.map +0 -1
  116. package/dist/messages/pl.js +0 -21
  117. package/dist/messages/pl.js.map +0 -1
  118. package/src/messages/pl.ts +0 -22
@@ -0,0 +1,28 @@
1
+ import type { ComposeFont } from "./compose.js";
2
+
3
+ /** HTML helpers shared by the compositions (the screen film's and the footage film's). */
4
+
5
+ export function escapeHtml(text: string): string {
6
+ return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
7
+ }
8
+
9
+ const FONT_FORMATS: Record<string, string> = { woff2: "woff2", woff: "woff", ttf: "truetype", otf: "opentype" };
10
+
11
+ function getFontFormat(src: string): string {
12
+ const extension = src.split(".").at(-1)?.toLowerCase() ?? "";
13
+ const format = FONT_FORMATS[extension];
14
+ if (format === undefined) throw new Error(`Font ${src}: expected a .woff2, .woff, .ttf or .otf file.`);
15
+ return format;
16
+ }
17
+
18
+ export function fontFaces(font: ComposeFont | null): string[] {
19
+ if (font === null) return [];
20
+ return font.faces.map((face) => {
21
+ const range = face.unicodeRange === null ? "" : `;unicode-range:${face.unicodeRange}`;
22
+ return `@font-face{font-family:"${font.family}";src:url("${face.src}") format("${getFontFormat(face.src)}");font-weight:${face.weight};font-style:${face.style}${range}}`;
23
+ });
24
+ }
25
+
26
+ export function fontStack(font: ComposeFont | null, fallback: string): string {
27
+ return font === null ? fallback : `"${font.family}",${font.fallback}`;
28
+ }
@@ -3,7 +3,9 @@ import { dirname, resolve } from "node:path";
3
3
 
4
4
  import { getLayoutName } from "../compose/timeline.js";
5
5
  import type { Device, FilmScript } from "../film.js";
6
- import type { MarketingLocale } from "../messages/index.js";
6
+ import { DEFAULT_MUSIC_VOLUME, getDefaultFillers, type FootageFilm, type MusicSource } from "../footage/film.js";
7
+ import type { LayoutOverride } from "../compose/timeline.js";
8
+ import { getMarketingMessages, type MarketingMessages } from "../messages/index.js";
7
9
  import { DEFAULT_LINK_IN_BIO, PLATFORMS, type Platform } from "../platforms.js";
8
10
  import type { PlaceholderPace } from "../voice/placeholder.js";
9
11
  import type { SceneAction } from "./actions-schema.js";
@@ -74,6 +76,16 @@ export interface VideoConfig extends FilmScript {
74
76
  today: string | null;
75
77
  }
76
78
 
79
+ /** A footage film from `marketing.json` (`footage[]`), paths absolute, defaults applied. */
80
+ export interface FootageConfig extends FootageFilm {
81
+ /** The entry's position in `footage`, for errors about it. */
82
+ index: number;
83
+ /** The project's override of this format's caption box and end card (`marketing.json` `layout`). */
84
+ layout: LayoutOverride;
85
+ /** The post copy, or null when `social.posts` has no entry for this film. */
86
+ post: VideoPost | null;
87
+ }
88
+
77
89
  export interface MarketingConfig {
78
90
  /** Absolute path of the config file and the folder every path resolves against. */
79
91
  file: string;
@@ -82,8 +94,8 @@ export interface MarketingConfig {
82
94
  name: string;
83
95
  /** BCP 47, e.g. `en-US`. */
84
96
  locale: string;
85
- /** The dictionary of the copy: the locale's language. */
86
- language: MarketingLocale;
97
+ /** The copy of the posts and the film: English with `brand.messages` applied. */
98
+ messages: MarketingMessages;
87
99
  timezone: string;
88
100
  logo: string | null;
89
101
  colors: BrandColors;
@@ -99,6 +111,7 @@ export interface MarketingConfig {
99
111
  };
100
112
  voice: { provider: "elevenlabs"; cacheDir: string; minIntervalSeconds: number; placeholder: PlaceholderPace };
101
113
  videos: VideoConfig[];
114
+ footage: FootageConfig[];
102
115
  social: { linkTemplate: string } | null;
103
116
  screenshots: MarketingJson["screenshots"];
104
117
  /** How `shots` signs in for `signedIn` entries; null without a `signIn` block. */
@@ -180,6 +193,62 @@ function resolveVideos(data: MarketingJson, at: (relative: string) => string): V
180
193
  });
181
194
  }
182
195
 
196
+ function resolveMusicSource(music: NonNullable<MarketingJson["footage"][number]["music"]>, at: (relative: string) => string): MusicSource {
197
+ if (music.file !== undefined) return { kind: "file", path: at(music.file) };
198
+ if (music.prompt !== undefined) return { kind: "prompt", prompt: music.prompt };
199
+ // The schema requires exactly one of the three sources.
200
+ const fromVideo = music.fromVideo ?? { description: "", tags: [] };
201
+ return { kind: "video", description: fromVideo.description, tags: fromVideo.tags };
202
+ }
203
+
204
+ function resolveFootage(data: MarketingJson, at: (relative: string) => string): FootageConfig[] {
205
+ const posts = new Map((data.social?.posts ?? []).map((post) => [post.video, post]));
206
+ const platforms = data.social?.platforms ?? {};
207
+ return data.footage.map((film, index) => {
208
+ const language = film.language ?? data.voice.language;
209
+ const post = posts.get(film.id);
210
+ return {
211
+ index,
212
+ id: film.id,
213
+ title: film.title,
214
+ format: film.format,
215
+ language,
216
+ layout: data.layout?.[film.format] ?? {},
217
+ clips: film.clips.map((clip) => ({
218
+ id: clip.id,
219
+ source: /^https?:\/\//i.test(clip.source) ? clip.source : at(clip.source),
220
+ role: clip.role,
221
+ fit: clip.fit,
222
+ trim: { start: clip.trim.start, end: clip.trim.end ?? null },
223
+ script: clip.script ?? null,
224
+ })),
225
+ isolateVoice: film.isolateVoice,
226
+ cut: { fillers: film.fillers ?? getDefaultFillers(language), pauseSeconds: film.pauseSeconds, padSeconds: film.padSeconds, maxSeconds: film.maxSeconds ?? null },
227
+ transitions: film.transitions,
228
+ music:
229
+ film.music === undefined
230
+ ? { source: { kind: "none" }, ...DEFAULT_MUSIC_VOLUME }
231
+ : { source: resolveMusicSource(film.music, at), volume: film.music.volume, duckedVolume: film.music.duckedVolume },
232
+ captions: film.captions,
233
+ endCard: film.endCard ?? null,
234
+ post:
235
+ post === undefined
236
+ ? null
237
+ : {
238
+ caption: post.caption,
239
+ // The disclosure speaks of a persona and an AI voice, which a filmed person is not.
240
+ disclosure: null,
241
+ hashtags: post.hashtags,
242
+ channels: PLATFORMS.flatMap((platform) => {
243
+ const channel = platforms[platform];
244
+ if (channel === undefined) return [];
245
+ return [{ platform, code: post.codes?.[platform] ?? channel.code, linkInBio: channel.linkInBio ?? DEFAULT_LINK_IN_BIO[platform] }];
246
+ }),
247
+ },
248
+ };
249
+ });
250
+ }
251
+
183
252
  /** Reads and validates `marketing.json`; every problem comes back at once, by JSON path. */
184
253
  export function loadMarketingConfig(path: string): LoadConfigResult {
185
254
  const file = resolve(path);
@@ -210,8 +279,7 @@ export function loadMarketingConfig(path: string): LoadConfigResult {
210
279
  brand: {
211
280
  name: data.brand.name,
212
281
  locale: data.brand.locale,
213
- // The schema refuses a locale whose language has no dictionary.
214
- language: data.brand.locale.split("-")[0] as MarketingLocale,
282
+ messages: getMarketingMessages(data.brand.messages),
215
283
  timezone: data.brand.timezone,
216
284
  logo: data.brand.logo === undefined ? null : at(data.brand.logo.svg),
217
285
  colors: colors.colors,
@@ -227,6 +295,7 @@ export function loadMarketingConfig(path: string): LoadConfigResult {
227
295
  },
228
296
  voice: { provider: data.voice.provider, cacheDir: at(data.voice.cacheDir), minIntervalSeconds: data.voice.minIntervalSeconds, placeholder: data.voice.placeholder },
229
297
  videos: resolveVideos(data, at),
298
+ footage: resolveFootage(data, at),
230
299
  social: data.social === undefined ? null : { linkTemplate: data.social.linkTemplate },
231
300
  screenshots: data.screenshots,
232
301
  signIn: data.signIn ?? null,
@@ -264,6 +333,33 @@ export function findMissingFiles(config: MarketingConfig, video: VideoConfig, is
264
333
  return issues;
265
334
  }
266
335
 
336
+ /** Finds a footage film by id; null when the config has none. */
337
+ export function findFootage(config: MarketingConfig, id: string): FootageConfig | null {
338
+ return config.footage.find((film) => film.id === id) ?? null;
339
+ }
340
+
341
+ /** Files a footage film reads, checked before anything slow starts: local clips and music, and the brand's files when it renders. */
342
+ export function findMissingFootageFiles(config: MarketingConfig, film: FootageConfig, isRendering: boolean): ConfigIssue[] {
343
+ const issues: ConfigIssue[] = [];
344
+ const check = (path: PropertyKey[], file: string) => {
345
+ if (!existsSync(file)) issues.push({ path, message: `no file at ${file}` });
346
+ };
347
+ film.clips.forEach((clip, index) => {
348
+ if (!/^https?:\/\//i.test(clip.source)) check(["footage", film.index, "clips", index, "source"], clip.source);
349
+ });
350
+ if (film.music.source.kind === "file") check(["footage", film.index, "music", "file"], film.music.source.path);
351
+ if (!isRendering) return issues;
352
+ if (config.brand.logo !== null) check(["brand", "logo", "svg"], config.brand.logo);
353
+ for (const kind of ["heading", "body"] as const) {
354
+ config.brand.fonts[kind]?.files.forEach((font, index) => check(["brand", "fonts", kind, "files", index, "path"], font.path));
355
+ }
356
+ for (const event of SFX_EVENTS) {
357
+ const sound = config.sfx[event];
358
+ if (sound !== undefined) check(["sfx", event], sound);
359
+ }
360
+ return issues;
361
+ }
362
+
267
363
  /** Problems found after loading, in the same format as the load errors. */
268
364
  export function formatConfigIssues(config: MarketingConfig, issues: readonly ConfigIssue[]): string {
269
365
  return formatIssues(config.file, issues);
@@ -12,9 +12,9 @@ import {
12
12
  resolveLayout,
13
13
  type LayoutName,
14
14
  } from "../compose/timeline.js";
15
- import { MARKETING_LOCALES, type MarketingLocale } from "../messages/index.js";
16
15
  import { bigNumberDataSchema, carouselDataSchema, headlineChartDataSchema, headlineCtaDataSchema } from "../og/templates/schemas.js";
17
16
  import { CHANNEL_CODE_MAX_LENGTH, CHANNEL_CODE_PATTERN, DEFAULT_LINK_IN_BIO, PLATFORMS } from "../platforms.js";
17
+ import { CLIP_FITS, CLIP_ROLES, CUT_TRANSITIONS } from "../footage/film.js";
18
18
  import { ELEVENLABS_DEFAULT_MODEL } from "../voice/voiceover.js";
19
19
  import { actionSchema, type SceneAction } from "./actions-schema.js";
20
20
  import { COLOR_ROLES, COLOR_THEMES, isHexColor, type ColorRole } from "./colors.js";
@@ -77,11 +77,6 @@ function isKnownTimezone(zone: string): boolean {
77
77
  }
78
78
  }
79
79
 
80
- function hasMessages(locale: string): boolean {
81
- const language = locale.split("-")[0];
82
- return MARKETING_LOCALES.some((known: MarketingLocale) => known === language);
83
- }
84
-
85
80
  function getWords(sentence: string): string[] {
86
81
  return sentence.split(/\s+/).map((word) => word.replace(/[.,?!:;]/g, ""));
87
82
  }
@@ -145,13 +140,43 @@ const roleTokensShape = Object.fromEntries(
145
140
  z.ZodOptional<typeof tokenName>
146
141
  >;
147
142
 
143
+ const messageText = (key: string) => nonEmpty.optional().describe(`src/messages/en.ts ${key}; English when left out.`);
144
+
145
+ /** The built-in copy (`src/messages/en.ts`), every key optional: the app's own translation or changed English copy. */
146
+ const brandMessagesSchema = z
147
+ .strictObject({
148
+ posts: z
149
+ .strictObject({
150
+ title: messageText("posts.title: the heading of posts.md, {title} is the film's title"),
151
+ linkInBio: messageText("posts.linkInBio: the call to action where a caption link is not clickable"),
152
+ bioLink: messageText("posts.bioLink: the bio link line, {link}"),
153
+ postLink: messageText("posts.postLink: the post link line, {link}"),
154
+ platforms: z
155
+ .strictObject({
156
+ instagram: messageText("posts.platforms.instagram"),
157
+ facebook: messageText("posts.platforms.facebook"),
158
+ tiktok: messageText("posts.platforms.tiktok"),
159
+ youtube: messageText("posts.platforms.youtube"),
160
+ linkedin: messageText("posts.platforms.linkedin"),
161
+ x: messageText("posts.platforms.x"),
162
+ })
163
+ .optional()
164
+ .describe("The platform names in posts.md."),
165
+ })
166
+ .optional()
167
+ .describe("The copy of posts.md."),
168
+ film: z.strictObject({ persona: messageText("film.persona: the persona card's first line, {name} and {age}") }).optional().describe("The copy inside the film."),
169
+ })
170
+ .default({})
171
+ .describe("The copy of the posts and the film, every key optional (src/messages/en.ts): the product's own translation, or changed English copy. A key left out reads English.");
172
+
148
173
  const brandSchema = z.strictObject({
149
174
  name: nonEmpty.describe("The product's name, shown on the end card."),
150
175
  locale: z
151
176
  .string()
152
177
  .regex(LOCALE_PATTERN, "must be a BCP 47 locale such as en-US")
153
- .refine(hasMessages, `needs a language with message dictionaries: ${MARKETING_LOCALES.join(", ")}`)
154
- .describe(`BCP 47 locale (en-US): the recording browser's locale, <html lang> and the language of the copy. Its language needs a message dictionary: ${MARKETING_LOCALES.join(", ")}.`),
178
+ .describe("BCP 47 locale (en-US): the recording browser's locale and <html lang>. The copy is English unless brand.messages translates it."),
179
+ messages: brandMessagesSchema,
155
180
  timezone: z.string().refine(isKnownTimezone, "must be an IANA timezone such as Europe/London").describe("IANA zone of the recording browser, e.g. Europe/London."),
156
181
  logo: z
157
182
  .strictObject({ svg: relativePath.endsWith(".svg", "must be an .svg file").describe("The logo as an .svg file, relative to the folder of marketing.json.") })
@@ -426,6 +451,106 @@ const videoSchema = z
426
451
  });
427
452
  });
428
453
 
454
+ const endCardSchema = z
455
+ .strictObject({
456
+ headline: nonEmpty.describe("The end card's headline."),
457
+ url: nonEmpty.describe("The address shown in the end card's link pill, as written (e.g. example.com)."),
458
+ note: z.string().default("").describe("A small line under the link; empty: none."),
459
+ });
460
+
461
+ const clipSource = z
462
+ .string()
463
+ .min(1)
464
+ .describe("The clip: a path relative to the folder of marketing.json, or an https:// URL downloaded once into the build folder.");
465
+
466
+ const volume = z.number().min(0).max(1);
467
+
468
+ const footageSchema = z
469
+ .strictObject({
470
+ id: id.describe("The film's id: its folder under output.dir, unique across videos and footage; social.posts may name it."),
471
+ title: nonEmpty.describe("The film's title: the heading of its posts.md and the composition's <title>."),
472
+ format: z.enum(VIDEO_FORMATS).default("9:16").describe("The film's aspect ratio: 9:16 (1080×1920), 1:1 or 16:9; every clip is fitted to it."),
473
+ language: z
474
+ .string()
475
+ .regex(LANGUAGE_PATTERN, "must be an ISO 639 language code such as pl")
476
+ .optional()
477
+ .describe("ISO 639 code the clips speak (pl, en): the transcript's language and the default fillers; without it, voice.language."),
478
+ clips: z
479
+ .array(
480
+ z.strictObject({
481
+ id: id.describe("The clip's id, unique within the film; the EDL names clips by it."),
482
+ source: clipSource,
483
+ role: z.enum(CLIP_ROLES).default("talk").describe("talk: someone speaks, the cut follows the words; broll: pictures without speech, kept whole with a slow zoom."),
484
+ fit: z
485
+ .enum(CLIP_FITS)
486
+ .default("auto")
487
+ .describe("How a clip of another aspect fills the frame: crop (cover, edges cut), blur (the whole picture over a blurred copy) or auto (crop within 15 % of the frame's aspect, else blur)."),
488
+ trim: z
489
+ .strictObject({
490
+ start: z.number().min(0).default(0).describe("Seconds cut from the clip's start."),
491
+ end: z.number().positive().optional().describe("The second the clip ends at; without it, its own end."),
492
+ })
493
+ .prefault({})
494
+ .describe("The part of the clip the film uses."),
495
+ script: nonBlank
496
+ .optional()
497
+ .describe("What the clip says, for --placeholder only: its words spread evenly over the clip as a free stand-in transcript."),
498
+ }),
499
+ )
500
+ .min(1, "a footage film needs at least one clip")
501
+ .describe("The filmed clips in the film's order."),
502
+ isolateVoice: z.boolean().default(false).describe("Clean the talking clips' voice of background noise (ElevenLabs Voice Isolator, paid with --commit) before transcribing."),
503
+ fillers: z
504
+ .array(nonBlank)
505
+ .optional()
506
+ .describe("Filler words cut out of the talking clips, compared without case, punctuation and repeated letters; without it, the language's defaults (pl: yyy, eee, yhm and more; en: um, uh and more)."),
507
+ pauseSeconds: z.number().min(0.1).max(10).default(0.6).describe("A silence between two words longer than this is cut (0.1-10 s, default 0.6)."),
508
+ padSeconds: z.number().min(0).max(1).default(0.12).describe("Seconds kept around every cut (0-1, default 0.12)."),
509
+ maxSeconds: z.number().min(1).max(600).optional().describe("The cut's longest length in seconds; later segments are shortened or dropped."),
510
+ transitions: z
511
+ .strictObject({
512
+ jump: z.enum(CUT_TRANSITIONS).default("zoom").describe("A cut inside one talking clip: cut, fade, zoom (a punch-in, the default) or whoosh."),
513
+ clip: z.enum(CUT_TRANSITIONS).default("fade").describe("A cut from one clip to the next: cut, fade (the default), zoom or whoosh."),
514
+ })
515
+ .prefault({})
516
+ .describe("Default transitions by kind of cut; each segment of the EDL can name its own."),
517
+ music: z
518
+ .strictObject({
519
+ file: relativePath.optional().describe("A local music file, relative to the folder of marketing.json."),
520
+ prompt: nonBlank.optional().describe("A prompt for ElevenLabs Music (instrumental, paid with --commit, cached)."),
521
+ fromVideo: z
522
+ .strictObject({
523
+ description: z.string().max(4100).default("").describe("What the music should be like (up to 4100 characters)."),
524
+ tags: z.array(nonBlank).max(10).default([]).describe("Style tags such as upbeat or cinematic (up to 10)."),
525
+ })
526
+ .optional()
527
+ .describe("ElevenLabs Video to Music scored to the cut itself (paid with --commit, cached)."),
528
+ volume: volume.default(0.35).describe("The music's volume between sentences (0-1, default 0.35)."),
529
+ duckedVolume: volume.default(0.1).describe("The music's volume under speech (0-1, default 0.1)."),
530
+ })
531
+ .superRefine((music, context) => {
532
+ const sources = [music.file, music.prompt, music.fromVideo].filter((source) => source !== undefined).length;
533
+ if (sources !== 1) context.addIssue({ code: "custom", path: [], message: "needs exactly one of file, prompt or fromVideo" });
534
+ })
535
+ .optional()
536
+ .describe("Music under the film, ducked while someone speaks; without it, none."),
537
+ captions: z.boolean().default(true).describe("Word-by-word captions from the transcript (default true)."),
538
+ endCard: endCardSchema.optional().describe("The closing card after the last segment; without it, the film ends with its last segment."),
539
+ })
540
+ .superRefine((film, context) => {
541
+ const seen = new Set<string>();
542
+ film.clips.forEach((clip, index) => {
543
+ if (seen.has(clip.id)) context.addIssue({ code: "custom", path: ["clips", index, "id"], message: `"${clip.id}" appears twice` });
544
+ seen.add(clip.id);
545
+ if (clip.trim.end !== undefined && clip.trim.end <= clip.trim.start) {
546
+ context.addIssue({ code: "custom", path: ["clips", index, "trim", "end"], message: "must be after trim.start" });
547
+ }
548
+ if (/^[a-z]+:\/\//i.test(clip.source) && !/^https?:\/\//i.test(clip.source)) {
549
+ context.addIssue({ code: "custom", path: ["clips", index, "source"], message: "a URL must start with https:// or http://" });
550
+ }
551
+ });
552
+ });
553
+
429
554
  const LINK_IN_BIO_DEFAULTS = PLATFORMS.filter((platform) => DEFAULT_LINK_IN_BIO[platform]).join(", ");
430
555
 
431
556
  const socialSchema = z.strictObject({
@@ -722,7 +847,8 @@ export const marketingSchema = z
722
847
  brand: brandSchema.describe("The product's name, language, colours, fonts and logo."),
723
848
  app: appSchema.describe("The app the films and screenshots are recorded from."),
724
849
  voice: voiceSchema.describe("The voiceover: provider, voice, language and the paid cache."),
725
- videos: z.array(videoSchema).min(1, "needs at least one video").describe("The films, at least one."),
850
+ videos: z.array(videoSchema).describe("The screen films recorded from the app (may be empty when footage has a film); videos and footage hold at least one film between them."),
851
+ footage: z.array(footageSchema).default([]).describe("Footage films cut from filmed clips (softure-marketing footage)."),
726
852
  social: socialSchema.optional().describe("Post copy for the films: the link, the platforms and their channel codes."),
727
853
  screenshots: z.array(screenshotSchema).default([]).describe("Screenshots taken by softure-marketing shots."),
728
854
  signIn: signInSchema
@@ -743,7 +869,7 @@ export const marketingSchema = z
743
869
  .describe("Where the outputs go and at what quality."),
744
870
  })
745
871
  .superRefine((config, context) => {
746
- const checkUnique = (key: "videos" | "screenshots" | "ogImages") => {
872
+ const checkUnique = (key: "videos" | "footage" | "screenshots" | "ogImages") => {
747
873
  const seen = new Set<string>();
748
874
  config[key].forEach((entry, index) => {
749
875
  if (seen.has(entry.id)) context.addIssue({ code: "custom", path: [key, index, "id"], message: `"${entry.id}" appears twice` });
@@ -751,6 +877,14 @@ export const marketingSchema = z
751
877
  });
752
878
  };
753
879
  checkUnique("videos");
880
+ checkUnique("footage");
881
+ if (config.videos.length === 0 && config.footage.length === 0) {
882
+ context.addIssue({ code: "custom", path: ["videos"], message: "needs at least one video, here or in footage" });
883
+ }
884
+ const screenIds = new Set(config.videos.map((video) => video.id));
885
+ config.footage.forEach((film, index) => {
886
+ if (screenIds.has(film.id)) context.addIssue({ code: "custom", path: ["footage", index, "id"], message: `"${film.id}" is also a video's id; both would write ${film.id}/` });
887
+ });
754
888
  config.videos.forEach((video, index) => {
755
889
  const device = video.device ?? config.app.device;
756
890
  if (device.kind === "desktop" && video.format !== "16:9") {
@@ -791,11 +925,11 @@ export const marketingSchema = z
791
925
  if (data !== undefined) context.addIssue({ code: "custom", path, message: `{data:${data.key}} needs signIn.prepare, the command that prints the data` });
792
926
  }
793
927
  }
794
- const videoIds = new Set(config.videos.map((video) => video.id));
928
+ const videoIds = new Set([...config.videos, ...config.footage].map((video) => video.id));
795
929
  const posted = new Set<string>();
796
930
  config.social?.posts.forEach((post, index) => {
797
931
  if (!videoIds.has(post.video)) {
798
- context.addIssue({ code: "custom", path: ["social", "posts", index, "video"], message: `no video "${post.video}" in videos` });
932
+ context.addIssue({ code: "custom", path: ["social", "posts", index, "video"], message: `no video "${post.video}" in videos or footage` });
799
933
  }
800
934
  if (posted.has(post.video)) context.addIssue({ code: "custom", path: ["social", "posts", index, "video"], message: `"${post.video}" has two posts` });
801
935
  posted.add(post.video);
@@ -0,0 +1,66 @@
1
+ import { createHash } from "node:crypto";
2
+ import { createReadStream, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
3
+ import { dirname, join } from "node:path";
4
+
5
+ import type { TimedWord } from "../voice/voiceover.js";
6
+
7
+ /**
8
+ * The paid footage cache: what a provider returned, stored under a key made of the input's bytes and every setting
9
+ * that changes the answer, so a re-render never pays twice and a changed clip is never served a stale result. Files
10
+ * live in `<cacheDir>/<film id>/` (the project commits them, as it commits the voiceover).
11
+ */
12
+
13
+ export type FootageCacheKind = "transcript" | "isolated" | "music";
14
+
15
+ const SUFFIXES: Record<FootageCacheKind, string> = { transcript: "transcript.json", isolated: "isolated.mp3", music: "music.mp3" };
16
+
17
+ /** SHA-256 of a file's bytes, streamed (phone clips are large). */
18
+ export async function hashFile(path: string): Promise<string> {
19
+ const hash = createHash("sha256");
20
+ for await (const chunk of createReadStream(path)) hash.update(chunk as Buffer);
21
+ return hash.digest("hex");
22
+ }
23
+
24
+ /** A cache key: the first 16 hex digits of the SHA-256 of the parts as JSON. */
25
+ export function footageCacheKey(kind: FootageCacheKind, parts: Record<string, unknown>): string {
26
+ return createHash("sha256")
27
+ .update(JSON.stringify({ kind, ...parts }))
28
+ .digest("hex")
29
+ .slice(0, 16);
30
+ }
31
+
32
+ export function getFootageCachePath(cacheDir: string, filmId: string, kind: FootageCacheKind, key: string): string {
33
+ return join(cacheDir, filmId, `${key}.${SUFFIXES[kind]}`);
34
+ }
35
+
36
+ export function writeCacheFile(path: string, data: Buffer | string): void {
37
+ mkdirSync(dirname(path), { recursive: true });
38
+ writeFileSync(path, data);
39
+ }
40
+
41
+ function isTimedWords(value: unknown): value is TimedWord[] {
42
+ return (
43
+ Array.isArray(value) &&
44
+ value.every((item: unknown) => {
45
+ if (typeof item !== "object" || item === null) return false;
46
+ const word = item as Record<string, unknown>;
47
+ return typeof word.text === "string" && typeof word.start === "number" && typeof word.end === "number";
48
+ })
49
+ );
50
+ }
51
+
52
+ /** A cached transcript; null when there is none, an error naming a broken file. */
53
+ export function readCachedTranscript(path: string): { ok: true; words: TimedWord[] | null } | { ok: false; error: string } {
54
+ if (!existsSync(path)) return { ok: true, words: null };
55
+ let words: unknown;
56
+ try {
57
+ words = JSON.parse(readFileSync(path, "utf8")) as unknown;
58
+ } catch (error) {
59
+ return { ok: false, error: `cannot read ${path}: ${String(error)}` };
60
+ }
61
+ return isTimedWords(words) ? { ok: true, words } : { ok: false, error: `${path} is not a list of timed words` };
62
+ }
63
+
64
+ export function writeTranscript(path: string, words: TimedWord[]): void {
65
+ writeCacheFile(path, `${JSON.stringify(words, null, 1)}\n`);
66
+ }