@softure-ai/marketing-kit 0.11.0 → 0.13.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 (91) hide show
  1. package/CHANGELOG.md +85 -0
  2. package/README.md +67 -9
  3. package/dist/cli/footage.js +1 -1
  4. package/dist/cli/footage.js.map +1 -1
  5. package/dist/compose/timeline.d.ts +23 -3
  6. package/dist/compose/timeline.d.ts.map +1 -1
  7. package/dist/compose/timeline.js +31 -11
  8. package/dist/compose/timeline.js.map +1 -1
  9. package/dist/config/actions-schema.d.ts +14 -14
  10. package/dist/config/config.d.ts.map +1 -1
  11. package/dist/config/config.js +2 -0
  12. package/dist/config/config.js.map +1 -1
  13. package/dist/config/schema.d.ts +83 -70
  14. package/dist/config/schema.d.ts.map +1 -1
  15. package/dist/config/schema.js +21 -1
  16. package/dist/config/schema.js.map +1 -1
  17. package/dist/config/shot-steps.d.ts +16 -16
  18. package/dist/footage/captions.d.ts +45 -3
  19. package/dist/footage/captions.d.ts.map +1 -1
  20. package/dist/footage/captions.js +65 -5
  21. package/dist/footage/captions.js.map +1 -1
  22. package/dist/footage/compose.d.ts.map +1 -1
  23. package/dist/footage/compose.js +8 -4
  24. package/dist/footage/compose.js.map +1 -1
  25. package/dist/footage/declick.d.ts +106 -0
  26. package/dist/footage/declick.d.ts.map +1 -0
  27. package/dist/footage/declick.js +296 -0
  28. package/dist/footage/declick.js.map +1 -0
  29. package/dist/footage/draft.d.ts +8 -3
  30. package/dist/footage/draft.d.ts.map +1 -1
  31. package/dist/footage/draft.js +55 -22
  32. package/dist/footage/draft.js.map +1 -1
  33. package/dist/footage/edl.d.ts +28 -2
  34. package/dist/footage/edl.d.ts.map +1 -1
  35. package/dist/footage/edl.js +53 -2
  36. package/dist/footage/edl.js.map +1 -1
  37. package/dist/footage/film.d.ts +29 -3
  38. package/dist/footage/film.d.ts.map +1 -1
  39. package/dist/footage/film.js +12 -0
  40. package/dist/footage/film.js.map +1 -1
  41. package/dist/footage/isolate-ranges.d.ts +37 -0
  42. package/dist/footage/isolate-ranges.d.ts.map +1 -0
  43. package/dist/footage/isolate-ranges.js +113 -0
  44. package/dist/footage/isolate-ranges.js.map +1 -0
  45. package/dist/footage/loudness.d.ts +76 -0
  46. package/dist/footage/loudness.d.ts.map +1 -1
  47. package/dist/footage/loudness.js +134 -0
  48. package/dist/footage/loudness.js.map +1 -1
  49. package/dist/footage/paid.d.ts +18 -0
  50. package/dist/footage/paid.d.ts.map +1 -1
  51. package/dist/footage/paid.js +32 -2
  52. package/dist/footage/paid.js.map +1 -1
  53. package/dist/footage/pipeline.d.ts +43 -5
  54. package/dist/footage/pipeline.d.ts.map +1 -1
  55. package/dist/footage/pipeline.js +105 -20
  56. package/dist/footage/pipeline.js.map +1 -1
  57. package/dist/footage/providers.d.ts +5 -0
  58. package/dist/footage/providers.d.ts.map +1 -1
  59. package/dist/footage/publish.d.ts +11 -2
  60. package/dist/footage/publish.d.ts.map +1 -1
  61. package/dist/footage/publish.js +14 -10
  62. package/dist/footage/publish.js.map +1 -1
  63. package/dist/footage/speech-ranges.d.ts +65 -0
  64. package/dist/footage/speech-ranges.d.ts.map +1 -0
  65. package/dist/footage/speech-ranges.js +98 -0
  66. package/dist/footage/speech-ranges.js.map +1 -0
  67. package/dist/index.d.ts +10 -7
  68. package/dist/index.d.ts.map +1 -1
  69. package/dist/index.js +10 -7
  70. package/dist/index.js.map +1 -1
  71. package/package.json +1 -1
  72. package/schema/edl.schema.json +17 -0
  73. package/schema/marketing.schema.json +43 -1
  74. package/src/cli/footage.ts +1 -1
  75. package/src/compose/timeline.ts +41 -10
  76. package/src/config/config.ts +2 -0
  77. package/src/config/schema.ts +23 -1
  78. package/src/footage/captions.ts +81 -6
  79. package/src/footage/compose.ts +8 -4
  80. package/src/footage/declick.ts +353 -0
  81. package/src/footage/draft.ts +58 -23
  82. package/src/footage/edl.ts +69 -2
  83. package/src/footage/film.ts +37 -3
  84. package/src/footage/isolate-ranges.ts +161 -0
  85. package/src/footage/loudness.ts +170 -0
  86. package/src/footage/paid.ts +40 -2
  87. package/src/footage/pipeline.ts +158 -22
  88. package/src/footage/providers.ts +2 -0
  89. package/src/footage/publish.ts +20 -11
  90. package/src/footage/speech-ranges.ts +131 -0
  91. package/src/index.ts +75 -0
@@ -2876,6 +2876,16 @@
2876
2876
  "minimum": 1,
2877
2877
  "maximum": 4
2878
2878
  },
2879
+ "captionKeepWithNext": {
2880
+ "description": "Words a caption card must not end on (they move to the next card), compared lower-case; a number always keeps with the next word. Without it, the language's default (pl: one-letter words and short prepositions, en: articles); [] keeps numbers only.",
2881
+ "maxItems": 100,
2882
+ "type": "array",
2883
+ "items": {
2884
+ "type": "string",
2885
+ "minLength": 1,
2886
+ "maxLength": 20
2887
+ }
2888
+ },
2879
2889
  "edit": {
2880
2890
  "description": "The cut's look; the defaults read as an ordinary phone video.",
2881
2891
  "default": {},
@@ -2955,6 +2965,24 @@
2955
2965
  ],
2956
2966
  "additionalProperties": false
2957
2967
  },
2968
+ "speech": {
2969
+ "description": "The speech track's cleanup before its loudness normalization.",
2970
+ "default": {},
2971
+ "type": "object",
2972
+ "properties": {
2973
+ "declick": {
2974
+ "default": "off",
2975
+ "description": "Mouth clicks and lip smacks between words, cleaned before the loudness pass: gentle lowers the pauses by 15 dB and removes short clicks, strong by 20 dB with a more sensitive detection; off (the default) leaves the speech track as cut.",
2976
+ "type": "string",
2977
+ "enum": [
2978
+ "off",
2979
+ "gentle",
2980
+ "strong"
2981
+ ]
2982
+ }
2983
+ },
2984
+ "additionalProperties": false
2985
+ },
2958
2986
  "loudness": {
2959
2987
  "default": {
2960
2988
  "target": -14,
@@ -2993,7 +3021,7 @@
2993
3021
  "target": -14,
2994
3022
  "truePeak": -1
2995
3023
  },
2996
- "description": "The finished film's mix (speech and music), measured after the render and normalized in two passes; false leaves the mix as rendered. Default -14 LUFS, -1 dBTP.",
3024
+ "description": "The finished film's mix (speech and music), measured after the render, brought to the target by one gain and held under the true peak by a limiter; false leaves the mix as rendered. Default -14 LUFS, -1 dBTP.",
2997
3025
  "anyOf": [
2998
3026
  {
2999
3027
  "type": "boolean",
@@ -3015,6 +3043,20 @@
3015
3043
  "type": "number",
3016
3044
  "minimum": -9,
3017
3045
  "maximum": 0
3046
+ },
3047
+ "tolerance": {
3048
+ "description": "How far from target the mix may land, in LU (0.2 to 3, default 1).",
3049
+ "type": "number",
3050
+ "minimum": 0.2,
3051
+ "maximum": 3
3052
+ },
3053
+ "keep": {
3054
+ "description": "\"loudness\" (default): one gain brings the mix to target; \"speech\": no gain while the mix measures inside target ± tolerance, so the speech keeps its level whatever the music volume.",
3055
+ "type": "string",
3056
+ "enum": [
3057
+ "loudness",
3058
+ "speech"
3059
+ ]
3018
3060
  }
3019
3061
  },
3020
3062
  "additionalProperties": false
@@ -80,7 +80,7 @@ export async function runFootage(config: MarketingConfig, options: FootageOption
80
80
  if (options.step === "cut") return;
81
81
  } else {
82
82
  if (!existsSync(edlPath)) fail(`no EDL at ${edlPath}: run softure-marketing footage ${film.id} --step=cut first.`);
83
- const read = readEdlFile(film, clips.value, edlPath);
83
+ const read = readEdlFile(film, clips.value, edlPath, run.layout);
84
84
  if (!read.ok) fail(read.error);
85
85
  edl = read.value;
86
86
  console.log(`cut: ${edlPath} (${edl.segments.length} segments), as it is; --step=cut builds it again.`);
@@ -318,25 +318,56 @@ export interface CaptionChunk {
318
318
  end: number;
319
319
  }
320
320
 
321
+ /** How words are cut into caption chunks. */
322
+ export interface CaptionChunkOptions {
323
+ /** The most words a chunk holds; default 4. */
324
+ maxWords?: number;
325
+ /**
326
+ * Words that must not end a chunk (a one-letter word, a short preposition, a number before its unit): a full chunk
327
+ * ending on one hands it, with the kept words before it, to the next chunk. A word ending in punctuation still ends
328
+ * its chunk. Absent: every word may end one.
329
+ */
330
+ keepsWithNext?: (word: TimedWord) => boolean;
331
+ }
332
+
333
+ /**
334
+ * A full chunk cut after its last word that does not keep with the next: the chunk and the words it carries over to
335
+ * the next one. A chunk of kept words only stays whole.
336
+ */
337
+ export function splitAfterKept(words: TimedWord[], keepsWithNext: ((word: TimedWord) => boolean) | undefined): { chunk: TimedWord[]; carry: TimedWord[] } {
338
+ if (keepsWithNext === undefined) return { chunk: words, carry: [] };
339
+ const lastFree = words.findLastIndex((word) => !keepsWithNext(word));
340
+ if (lastFree === -1) return { chunk: words, carry: [] };
341
+ return { chunk: words.slice(0, lastFree + 1), carry: words.slice(lastFree + 1) };
342
+ }
343
+
321
344
  /**
322
- * Words → caption chunks: at most `maxWords` words, broken after the end of a sentence and after a
323
- * comma, so a caption does not glue two thoughts together.
345
+ * Words → caption chunks: at most `maxWords` words, broken after the end of a sentence and after a comma, so a caption
346
+ * does not glue two thoughts together; never after a word `keepsWithNext` keeps, unless punctuation ends it or every
347
+ * word of the chunk is kept. A number as `options` is `maxWords`.
324
348
  */
325
- export function captionChunks(words: TimedWord[], maxWords = 4): CaptionChunk[] {
349
+ export function captionChunks(words: TimedWord[], options: number | CaptionChunkOptions = {}): CaptionChunk[] {
350
+ const { maxWords = 4, keepsWithNext } = typeof options === "number" ? { maxWords: options } : options;
326
351
  const chunks: CaptionChunk[] = [];
327
352
  let current: TimedWord[] = [];
328
- const flush = () => {
329
- const first = current[0];
330
- const last = current[current.length - 1];
353
+ const push = (chunkWords: TimedWord[]) => {
354
+ const first = chunkWords[0];
355
+ const last = chunkWords[chunkWords.length - 1];
331
356
  if (first === undefined || last === undefined) return;
332
- chunks.push({ words: current, start: first.start, end: last.end });
333
- current = [];
357
+ chunks.push({ words: chunkWords, start: first.start, end: last.end });
334
358
  };
335
359
  for (const word of words) {
336
360
  current.push(word);
337
- if (/[.,?!:;]$/.test(word.text) || current.length === maxWords) flush();
361
+ if (/[.,?!:;]$/.test(word.text)) {
362
+ push(current);
363
+ current = [];
364
+ } else if (current.length >= maxWords) {
365
+ const { chunk, carry } = splitAfterKept(current, keepsWithNext);
366
+ push(chunk);
367
+ current = carry;
368
+ }
338
369
  }
339
- flush();
370
+ push(current);
340
371
  return chunks;
341
372
  }
342
373
 
@@ -247,6 +247,7 @@ function resolveFootage(data: MarketingJson, at: (relative: string) => string):
247
247
  captionStyle: film.captionStyle,
248
248
  ...(film.captionPreset === undefined ? {} : { captionPreset: film.captionPreset }),
249
249
  ...(film.captionMaxLines === undefined ? {} : { captionMaxLines: film.captionMaxLines }),
250
+ ...(film.captionKeepWithNext === undefined ? {} : { captionKeepWithNext: film.captionKeepWithNext }),
250
251
  edit: {
251
252
  zoomPercent: film.edit.zoomPercent,
252
253
  zoomEaseFrames: film.edit.zoomEaseFrames,
@@ -257,6 +258,7 @@ function resolveFootage(data: MarketingJson, at: (relative: string) => string):
257
258
  isCutAudioCrossfade: film.edit.cutAudioCrossfade,
258
259
  },
259
260
  endCard: film.endCard ?? null,
261
+ ...(film.speech.declick === "off" ? {} : { speech: { declick: film.speech.declick } }),
260
262
  loudness: film.loudness === false ? null : film.loudness,
261
263
  mixLoudness: film.mixLoudness === false ? null : film.mixLoudness,
262
264
  cover: film.cover === false ? null : film.cover,
@@ -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 { DECLICK_LEVELS } from "../footage/declick.js";
17
18
  import { CAPTION_PRESETS, CAPTION_STYLES, CLIP_FITS, CLIP_ROLES, CUT_TRANSITIONS, JUMP_TRANSITIONS } from "../footage/film.js";
18
19
  import { normalizeKeyTerms } from "../footage/keyterms.js";
19
20
  import { ELEVENLABS_DEFAULT_MODEL } from "../voice/voiceover.js";
@@ -574,6 +575,11 @@ const footageSchema = z
574
575
  .max(4)
575
576
  .optional()
576
577
  .describe("The most lines a caption card may take (1-4): the render shrinks a longer card's font, to 70 % at most; without it, no limit."),
578
+ captionKeepWithNext: z
579
+ .array(z.string().trim().min(1).max(20))
580
+ .max(100)
581
+ .optional()
582
+ .describe("Words a caption card must not end on (they move to the next card), compared lower-case; a number always keeps with the next word. Without it, the language's default (pl: one-letter words and short prepositions, en: articles); [] keeps numbers only."),
577
583
  edit: z
578
584
  .strictObject({
579
585
  zoomPercent: z.number().min(105).max(112).default(108).describe("How far a zoom cut punches in (105-112 %, default 108)."),
@@ -596,6 +602,17 @@ const footageSchema = z
596
602
  .prefault({})
597
603
  .describe("The cut's look; the defaults read as an ordinary phone video."),
598
604
  endCard: endCardSchema.optional().describe("The closing card after the last segment; without it, the film ends with its last segment."),
605
+ speech: z
606
+ .strictObject({
607
+ declick: z
608
+ .enum(DECLICK_LEVELS)
609
+ .default("off")
610
+ .describe(
611
+ "Mouth clicks and lip smacks between words, cleaned before the loudness pass: gentle lowers the pauses by 15 dB and removes short clicks, strong by 20 dB with a more sensitive detection; off (the default) leaves the speech track as cut.",
612
+ ),
613
+ })
614
+ .prefault({})
615
+ .describe("The speech track's cleanup before its loudness normalization."),
599
616
  loudness: z
600
617
  .union([
601
618
  z.literal(false),
@@ -612,10 +629,15 @@ const footageSchema = z
612
629
  z.strictObject({
613
630
  target: z.number().min(-40).max(-5).default(-14).describe("Integrated loudness in LUFS (-40 to -5, default -14)."),
614
631
  truePeak: z.number().min(-9).max(0).default(-1).describe("The highest true peak in dBTP (-9 to 0, default -1)."),
632
+ tolerance: z.number().min(0.2).max(3).optional().describe("How far from target the mix may land, in LU (0.2 to 3, default 1)."),
633
+ keep: z
634
+ .enum(["loudness", "speech"])
635
+ .optional()
636
+ .describe('"loudness" (default): one gain brings the mix to target; "speech": no gain while the mix measures inside target ± tolerance, so the speech keeps its level whatever the music volume.'),
615
637
  }),
616
638
  ])
617
639
  .default({ target: -14, truePeak: -1 })
618
- .describe("The finished film's mix (speech and music), measured after the render and normalized in two passes; false leaves the mix as rendered. Default -14 LUFS, -1 dBTP."),
640
+ .describe("The finished film's mix (speech and music), measured after the render, brought to the target by one gain and held under the true peak by a limiter; false leaves the mix as rendered. Default -14 LUFS, -1 dBTP."),
619
641
  cover: z
620
642
  .union([
621
643
  z.literal(false),
@@ -1,10 +1,11 @@
1
1
  import { readFileSync } from "node:fs";
2
2
 
3
- import { resolveLayout, type CaptionLayout, type LayoutOverride } from "../compose/timeline.js";
3
+ import { CAPTION_LINE_HEIGHT, CAPTION_PILL_PADDING, captionChunks, resolveLayout, splitAfterKept, type CaptionLayout, type LayoutOverride } from "../compose/timeline.js";
4
4
  import type { BrandFont } from "../config/config.js";
5
5
  import { readCharacterMap, type CharacterMap } from "../og/character-map.js";
6
6
  import type { TimedWord } from "../voice/voiceover.js";
7
- import type { CaptionPreset, FootageFilm } from "./film.js";
7
+ import { findSegmentAt, type Edl, type EdlCaption, type EdlCaptionBounds } from "./edl.js";
8
+ import { DEFAULT_CAPTION_KEEP_WITH_NEXT, type CaptionPreset, type FootageFilm } from "./film.js";
8
9
 
9
10
  /**
10
11
  * The footage film's captions: plain phrases (the default style), the 9:16 caption box inside a platform's safe zone,
@@ -23,23 +24,39 @@ const MAX_PHRASE_WORDS = 6;
23
24
  /** A silence this long between two words starts a new phrase. */
24
25
  const PHRASE_GAP_SECONDS = 0.7;
25
26
 
27
+ /** How words are cut into phrases. */
28
+ export interface PhraseChunkOptions {
29
+ /**
30
+ * Words that must not end a phrase (`getCaptionKeepsWithNext`): neither a pause nor the six-word limit ends a
31
+ * phrase on one (a full phrase hands it to the next); punctuation still does. Absent: every word may end one.
32
+ */
33
+ keepsWithNext?: (word: TimedWord) => boolean;
34
+ }
35
+
26
36
  /**
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
37
+ * The words as phrases of 2-6: a phrase ends at punctuation, after six words or at a pause, never on a word
38
+ * `keepsWithNext` keeps (unless punctuation ends it or the phrase holds kept words only); a single word left alone
28
39
  * joins the phrase before it when that one has room and no pause separates them.
29
40
  */
30
- export function phraseChunks(words: TimedWord[]): PhraseChunk[] {
41
+ export function phraseChunks(words: TimedWord[], options: PhraseChunkOptions = {}): PhraseChunk[] {
42
+ const { keepsWithNext } = options;
31
43
  const groups: TimedWord[][] = [];
32
44
  let current: TimedWord[] = [];
33
45
  words.forEach((word, index) => {
34
46
  const previous = words[index - 1];
35
- if (current.length > 0 && previous !== undefined && word.start - previous.end > PHRASE_GAP_SECONDS) {
47
+ const isPreviousKept = previous !== undefined && keepsWithNext !== undefined && keepsWithNext(previous);
48
+ if (current.length > 0 && previous !== undefined && !isPreviousKept && word.start - previous.end > PHRASE_GAP_SECONDS) {
36
49
  groups.push(current);
37
50
  current = [];
38
51
  }
39
52
  current.push(word);
40
- if (/[.,?!:;…]$/u.test(word.text) || current.length === MAX_PHRASE_WORDS) {
53
+ if (/[.,?!:;…]$/u.test(word.text)) {
41
54
  groups.push(current);
42
55
  current = [];
56
+ } else if (current.length === MAX_PHRASE_WORDS) {
57
+ const { chunk, carry } = splitAfterKept(current, keepsWithNext);
58
+ groups.push(chunk);
59
+ current = carry;
43
60
  }
44
61
  });
45
62
  if (current.length > 0) groups.push(current);
@@ -55,6 +72,31 @@ export function phraseChunks(words: TimedWord[]): PhraseChunk[] {
55
72
  return merged.map((group) => ({ words: group, start: (group[0] as TimedWord).start, end: (group[group.length - 1] as TimedWord).end }));
56
73
  }
57
74
 
75
+ /** What a film's caption cards are cut by; without `language`, no language default applies. */
76
+ export type CaptionWordsFilm = Pick<FootageFilm, "captionKeepWithNext"> & { language?: string };
77
+
78
+ const NUMBER_PATTERN = /^\d+(?:[.,]\d+)*$/u;
79
+
80
+ /**
81
+ * Which of a film's words keep with the next on a caption card: a number, and a word of `captionKeepWithNext` (absent:
82
+ * the language's `DEFAULT_CAPTION_KEEP_WITH_NEXT`), compared lower-case. The render and the draft cut cards alike.
83
+ */
84
+ export function getCaptionKeepsWithNext(film: CaptionWordsFilm): (word: TimedWord) => boolean {
85
+ const defaults = film.language === undefined ? [] : (DEFAULT_CAPTION_KEEP_WITH_NEXT[film.language] ?? []);
86
+ const words = new Set((film.captionKeepWithNext ?? defaults).map((text) => text.toLowerCase()));
87
+ return (word) => NUMBER_PATTERN.test(word.text) || words.has(word.text.toLowerCase());
88
+ }
89
+
90
+ /**
91
+ * A footage film's caption cards in film time: none without captions, `captionChunks` for `highlight`, `phraseChunks`
92
+ * otherwise; both keep the film's kept words with the next (`getCaptionKeepsWithNext`). The render and the draft share it.
93
+ */
94
+ export function getFootageCaptionChunks(film: CaptionWordsFilm & Pick<FootageFilm, "captions" | "captionStyle">, words: TimedWord[]): PhraseChunk[] {
95
+ if (!film.captions) return [];
96
+ const keepsWithNext = getCaptionKeepsWithNext(film);
97
+ return film.captionStyle === "highlight" ? captionChunks(words, { keepsWithNext }) : phraseChunks(words, { keepsWithNext });
98
+ }
99
+
58
100
  /** When a caption chunk is on screen, in film seconds. */
59
101
  export interface CaptionSpan {
60
102
  start: number;
@@ -128,6 +170,39 @@ export function getFootageCaptionLayout(film: Pick<FootageFilm, "format" | "capt
128
170
  return getCaptionPresetLayout(film.captionPreset, base.caption.fontSize);
129
171
  }
130
172
 
173
+ /**
174
+ * A caption box moved by a segment's `caption` field: its `bottom` anchors the box by its foot; its `top` alone hangs
175
+ * the box from that top (the film's `bottom` dropped). Without either, the film's box itself.
176
+ */
177
+ export function applySegmentCaption(base: CaptionLayout, caption: EdlCaption | undefined): CaptionLayout {
178
+ if (caption?.bottom !== undefined) return { ...base, top: caption.top ?? base.top, bottom: caption.bottom };
179
+ if (caption?.top === undefined) return base;
180
+ return { top: caption.top, left: base.left, right: base.right, fontSize: base.fontSize };
181
+ }
182
+
183
+ /** The caption box of one segment of the cut: the film's box (`getFootageCaptionLayout`) with the segment's `caption` over it. */
184
+ export function getSegmentCaptionLayout(film: Pick<FootageFilm, "format" | "captionPreset">, edl: Edl, segmentIndex: number, override: LayoutOverride = {}): CaptionLayout {
185
+ return applySegmentCaption(getFootageCaptionLayout(film, override), edl.segments[segmentIndex]?.caption);
186
+ }
187
+
188
+ /**
189
+ * The box each caption chunk is drawn in: the box of the segment where the chunk's first word starts (film time), so
190
+ * a chunk that spans a cut keeps one box. The render and the draft place chunks alike.
191
+ */
192
+ export function getCaptionChunkLayouts(chunks: readonly { start: number }[], edl: Edl, base: CaptionLayout): CaptionLayout[] {
193
+ return chunks.map((chunk) => applySegmentCaption(base, edl.segments[findSegmentAt(edl, chunk.start)]?.caption));
194
+ }
195
+
196
+ /** Whether two caption boxes sit in the same place (a chunk in the film's box is drawn exactly as before). */
197
+ export function isSameCaptionPlace(a: CaptionLayout, b: CaptionLayout): boolean {
198
+ return a.bottom === b.bottom && (a.bottom !== undefined || a.top === b.top);
199
+ }
200
+
201
+ /** The frame a segment's caption box must stay in (`validateEdl`): the frame's height and a one-line card's. */
202
+ export function getCaptionBounds(frameHeight: number, caption: Pick<CaptionLayout, "fontSize">): EdlCaptionBounds {
203
+ return { frameHeight, cardHeight: Math.ceil(caption.fontSize * CAPTION_LINE_HEIGHT + 2 * CAPTION_PILL_PADDING.y) };
204
+ }
205
+
131
206
  /** A character a font is asked to draw and does not have. */
132
207
  export interface MissingCaptionGlyphs {
133
208
  /** The family, as `brand.fonts` names it. */
@@ -2,9 +2,9 @@ import type { BrandColors } from "../config/colors.js";
2
2
  import type { SfxEvent } from "../config/schema.js";
3
3
  import type { ComposeFont } from "../compose/compose.js";
4
4
  import { escapeHtml, fontFaces, fontStack } from "../compose/html.js";
5
- import { CAPTION_LINE_HEIGHT, captionChunks, getCaptionPillCss, getCaptionPositionCss, type CaptionLayout } from "../compose/timeline.js";
5
+ import { CAPTION_LINE_HEIGHT, getCaptionPillCss, getCaptionPositionCss, type CaptionLayout } from "../compose/timeline.js";
6
6
  import type { TimedWord } from "../voice/voiceover.js";
7
- import { getCaptionSpans, phraseChunks, type CaptionSpan } from "./captions.js";
7
+ import { getCaptionChunkLayouts, getCaptionSpans, getFootageCaptionChunks, isSameCaptionPlace, type CaptionSpan } from "./captions.js";
8
8
  import { getEdlDuration, getSegmentStarts, type Edl } from "./edl.js";
9
9
  import { CAPTION_MIN_FONT_SCALE, DEFAULT_EDIT, getFootageEdit, type FootageEdit, type FootageFilm } from "./film.js";
10
10
  import { FOOTAGE_FPS } from "./normalize.js";
@@ -142,15 +142,19 @@ export function composeFootage(input: FootageComposeInput): string {
142
142
 
143
143
  // --- Captions: plain phrases, or the pill that lights each word ---
144
144
  const isHighlight = film.captionStyle === "highlight";
145
- const caption = !film.captions ? [] : isHighlight ? captionChunks(words) : phraseChunks(words);
145
+ const caption = getFootageCaptionChunks(film, words);
146
146
  const spans = getCaptionSpans(caption, cutEnd);
147
+ const boxes = getCaptionChunkLayouts(caption, edl, captionBox);
147
148
  const captionHtml = caption
148
149
  .map((chunk, i) => {
149
150
  const { start, end: stop } = spans[i] as CaptionSpan;
151
+ const place = boxes[i] ?? captionBox;
152
+ // A chunk in a segment's own box overrides the shared rule's anchor; one in the film's box is written as before.
153
+ const style = isSameCaptionPlace(place, captionBox) ? "" : ` style="${place.bottom === undefined ? `bottom:auto;top:${place.top}px` : `top:auto;bottom:${place.bottom}px`}"`;
150
154
  const box = isHighlight
151
155
  ? `<p class="pill">${chunk.words.map((w, j) => `<span id="cw${i}_${j}">${escapeHtml(w.text)}</span>`).join(" ")}</p>`
152
156
  : `<p class="phrase">${escapeHtml(chunk.words.map((w) => w.text).join(" "))}</p>`;
153
- return `<div id="cap${i}" class="clip caption" data-start="${start}" data-duration="${r3(stop - start)}">${box}</div>`;
157
+ return `<div id="cap${i}" class="clip caption" data-start="${start}" data-duration="${r3(stop - start)}"${style}>${box}</div>`;
154
158
  })
155
159
  .join("\n ");
156
160