@softure-ai/marketing-kit 0.2.0 → 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 (108) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +108 -3
  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 +18 -1
  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 +16 -0
  22. package/dist/config/config.d.ts.map +1 -1
  23. package/dist/config/config.js +88 -0
  24. package/dist/config/config.js.map +1 -1
  25. package/dist/config/schema.d.ts +133 -70
  26. package/dist/config/schema.d.ts.map +1 -1
  27. package/dist/config/schema.js +110 -3
  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 +13 -1
  79. package/dist/index.d.ts.map +1 -1
  80. package/dist/index.js +15 -2
  81. package/dist/index.js.map +1 -1
  82. package/dist/render/render.d.ts +6 -0
  83. package/dist/render/render.d.ts.map +1 -1
  84. package/dist/render/render.js +1 -1
  85. package/dist/render/render.js.map +1 -1
  86. package/package.json +1 -1
  87. package/schema/marketing.schema.json +254 -2
  88. package/src/cli/footage.ts +87 -0
  89. package/src/cli/main.ts +17 -1
  90. package/src/cli/options.ts +51 -4
  91. package/src/compose/compose.ts +1 -25
  92. package/src/compose/html.ts +28 -0
  93. package/src/config/config.ts +97 -0
  94. package/src/config/schema.ts +114 -4
  95. package/src/footage/cache.ts +66 -0
  96. package/src/footage/compose.ts +213 -0
  97. package/src/footage/edl.ts +204 -0
  98. package/src/footage/elevenlabs.ts +154 -0
  99. package/src/footage/fake.ts +92 -0
  100. package/src/footage/film.ts +111 -0
  101. package/src/footage/music.ts +86 -0
  102. package/src/footage/normalize.ts +133 -0
  103. package/src/footage/pipeline.ts +447 -0
  104. package/src/footage/probe.ts +172 -0
  105. package/src/footage/providers.ts +71 -0
  106. package/src/footage/render.ts +82 -0
  107. package/src/index.ts +109 -1
  108. package/src/render/render.ts +1 -1
@@ -3,6 +3,8 @@ 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 { DEFAULT_MUSIC_VOLUME, getDefaultFillers, type FootageFilm, type MusicSource } from "../footage/film.js";
7
+ import type { LayoutOverride } from "../compose/timeline.js";
6
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";
@@ -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;
@@ -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);
@@ -226,6 +295,7 @@ export function loadMarketingConfig(path: string): LoadConfigResult {
226
295
  },
227
296
  voice: { provider: data.voice.provider, cacheDir: at(data.voice.cacheDir), minIntervalSeconds: data.voice.minIntervalSeconds, placeholder: data.voice.placeholder },
228
297
  videos: resolveVideos(data, at),
298
+ footage: resolveFootage(data, at),
229
299
  social: data.social === undefined ? null : { linkTemplate: data.social.linkTemplate },
230
300
  screenshots: data.screenshots,
231
301
  signIn: data.signIn ?? null,
@@ -263,6 +333,33 @@ export function findMissingFiles(config: MarketingConfig, video: VideoConfig, is
263
333
  return issues;
264
334
  }
265
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
+
266
363
  /** Problems found after loading, in the same format as the load errors. */
267
364
  export function formatConfigIssues(config: MarketingConfig, issues: readonly ConfigIssue[]): string {
268
365
  return formatIssues(config.file, issues);
@@ -14,6 +14,7 @@ import {
14
14
  } from "../compose/timeline.js";
15
15
  import { bigNumberDataSchema, carouselDataSchema, headlineChartDataSchema, headlineCtaDataSchema } from "../og/templates/schemas.js";
16
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";
17
18
  import { ELEVENLABS_DEFAULT_MODEL } from "../voice/voiceover.js";
18
19
  import { actionSchema, type SceneAction } from "./actions-schema.js";
19
20
  import { COLOR_ROLES, COLOR_THEMES, isHexColor, type ColorRole } from "./colors.js";
@@ -450,6 +451,106 @@ const videoSchema = z
450
451
  });
451
452
  });
452
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
+
453
554
  const LINK_IN_BIO_DEFAULTS = PLATFORMS.filter((platform) => DEFAULT_LINK_IN_BIO[platform]).join(", ");
454
555
 
455
556
  const socialSchema = z.strictObject({
@@ -746,7 +847,8 @@ export const marketingSchema = z
746
847
  brand: brandSchema.describe("The product's name, language, colours, fonts and logo."),
747
848
  app: appSchema.describe("The app the films and screenshots are recorded from."),
748
849
  voice: voiceSchema.describe("The voiceover: provider, voice, language and the paid cache."),
749
- 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)."),
750
852
  social: socialSchema.optional().describe("Post copy for the films: the link, the platforms and their channel codes."),
751
853
  screenshots: z.array(screenshotSchema).default([]).describe("Screenshots taken by softure-marketing shots."),
752
854
  signIn: signInSchema
@@ -767,7 +869,7 @@ export const marketingSchema = z
767
869
  .describe("Where the outputs go and at what quality."),
768
870
  })
769
871
  .superRefine((config, context) => {
770
- const checkUnique = (key: "videos" | "screenshots" | "ogImages") => {
872
+ const checkUnique = (key: "videos" | "footage" | "screenshots" | "ogImages") => {
771
873
  const seen = new Set<string>();
772
874
  config[key].forEach((entry, index) => {
773
875
  if (seen.has(entry.id)) context.addIssue({ code: "custom", path: [key, index, "id"], message: `"${entry.id}" appears twice` });
@@ -775,6 +877,14 @@ export const marketingSchema = z
775
877
  });
776
878
  };
777
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
+ });
778
888
  config.videos.forEach((video, index) => {
779
889
  const device = video.device ?? config.app.device;
780
890
  if (device.kind === "desktop" && video.format !== "16:9") {
@@ -815,11 +925,11 @@ export const marketingSchema = z
815
925
  if (data !== undefined) context.addIssue({ code: "custom", path, message: `{data:${data.key}} needs signIn.prepare, the command that prints the data` });
816
926
  }
817
927
  }
818
- const videoIds = new Set(config.videos.map((video) => video.id));
928
+ const videoIds = new Set([...config.videos, ...config.footage].map((video) => video.id));
819
929
  const posted = new Set<string>();
820
930
  config.social?.posts.forEach((post, index) => {
821
931
  if (!videoIds.has(post.video)) {
822
- 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` });
823
933
  }
824
934
  if (posted.has(post.video)) context.addIssue({ code: "custom", path: ["social", "posts", index, "video"], message: `"${post.video}" has two posts` });
825
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
+ }
@@ -0,0 +1,213 @@
1
+ import type { BrandColors } from "../config/colors.js";
2
+ import type { SfxEvent } from "../config/schema.js";
3
+ import type { ComposeFont } from "../compose/compose.js";
4
+ import { escapeHtml, fontFaces, fontStack } from "../compose/html.js";
5
+ import { captionChunks, type CaptionLayout } from "../compose/timeline.js";
6
+ import type { TimedWord } from "../voice/voiceover.js";
7
+ import { getEdlDuration, getSegmentStarts, type Edl } from "./edl.js";
8
+ import type { FootageFilm } from "./film.js";
9
+
10
+ /**
11
+ * The HyperFrames composition of a footage film (the same 0.8.85 contract as `composeFilm`): one `<video>` clip per
12
+ * EDL segment over the normalized clip with its media start, the transitions (`fade` cross-fades from the segment
13
+ * before, `zoom` punches in on alternate jump cuts, `whoosh` plays the whoosh sound), a slow zoom on b-roll, the
14
+ * word-by-word captions, the end card over the cut's last frame, the cut speech track and the ducked music.
15
+ */
16
+
17
+ const COMPOSITION_ID = "film";
18
+ /** A cross-fade's length; the outgoing segment plays on under the incoming one for this long. */
19
+ export const FADE_SECONDS = 0.35;
20
+ /** The punch-in of a `zoom` cut. */
21
+ const ZOOM_SCALE = 1.12;
22
+ /** How far a b-roll segment zooms over its length. */
23
+ const KEN_BURNS_SCALE = 1.08;
24
+ /** The end card's length after the cut. */
25
+ export const END_CARD_SECONDS = 3;
26
+
27
+ export interface FootageComposeAssets {
28
+ /** The normalized clips by id. */
29
+ clips: Record<string, string>;
30
+ /** The cut speech track (as long as the cut). */
31
+ speech: string;
32
+ /** The ducked music track, or null for none. */
33
+ music: string | null;
34
+ /** The cut's last frame, under the end card. */
35
+ lastFrame: string;
36
+ logo: string | null;
37
+ sfx: Partial<Record<SfxEvent, string>>;
38
+ }
39
+
40
+ export interface FootageComposeInput {
41
+ film: FootageFilm;
42
+ edl: Edl;
43
+ /** The film's words in film time (`remapWords`), for the captions. */
44
+ words: TimedWord[];
45
+ frame: { width: number; height: number };
46
+ caption: CaptionLayout;
47
+ /** The end card's headline size. */
48
+ headlineSize: number;
49
+ colors: BrandColors;
50
+ fonts: { heading: ComposeFont | null; body: ComposeFont | null };
51
+ assets: FootageComposeAssets;
52
+ brandName: string;
53
+ locale: string;
54
+ }
55
+
56
+ const r3 = (value: number): number => Math.round(value * 1000) / 1000 || 0;
57
+
58
+ /** The film's length: the cut plus the end card. */
59
+ export function getFootageFilmSeconds(film: Pick<FootageFilm, "endCard">, edl: Edl): number {
60
+ return r3(getEdlDuration(edl) + (film.endCard === null ? 0 : END_CARD_SECONDS));
61
+ }
62
+
63
+ /** The picture scale each segment starts at: `zoom` cuts alternate between punched in and back out. */
64
+ export function getSegmentScales(edl: Edl): number[] {
65
+ const scales: number[] = [];
66
+ edl.segments.forEach((segment, index) => {
67
+ const previous = scales[index - 1] ?? 1;
68
+ scales.push(segment.transition === "zoom" && index > 0 ? (previous === 1 ? ZOOM_SCALE : 1) : 1);
69
+ });
70
+ return scales;
71
+ }
72
+
73
+ export function composeFootage(input: FootageComposeInput): string {
74
+ const { film, edl, words, frame, colors: c, fonts, assets, caption: captionBox } = input;
75
+ const starts = getSegmentStarts(edl);
76
+ const cutEnd = getEdlDuration(edl);
77
+ const end = getFootageFilmSeconds(film, edl);
78
+ const scales = getSegmentScales(edl);
79
+
80
+ const segments = edl.segments.map((segment, index) => {
81
+ const src = assets.clips[segment.clip];
82
+ if (src === undefined) throw new Error(`The EDL names clip "${segment.clip}", which the film has no file for.`);
83
+ const next = edl.segments[index + 1];
84
+ const tail = next?.transition === "fade" ? FADE_SECONDS : 0;
85
+ const start = starts[index] as number;
86
+ const duration = r3(segment.end - segment.start + tail);
87
+ const scale = scales[index] as number;
88
+ const style = scale === 1 ? "" : ` style="transform:scale(${scale})"`;
89
+ return `<video id="seg${index}" class="clip shot" src="${escapeHtml(src)}" data-start="${start}" data-media-start="${segment.start}" data-duration="${duration}"${style} muted playsinline></video>`;
90
+ });
91
+
92
+ const tweens: string[] = [];
93
+ edl.segments.forEach((segment, index) => {
94
+ const start = starts[index] as number;
95
+ if (segment.transition === "fade" && index > 0) {
96
+ tweens.push(`tl.fromTo("#seg${index}", { opacity: 0 }, { opacity: 1, duration: ${FADE_SECONDS}, ease: "none", immediateRender: false }, ${start});`);
97
+ }
98
+ if (segment.motion === "kenburns") {
99
+ const from = scales[index] as number;
100
+ tweens.push(
101
+ `tl.fromTo("#seg${index}", { scale: ${from} }, { scale: ${r3(from * KEN_BURNS_SCALE)}, duration: ${r3(segment.end - segment.start)}, ease: "none", immediateRender: false }, ${start});`,
102
+ );
103
+ }
104
+ });
105
+
106
+ // --- Captions ---
107
+ const caption = input.film.captions ? captionChunks(words) : [];
108
+ const captionHtml = caption
109
+ .map((chunk, i) => {
110
+ const next = caption[i + 1];
111
+ const start = r3(chunk.start - 0.05);
112
+ const stop = Math.min(chunk.end + 0.35, next === undefined ? cutEnd : next.start - 0.06);
113
+ const spans = chunk.words.map((w, j) => `<span id="cw${i}_${j}">${escapeHtml(w.text)}</span>`).join(" ");
114
+ return `<div id="cap${i}" class="clip caption" data-start="${start}" data-duration="${r3(Math.max(0.1, stop - start))}"><p class="pill">${spans}</p></div>`;
115
+ })
116
+ .join("\n ");
117
+
118
+ // --- Sound ---
119
+ const sfx: { src: string; t: number; volume: number; dur: number }[] = [];
120
+ const play = (event: SfxEvent, t: number, volume: number, dur: number) => {
121
+ const src = assets.sfx[event];
122
+ if (src !== undefined) sfx.push({ src, t: r3(Math.max(0, t)), volume, dur });
123
+ };
124
+ edl.segments.forEach((segment, index) => {
125
+ if (segment.transition === "whoosh" && index > 0) play("whoosh", (starts[index] as number) - 0.1, 0.45, 0.57);
126
+ });
127
+ if (film.endCard !== null) {
128
+ play("whoosh", cutEnd, 0.3, 0.57);
129
+ play("pop", r3(cutEnd + 0.9), 0.35, 0.72);
130
+ }
131
+ const audio = [
132
+ `<audio id="speech" src="${escapeHtml(assets.speech)}" data-start="0" data-duration="${cutEnd}" data-volume="1"></audio>`,
133
+ ...(assets.music === null ? [] : [`<audio id="music" src="${escapeHtml(assets.music)}" data-start="0" data-duration="${end}" data-volume="1"></audio>`]),
134
+ ...sfx.map((s, i) => `<audio id="sfx${i}" src="${escapeHtml(s.src)}" data-start="${s.t}" data-duration="${s.dur}" data-volume="${s.volume}"></audio>`),
135
+ ].join("\n ");
136
+
137
+ const tail = r3(end - cutEnd);
138
+ const endCard = film.endCard;
139
+ const endCardHtml =
140
+ endCard === null
141
+ ? ""
142
+ : `<img id="last" class="clip shot" src="${escapeHtml(assets.lastFrame)}" data-start="${cutEnd}" data-duration="${tail}" />
143
+ <div class="shade" id="shade"></div>
144
+ <div class="endcard">
145
+ <div class="brand" id="ec-brand">${assets.logo === null ? "" : `<img class="logo" src="${escapeHtml(assets.logo)}" alt="" />`}<span>${escapeHtml(input.brandName)}</span></div>
146
+ <p class="headline" id="ec-headline">${escapeHtml(endCard.headline)}</p>
147
+ <p class="url" id="ec-url">${escapeHtml(endCard.url)}</p>
148
+ ${endCard.note.length > 0 ? `<p class="note" id="ec-note">${escapeHtml(endCard.note)}</p>` : ""}
149
+ </div>`;
150
+ const endCardTweens =
151
+ endCard === null
152
+ ? []
153
+ : [
154
+ `tl.fromTo("#shade", { opacity: 0 }, { opacity: 0.82, duration: 0.45, ease: "power2.out" }, ${cutEnd});`,
155
+ `tl.fromTo("#ec-brand", { y: 30, opacity: 0 }, { y: 0, opacity: 1, duration: 0.5, ease: "power3.out" }, ${r3(cutEnd + 0.3)});`,
156
+ `tl.fromTo("#ec-headline", { y: 40, opacity: 0 }, { y: 0, opacity: 1, duration: 0.6, ease: "power3.out" }, ${r3(cutEnd + 0.45)});`,
157
+ `tl.fromTo("#ec-url", { y: 30, opacity: 0, scale: 0.94 }, { y: 0, opacity: 1, scale: 1, duration: 0.55, ease: "power3.out" }, ${r3(cutEnd + 0.9)});`,
158
+ ...(endCard.note.length > 0 ? [`tl.fromTo("#ec-note", { opacity: 0 }, { opacity: 1, duration: 0.5, ease: "power2.out" }, ${r3(cutEnd + 1.3)});`] : []),
159
+ ];
160
+
161
+ const bodyFont = fontStack(fonts.body, "sans-serif");
162
+ const headingFont = fonts.heading === null ? bodyFont : fontStack(fonts.heading, "sans-serif");
163
+ const faces = [...fontFaces(fonts.body), ...fontFaces(fonts.heading)];
164
+
165
+ return `<!doctype html>
166
+ <html lang="${escapeHtml(input.locale)}">
167
+ <head>
168
+ <meta charset="UTF-8" />
169
+ <meta name="viewport" content="width=${frame.width}, height=${frame.height}" />
170
+ <title>${escapeHtml(film.title)}</title>
171
+ <script src="assets/gsap.min.js"></script>
172
+ <style>
173
+ ${faces.join("\n")}
174
+ *{margin:0;padding:0;box-sizing:border-box}
175
+ html,body{width:${frame.width}px;height:${frame.height}px;overflow:hidden;background:#000}
176
+ #root{position:relative;width:${frame.width}px;height:${frame.height}px;overflow:hidden;background:#000;font-family:${bodyFont};color:${c.foreground}}
177
+ .shot{position:absolute;inset:0;width:100%;height:100%;object-fit:cover;transform-origin:50% 42%}
178
+ .shade{position:absolute;inset:0;background:${c.background};opacity:0}
179
+ .caption{position:absolute;left:${captionBox.left}px;right:${captionBox.right}px;top:${captionBox.top}px;display:flex;justify-content:center}
180
+ .pill{font-weight:650;font-size:${captionBox.fontSize}px;line-height:1.18;letter-spacing:-.01em;text-align:center;padding:16px 28px;border-radius:22px;background:${c.captionBackground};box-shadow:0 14px 44px rgba(0,0,0,.5);color:${c.captionText}}
181
+ .pill span{display:inline-block}
182
+ .endcard{position:absolute;inset:0;display:flex;flex-direction:column;justify-content:center;align-items:center;padding:0 80px;text-align:center}
183
+ .brand{display:flex;justify-content:center;align-items:center;gap:18px;font-family:${headingFont};font-size:46px}
184
+ .logo{height:60px;width:auto}
185
+ .headline{font-family:${headingFont};font-weight:500;font-size:${input.headlineSize}px;letter-spacing:-.025em;line-height:1.02;margin-top:44px}
186
+ .url{display:inline-block;margin-top:40px;padding:20px 38px;border-radius:999px;font-size:44px;font-weight:600;color:${c.onCta};background:${c.cta}}
187
+ .note{margin-top:26px;font-size:30px;color:${c.muted}}
188
+ </style>
189
+ </head>
190
+ <body>
191
+ <div id="root" data-composition-id="${COMPOSITION_ID}" data-start="0" data-duration="${end}" data-width="${frame.width}" data-height="${frame.height}">
192
+ ${segments.join("\n ")}
193
+ ${endCardHtml}
194
+ ${captionHtml}
195
+ ${audio}
196
+ </div>
197
+ <script>
198
+ const tl = gsap.timeline({ paused: true });
199
+ ${tweens.join("\n")}
200
+ const captions = ${JSON.stringify(caption.map((chunk) => chunk.words.map((w) => w.start)))};
201
+ captions.forEach((words, i) => {
202
+ tl.fromTo("#cap" + i + " .pill", { y: 14, opacity: 0 }, { y: 0, opacity: 1, duration: 0.16, ease: "power3.out" }, Math.max(0, words[0] - 0.05));
203
+ words.forEach((t, j) => tl.fromTo("#cw" + i + "_" + j, { color: "${c.captionText}" }, { color: "${c.captionHighlight}", duration: 0.06, immediateRender: false }, t).to("#cw" + i + "_" + j, { color: "${c.captionText}", duration: 0.2 }, t + 0.32));
204
+ });
205
+ ${endCardTweens.join("\n")}
206
+ tl.set({}, {}, ${end});
207
+ window.__timelines = window.__timelines || {};
208
+ window.__timelines["${COMPOSITION_ID}"] = tl;
209
+ </script>
210
+ </body>
211
+ </html>
212
+ `;
213
+ }