@softure-ai/marketing-kit 0.5.0 → 0.7.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 (138) hide show
  1. package/CHANGELOG.md +98 -0
  2. package/README.md +130 -17
  3. package/dist/cli/footage.d.ts.map +1 -1
  4. package/dist/cli/footage.js +5 -2
  5. package/dist/cli/footage.js.map +1 -1
  6. package/dist/compose/compose.d.ts.map +1 -1
  7. package/dist/compose/compose.js +3 -3
  8. package/dist/compose/compose.js.map +1 -1
  9. package/dist/compose/timeline.d.ts +16 -0
  10. package/dist/compose/timeline.d.ts.map +1 -1
  11. package/dist/compose/timeline.js +17 -1
  12. package/dist/compose/timeline.js.map +1 -1
  13. package/dist/config/config.d.ts.map +1 -1
  14. package/dist/config/config.js +25 -2
  15. package/dist/config/config.js.map +1 -1
  16. package/dist/config/schema.d.ts +17 -0
  17. package/dist/config/schema.d.ts.map +1 -1
  18. package/dist/config/schema.js +61 -3
  19. package/dist/config/schema.js.map +1 -1
  20. package/dist/footage/audio.d.ts +6 -2
  21. package/dist/footage/audio.d.ts.map +1 -1
  22. package/dist/footage/audio.js +15 -3
  23. package/dist/footage/audio.js.map +1 -1
  24. package/dist/footage/captions.d.ts +26 -3
  25. package/dist/footage/captions.d.ts.map +1 -1
  26. package/dist/footage/captions.js +35 -2
  27. package/dist/footage/captions.js.map +1 -1
  28. package/dist/footage/compose.d.ts +13 -2
  29. package/dist/footage/compose.d.ts.map +1 -1
  30. package/dist/footage/compose.js +79 -28
  31. package/dist/footage/compose.js.map +1 -1
  32. package/dist/footage/cuts.d.ts +44 -0
  33. package/dist/footage/cuts.d.ts.map +1 -0
  34. package/dist/footage/cuts.js +83 -0
  35. package/dist/footage/cuts.js.map +1 -0
  36. package/dist/footage/disk.d.ts +25 -0
  37. package/dist/footage/disk.d.ts.map +1 -0
  38. package/dist/footage/disk.js +72 -0
  39. package/dist/footage/disk.js.map +1 -0
  40. package/dist/footage/draft.d.ts +119 -0
  41. package/dist/footage/draft.d.ts.map +1 -0
  42. package/dist/footage/draft.js +296 -0
  43. package/dist/footage/draft.js.map +1 -0
  44. package/dist/footage/edl.d.ts +2 -1
  45. package/dist/footage/edl.d.ts.map +1 -1
  46. package/dist/footage/edl.js +5 -2
  47. package/dist/footage/edl.js.map +1 -1
  48. package/dist/footage/elevenlabs.d.ts.map +1 -1
  49. package/dist/footage/elevenlabs.js +2 -0
  50. package/dist/footage/elevenlabs.js.map +1 -1
  51. package/dist/footage/film.d.ts +54 -3
  52. package/dist/footage/film.d.ts.map +1 -1
  53. package/dist/footage/film.js +7 -1
  54. package/dist/footage/film.js.map +1 -1
  55. package/dist/footage/keyterms.d.ts +26 -0
  56. package/dist/footage/keyterms.d.ts.map +1 -0
  57. package/dist/footage/keyterms.js +36 -0
  58. package/dist/footage/keyterms.js.map +1 -0
  59. package/dist/footage/loudness.d.ts +20 -3
  60. package/dist/footage/loudness.d.ts.map +1 -1
  61. package/dist/footage/loudness.js +36 -18
  62. package/dist/footage/loudness.js.map +1 -1
  63. package/dist/footage/music.d.ts +3 -0
  64. package/dist/footage/music.d.ts.map +1 -1
  65. package/dist/footage/music.js +5 -0
  66. package/dist/footage/music.js.map +1 -1
  67. package/dist/footage/normalize.d.ts +30 -2
  68. package/dist/footage/normalize.d.ts.map +1 -1
  69. package/dist/footage/normalize.js +39 -11
  70. package/dist/footage/normalize.js.map +1 -1
  71. package/dist/footage/paid.d.ts +2 -1
  72. package/dist/footage/paid.d.ts.map +1 -1
  73. package/dist/footage/paid.js +13 -3
  74. package/dist/footage/paid.js.map +1 -1
  75. package/dist/footage/picture.d.ts +42 -0
  76. package/dist/footage/picture.d.ts.map +1 -0
  77. package/dist/footage/picture.js +141 -0
  78. package/dist/footage/picture.js.map +1 -0
  79. package/dist/footage/pipeline.d.ts +66 -4
  80. package/dist/footage/pipeline.d.ts.map +1 -1
  81. package/dist/footage/pipeline.js +172 -34
  82. package/dist/footage/pipeline.js.map +1 -1
  83. package/dist/footage/process.d.ts +2 -0
  84. package/dist/footage/process.d.ts.map +1 -1
  85. package/dist/footage/process.js +1 -0
  86. package/dist/footage/process.js.map +1 -1
  87. package/dist/footage/providers.d.ts +12 -3
  88. package/dist/footage/providers.d.ts.map +1 -1
  89. package/dist/footage/providers.js.map +1 -1
  90. package/dist/footage/publish.d.ts +4 -2
  91. package/dist/footage/publish.d.ts.map +1 -1
  92. package/dist/footage/publish.js +8 -5
  93. package/dist/footage/publish.js.map +1 -1
  94. package/dist/footage/render.d.ts +18 -3
  95. package/dist/footage/render.d.ts.map +1 -1
  96. package/dist/footage/render.js +67 -16
  97. package/dist/footage/render.js.map +1 -1
  98. package/dist/footage/tools.d.ts +15 -3
  99. package/dist/footage/tools.d.ts.map +1 -1
  100. package/dist/footage/tools.js +15 -2
  101. package/dist/footage/tools.js.map +1 -1
  102. package/dist/index.d.ts +14 -9
  103. package/dist/index.d.ts.map +1 -1
  104. package/dist/index.js +14 -9
  105. package/dist/index.js.map +1 -1
  106. package/docker/footage-worker.Dockerfile +7 -0
  107. package/fonts/DejaVuSans-Bold-Latin.ttf +0 -0
  108. package/fonts/LICENSE-DejaVu.txt +46 -0
  109. package/fonts/README.md +12 -0
  110. package/package.json +2 -1
  111. package/schema/marketing.schema.json +112 -4
  112. package/src/cli/footage.ts +4 -2
  113. package/src/compose/compose.ts +13 -3
  114. package/src/compose/timeline.ts +27 -1
  115. package/src/config/config.ts +26 -2
  116. package/src/config/schema.ts +63 -3
  117. package/src/footage/audio.ts +16 -3
  118. package/src/footage/captions.ts +45 -4
  119. package/src/footage/compose.ts +90 -28
  120. package/src/footage/cuts.ts +104 -0
  121. package/src/footage/disk.ts +75 -0
  122. package/src/footage/draft.ts +395 -0
  123. package/src/footage/edl.ts +5 -2
  124. package/src/footage/elevenlabs.ts +1 -0
  125. package/src/footage/film.ts +63 -5
  126. package/src/footage/keyterms.ts +38 -0
  127. package/src/footage/loudness.ts +38 -16
  128. package/src/footage/music.ts +7 -0
  129. package/src/footage/normalize.ts +51 -10
  130. package/src/footage/paid.ts +12 -3
  131. package/src/footage/picture.ts +179 -0
  132. package/src/footage/pipeline.ts +219 -37
  133. package/src/footage/process.ts +3 -0
  134. package/src/footage/providers.ts +10 -3
  135. package/src/footage/publish.ts +8 -5
  136. package/src/footage/render.ts +77 -16
  137. package/src/footage/tools.ts +23 -3
  138. package/src/index.ts +70 -4
@@ -14,7 +14,8 @@ 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 { CAPTION_PRESETS, CAPTION_STYLES, CLIP_FITS, CLIP_ROLES, CUT_TRANSITIONS } from "../footage/film.js";
17
+ import { CAPTION_PRESETS, CAPTION_STYLES, CLIP_FITS, CLIP_ROLES, CUT_TRANSITIONS, JUMP_TRANSITIONS } from "../footage/film.js";
18
+ import { normalizeKeyTerms } from "../footage/keyterms.js";
18
19
  import { ELEVENLABS_DEFAULT_MODEL } from "../voice/voiceover.js";
19
20
  import { actionSchema, type SceneAction } from "./actions-schema.js";
20
21
  import { COLOR_ROLES, COLOR_THEMES, isHexColor, type ColorRole } from "./colors.js";
@@ -500,6 +501,16 @@ const footageSchema = z
500
501
  .min(1, "a footage film needs at least one clip")
501
502
  .describe("The filmed clips in the film's order."),
502
503
  isolateVoice: z.boolean().default(false).describe("Clean the talking clips' voice of background noise (ElevenLabs Voice Isolator, paid with --commit) before transcribing."),
504
+ keyTerms: z
505
+ .array(z.string())
506
+ .superRefine((terms, context) => {
507
+ const normalized = normalizeKeyTerms(terms);
508
+ if (!normalized.ok) for (const message of normalized.errors) context.addIssue({ code: "custom", message });
509
+ })
510
+ .optional()
511
+ .describe(
512
+ "Names and brand words the transcript should spell as given (ElevenLabs Scribe keyterm prompting, billed on top of the transcription): up to 1000 terms of at most 50 characters and 5 words each; trimmed, deduplicated and sorted.",
513
+ ),
503
514
  fillers: z
504
515
  .array(nonBlank)
505
516
  .optional()
@@ -509,8 +520,19 @@ const footageSchema = z
509
520
  maxSeconds: z.number().min(1).max(600).optional().describe("The cut's longest length in seconds; later segments are shortened or dropped."),
510
521
  transitions: z
511
522
  .strictObject({
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."),
523
+ jump: z
524
+ .enum(JUMP_TRANSITIONS)
525
+ .default("cut")
526
+ .describe(
527
+ "A cut inside one talking clip: cut (the default), fade, zoom (a punch-in), whoosh, or auto (zoom when the frames on both sides look alike, fade when the camera moved; measured when the cut is built).",
528
+ ),
513
529
  clip: z.enum(CUT_TRANSITIONS).default("cut").describe("A cut from one clip to the next: cut (the default), fade, zoom or whoosh."),
530
+ autoThreshold: z
531
+ .number()
532
+ .min(0)
533
+ .max(1)
534
+ .optional()
535
+ .describe("With jump auto: the frame difference (0-1) from which a jump cut fades instead of zooming (default 0.08)."),
514
536
  })
515
537
  .prefault({})
516
538
  .describe("Default transitions by kind of cut; each segment of the EDL can name its own."),
@@ -527,6 +549,8 @@ const footageSchema = z
527
549
  .describe("ElevenLabs Video to Music scored to the cut itself (paid with --commit, cached)."),
528
550
  volume: volume.default(0.35).describe("The music's volume between sentences (0-1, default 0.35)."),
529
551
  duckedVolume: volume.default(0.1).describe("The music's volume under speech (0-1, default 0.1)."),
552
+ attack: z.number().min(0).max(5).optional().describe("Seconds the music takes to go down before speech (0-5, default 0.25)."),
553
+ release: z.number().min(0).max(5).optional().describe("Seconds the music takes to come back up after speech (0-5, default 0.5)."),
530
554
  })
531
555
  .superRefine((music, context) => {
532
556
  const sources = [music.file, music.prompt, music.fromVideo].filter((source) => source !== undefined).length;
@@ -543,12 +567,31 @@ const footageSchema = z
543
567
  .enum(CAPTION_PRESETS)
544
568
  .optional()
545
569
  .describe("Keeps a 9:16 film's captions inside a platform's safe zone: reels, shorts, tiktok or all; without it, layout decides."),
570
+ captionMaxLines: z
571
+ .number()
572
+ .int()
573
+ .min(1)
574
+ .max(4)
575
+ .optional()
576
+ .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."),
546
577
  edit: z
547
578
  .strictObject({
548
- zoomPercent: z.number().min(105).max(110).default(108).describe("How far a zoom cut punches in (105-110 %, default 108)."),
579
+ zoomPercent: z.number().min(105).max(112).default(108).describe("How far a zoom cut punches in (105-112 %, default 108)."),
580
+ zoomEaseFrames: z
581
+ .number()
582
+ .int()
583
+ .min(0)
584
+ .max(15)
585
+ .default(0)
586
+ .describe("Frames at 30 fps a zoom cut eases into its scale over (0-15, default 0: a step; 3-5 reads as a smooth punch-in)."),
549
587
  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
588
  kenBurnsPercent: z.number().min(0).max(5).default(0).describe("How far b-roll zooms over its length (0-5 %, default 0: still)."),
551
589
  endCardWhoosh: z.boolean().default(false).describe("Play the whoosh and pop as the end card comes in (default false)."),
590
+ cutAudioFadeMs: z.number().int().min(10).max(100).default(20).describe("The speech track's fade at every cut in milliseconds (10-100, default 20)."),
591
+ cutAudioCrossfade: z
592
+ .boolean()
593
+ .default(false)
594
+ .describe("Cross-fade the sound of the two sides of every cut over cutAudioFadeMs, centred on the cut, instead of a short dip to silence (default false)."),
552
595
  })
553
596
  .prefault({})
554
597
  .describe("The cut's look; the defaults read as an ordinary phone video."),
@@ -563,6 +606,16 @@ const footageSchema = z
563
606
  ])
564
607
  .default({ target: -14, truePeak: -1 })
565
608
  .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."),
609
+ mixLoudness: z
610
+ .union([
611
+ z.literal(false),
612
+ z.strictObject({
613
+ target: z.number().min(-40).max(-5).default(-14).describe("Integrated loudness in LUFS (-40 to -5, default -14)."),
614
+ truePeak: z.number().min(-9).max(0).default(-1).describe("The highest true peak in dBTP (-9 to 0, default -1)."),
615
+ }),
616
+ ])
617
+ .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."),
566
619
  cover: z
567
620
  .union([
568
621
  z.literal(false),
@@ -819,6 +872,13 @@ function layoutOverrideSchema(name: LayoutName) {
819
872
  caption: z
820
873
  .strictObject({
821
874
  top: y("The caption's top edge, in px from the frame's top.", caption.top),
875
+ bottom: z
876
+ .number()
877
+ .int()
878
+ .min(0)
879
+ .max(frame.height)
880
+ .optional()
881
+ .describe("The caption's bottom edge, in px from the frame's bottom: the box grows upwards from it and top is ignored. Default none."),
822
882
  left: x("The caption's left margin, in px from the frame's left edge.", caption.left),
823
883
  right: x("The caption's right margin, in px from the frame's right edge.", caption.right),
824
884
  fontSize: z.number().int().min(16).max(200).optional().describe(`The caption's font size in px (16-200). Default ${caption.fontSize}.`),
@@ -8,7 +8,10 @@ import { runFfprobe } from "./probe.js";
8
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
9
  */
10
10
 
11
- /** Accepted music file extensions and the content types a browser or a storage reports for each. */
11
+ /**
12
+ * Accepted music file extensions and the content types a browser or a storage reports for each. The video containers
13
+ * at the end are accepted for their sound (a clip's own audio as the bed); `probeAudio` still requires an audio stream.
14
+ */
12
15
  export const MUSIC_FILE_TYPES: Readonly<Record<string, readonly string[]>> = {
13
16
  ".mp3": ["audio/mpeg", "audio/mp3"],
14
17
  ".m4a": ["audio/mp4", "audio/x-m4a", "audio/m4a"],
@@ -18,6 +21,10 @@ export const MUSIC_FILE_TYPES: Readonly<Record<string, readonly string[]>> = {
18
21
  ".oga": ["audio/ogg"],
19
22
  ".opus": ["audio/opus", "audio/ogg"],
20
23
  ".flac": ["audio/flac", "audio/x-flac"],
24
+ ".mp4": ["video/mp4", "audio/mp4"],
25
+ ".m4v": ["video/x-m4v", "video/mp4"],
26
+ ".mov": ["video/quicktime"],
27
+ ".webm": ["video/webm", "audio/webm"],
21
28
  };
22
29
 
23
30
  export type MusicFileTypeCheck = { ok: true; extension: string | null; contentType: string | null } | { ok: false; error: string };
@@ -32,12 +39,18 @@ function getAcceptedTypes(extension: string): readonly string[] | null {
32
39
  return Object.hasOwn(MUSIC_FILE_TYPES, extension) ? (MUSIC_FILE_TYPES[extension] ?? null) : null;
33
40
  }
34
41
 
42
+ function getExtension(fileName: string | undefined): string | null {
43
+ const extension = fileName === undefined ? "" : extname(fileName).toLowerCase();
44
+ return extension === "" ? null : extension;
45
+ }
46
+
35
47
  /**
36
48
  * 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.
49
+ * the content type must be one of the extension's. Parameters (`; codecs=…`) and letter case are ignored. A name
50
+ * without an extension (a storage key) counts as no name.
38
51
  */
39
52
  export function checkMusicFileType(input: { fileName?: string; contentType?: string }): MusicFileTypeCheck {
40
- const extension = input.fileName === undefined ? null : extname(input.fileName).toLowerCase();
53
+ const extension = getExtension(input.fileName);
41
54
  const contentType = input.contentType === undefined ? null : normalizeContentType(input.contentType);
42
55
  if (extension === null && contentType === null) return { ok: false, error: "a music file needs a file name or a content type to check" };
43
56
  if (extension !== null) {
@@ -1,10 +1,10 @@
1
1
  import { readFileSync } from "node:fs";
2
2
 
3
- import type { CaptionLayout } from "../compose/timeline.js";
3
+ import { resolveLayout, 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 } from "./film.js";
7
+ import type { CaptionPreset, FootageFilm } from "./film.js";
8
8
 
9
9
  /**
10
10
  * The footage film's captions: plain phrases (the default style), the 9:16 caption box inside a platform's safe zone,
@@ -55,6 +55,32 @@ export function phraseChunks(words: TimedWord[]): PhraseChunk[] {
55
55
  return merged.map((group) => ({ words: group, start: (group[0] as TimedWord).start, end: (group[group.length - 1] as TimedWord).end }));
56
56
  }
57
57
 
58
+ /** When a caption chunk is on screen, in film seconds. */
59
+ export interface CaptionSpan {
60
+ start: number;
61
+ end: number;
62
+ }
63
+
64
+ const CAPTION_LEAD_SECONDS = 0.05;
65
+ const CAPTION_HOLD_SECONDS = 0.35;
66
+ const CAPTION_GAP_SECONDS = 0.06;
67
+ const MIN_CAPTION_SECONDS = 0.1;
68
+
69
+ const r3 = (value: number): number => Math.round(value * 1000) / 1000 || 0;
70
+
71
+ /**
72
+ * The span each caption chunk is shown for: from just before its first word to a moment after its last, never into
73
+ * the next chunk, the last one never past the cut's end; at least 0.1 s. The render and the draft time captions alike.
74
+ */
75
+ export function getCaptionSpans(chunks: readonly { start: number; end: number }[], cutEnd: number): CaptionSpan[] {
76
+ return chunks.map((chunk, index) => {
77
+ const next = chunks[index + 1];
78
+ const start = r3(chunk.start - CAPTION_LEAD_SECONDS);
79
+ const stop = Math.min(chunk.end + CAPTION_HOLD_SECONDS, next === undefined ? cutEnd : next.start - CAPTION_GAP_SECONDS);
80
+ return { start, end: r3(start + r3(Math.max(MIN_CAPTION_SECONDS, stop - start))) };
81
+ });
82
+ }
83
+
58
84
  /** Margins of a 1080×1920 frame that a platform's own buttons and text cover. */
59
85
  export interface SafeZone {
60
86
  top: number;
@@ -79,12 +105,27 @@ const FRAME_HEIGHT = 1920;
79
105
  const CAPTION_LINES_HEIGHT = 2.5;
80
106
  const CAPTION_PADDING = 40;
81
107
 
82
- /** The caption box of a 9:16 film with its bottom line kept above the preset's bottom margin, centred between equal sides. */
108
+ /**
109
+ * The caption box of a 9:16 film anchored by its foot at the preset's bottom margin, so a card of any number of lines
110
+ * grows upwards and never into the platform's interface; centred between equal sides. `top` is where a two-line box
111
+ * would start, for readers of it.
112
+ */
83
113
  export function getCaptionPresetLayout(preset: CaptionPreset, fontSize: number): CaptionLayout {
84
114
  const zone = CAPTION_SAFE_ZONES[preset];
85
115
  const side = Math.max(zone.left, zone.right);
86
116
  const top = Math.round(FRAME_HEIGHT - zone.bottom - CAPTION_LINES_HEIGHT * fontSize - CAPTION_PADDING);
87
- return { top, left: side, right: side, fontSize };
117
+ return { top, bottom: zone.bottom, left: side, right: side, fontSize };
118
+ }
119
+
120
+ /**
121
+ * The caption box a footage film's captions are drawn in: the format's layout, with a 9:16 film's box placed by its
122
+ * caption preset unless the project overrides the caption box (`marketing.json` `layout`). The render and the draft
123
+ * share it.
124
+ */
125
+ export function getFootageCaptionLayout(film: Pick<FootageFilm, "format" | "captionPreset">, override: LayoutOverride = {}): CaptionLayout {
126
+ const base = resolveLayout(film.format, override);
127
+ if (film.captionPreset === undefined || film.format !== "9:16" || override.caption !== undefined) return base.caption;
128
+ return getCaptionPresetLayout(film.captionPreset, base.caption.fontSize);
88
129
  }
89
130
 
90
131
  /** A character a font is asked to draw and does not have. */
@@ -2,11 +2,11 @@ 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 { captionChunks, type CaptionLayout } from "../compose/timeline.js";
5
+ import { CAPTION_LINE_HEIGHT, captionChunks, getCaptionPillCss, getCaptionPositionCss, type CaptionLayout } from "../compose/timeline.js";
6
6
  import type { TimedWord } from "../voice/voiceover.js";
7
- import { phraseChunks } from "./captions.js";
7
+ import { getCaptionSpans, phraseChunks, type CaptionSpan } from "./captions.js";
8
8
  import { getEdlDuration, getSegmentStarts, type Edl } from "./edl.js";
9
- import { DEFAULT_EDIT, getFootageEdit, type FootageFilm } from "./film.js";
9
+ import { CAPTION_MIN_FONT_SCALE, DEFAULT_EDIT, getFootageEdit, type FootageEdit, type FootageFilm } from "./film.js";
10
10
  import { FOOTAGE_FPS } from "./normalize.js";
11
11
 
12
12
  const r3 = (value: number): number => Math.round(value * 1000) / 1000 || 0;
@@ -14,7 +14,7 @@ const r3 = (value: number): number => Math.round(value * 1000) / 1000 || 0;
14
14
  /**
15
15
  * The HyperFrames composition of a footage film (the same 0.8.85 contract as `composeFilm`): one `<video>` clip per
16
16
  * EDL segment over the normalized clip with its media start, the transitions (`fade` cross-fades from the segment
17
- * before over `fadeFrames`, `zoom` punches in by `zoomPercent` on alternate jump cuts, `whoosh` plays the whoosh
17
+ * before over `fadeFrames`, `zoom` punches in by `zoomPercent` on alternate jump cuts, eased over `zoomEaseFrames`, `whoosh` plays the whoosh
18
18
  * sound), a slow zoom on `kenburns` segments, the captions (plain phrases, or the word-highlight pill), the end card
19
19
  * over the cut's last frame (its whoosh only with `isEndCardWhoosh`), the cut speech track and the ducked music.
20
20
  */
@@ -28,8 +28,14 @@ const HAND_KEN_BURNS_PERCENT = 4;
28
28
  export const END_CARD_SECONDS = 3;
29
29
 
30
30
  export interface FootageComposeAssets {
31
- /** The normalized clips by id. */
31
+ /** The normalized clips by id (read when there is no `picture`). */
32
32
  clips: Record<string, string>;
33
+ /**
34
+ * The cut's picture in film time (`planFootagePicture`, cross-fades drawn in): the composition then plays it as one
35
+ * `<video>` and zooms that one element, instead of one `<video>` per segment. One video keeps hyperframes' frame
36
+ * extraction to one ffmpeg and its Chrome renderer lean (issue #1030). Absent: one `<video>` per segment.
37
+ */
38
+ picture?: string;
33
39
  /** The cut speech track (as long as the cut). */
34
40
  speech: string;
35
41
  /** The ducked music track, or null for none. */
@@ -71,6 +77,18 @@ export function getSegmentScales(edl: Edl, zoomPercent = DEFAULT_EDIT.zoomPercen
71
77
  return scales;
72
78
  }
73
79
 
80
+ /**
81
+ * The frames each segment's zoom eases over (`zoomEaseFrames`, at most the segment's own frames): a `zoom` cut after
82
+ * the first segment that changes the scale and is not `kenburns` (its slow zoom owns the scale); 0 for every other.
83
+ */
84
+ export function getSegmentZoomEases(edl: Edl, edit: Pick<FootageEdit, "zoomPercent" | "zoomEaseFrames">): number[] {
85
+ const scales = getSegmentScales(edl, edit.zoomPercent);
86
+ return edl.segments.map((segment, index) => {
87
+ const isEased = edit.zoomEaseFrames > 0 && index > 0 && segment.transition === "zoom" && segment.motion !== "kenburns" && scales[index - 1] !== scales[index];
88
+ return isEased ? Math.max(1, Math.min(edit.zoomEaseFrames, Math.floor((segment.end - segment.start) * FOOTAGE_FPS))) : 0;
89
+ });
90
+ }
91
+
74
92
  export function composeFootage(input: FootageComposeInput): string {
75
93
  const { film, edl, words, frame, colors: c, fonts, assets, caption: captionBox } = input;
76
94
  const starts = getSegmentStarts(edl);
@@ -78,31 +96,46 @@ export function composeFootage(input: FootageComposeInput): string {
78
96
  const end = getFootageFilmSeconds(film, edl);
79
97
  const edit = getFootageEdit(film);
80
98
  const scales = getSegmentScales(edl, edit.zoomPercent);
99
+ const eases = getSegmentZoomEases(edl, edit);
81
100
  const fadeSeconds = r3(edit.fadeFrames / FOOTAGE_FPS);
82
101
  const kenBurnsScale = 1 + (edit.kenBurnsPercent > 0 ? edit.kenBurnsPercent : HAND_KEN_BURNS_PERCENT) / 100;
83
102
 
84
- const segments = edl.segments.map((segment, index) => {
85
- const src = assets.clips[segment.clip];
86
- if (src === undefined) throw new Error(`The EDL names clip "${segment.clip}", which the film has no file for.`);
87
- const next = edl.segments[index + 1];
88
- const tail = next?.transition === "fade" ? fadeSeconds : 0;
89
- const start = starts[index] as number;
90
- const duration = r3(segment.end - segment.start + tail);
91
- const scale = scales[index] as number;
92
- const style = scale === 1 ? "" : ` style="transform:scale(${scale})"`;
93
- 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>`;
94
- });
103
+ const picture = assets.picture;
104
+ const segments =
105
+ picture === undefined
106
+ ? edl.segments.map((segment, index) => {
107
+ const src = assets.clips[segment.clip];
108
+ if (src === undefined) throw new Error(`The EDL names clip "${segment.clip}", which the film has no file for.`);
109
+ const next = edl.segments[index + 1];
110
+ const tail = next?.transition === "fade" ? fadeSeconds : 0;
111
+ const start = starts[index] as number;
112
+ const duration = r3(segment.end - segment.start + tail);
113
+ const scale = scales[index] as number;
114
+ const style = scale === 1 ? "" : ` style="transform:scale(${scale})"`;
115
+ 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>`;
116
+ })
117
+ : [`<video id="picture" class="clip shot" src="${escapeHtml(picture)}" data-start="0" data-media-start="0" data-duration="${cutEnd}" muted playsinline></video>`];
95
118
 
96
119
  const tweens: string[] = [];
97
120
  edl.segments.forEach((segment, index) => {
98
121
  const start = starts[index] as number;
99
- if (segment.transition === "fade" && index > 0) {
100
- tweens.push(`tl.fromTo("#seg${index}", { opacity: 0 }, { opacity: 1, duration: ${fadeSeconds}, ease: "none", immediateRender: false }, ${start});`);
122
+ const scale = scales[index] as number;
123
+ const target = picture === undefined ? `#seg${index}` : "#picture";
124
+ // One video carries every segment: each one sets the zoom it starts at (a fade is already in the picture).
125
+ if (picture !== undefined) tweens.push(`tl.set("#picture", { scale: ${scale} }, ${start});`);
126
+ if (picture === undefined && segment.transition === "fade" && index > 0) {
127
+ tweens.push(`tl.fromTo("${target}", { opacity: 0 }, { opacity: 1, duration: ${fadeSeconds}, ease: "none", immediateRender: false }, ${start});`);
128
+ }
129
+ const ease = eases[index] as number;
130
+ if (ease > 0) {
131
+ // Eases from the scale on screen before the cut, so the punch-in (or back out) reads as one move of the camera.
132
+ tweens.push(
133
+ `tl.fromTo("${target}", { scale: ${scales[index - 1] as number} }, { scale: ${scales[index] as number}, duration: ${r3(ease / FOOTAGE_FPS)}, ease: "power1.out", immediateRender: false }, ${start});`,
134
+ );
101
135
  }
102
136
  if (segment.motion === "kenburns") {
103
- const from = scales[index] as number;
104
137
  tweens.push(
105
- `tl.fromTo("#seg${index}", { scale: ${from} }, { scale: ${r3(from * kenBurnsScale)}, duration: ${r3(segment.end - segment.start)}, ease: "none", immediateRender: false }, ${start});`,
138
+ `tl.fromTo("${target}", { scale: ${scale} }, { scale: ${r3(scale * kenBurnsScale)}, duration: ${r3(segment.end - segment.start)}, ease: "none", immediateRender: false }, ${start});`,
106
139
  );
107
140
  }
108
141
  });
@@ -110,18 +143,19 @@ export function composeFootage(input: FootageComposeInput): string {
110
143
  // --- Captions: plain phrases, or the pill that lights each word ---
111
144
  const isHighlight = film.captionStyle === "highlight";
112
145
  const caption = !film.captions ? [] : isHighlight ? captionChunks(words) : phraseChunks(words);
146
+ const spans = getCaptionSpans(caption, cutEnd);
113
147
  const captionHtml = caption
114
148
  .map((chunk, i) => {
115
- const next = caption[i + 1];
116
- const start = r3(chunk.start - 0.05);
117
- const stop = Math.min(chunk.end + 0.35, next === undefined ? cutEnd : next.start - 0.06);
149
+ const { start, end: stop } = spans[i] as CaptionSpan;
118
150
  const box = isHighlight
119
151
  ? `<p class="pill">${chunk.words.map((w, j) => `<span id="cw${i}_${j}">${escapeHtml(w.text)}</span>`).join(" ")}</p>`
120
152
  : `<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>`;
153
+ return `<div id="cap${i}" class="clip caption" data-start="${start}" data-duration="${r3(stop - start)}">${box}</div>`;
122
154
  })
123
155
  .join("\n ");
124
156
 
157
+ const captionFit = film.captions && film.captionMaxLines !== undefined ? getCaptionFitScript(film.captionMaxLines, Math.round(captionBox.fontSize * CAPTION_MIN_FONT_SCALE)) : "";
158
+
125
159
  // --- Sound ---
126
160
  const sfx: { src: string; t: number; volume: number; dur: number }[] = [];
127
161
  const play = (event: SfxEvent, t: number, volume: number, dur: number) => {
@@ -183,10 +217,10 @@ html,body{width:${frame.width}px;height:${frame.height}px;overflow:hidden;backgr
183
217
  #root{position:relative;width:${frame.width}px;height:${frame.height}px;overflow:hidden;background:#000;font-family:${bodyFont};color:${c.foreground}}
184
218
  .shot{position:absolute;inset:0;width:100%;height:100%;object-fit:cover;transform-origin:50% 42%}
185
219
  .shade{position:absolute;inset:0;background:${c.background};opacity:0}
186
- .caption{position:absolute;left:${captionBox.left}px;right:${captionBox.right}px;top:${captionBox.top}px;display:flex;justify-content:center}
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}}
220
+ .caption{position:absolute;left:${captionBox.left}px;right:${captionBox.right}px;${getCaptionPositionCss(captionBox)};display:flex;justify-content:center}
221
+ .pill{${getCaptionPillCss(captionBox.fontSize)};border-radius:22px;background:${c.captionBackground};box-shadow:0 14px 44px rgba(0,0,0,.5);color:${c.captionText}}
188
222
  .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)}
223
+ .phrase{font-weight:650;font-size:${captionBox.fontSize}px;line-height:${CAPTION_LINE_HEIGHT};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)}
190
224
  .endcard{position:absolute;inset:0;display:flex;flex-direction:column;justify-content:center;align-items:center;padding:0 80px;text-align:center}
191
225
  .brand{display:flex;justify-content:center;align-items:center;gap:18px;font-family:${headingFont};font-size:46px}
192
226
  .logo{height:60px;width:auto}
@@ -202,7 +236,7 @@ html,body{width:${frame.width}px;height:${frame.height}px;overflow:hidden;backgr
202
236
  ${captionHtml}
203
237
  ${audio}
204
238
  </div>
205
- <script>
239
+ ${captionFit}<script>
206
240
  const tl = gsap.timeline({ paused: true });
207
241
  ${tweens.join("\n")}
208
242
  const captions = ${JSON.stringify(isHighlight ? caption.map((chunk) => chunk.words.map((w) => w.start)) : [])};
@@ -219,3 +253,31 @@ window.__timelines["${COMPOSITION_ID}"] = tl;
219
253
  </html>
220
254
  `;
221
255
  }
256
+
257
+ /**
258
+ * A page script that shrinks each caption's font in 1 px steps until its text takes at most `maxLines` lines, or the
259
+ * font reaches `minFontSize`. Only the browser knows how the font wraps, so it measures there: once at load and again
260
+ * when the fonts are ready (hyperframes waits for them before the first frame). Hidden clips keep their layout.
261
+ */
262
+ function getCaptionFitScript(maxLines: number, minFontSize: number): string {
263
+ return `<script>
264
+ (() => {
265
+ const captionMaxLines = ${maxLines}, captionMinFontSize = ${minFontSize};
266
+ const countLines = (el) => {
267
+ const style = getComputedStyle(el);
268
+ return Math.round((el.clientHeight - parseFloat(style.paddingTop) - parseFloat(style.paddingBottom)) / parseFloat(style.lineHeight));
269
+ };
270
+ const fit = () => document.querySelectorAll(".caption > p").forEach((el) => {
271
+ el.style.fontSize = "";
272
+ let size = parseFloat(getComputedStyle(el).fontSize);
273
+ while (countLines(el) > captionMaxLines && size > captionMinFontSize) {
274
+ size -= 1;
275
+ el.style.fontSize = size + "px";
276
+ }
277
+ });
278
+ fit();
279
+ if (document.fonts) document.fonts.ready.then(fit);
280
+ })();
281
+ </script>
282
+ `;
283
+ }
@@ -0,0 +1,104 @@
1
+ import { mkdirSync, readFileSync, rmSync } from "node:fs";
2
+ import { join } from "node:path";
3
+
4
+ import type { Edl } from "./edl.js";
5
+ import { DEFAULT_AUTO_THRESHOLD } from "./film.js";
6
+ import { FOOTAGE_FPS } from "./normalize.js";
7
+ import { runFfmpeg } from "./process.js";
8
+
9
+ /**
10
+ * Transitions chosen from the frames around each jump cut (`transitions.jump: "auto"`): the last frame before a cut
11
+ * and the first after it, both from the normalized clips, are shrunk to a small gray thumbnail and compared. A small
12
+ * difference (the same framing, a removed filler) gets an eased punch-in (`zoom`), a large one (the camera moved) a
13
+ * short dissolve (`fade`). Deterministic and local: ffmpeg only, no provider.
14
+ */
15
+
16
+ /** The thumbnail both frames are compared at: small enough that handheld shake and noise average out. */
17
+ export const CUT_THUMBNAIL = { width: 48, height: 48 } as const;
18
+
19
+ /** What the frames around one cut measured and the transition it got. */
20
+ export interface CutMeasure {
21
+ /** The id of the segment the cut starts. */
22
+ segment: string;
23
+ /** The mean absolute difference of the two thumbnails' gray levels, 0 (the same) to 1 (black against white). */
24
+ difference: number;
25
+ transition: "zoom" | "fade";
26
+ }
27
+
28
+ const r4 = (value: number): number => Math.round(value * 10000) / 10000 || 0;
29
+
30
+ /** The mean absolute difference of two gray frames of the same size, 0-1. */
31
+ export function measureFrameDifference(before: Uint8Array, after: Uint8Array): number {
32
+ if (before.length === 0 || before.length !== after.length) {
33
+ throw new Error(`Comparing the frames around a cut needs two frames of one size, got ${before.length} and ${after.length} bytes.`);
34
+ }
35
+ let sum = 0;
36
+ for (let index = 0; index < before.length; index++) sum += Math.abs((before[index] as number) - (after[index] as number));
37
+ return r4(sum / before.length / 255);
38
+ }
39
+
40
+ /** `fade` from `threshold` up (the picture moved), `zoom` below it (the same shot). */
41
+ export function chooseCutTransition(difference: number, threshold: number = DEFAULT_AUTO_THRESHOLD): "zoom" | "fade" {
42
+ return difference >= threshold ? "fade" : "zoom";
43
+ }
44
+
45
+ /** One frame of a clip at `seconds` as a raw gray thumbnail (`CUT_THUMBNAIL`). */
46
+ export function buildCutFrameArgs(file: string, seconds: number, output: string): string[] {
47
+ const { width, height } = CUT_THUMBNAIL;
48
+ return ["-v", "error", "-y", "-ss", String(seconds), "-i", file, "-frames:v", "1", "-vf", `scale=${width}:${height}:flags=area,format=gray`, "-f", "rawvideo", output];
49
+ }
50
+
51
+ /** The indexes of the jump cuts the auto choice sets: a plain cut inside one clip, after the first segment. */
52
+ export function findAutoCuts(edl: Edl): number[] {
53
+ return edl.segments.flatMap((segment, index) => {
54
+ const previous = edl.segments[index - 1];
55
+ return previous !== undefined && previous.clip === segment.clip && segment.transition === "cut" ? [index] : [];
56
+ });
57
+ }
58
+
59
+ export interface ChooseCutTransitionsOptions {
60
+ /** The difference from which a cut fades; default `DEFAULT_AUTO_THRESHOLD`. */
61
+ threshold?: number;
62
+ /** A folder for the thumbnails; created, and removed when done. */
63
+ workDir: string;
64
+ signal?: AbortSignal;
65
+ }
66
+
67
+ /**
68
+ * Measures every plain jump cut of `edl` (`findAutoCuts`) on the normalized clips and gives it `zoom` or `fade`. Cuts
69
+ * between clips and every other transition stay as they are. Answers the new EDL and what each cut measured.
70
+ */
71
+ export async function chooseCutTransitions(edl: Edl, clips: Record<string, string>, options: ChooseCutTransitionsOptions): Promise<{ edl: Edl; cuts: CutMeasure[] }> {
72
+ const threshold = options.threshold ?? DEFAULT_AUTO_THRESHOLD;
73
+ if (!(threshold >= 0 && threshold <= 1)) throw new Error(`transitions.autoThreshold must be between 0 and 1, got ${String(threshold)}.`);
74
+ const indexes = findAutoCuts(edl);
75
+ if (indexes.length === 0) return { edl, cuts: [] };
76
+ const signal = options.signal === undefined ? {} : { signal: options.signal };
77
+ const getClip = (id: string): string => {
78
+ const file = clips[id];
79
+ if (file === undefined) throw new Error(`No file for clip "${id}" of the EDL.`);
80
+ return file;
81
+ };
82
+ mkdirSync(options.workDir, { recursive: true });
83
+ const segments = [...edl.segments];
84
+ const cuts: CutMeasure[] = [];
85
+ try {
86
+ for (const index of indexes) {
87
+ const segment = segments[index] as Edl["segments"][number];
88
+ const previous = segments[index - 1] as Edl["segments"][number];
89
+ const beforeFile = join(options.workDir, `${segment.id}-before.gray`);
90
+ const afterFile = join(options.workDir, `${segment.id}-after.gray`);
91
+ // The last frame the cut shows before it, and the first after it.
92
+ const beforeAt = Math.round(Math.max(previous.start, previous.end - 1 / FOOTAGE_FPS) * 1000) / 1000;
93
+ await runFfmpeg(`The frame before cut ${segment.id}`, buildCutFrameArgs(getClip(previous.clip), beforeAt, beforeFile), { ...signal, output: beforeFile });
94
+ await runFfmpeg(`The frame after cut ${segment.id}`, buildCutFrameArgs(getClip(segment.clip), segment.start, afterFile), { ...signal, output: afterFile });
95
+ const difference = measureFrameDifference(readFileSync(beforeFile), readFileSync(afterFile));
96
+ const transition = chooseCutTransition(difference, threshold);
97
+ segments[index] = { ...segment, transition };
98
+ cuts.push({ segment: segment.id, difference, transition });
99
+ }
100
+ } finally {
101
+ rmSync(options.workDir, { recursive: true, force: true });
102
+ }
103
+ return { edl: { ...edl, segments }, cuts };
104
+ }
@@ -0,0 +1,75 @@
1
+ import { existsSync, statfsSync } from "node:fs";
2
+ import { tmpdir } from "node:os";
3
+ import { dirname, resolve } from "node:path";
4
+
5
+ /**
6
+ * The free space a hyperframes render needs. hyperframes 0.8.85 refuses to render (exit code 1, "Low disk space")
7
+ * when its temp folder (`os.tmpdir()`, where it also extracts the clips' frames) or its output's folder has under
8
+ * 1 GiB free, measured as `statfs` `bsize * bavail`. The kit measures the same way, so it never refuses a render
9
+ * hyperframes would run.
10
+ */
11
+ export const RENDER_MIN_FREE_BYTES = 1024 ** 3;
12
+
13
+ /** Reads a folder's free bytes; null when it cannot be read. Injected in tests. */
14
+ export type FreeBytesReader = (folder: string) => number | null;
15
+
16
+ /** The nearest existing folder of a path: a folder the run creates later is measured on the disk it will live on. */
17
+ function findExistingFolder(path: string): string {
18
+ let current = resolve(path);
19
+ while (!existsSync(current)) {
20
+ const parent = dirname(current);
21
+ if (parent === current) return current;
22
+ current = parent;
23
+ }
24
+ return current;
25
+ }
26
+
27
+ /** Free bytes for an unprivileged writer at `folder` (or its nearest existing parent); null when `statfs` fails. */
28
+ export function getFreeBytes(folder: string): number | null {
29
+ try {
30
+ const stats = statfsSync(findExistingFolder(folder));
31
+ return stats.bsize * stats.bavail;
32
+ } catch {
33
+ // An unreadable disk is not reported: hyperframes passes it as "Unable to check" too.
34
+ return null;
35
+ }
36
+ }
37
+
38
+ /**
39
+ * The temp folder the hyperframes process will use: `tempDir` when given (the kit passes it as `TMPDIR`), else the
40
+ * `TMPDIR`, `TMP` or `TEMP` of the environment it runs with, else this process's `os.tmpdir()`.
41
+ */
42
+ export function getRenderTempDir(env: NodeJS.ProcessEnv, tempDir?: string): string {
43
+ if (tempDir !== undefined && tempDir.length > 0) return resolve(tempDir);
44
+ for (const name of ["TMPDIR", "TMP", "TEMP"]) {
45
+ const value = env[name];
46
+ if (value !== undefined && value.length > 0) return resolve(value);
47
+ }
48
+ return tmpdir();
49
+ }
50
+
51
+ const toGiB = (bytes: number): string => (bytes / 1024 ** 3).toFixed(1);
52
+
53
+ /**
54
+ * One sentence per folder with less free space than a render needs, naming the folder and how to fix it. Folders
55
+ * are checked once each; an unreadable one is skipped.
56
+ */
57
+ export function findLowDiskProblems(folders: { temp: string; build?: string }, readFreeBytes: FreeBytesReader = getFreeBytes): string[] {
58
+ const entries: { folder: string; role: string; hint: string }[] = [
59
+ {
60
+ folder: resolve(folders.temp),
61
+ role: "the temp folder",
62
+ hint: "hyperframes extracts the clips' frames there (hundreds of MB per minute of film): point TMPDIR (or renderFootage's tempDir) at a data volume, not a small tmpfs",
63
+ },
64
+ ];
65
+ if (folders.build !== undefined && resolve(folders.build) !== entries[0]?.folder) {
66
+ entries.push({ folder: resolve(folders.build), role: "the build folder", hint: "hyperframes writes the render there: free space or move buildDir to a larger disk" });
67
+ }
68
+ const problems: string[] = [];
69
+ for (const entry of entries) {
70
+ const free = readFreeBytes(entry.folder);
71
+ if (free === null || free >= RENDER_MIN_FREE_BYTES) continue;
72
+ problems.push(`${entry.role} ${entry.folder} has ${toGiB(free)} GiB free and a hyperframes render needs ${toGiB(RENDER_MIN_FREE_BYTES)} GiB; ${entry.hint}.`);
73
+ }
74
+ return problems;
75
+ }