@softure-ai/marketing-kit 0.3.1 → 0.5.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 (126) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/README.md +135 -14
  3. package/dist/cli/footage.d.ts.map +1 -1
  4. package/dist/cli/footage.js +15 -6
  5. package/dist/cli/footage.js.map +1 -1
  6. package/dist/config/actions-schema.d.ts +14 -14
  7. package/dist/config/config.d.ts.map +1 -1
  8. package/dist/config/config.js +5 -0
  9. package/dist/config/config.js.map +1 -1
  10. package/dist/config/schema.d.ts +92 -69
  11. package/dist/config/schema.d.ts.map +1 -1
  12. package/dist/config/schema.js +40 -4
  13. package/dist/config/schema.js.map +1 -1
  14. package/dist/config/shot-steps.d.ts +16 -16
  15. package/dist/footage/audio.d.ts +52 -0
  16. package/dist/footage/audio.d.ts.map +1 -0
  17. package/dist/footage/audio.js +100 -0
  18. package/dist/footage/audio.js.map +1 -0
  19. package/dist/footage/captions.d.ts +57 -0
  20. package/dist/footage/captions.d.ts.map +1 -0
  21. package/dist/footage/captions.js +112 -0
  22. package/dist/footage/captions.js.map +1 -0
  23. package/dist/footage/compose.d.ts +5 -5
  24. package/dist/footage/compose.d.ts.map +1 -1
  25. package/dist/footage/compose.js +31 -22
  26. package/dist/footage/compose.js.map +1 -1
  27. package/dist/footage/edl.d.ts +54 -16
  28. package/dist/footage/edl.d.ts.map +1 -1
  29. package/dist/footage/edl.js +204 -52
  30. package/dist/footage/edl.js.map +1 -1
  31. package/dist/footage/elevenlabs.d.ts +4 -1
  32. package/dist/footage/elevenlabs.d.ts.map +1 -1
  33. package/dist/footage/elevenlabs.js +18 -6
  34. package/dist/footage/elevenlabs.js.map +1 -1
  35. package/dist/footage/fake.d.ts +2 -0
  36. package/dist/footage/fake.d.ts.map +1 -1
  37. package/dist/footage/fake.js +2 -1
  38. package/dist/footage/fake.js.map +1 -1
  39. package/dist/footage/film.d.ts +35 -1
  40. package/dist/footage/film.d.ts.map +1 -1
  41. package/dist/footage/film.js +9 -1
  42. package/dist/footage/film.js.map +1 -1
  43. package/dist/footage/frames.d.ts +38 -0
  44. package/dist/footage/frames.d.ts.map +1 -0
  45. package/dist/footage/frames.js +40 -0
  46. package/dist/footage/frames.js.map +1 -0
  47. package/dist/footage/loudness.d.ts +49 -0
  48. package/dist/footage/loudness.d.ts.map +1 -0
  49. package/dist/footage/loudness.js +114 -0
  50. package/dist/footage/loudness.js.map +1 -0
  51. package/dist/footage/normalize.d.ts +6 -2
  52. package/dist/footage/normalize.d.ts.map +1 -1
  53. package/dist/footage/normalize.js +7 -9
  54. package/dist/footage/normalize.js.map +1 -1
  55. package/dist/footage/paid.d.ts +70 -0
  56. package/dist/footage/paid.d.ts.map +1 -0
  57. package/dist/footage/paid.js +172 -0
  58. package/dist/footage/paid.js.map +1 -0
  59. package/dist/footage/pipeline.d.ts +34 -10
  60. package/dist/footage/pipeline.d.ts.map +1 -1
  61. package/dist/footage/pipeline.js +294 -85
  62. package/dist/footage/pipeline.js.map +1 -1
  63. package/dist/footage/probe.d.ts +18 -4
  64. package/dist/footage/probe.d.ts.map +1 -1
  65. package/dist/footage/probe.js +18 -13
  66. package/dist/footage/probe.js.map +1 -1
  67. package/dist/footage/process.d.ts +45 -0
  68. package/dist/footage/process.d.ts.map +1 -0
  69. package/dist/footage/process.js +109 -0
  70. package/dist/footage/process.js.map +1 -0
  71. package/dist/footage/providers.d.ts +49 -5
  72. package/dist/footage/providers.d.ts.map +1 -1
  73. package/dist/footage/providers.js +4 -0
  74. package/dist/footage/providers.js.map +1 -1
  75. package/dist/footage/publish.d.ts +62 -0
  76. package/dist/footage/publish.d.ts.map +1 -0
  77. package/dist/footage/publish.js +164 -0
  78. package/dist/footage/publish.js.map +1 -0
  79. package/dist/footage/render.d.ts +5 -4
  80. package/dist/footage/render.d.ts.map +1 -1
  81. package/dist/footage/render.js +29 -17
  82. package/dist/footage/render.js.map +1 -1
  83. package/dist/footage/sentences.d.ts +44 -0
  84. package/dist/footage/sentences.d.ts.map +1 -0
  85. package/dist/footage/sentences.js +102 -0
  86. package/dist/footage/sentences.js.map +1 -0
  87. package/dist/footage/tools.d.ts +33 -0
  88. package/dist/footage/tools.d.ts.map +1 -0
  89. package/dist/footage/tools.js +108 -0
  90. package/dist/footage/tools.js.map +1 -0
  91. package/dist/footage/words.d.ts +6 -0
  92. package/dist/footage/words.d.ts.map +1 -0
  93. package/dist/footage/words.js +14 -0
  94. package/dist/footage/words.js.map +1 -0
  95. package/dist/index.d.ts +15 -6
  96. package/dist/index.d.ts.map +1 -1
  97. package/dist/index.js +15 -6
  98. package/dist/index.js.map +1 -1
  99. package/docker/footage-worker.Dockerfile +29 -0
  100. package/package.json +2 -1
  101. package/schema/edl.schema.json +115 -0
  102. package/schema/marketing.schema.json +112 -5
  103. package/src/cli/footage.ts +13 -5
  104. package/src/config/config.ts +5 -0
  105. package/src/config/schema.ts +40 -4
  106. package/src/footage/audio.ts +123 -0
  107. package/src/footage/captions.ts +146 -0
  108. package/src/footage/compose.ts +32 -24
  109. package/src/footage/edl.ts +225 -56
  110. package/src/footage/elevenlabs.ts +21 -8
  111. package/src/footage/fake.ts +4 -1
  112. package/src/footage/film.ts +43 -2
  113. package/src/footage/frames.ts +65 -0
  114. package/src/footage/loudness.ts +143 -0
  115. package/src/footage/normalize.ts +7 -9
  116. package/src/footage/paid.ts +213 -0
  117. package/src/footage/pipeline.ts +344 -89
  118. package/src/footage/probe.ts +20 -12
  119. package/src/footage/process.ts +135 -0
  120. package/src/footage/providers.ts +56 -6
  121. package/src/footage/publish.ts +180 -0
  122. package/src/footage/render.ts +29 -19
  123. package/src/footage/sentences.ts +137 -0
  124. package/src/footage/tools.ts +119 -0
  125. package/src/footage/words.ts +15 -0
  126. package/src/index.ts +84 -0
@@ -3,9 +3,10 @@ import { join } from "node:path";
3
3
 
4
4
  import { findFootage, findMissingFootageFiles, formatConfigIssues, type FootageConfig, type MarketingConfig } from "../config/config.js";
5
5
  import { createElevenLabsFootageProviders } from "../footage/elevenlabs.js";
6
- import { cutFootage, getEdlPath, prepareFootage, readEdlFile, renderFootage, transcribeFootage, type RenderFootageOptions } from "../footage/pipeline.js";
6
+ import { findRetakes } from "../footage/sentences.js";
7
+ import { cutFootage, getEdlPath, getFootageSentences, prepareFootage, readEdlFile, renderFootage, transcribeFootage, type RenderFootageOptions } from "../footage/pipeline.js";
8
+ import { checkFootageTools } from "../footage/tools.js";
7
9
  import { postsMarkdown } from "../posts/posts.js";
8
- import { findMachineProblem } from "../render/preflight.js";
9
10
  import { fail } from "./failure.js";
10
11
  import type { FootageOptions } from "./options.js";
11
12
 
@@ -47,8 +48,9 @@ export async function runFootage(config: MarketingConfig, options: FootageOption
47
48
  const film = findFootage(config, options.filmId);
48
49
  if (film === null) fail(`no footage film "${options.filmId}" in ${config.file}. Available: ${config.footage.map((entry) => entry.id).join(", ") || "none"}.`);
49
50
  const needsRender = options.step === "all" || options.step === "render";
50
- const problem = findMachineProblem({ needsRender, cwd: config.root });
51
- if (problem !== null) fail(problem);
51
+ // On a developer's machine hyperframes' first render downloads its browser; a worker image is checked without that.
52
+ const problems = await checkFootageTools({ needsRender, isBrowserDownloadAllowed: true });
53
+ if (problems.length > 0) fail(problems.join("\n"));
52
54
  const missing = findMissingFootageFiles(config, film, needsRender);
53
55
  if (missing.length > 0) fail(formatConfigIssues(config, missing));
54
56
  const run = getRunOptions(config, film, options);
@@ -69,6 +71,10 @@ export async function runFootage(config: MarketingConfig, options: FootageOption
69
71
  if (isRecut) {
70
72
  edl = cutFootage(film, clips.value, transcript.value.words, edlPath);
71
73
  console.log(`cut: ${edl.segments.length} segments written to ${edlPath}; check or edit it, then softure-marketing footage ${film.id} --step=render.`);
74
+ // Suggestions only: the EDL keeps every sentence until someone drops one.
75
+ for (const suggestion of findRetakes(getFootageSentences(clips.value, transcript.value.words))) {
76
+ console.log(` maybe drop ${suggestion.sentence} (${suggestion.kind}): ${suggestion.reason}`);
77
+ }
72
78
  if (options.step === "cut") return;
73
79
  } else {
74
80
  if (!existsSync(edlPath)) fail(`no EDL at ${edlPath}: run softure-marketing footage ${film.id} --step=cut first.`);
@@ -80,8 +86,10 @@ export async function runFootage(config: MarketingConfig, options: FootageOption
80
86
  const rendered = await renderFootage(film, clips.value, transcript.value, edl, run);
81
87
  if (!rendered.ok) fail(rendered.error);
82
88
  if (rendered.value.kind === "dry-run") return;
83
- const { output, seconds } = rendered.value;
89
+ const { output, seconds, bytes, width, height, durationSeconds, cover } = rendered.value;
84
90
  console.log(`\n✓ ${output} (${seconds.toFixed(1)} s, ${film.format})`);
91
+ console.log(` ${width}×${height}, ${durationSeconds.toFixed(2)} s, ${(bytes / 1_000_000).toFixed(1)} MB, H.264 High, AAC 48 kHz stereo, fast start`);
92
+ if (cover !== null) console.log(`✓ ${cover}: cover`);
85
93
  const posts = writeFootagePosts(config, film);
86
94
  console.log(posts === null ? `no post copy: social.posts has no entry for "${film.id}" in ${config.file}.` : `✓ ${posts}: post copy`);
87
95
  }
@@ -230,7 +230,12 @@ function resolveFootage(data: MarketingJson, at: (relative: string) => string):
230
230
  ? { source: { kind: "none" }, ...DEFAULT_MUSIC_VOLUME }
231
231
  : { source: resolveMusicSource(film.music, at), volume: film.music.volume, duckedVolume: film.music.duckedVolume },
232
232
  captions: film.captions,
233
+ captionStyle: film.captionStyle,
234
+ ...(film.captionPreset === undefined ? {} : { captionPreset: film.captionPreset }),
235
+ edit: { zoomPercent: film.edit.zoomPercent, fadeFrames: film.edit.fadeFrames, kenBurnsPercent: film.edit.kenBurnsPercent, isEndCardWhoosh: film.edit.endCardWhoosh },
233
236
  endCard: film.endCard ?? null,
237
+ loudness: film.loudness === false ? null : film.loudness,
238
+ cover: film.cover === false ? null : film.cover,
234
239
  post:
235
240
  post === undefined
236
241
  ? null
@@ -14,7 +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
+ import { CAPTION_PRESETS, CAPTION_STYLES, 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";
@@ -509,8 +509,8 @@ const footageSchema = z
509
509
  maxSeconds: z.number().min(1).max(600).optional().describe("The cut's longest length in seconds; later segments are shortened or dropped."),
510
510
  transitions: z
511
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."),
512
+ jump: z.enum(CUT_TRANSITIONS).default("cut").describe("A cut inside one talking clip: cut (the default), fade, zoom (a punch-in) or whoosh."),
513
+ clip: z.enum(CUT_TRANSITIONS).default("cut").describe("A cut from one clip to the next: cut (the default), fade, zoom or whoosh."),
514
514
  })
515
515
  .prefault({})
516
516
  .describe("Default transitions by kind of cut; each segment of the EDL can name its own."),
@@ -534,8 +534,44 @@ const footageSchema = z
534
534
  })
535
535
  .optional()
536
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)."),
537
+ captions: z.boolean().default(true).describe("Captions from the transcript (default true)."),
538
+ captionStyle: z
539
+ .enum(CAPTION_STYLES)
540
+ .default("phrase")
541
+ .describe("phrase (the default): 2-6 words of plain text with a soft shadow; highlight: a pill that lights each word as it is said."),
542
+ captionPreset: z
543
+ .enum(CAPTION_PRESETS)
544
+ .optional()
545
+ .describe("Keeps a 9:16 film's captions inside a platform's safe zone: reels, shorts, tiktok or all; without it, layout decides."),
546
+ edit: z
547
+ .strictObject({
548
+ zoomPercent: z.number().min(105).max(110).default(108).describe("How far a zoom cut punches in (105-110 %, default 108)."),
549
+ fadeFrames: z.number().int().min(1).max(30).default(10).describe("A fade cut's length in frames at 30 fps (1-30, default 10)."),
550
+ kenBurnsPercent: z.number().min(0).max(5).default(0).describe("How far b-roll zooms over its length (0-5 %, default 0: still)."),
551
+ endCardWhoosh: z.boolean().default(false).describe("Play the whoosh and pop as the end card comes in (default false)."),
552
+ })
553
+ .prefault({})
554
+ .describe("The cut's look; the defaults read as an ordinary phone video."),
538
555
  endCard: endCardSchema.optional().describe("The closing card after the last segment; without it, the film ends with its last segment."),
556
+ loudness: z
557
+ .union([
558
+ z.literal(false),
559
+ z.strictObject({
560
+ target: z.number().min(-40).max(-5).default(-14).describe("Integrated loudness in LUFS (-40 to -5, default -14)."),
561
+ truePeak: z.number().min(-9).max(0).default(-1).describe("The highest true peak in dBTP (-9 to 0, default -1)."),
562
+ }),
563
+ ])
564
+ .default({ target: -14, truePeak: -1 })
565
+ .describe("The speech track's loudness, measured and normalized in two passes before the music goes under it; false leaves it as filmed. Default -14 LUFS, -1 dBTP."),
566
+ cover: z
567
+ .union([
568
+ z.literal(false),
569
+ z.strictObject({
570
+ at: z.number().min(0).optional().describe("The second of the film the cover is taken at; without it, the middle of the first talking segment."),
571
+ }),
572
+ ])
573
+ .default({})
574
+ .describe("The cover JPG written next to the film (its name with .jpg); false writes none."),
539
575
  })
540
576
  .superRefine((film, context) => {
541
577
  const seen = new Set<string>();
@@ -0,0 +1,123 @@
1
+ import { extname } from "node:path";
2
+ import { z } from "zod";
3
+
4
+ import { runFfprobe } from "./probe.js";
5
+
6
+ /**
7
+ * Music beds: the audio files an app accepts to lay quietly under the voice. One list of accepted types, checked the
8
+ * same way by an app's upload and by the footage pipeline's `music.file`, and an ffprobe reading of what is inside.
9
+ */
10
+
11
+ /** Accepted music file extensions and the content types a browser or a storage reports for each. */
12
+ export const MUSIC_FILE_TYPES: Readonly<Record<string, readonly string[]>> = {
13
+ ".mp3": ["audio/mpeg", "audio/mp3"],
14
+ ".m4a": ["audio/mp4", "audio/x-m4a", "audio/m4a"],
15
+ ".aac": ["audio/aac"],
16
+ ".wav": ["audio/wav", "audio/x-wav", "audio/wave", "audio/vnd.wave"],
17
+ ".ogg": ["audio/ogg"],
18
+ ".oga": ["audio/ogg"],
19
+ ".opus": ["audio/opus", "audio/ogg"],
20
+ ".flac": ["audio/flac", "audio/x-flac"],
21
+ };
22
+
23
+ export type MusicFileTypeCheck = { ok: true; extension: string | null; contentType: string | null } | { ok: false; error: string };
24
+
25
+ const ACCEPTED_LIST = Object.keys(MUSIC_FILE_TYPES).join(", ");
26
+
27
+ function normalizeContentType(contentType: string): string {
28
+ return (contentType.split(";")[0] ?? "").trim().toLowerCase();
29
+ }
30
+
31
+ function getAcceptedTypes(extension: string): readonly string[] | null {
32
+ return Object.hasOwn(MUSIC_FILE_TYPES, extension) ? (MUSIC_FILE_TYPES[extension] ?? null) : null;
33
+ }
34
+
35
+ /**
36
+ * Whether a file is an accepted music bed by its name (or path) and its content type. Give either or both; with both,
37
+ * the content type must be one of the extension's. Parameters (`; codecs=…`) and letter case are ignored.
38
+ */
39
+ export function checkMusicFileType(input: { fileName?: string; contentType?: string }): MusicFileTypeCheck {
40
+ const extension = input.fileName === undefined ? null : extname(input.fileName).toLowerCase();
41
+ const contentType = input.contentType === undefined ? null : normalizeContentType(input.contentType);
42
+ if (extension === null && contentType === null) return { ok: false, error: "a music file needs a file name or a content type to check" };
43
+ if (extension !== null) {
44
+ const types = getAcceptedTypes(extension);
45
+ if (types === null) return { ok: false, error: `${input.fileName ?? ""}: not a music file (accepted: ${ACCEPTED_LIST})` };
46
+ if (contentType !== null && !types.includes(contentType)) return { ok: false, error: `${input.fileName ?? ""}: content type ${contentType} does not match ${extension} (expected ${types.join(" or ")})` };
47
+ return { ok: true, extension, contentType };
48
+ }
49
+ const isAccepted = Object.values(MUSIC_FILE_TYPES).some((types) => contentType !== null && types.includes(contentType));
50
+ return isAccepted ? { ok: true, extension: null, contentType } : { ok: false, error: `content type ${contentType ?? ""} is not a music file (accepted: ${ACCEPTED_LIST})` };
51
+ }
52
+
53
+ /** What ffprobe says about a music file: enough to check it, fit it under the cut and store it with the asset. */
54
+ export interface AudioProbe {
55
+ /** Seconds. */
56
+ duration: number;
57
+ codec: string;
58
+ /** Hz. */
59
+ sampleRate: number;
60
+ channels: number;
61
+ /** Bits per second; null when the container reports none (Opus in Ogg, FLAC). */
62
+ bitRate: number | null;
63
+ }
64
+
65
+ /** Why a file is not a usable music bed. `unreadable`: ffprobe could not open it (missing, corrupt, not media). */
66
+ export type AudioProbeFailure = "no-audio-stream" | "no-duration" | "unexpected-output" | "unreadable";
67
+
68
+ export type AudioProbeResult = { ok: true; probe: AudioProbe } | { ok: false; reason: AudioProbeFailure; error: string };
69
+
70
+ const audioStreamSchema = z.looseObject({
71
+ codec_type: z.string().optional(),
72
+ codec_name: z.string().optional(),
73
+ sample_rate: z.string().optional(),
74
+ channels: z.number().optional(),
75
+ bit_rate: z.string().optional(),
76
+ duration: z.string().optional(),
77
+ });
78
+
79
+ const audioProbeSchema = z.looseObject({
80
+ streams: z.array(audioStreamSchema).default([]),
81
+ format: z.looseObject({ duration: z.string().optional(), bit_rate: z.string().optional() }).optional(),
82
+ });
83
+
84
+ function readPositive(value: string | undefined): number | null {
85
+ const number = Number(value);
86
+ return value !== undefined && Number.isFinite(number) && number > 0 ? number : null;
87
+ }
88
+
89
+ /** ffprobe's JSON (`-show_streams -show_format -of json`) read as a music bed: the first audio stream, cover art ignored. */
90
+ export function readAudioProbe(json: unknown): AudioProbeResult {
91
+ const parsed = audioProbeSchema.safeParse(json);
92
+ if (!parsed.success) return { ok: false, reason: "unexpected-output", error: "ffprobe printed an unexpected shape" };
93
+ const { streams, format } = parsed.data;
94
+ const audio = streams.find((stream) => stream.codec_type === "audio");
95
+ if (audio === undefined) return { ok: false, reason: "no-audio-stream", error: "no audio stream" };
96
+ const duration = readPositive(format?.duration) ?? readPositive(audio.duration);
97
+ if (duration === null) return { ok: false, reason: "no-duration", error: "no duration" };
98
+ return {
99
+ ok: true,
100
+ probe: {
101
+ duration,
102
+ codec: audio.codec_name ?? "unknown",
103
+ sampleRate: readPositive(audio.sample_rate) ?? 0,
104
+ channels: audio.channels ?? 0,
105
+ bitRate: readPositive(audio.bit_rate) ?? readPositive(format?.bit_rate),
106
+ },
107
+ };
108
+ }
109
+
110
+ /** Probes one music file (or URL) with ffprobe; a failure carries its reason and names the file. Rejects only on abort. */
111
+ export async function probeAudio(path: string, options: { signal?: AbortSignal } = {}): Promise<AudioProbeResult> {
112
+ const output = await runFfprobe(path, options);
113
+ if (!output.ok) return { ok: false, reason: "unreadable", error: output.error };
114
+ const read = readAudioProbe(output.json);
115
+ return read.ok ? read : { ...read, error: `${path}: ${read.error}` };
116
+ }
117
+
118
+ /** One line about a probed music file, for the log. */
119
+ export function describeAudioProbe(probe: AudioProbe): string {
120
+ const parts = [probe.codec, `${probe.duration.toFixed(1)} s`, `${String(probe.sampleRate)} Hz`, probe.channels === 1 ? "mono" : `${String(probe.channels)} channels`];
121
+ if (probe.bitRate !== null) parts.push(`${String(Math.round(probe.bitRate / 1000))} kb/s`);
122
+ return parts.join(", ");
123
+ }
@@ -0,0 +1,146 @@
1
+ import { readFileSync } from "node:fs";
2
+
3
+ import type { CaptionLayout } from "../compose/timeline.js";
4
+ import type { BrandFont } from "../config/config.js";
5
+ import { readCharacterMap, type CharacterMap } from "../og/character-map.js";
6
+ import type { TimedWord } from "../voice/voiceover.js";
7
+ import type { CaptionPreset } from "./film.js";
8
+
9
+ /**
10
+ * The footage film's captions: plain phrases (the default style), the 9:16 caption box inside a platform's safe zone,
11
+ * and a check that the caption and end-card fonts draw every letter the film shows (Polish letters above all), since
12
+ * the browser would quietly draw a missing one in another font.
13
+ */
14
+
15
+ export interface PhraseChunk {
16
+ words: TimedWord[];
17
+ start: number;
18
+ end: number;
19
+ }
20
+
21
+ const MIN_PHRASE_WORDS = 2;
22
+ const MAX_PHRASE_WORDS = 6;
23
+ /** A silence this long between two words starts a new phrase. */
24
+ const PHRASE_GAP_SECONDS = 0.7;
25
+
26
+ /**
27
+ * The words as phrases of 2-6: a phrase ends at punctuation, after six words or at a pause; a single word left alone
28
+ * joins the phrase before it when that one has room and no pause separates them.
29
+ */
30
+ export function phraseChunks(words: TimedWord[]): PhraseChunk[] {
31
+ const groups: TimedWord[][] = [];
32
+ let current: TimedWord[] = [];
33
+ words.forEach((word, index) => {
34
+ const previous = words[index - 1];
35
+ if (current.length > 0 && previous !== undefined && word.start - previous.end > PHRASE_GAP_SECONDS) {
36
+ groups.push(current);
37
+ current = [];
38
+ }
39
+ current.push(word);
40
+ if (/[.,?!:;…]$/u.test(word.text) || current.length === MAX_PHRASE_WORDS) {
41
+ groups.push(current);
42
+ current = [];
43
+ }
44
+ });
45
+ if (current.length > 0) groups.push(current);
46
+ const merged: TimedWord[][] = [];
47
+ for (const group of groups) {
48
+ const previous = merged.at(-1);
49
+ const first = group[0] as TimedWord;
50
+ const last = previous?.at(-1);
51
+ const isClose = last !== undefined && first.start - last.end <= PHRASE_GAP_SECONDS;
52
+ if (previous !== undefined && group.length < MIN_PHRASE_WORDS && previous.length < MAX_PHRASE_WORDS && isClose) previous.push(...group);
53
+ else merged.push(group);
54
+ }
55
+ return merged.map((group) => ({ words: group, start: (group[0] as TimedWord).start, end: (group[group.length - 1] as TimedWord).end }));
56
+ }
57
+
58
+ /** Margins of a 1080×1920 frame that a platform's own buttons and text cover. */
59
+ export interface SafeZone {
60
+ top: number;
61
+ bottom: number;
62
+ left: number;
63
+ right: number;
64
+ }
65
+
66
+ /**
67
+ * The areas each platform keeps for its interface on a 9:16 video, rounded up from the platforms' creator guides; `all`
68
+ * is the zone that is safe on every one of them.
69
+ */
70
+ export const CAPTION_SAFE_ZONES: Record<CaptionPreset, SafeZone> = {
71
+ reels: { top: 220, bottom: 420, left: 60, right: 120 },
72
+ shorts: { top: 190, bottom: 380, left: 60, right: 140 },
73
+ tiktok: { top: 160, bottom: 480, left: 60, right: 150 },
74
+ all: { top: 220, bottom: 480, left: 60, right: 150 },
75
+ };
76
+
77
+ const FRAME_HEIGHT = 1920;
78
+ /** Two caption lines and the box's padding, in caption font sizes. */
79
+ const CAPTION_LINES_HEIGHT = 2.5;
80
+ const CAPTION_PADDING = 40;
81
+
82
+ /** The caption box of a 9:16 film with its bottom line kept above the preset's bottom margin, centred between equal sides. */
83
+ export function getCaptionPresetLayout(preset: CaptionPreset, fontSize: number): CaptionLayout {
84
+ const zone = CAPTION_SAFE_ZONES[preset];
85
+ const side = Math.max(zone.left, zone.right);
86
+ const top = Math.round(FRAME_HEIGHT - zone.bottom - CAPTION_LINES_HEIGHT * fontSize - CAPTION_PADDING);
87
+ return { top, left: side, right: side, fontSize };
88
+ }
89
+
90
+ /** A character a font is asked to draw and does not have. */
91
+ export interface MissingCaptionGlyphs {
92
+ /** The family, as `brand.fonts` names it. */
93
+ font: string;
94
+ characters: string[];
95
+ }
96
+
97
+ const INVISIBLE_PATTERN = /^[\p{White_Space}\p{Cc}\p{Cf}\u{FE00}-\u{FE0F}]$/u;
98
+
99
+ /** The character maps of a family's files; null when a file cannot be read (a WOFF2 file), so the family is not checked. */
100
+ function readFamilyMaps(font: BrandFont, read: (path: string) => Buffer): CharacterMap[] | null {
101
+ const maps: CharacterMap[] = [];
102
+ for (const file of font.files) {
103
+ const map = readCharacterMap(read(file.path));
104
+ if (!map.ok) return null;
105
+ maps.push(map.value);
106
+ }
107
+ return maps;
108
+ }
109
+
110
+ /**
111
+ * The characters of `texts` that no file of the family draws. A family whose files cannot all be read is skipped, and
112
+ * so is text without a brand font (the system font draws it).
113
+ */
114
+ function findMissingInFamily(font: BrandFont | null, texts: string[], read: (path: string) => Buffer): MissingCaptionGlyphs | null {
115
+ if (font === null || font.files.length === 0) return null;
116
+ const maps = readFamilyMaps(font, read);
117
+ if (maps === null) return null;
118
+ const characters = new Set<string>();
119
+ for (const text of texts) {
120
+ for (const character of text) {
121
+ if (INVISIBLE_PATTERN.test(character)) continue;
122
+ const codePoint = character.codePointAt(0) ?? 0;
123
+ if (!maps.some((map) => map.has(codePoint))) characters.add(character);
124
+ }
125
+ }
126
+ return characters.size === 0 ? null : { font: font.family, characters: [...characters] };
127
+ }
128
+
129
+ /**
130
+ * Glyphs the film's fonts lack: the body font against the captions and the end card's url and note, the heading font
131
+ * (the body font without one) against the brand name and the headline. Empty when every letter is drawn.
132
+ */
133
+ export function findMissingCaptionGlyphs(
134
+ input: { fonts: { heading: BrandFont | null; body: BrandFont | null }; captions: string[]; endCard: { headline: string; url: string; note: string } | null; brandName: string },
135
+ read: (path: string) => Buffer = readFileSync,
136
+ ): MissingCaptionGlyphs[] {
137
+ const { fonts, endCard } = input;
138
+ const body = findMissingInFamily(fonts.body, [...input.captions, ...(endCard === null ? [] : [endCard.url, endCard.note])], read);
139
+ const headingTexts = endCard === null ? [] : [input.brandName, endCard.headline];
140
+ const heading = findMissingInFamily(fonts.heading ?? fonts.body, headingTexts, read);
141
+ const missing = [body, heading].filter((entry): entry is MissingCaptionGlyphs => entry !== null);
142
+ // One family serving both roles is reported once.
143
+ const merged = new Map<string, Set<string>>();
144
+ for (const entry of missing) merged.set(entry.font, new Set([...(merged.get(entry.font) ?? []), ...entry.characters]));
145
+ return [...merged].map(([font, characters]) => ({ font, characters: [...characters] }));
146
+ }
@@ -4,23 +4,26 @@ import type { ComposeFont } from "../compose/compose.js";
4
4
  import { escapeHtml, fontFaces, fontStack } from "../compose/html.js";
5
5
  import { captionChunks, type CaptionLayout } from "../compose/timeline.js";
6
6
  import type { TimedWord } from "../voice/voiceover.js";
7
+ import { phraseChunks } from "./captions.js";
7
8
  import { getEdlDuration, getSegmentStarts, type Edl } from "./edl.js";
8
- import type { FootageFilm } from "./film.js";
9
+ import { DEFAULT_EDIT, getFootageEdit, type FootageFilm } from "./film.js";
10
+ import { FOOTAGE_FPS } from "./normalize.js";
11
+
12
+ const r3 = (value: number): number => Math.round(value * 1000) / 1000 || 0;
9
13
 
10
14
  /**
11
15
  * The HyperFrames composition of a footage film (the same 0.8.85 contract as `composeFilm`): one `<video>` clip per
12
16
  * 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.
17
+ * before over `fadeFrames`, `zoom` punches in by `zoomPercent` on alternate jump cuts, `whoosh` plays the whoosh
18
+ * sound), a slow zoom on `kenburns` segments, the captions (plain phrases, or the word-highlight pill), the end card
19
+ * over the cut's last frame (its whoosh only with `isEndCardWhoosh`), the cut speech track and the ducked music.
15
20
  */
16
21
 
17
22
  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;
23
+ /** The default cross-fade's length (`DEFAULT_EDIT.fadeFrames` at 30 fps); the outgoing segment plays on under the incoming one for this long. */
24
+ export const FADE_SECONDS = r3(DEFAULT_EDIT.fadeFrames / FOOTAGE_FPS);
25
+ /** How far a segment marked `kenburns` zooms when the film's `kenBurnsPercent` is 0 (a hand edit asked for it). */
26
+ const HAND_KEN_BURNS_PERCENT = 4;
24
27
  /** The end card's length after the cut. */
25
28
  export const END_CARD_SECONDS = 3;
26
29
 
@@ -53,19 +56,17 @@ export interface FootageComposeInput {
53
56
  locale: string;
54
57
  }
55
58
 
56
- const r3 = (value: number): number => Math.round(value * 1000) / 1000 || 0;
57
-
58
59
  /** The film's length: the cut plus the end card. */
59
60
  export function getFootageFilmSeconds(film: Pick<FootageFilm, "endCard">, edl: Edl): number {
60
61
  return r3(getEdlDuration(edl) + (film.endCard === null ? 0 : END_CARD_SECONDS));
61
62
  }
62
63
 
63
- /** The picture scale each segment starts at: `zoom` cuts alternate between punched in and back out. */
64
- export function getSegmentScales(edl: Edl): number[] {
64
+ /** The picture scale each segment starts at: `zoom` cuts alternate between punched in (`zoomPercent`) and back out. */
65
+ export function getSegmentScales(edl: Edl, zoomPercent = DEFAULT_EDIT.zoomPercent): number[] {
65
66
  const scales: number[] = [];
66
67
  edl.segments.forEach((segment, index) => {
67
68
  const previous = scales[index - 1] ?? 1;
68
- scales.push(segment.transition === "zoom" && index > 0 ? (previous === 1 ? ZOOM_SCALE : 1) : 1);
69
+ scales.push(segment.transition === "zoom" && index > 0 ? (previous === 1 ? zoomPercent / 100 : 1) : 1);
69
70
  });
70
71
  return scales;
71
72
  }
@@ -75,13 +76,16 @@ export function composeFootage(input: FootageComposeInput): string {
75
76
  const starts = getSegmentStarts(edl);
76
77
  const cutEnd = getEdlDuration(edl);
77
78
  const end = getFootageFilmSeconds(film, edl);
78
- const scales = getSegmentScales(edl);
79
+ const edit = getFootageEdit(film);
80
+ const scales = getSegmentScales(edl, edit.zoomPercent);
81
+ const fadeSeconds = r3(edit.fadeFrames / FOOTAGE_FPS);
82
+ const kenBurnsScale = 1 + (edit.kenBurnsPercent > 0 ? edit.kenBurnsPercent : HAND_KEN_BURNS_PERCENT) / 100;
79
83
 
80
84
  const segments = edl.segments.map((segment, index) => {
81
85
  const src = assets.clips[segment.clip];
82
86
  if (src === undefined) throw new Error(`The EDL names clip "${segment.clip}", which the film has no file for.`);
83
87
  const next = edl.segments[index + 1];
84
- const tail = next?.transition === "fade" ? FADE_SECONDS : 0;
88
+ const tail = next?.transition === "fade" ? fadeSeconds : 0;
85
89
  const start = starts[index] as number;
86
90
  const duration = r3(segment.end - segment.start + tail);
87
91
  const scale = scales[index] as number;
@@ -93,25 +97,28 @@ export function composeFootage(input: FootageComposeInput): string {
93
97
  edl.segments.forEach((segment, index) => {
94
98
  const start = starts[index] as number;
95
99
  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});`);
100
+ tweens.push(`tl.fromTo("#seg${index}", { opacity: 0 }, { opacity: 1, duration: ${fadeSeconds}, ease: "none", immediateRender: false }, ${start});`);
97
101
  }
98
102
  if (segment.motion === "kenburns") {
99
103
  const from = scales[index] as number;
100
104
  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});`,
105
+ `tl.fromTo("#seg${index}", { scale: ${from} }, { scale: ${r3(from * kenBurnsScale)}, duration: ${r3(segment.end - segment.start)}, ease: "none", immediateRender: false }, ${start});`,
102
106
  );
103
107
  }
104
108
  });
105
109
 
106
- // --- Captions ---
107
- const caption = input.film.captions ? captionChunks(words) : [];
110
+ // --- Captions: plain phrases, or the pill that lights each word ---
111
+ const isHighlight = film.captionStyle === "highlight";
112
+ const caption = !film.captions ? [] : isHighlight ? captionChunks(words) : phraseChunks(words);
108
113
  const captionHtml = caption
109
114
  .map((chunk, i) => {
110
115
  const next = caption[i + 1];
111
116
  const start = r3(chunk.start - 0.05);
112
117
  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>`;
118
+ const box = isHighlight
119
+ ? `<p class="pill">${chunk.words.map((w, j) => `<span id="cw${i}_${j}">${escapeHtml(w.text)}</span>`).join(" ")}</p>`
120
+ : `<p class="phrase">${escapeHtml(chunk.words.map((w) => w.text).join(" "))}</p>`;
121
+ return `<div id="cap${i}" class="clip caption" data-start="${start}" data-duration="${r3(Math.max(0.1, stop - start))}">${box}</div>`;
115
122
  })
116
123
  .join("\n ");
117
124
 
@@ -124,7 +131,7 @@ export function composeFootage(input: FootageComposeInput): string {
124
131
  edl.segments.forEach((segment, index) => {
125
132
  if (segment.transition === "whoosh" && index > 0) play("whoosh", (starts[index] as number) - 0.1, 0.45, 0.57);
126
133
  });
127
- if (film.endCard !== null) {
134
+ if (film.endCard !== null && edit.isEndCardWhoosh) {
128
135
  play("whoosh", cutEnd, 0.3, 0.57);
129
136
  play("pop", r3(cutEnd + 0.9), 0.35, 0.72);
130
137
  }
@@ -179,6 +186,7 @@ html,body{width:${frame.width}px;height:${frame.height}px;overflow:hidden;backgr
179
186
  .caption{position:absolute;left:${captionBox.left}px;right:${captionBox.right}px;top:${captionBox.top}px;display:flex;justify-content:center}
180
187
  .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
188
  .pill span{display:inline-block}
189
+ .phrase{font-weight:650;font-size:${captionBox.fontSize}px;line-height:1.18;letter-spacing:-.01em;text-align:center;color:#fff;text-shadow:0 2px 6px rgba(0,0,0,.55),0 0 18px rgba(0,0,0,.35)}
182
190
  .endcard{position:absolute;inset:0;display:flex;flex-direction:column;justify-content:center;align-items:center;padding:0 80px;text-align:center}
183
191
  .brand{display:flex;justify-content:center;align-items:center;gap:18px;font-family:${headingFont};font-size:46px}
184
192
  .logo{height:60px;width:auto}
@@ -197,7 +205,7 @@ html,body{width:${frame.width}px;height:${frame.height}px;overflow:hidden;backgr
197
205
  <script>
198
206
  const tl = gsap.timeline({ paused: true });
199
207
  ${tweens.join("\n")}
200
- const captions = ${JSON.stringify(caption.map((chunk) => chunk.words.map((w) => w.start)))};
208
+ const captions = ${JSON.stringify(isHighlight ? caption.map((chunk) => chunk.words.map((w) => w.start)) : [])};
201
209
  captions.forEach((words, i) => {
202
210
  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
211
  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));