@softure-ai/marketing-kit 0.4.0 → 0.6.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 (98) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/README.md +87 -6
  3. package/dist/config/config.d.ts.map +1 -1
  4. package/dist/config/config.js +7 -0
  5. package/dist/config/config.js.map +1 -1
  6. package/dist/config/schema.d.ts +1 -0
  7. package/dist/config/schema.d.ts.map +1 -1
  8. package/dist/config/schema.js +11 -0
  9. package/dist/config/schema.js.map +1 -1
  10. package/dist/footage/audio.d.ts +56 -0
  11. package/dist/footage/audio.d.ts.map +1 -0
  12. package/dist/footage/audio.js +112 -0
  13. package/dist/footage/audio.js.map +1 -0
  14. package/dist/footage/captions.d.ts +21 -2
  15. package/dist/footage/captions.d.ts.map +1 -1
  16. package/dist/footage/captions.js +29 -0
  17. package/dist/footage/captions.js.map +1 -1
  18. package/dist/footage/compose.d.ts.map +1 -1
  19. package/dist/footage/compose.js +4 -5
  20. package/dist/footage/compose.js.map +1 -1
  21. package/dist/footage/disk.d.ts +25 -0
  22. package/dist/footage/disk.d.ts.map +1 -0
  23. package/dist/footage/disk.js +72 -0
  24. package/dist/footage/disk.js.map +1 -0
  25. package/dist/footage/draft.d.ts +105 -0
  26. package/dist/footage/draft.d.ts.map +1 -0
  27. package/dist/footage/draft.js +282 -0
  28. package/dist/footage/draft.js.map +1 -0
  29. package/dist/footage/elevenlabs.d.ts.map +1 -1
  30. package/dist/footage/elevenlabs.js +2 -0
  31. package/dist/footage/elevenlabs.js.map +1 -1
  32. package/dist/footage/film.d.ts +12 -0
  33. package/dist/footage/film.d.ts.map +1 -1
  34. package/dist/footage/film.js.map +1 -1
  35. package/dist/footage/keyterms.d.ts +26 -0
  36. package/dist/footage/keyterms.d.ts.map +1 -0
  37. package/dist/footage/keyterms.js +36 -0
  38. package/dist/footage/keyterms.js.map +1 -0
  39. package/dist/footage/normalize.d.ts +21 -2
  40. package/dist/footage/normalize.d.ts.map +1 -1
  41. package/dist/footage/normalize.js +35 -11
  42. package/dist/footage/normalize.js.map +1 -1
  43. package/dist/footage/paid.d.ts +2 -1
  44. package/dist/footage/paid.d.ts.map +1 -1
  45. package/dist/footage/paid.js +13 -3
  46. package/dist/footage/paid.js.map +1 -1
  47. package/dist/footage/pipeline.d.ts +21 -4
  48. package/dist/footage/pipeline.d.ts.map +1 -1
  49. package/dist/footage/pipeline.js +58 -10
  50. package/dist/footage/pipeline.js.map +1 -1
  51. package/dist/footage/probe.d.ts +10 -0
  52. package/dist/footage/probe.d.ts.map +1 -1
  53. package/dist/footage/probe.js +10 -5
  54. package/dist/footage/probe.js.map +1 -1
  55. package/dist/footage/process.d.ts +2 -0
  56. package/dist/footage/process.d.ts.map +1 -1
  57. package/dist/footage/process.js +1 -0
  58. package/dist/footage/process.js.map +1 -1
  59. package/dist/footage/providers.d.ts +12 -3
  60. package/dist/footage/providers.d.ts.map +1 -1
  61. package/dist/footage/providers.js.map +1 -1
  62. package/dist/footage/render.d.ts +1 -1
  63. package/dist/footage/render.d.ts.map +1 -1
  64. package/dist/footage/render.js +5 -3
  65. package/dist/footage/render.js.map +1 -1
  66. package/dist/footage/tools.d.ts +15 -3
  67. package/dist/footage/tools.d.ts.map +1 -1
  68. package/dist/footage/tools.js +15 -2
  69. package/dist/footage/tools.js.map +1 -1
  70. package/dist/index.d.ts +8 -4
  71. package/dist/index.d.ts.map +1 -1
  72. package/dist/index.js +8 -4
  73. package/dist/index.js.map +1 -1
  74. package/docker/footage-worker.Dockerfile +6 -0
  75. package/fonts/DejaVuSans-Bold-Latin.ttf +0 -0
  76. package/fonts/LICENSE-DejaVu.txt +46 -0
  77. package/fonts/README.md +12 -0
  78. package/package.json +2 -1
  79. package/schema/marketing.schema.json +7 -0
  80. package/src/config/config.ts +8 -0
  81. package/src/config/schema.ts +11 -0
  82. package/src/footage/audio.ts +136 -0
  83. package/src/footage/captions.ts +39 -2
  84. package/src/footage/compose.ts +4 -5
  85. package/src/footage/disk.ts +75 -0
  86. package/src/footage/draft.ts +366 -0
  87. package/src/footage/elevenlabs.ts +1 -0
  88. package/src/footage/film.ts +16 -1
  89. package/src/footage/keyterms.ts +38 -0
  90. package/src/footage/normalize.ts +47 -10
  91. package/src/footage/paid.ts +12 -3
  92. package/src/footage/pipeline.ts +67 -13
  93. package/src/footage/probe.ts +10 -5
  94. package/src/footage/process.ts +3 -0
  95. package/src/footage/providers.ts +10 -3
  96. package/src/footage/render.ts +5 -3
  97. package/src/footage/tools.ts +23 -3
  98. package/src/index.ts +46 -2
@@ -0,0 +1,12 @@
1
+ # Fonts
2
+
3
+ `DejaVuSans-Bold-Latin.ttf` draws the captions of a footage draft (`renderFootageDraft`). It is DejaVu Sans Bold
4
+ ([dejavu-fonts.github.io](https://dejavu-fonts.github.io/)) subset to Basic Latin, Latin-1, Latin Extended-A (every
5
+ Polish letter) and common punctuation:
6
+
7
+ ```bash
8
+ pyftsubset DejaVuSans-Bold.ttf --unicodes="U+0020-007E,U+00A0-017F,U+2010-2027,U+2030-203A,U+20AC,U+2122" \
9
+ --layout-features='kern,liga' --output-file=DejaVuSans-Bold-Latin.ttf
10
+ ```
11
+
12
+ Licence: [LICENSE-DejaVu.txt](LICENSE-DejaVu.txt) (the Bitstream Vera licence; DejaVu changes are in the public domain).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@softure-ai/marketing-kit",
3
- "version": "0.4.0",
3
+ "version": "0.6.0",
4
4
  "description": "SOFTURE AI marketing kit: a CLI that turns a project's real app into a vertical film (cached voiceover, frame-by-frame recording, HTML composition, hyperframes render) plus per-platform post copy and OG images.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -19,6 +19,7 @@
19
19
  "src",
20
20
  "schema",
21
21
  "docker",
22
+ "fonts",
22
23
  "!src/**/*.test.ts",
23
24
  "!src/**/*.test.tsx"
24
25
  ],
@@ -2711,6 +2711,13 @@
2711
2711
  "description": "Clean the talking clips' voice of background noise (ElevenLabs Voice Isolator, paid with --commit) before transcribing.",
2712
2712
  "type": "boolean"
2713
2713
  },
2714
+ "keyTerms": {
2715
+ "description": "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.",
2716
+ "type": "array",
2717
+ "items": {
2718
+ "type": "string"
2719
+ }
2720
+ },
2714
2721
  "fillers": {
2715
2722
  "description": "Filler words cut out of the talking clips, compared without case, punctuation and repeated letters; without it, the language's defaults (pl: yyy, eee, yhm and more; en: um, uh and more).",
2716
2723
  "type": "array",
@@ -4,6 +4,7 @@ import { dirname, resolve } from "node:path";
4
4
  import { getLayoutName } from "../compose/timeline.js";
5
5
  import type { Device, FilmScript } from "../film.js";
6
6
  import { DEFAULT_MUSIC_VOLUME, getDefaultFillers, type FootageFilm, type MusicSource } from "../footage/film.js";
7
+ import { normalizeKeyTerms } from "../footage/keyterms.js";
7
8
  import type { LayoutOverride } from "../compose/timeline.js";
8
9
  import { getMarketingMessages, type MarketingMessages } from "../messages/index.js";
9
10
  import { DEFAULT_LINK_IN_BIO, PLATFORMS, type Platform } from "../platforms.js";
@@ -201,6 +202,12 @@ function resolveMusicSource(music: NonNullable<MarketingJson["footage"][number][
201
202
  return { kind: "video", description: fromVideo.description, tags: fromVideo.tags };
202
203
  }
203
204
 
205
+ /** The film's key terms, normalized (the schema has checked them); none when absent or empty. */
206
+ function resolveKeyTerms(terms: string[] | undefined): { keyTerms?: string[] } {
207
+ const normalized = normalizeKeyTerms(terms ?? []);
208
+ return normalized.ok && normalized.terms.length > 0 ? { keyTerms: normalized.terms } : {};
209
+ }
210
+
204
211
  function resolveFootage(data: MarketingJson, at: (relative: string) => string): FootageConfig[] {
205
212
  const posts = new Map((data.social?.posts ?? []).map((post) => [post.video, post]));
206
213
  const platforms = data.social?.platforms ?? {};
@@ -223,6 +230,7 @@ function resolveFootage(data: MarketingJson, at: (relative: string) => string):
223
230
  script: clip.script ?? null,
224
231
  })),
225
232
  isolateVoice: film.isolateVoice,
233
+ ...resolveKeyTerms(film.keyTerms),
226
234
  cut: { fillers: film.fillers ?? getDefaultFillers(language), pauseSeconds: film.pauseSeconds, padSeconds: film.padSeconds, maxSeconds: film.maxSeconds ?? null },
227
235
  transitions: film.transitions,
228
236
  music:
@@ -15,6 +15,7 @@ import {
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
17
  import { CAPTION_PRESETS, CAPTION_STYLES, CLIP_FITS, CLIP_ROLES, CUT_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()
@@ -0,0 +1,136 @@
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
+ /**
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
+ */
15
+ export const MUSIC_FILE_TYPES: Readonly<Record<string, readonly string[]>> = {
16
+ ".mp3": ["audio/mpeg", "audio/mp3"],
17
+ ".m4a": ["audio/mp4", "audio/x-m4a", "audio/m4a"],
18
+ ".aac": ["audio/aac"],
19
+ ".wav": ["audio/wav", "audio/x-wav", "audio/wave", "audio/vnd.wave"],
20
+ ".ogg": ["audio/ogg"],
21
+ ".oga": ["audio/ogg"],
22
+ ".opus": ["audio/opus", "audio/ogg"],
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"],
28
+ };
29
+
30
+ export type MusicFileTypeCheck = { ok: true; extension: string | null; contentType: string | null } | { ok: false; error: string };
31
+
32
+ const ACCEPTED_LIST = Object.keys(MUSIC_FILE_TYPES).join(", ");
33
+
34
+ function normalizeContentType(contentType: string): string {
35
+ return (contentType.split(";")[0] ?? "").trim().toLowerCase();
36
+ }
37
+
38
+ function getAcceptedTypes(extension: string): readonly string[] | null {
39
+ return Object.hasOwn(MUSIC_FILE_TYPES, extension) ? (MUSIC_FILE_TYPES[extension] ?? null) : null;
40
+ }
41
+
42
+ function getExtension(fileName: string | undefined): string | null {
43
+ const extension = fileName === undefined ? "" : extname(fileName).toLowerCase();
44
+ return extension === "" ? null : extension;
45
+ }
46
+
47
+ /**
48
+ * Whether a file is an accepted music bed by its name (or path) and its content type. Give either or both; with both,
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.
51
+ */
52
+ export function checkMusicFileType(input: { fileName?: string; contentType?: string }): MusicFileTypeCheck {
53
+ const extension = getExtension(input.fileName);
54
+ const contentType = input.contentType === undefined ? null : normalizeContentType(input.contentType);
55
+ if (extension === null && contentType === null) return { ok: false, error: "a music file needs a file name or a content type to check" };
56
+ if (extension !== null) {
57
+ const types = getAcceptedTypes(extension);
58
+ if (types === null) return { ok: false, error: `${input.fileName ?? ""}: not a music file (accepted: ${ACCEPTED_LIST})` };
59
+ if (contentType !== null && !types.includes(contentType)) return { ok: false, error: `${input.fileName ?? ""}: content type ${contentType} does not match ${extension} (expected ${types.join(" or ")})` };
60
+ return { ok: true, extension, contentType };
61
+ }
62
+ const isAccepted = Object.values(MUSIC_FILE_TYPES).some((types) => contentType !== null && types.includes(contentType));
63
+ return isAccepted ? { ok: true, extension: null, contentType } : { ok: false, error: `content type ${contentType ?? ""} is not a music file (accepted: ${ACCEPTED_LIST})` };
64
+ }
65
+
66
+ /** What ffprobe says about a music file: enough to check it, fit it under the cut and store it with the asset. */
67
+ export interface AudioProbe {
68
+ /** Seconds. */
69
+ duration: number;
70
+ codec: string;
71
+ /** Hz. */
72
+ sampleRate: number;
73
+ channels: number;
74
+ /** Bits per second; null when the container reports none (Opus in Ogg, FLAC). */
75
+ bitRate: number | null;
76
+ }
77
+
78
+ /** Why a file is not a usable music bed. `unreadable`: ffprobe could not open it (missing, corrupt, not media). */
79
+ export type AudioProbeFailure = "no-audio-stream" | "no-duration" | "unexpected-output" | "unreadable";
80
+
81
+ export type AudioProbeResult = { ok: true; probe: AudioProbe } | { ok: false; reason: AudioProbeFailure; error: string };
82
+
83
+ const audioStreamSchema = z.looseObject({
84
+ codec_type: z.string().optional(),
85
+ codec_name: z.string().optional(),
86
+ sample_rate: z.string().optional(),
87
+ channels: z.number().optional(),
88
+ bit_rate: z.string().optional(),
89
+ duration: z.string().optional(),
90
+ });
91
+
92
+ const audioProbeSchema = z.looseObject({
93
+ streams: z.array(audioStreamSchema).default([]),
94
+ format: z.looseObject({ duration: z.string().optional(), bit_rate: z.string().optional() }).optional(),
95
+ });
96
+
97
+ function readPositive(value: string | undefined): number | null {
98
+ const number = Number(value);
99
+ return value !== undefined && Number.isFinite(number) && number > 0 ? number : null;
100
+ }
101
+
102
+ /** ffprobe's JSON (`-show_streams -show_format -of json`) read as a music bed: the first audio stream, cover art ignored. */
103
+ export function readAudioProbe(json: unknown): AudioProbeResult {
104
+ const parsed = audioProbeSchema.safeParse(json);
105
+ if (!parsed.success) return { ok: false, reason: "unexpected-output", error: "ffprobe printed an unexpected shape" };
106
+ const { streams, format } = parsed.data;
107
+ const audio = streams.find((stream) => stream.codec_type === "audio");
108
+ if (audio === undefined) return { ok: false, reason: "no-audio-stream", error: "no audio stream" };
109
+ const duration = readPositive(format?.duration) ?? readPositive(audio.duration);
110
+ if (duration === null) return { ok: false, reason: "no-duration", error: "no duration" };
111
+ return {
112
+ ok: true,
113
+ probe: {
114
+ duration,
115
+ codec: audio.codec_name ?? "unknown",
116
+ sampleRate: readPositive(audio.sample_rate) ?? 0,
117
+ channels: audio.channels ?? 0,
118
+ bitRate: readPositive(audio.bit_rate) ?? readPositive(format?.bit_rate),
119
+ },
120
+ };
121
+ }
122
+
123
+ /** Probes one music file (or URL) with ffprobe; a failure carries its reason and names the file. Rejects only on abort. */
124
+ export async function probeAudio(path: string, options: { signal?: AbortSignal } = {}): Promise<AudioProbeResult> {
125
+ const output = await runFfprobe(path, options);
126
+ if (!output.ok) return { ok: false, reason: "unreadable", error: output.error };
127
+ const read = readAudioProbe(output.json);
128
+ return read.ok ? read : { ...read, error: `${path}: ${read.error}` };
129
+ }
130
+
131
+ /** One line about a probed music file, for the log. */
132
+ export function describeAudioProbe(probe: AudioProbe): string {
133
+ const parts = [probe.codec, `${probe.duration.toFixed(1)} s`, `${String(probe.sampleRate)} Hz`, probe.channels === 1 ? "mono" : `${String(probe.channels)} channels`];
134
+ if (probe.bitRate !== null) parts.push(`${String(Math.round(probe.bitRate / 1000))} kb/s`);
135
+ return parts.join(", ");
136
+ }
@@ -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;
@@ -87,6 +113,17 @@ export function getCaptionPresetLayout(preset: CaptionPreset, fontSize: number):
87
113
  return { top, left: side, right: side, fontSize };
88
114
  }
89
115
 
116
+ /**
117
+ * 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
118
+ * caption preset unless the project overrides the caption box (`marketing.json` `layout`). The render and the draft
119
+ * share it.
120
+ */
121
+ export function getFootageCaptionLayout(film: Pick<FootageFilm, "format" | "captionPreset">, override: LayoutOverride = {}): CaptionLayout {
122
+ const base = resolveLayout(film.format, override);
123
+ if (film.captionPreset === undefined || film.format !== "9:16" || override.caption !== undefined) return base.caption;
124
+ return getCaptionPresetLayout(film.captionPreset, base.caption.fontSize);
125
+ }
126
+
90
127
  /** A character a font is asked to draw and does not have. */
91
128
  export interface MissingCaptionGlyphs {
92
129
  /** The family, as `brand.fonts` names it. */
@@ -4,7 +4,7 @@ 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
+ import { getCaptionSpans, phraseChunks, type CaptionSpan } from "./captions.js";
8
8
  import { getEdlDuration, getSegmentStarts, type Edl } from "./edl.js";
9
9
  import { DEFAULT_EDIT, getFootageEdit, type FootageFilm } from "./film.js";
10
10
  import { FOOTAGE_FPS } from "./normalize.js";
@@ -110,15 +110,14 @@ export function composeFootage(input: FootageComposeInput): string {
110
110
  // --- Captions: plain phrases, or the pill that lights each word ---
111
111
  const isHighlight = film.captionStyle === "highlight";
112
112
  const caption = !film.captions ? [] : isHighlight ? captionChunks(words) : phraseChunks(words);
113
+ const spans = getCaptionSpans(caption, cutEnd);
113
114
  const captionHtml = caption
114
115
  .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);
116
+ const { start, end: stop } = spans[i] as CaptionSpan;
118
117
  const box = isHighlight
119
118
  ? `<p class="pill">${chunk.words.map((w, j) => `<span id="cw${i}_${j}">${escapeHtml(w.text)}</span>`).join(" ")}</p>`
120
119
  : `<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>`;
120
+ return `<div id="cap${i}" class="clip caption" data-start="${start}" data-duration="${r3(stop - start)}">${box}</div>`;
122
121
  })
123
122
  .join("\n ");
124
123
 
@@ -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
+ }