@softure-ai/marketing-kit 0.7.0 → 0.9.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 (38) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/README.md +51 -13
  3. package/dist/footage/draft-font.d.ts +18 -0
  4. package/dist/footage/draft-font.d.ts.map +1 -0
  5. package/dist/footage/draft-font.js +105 -0
  6. package/dist/footage/draft-font.js.map +1 -0
  7. package/dist/footage/draft.d.ts +49 -12
  8. package/dist/footage/draft.d.ts.map +1 -1
  9. package/dist/footage/draft.js +165 -35
  10. package/dist/footage/draft.js.map +1 -1
  11. package/dist/footage/normalize.d.ts +18 -7
  12. package/dist/footage/normalize.d.ts.map +1 -1
  13. package/dist/footage/normalize.js +31 -15
  14. package/dist/footage/normalize.js.map +1 -1
  15. package/dist/footage/pipeline.d.ts +31 -2
  16. package/dist/footage/pipeline.d.ts.map +1 -1
  17. package/dist/footage/pipeline.js +41 -12
  18. package/dist/footage/pipeline.js.map +1 -1
  19. package/dist/footage/tonemap-lut.d.ts +45 -0
  20. package/dist/footage/tonemap-lut.d.ts.map +1 -0
  21. package/dist/footage/tonemap-lut.js +100 -0
  22. package/dist/footage/tonemap-lut.js.map +1 -0
  23. package/dist/footage/tools.d.ts +4 -4
  24. package/dist/footage/tools.d.ts.map +1 -1
  25. package/dist/footage/tools.js +4 -4
  26. package/dist/footage/tools.js.map +1 -1
  27. package/dist/index.d.ts +4 -2
  28. package/dist/index.d.ts.map +1 -1
  29. package/dist/index.js +4 -2
  30. package/dist/index.js.map +1 -1
  31. package/package.json +1 -1
  32. package/src/footage/draft-font.ts +105 -0
  33. package/src/footage/draft.ts +184 -40
  34. package/src/footage/normalize.ts +39 -18
  35. package/src/footage/pipeline.ts +55 -12
  36. package/src/footage/tonemap-lut.ts +109 -0
  37. package/src/footage/tools.ts +4 -4
  38. package/src/index.ts +8 -0
@@ -0,0 +1,109 @@
1
+ import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
2
+ import { join } from "node:path";
3
+
4
+ import type { HdrKind } from "./probe.js";
5
+ import { runFfmpeg } from "./process.js";
6
+
7
+ /**
8
+ * The HDR to SDR tone map as a 3D LUT. The float chain (zscale to linear light, Hable curve, zscale back to BT.709)
9
+ * costs about a second per footage second at 1080x1920 on one CPU; the same chain is run once over an identity
10
+ * lattice of HDR R'G'B' values and written as a `.cube` file, which `lut3d` then applies per frame in 16-bit at about
11
+ * half the cost. A 3D LUT keeps what a per-channel curve would lose: HLG's system gamma and Hable's scaling both
12
+ * depend on all three channels.
13
+ *
14
+ * The LUT ends in linear BT.709 light, unclamped (negative where a colour lies outside BT.709), and the BT.709
15
+ * transfer is applied after it: the mapping up to there is smooth, so the lattice interpolates it closely, while the
16
+ * transfer's steep start and the gamut edge would not interpolate.
17
+ */
18
+
19
+ /** Points per axis: 65 is as fast as 33 in `lut3d` and closer to the float chain. */
20
+ export const TONE_MAP_LUT_SIZE = 65;
21
+ /** Bumped when the curve or the lattice changes, so a build folder's older LUT is not reused. */
22
+ const TONE_MAP_LUT_VERSION = 1;
23
+
24
+ /** The HDR transfers the tone map reads, by ffmpeg's names. */
25
+ export type ToneMapTransfer = "smpte2084" | "arib-std-b67";
26
+
27
+ const TRANSFER_BY_KIND: Record<HdrKind, ToneMapTransfer> = { pq: "smpte2084", hlg: "arib-std-b67", "dolby-vision": "arib-std-b67" };
28
+
29
+ /** The transfer to tone-map from: the stream's own when it is PQ or HLG, else the kind's (Dolby Vision through its HLG base layer). */
30
+ export function getToneMapTransfer(hdr: HdrKind, transfer: string | null): ToneMapTransfer {
31
+ return transfer === "smpte2084" || transfer === "arib-std-b67" ? transfer : TRANSFER_BY_KIND[hdr];
32
+ }
33
+
34
+ /** The float stages between linear BT.2020 light and linear BT.709 light: the Hable curve, no desaturation. */
35
+ export const HABLE_STAGES = ["format=gbrpf32le", "zscale=p=bt709", "tonemap=tonemap=hable:desat=0"] as const;
36
+
37
+ /** The LUT's file name; the file sits in the folder ffmpeg runs in, so the filter graph needs no path escaping. */
38
+ export function getToneMapLutName(transfer: ToneMapTransfer): string {
39
+ return `tonemap-v${TONE_MAP_LUT_VERSION}-${transfer}.cube`;
40
+ }
41
+
42
+ /** Every lattice point as 16-bit R, G, B (`rgb48le`), red changing fastest, then green, then blue, as `.cube` lists them. */
43
+ export function buildIdentityLattice(size: number): Buffer {
44
+ if (!Number.isInteger(size) || size < 2) throw new Error(`A LUT needs at least 2 whole points per axis, got ${size}.`);
45
+ const levels = Array.from({ length: size }, (_, i) => Math.round((i / (size - 1)) * 65_535));
46
+ const lattice = Buffer.alloc(size ** 3 * 6);
47
+ let offset = 0;
48
+ for (const blue of levels) {
49
+ for (const green of levels) {
50
+ for (const red of levels) {
51
+ offset = lattice.writeUInt16LE(red, offset);
52
+ offset = lattice.writeUInt16LE(green, offset);
53
+ offset = lattice.writeUInt16LE(blue, offset);
54
+ }
55
+ }
56
+ }
57
+ return lattice;
58
+ }
59
+
60
+ /**
61
+ * ffmpeg's arguments to run the float chain over the lattice: HDR R'G'B' (BT.2020, raw `rgb48le`) in, tone-mapped
62
+ * linear BT.709 light out (raw planar float `gbrpf32le`, unclamped).
63
+ */
64
+ export function buildToneMapLutArgs(options: { transfer: ToneMapTransfer; size: number; lattice: string; output: string }): string[] {
65
+ const { transfer, size } = options;
66
+ const chain = [`zscale=tin=${transfer}:pin=bt2020:t=linear:p=bt2020:npl=100`, ...HABLE_STAGES].join(",");
67
+ return ["-v", "error", "-y", "-f", "rawvideo", "-pix_fmt", "rgb48le", "-s", `${size}x${size * size}`, "-i", options.lattice, "-vf", chain, "-f", "rawvideo", "-pix_fmt", "gbrpf32le", options.output];
68
+ }
69
+
70
+ /** The `.cube` text for the mapped lattice (planar float: the green, blue, red planes). Throws when `mapped` does not hold `size`³ points. */
71
+ export function formatCube(size: number, mapped: Buffer): string {
72
+ const points = size ** 3;
73
+ if (mapped.length !== points * 12) throw new Error(`A ${size}-point LUT needs ${points * 12} bytes of gbrpf32le, got ${mapped.length}.`);
74
+ const lines = ["# HDR to linear BT.709 light, Hable curve (marketing-kit footage normalize)", `LUT_3D_SIZE ${size}`];
75
+ const plane = points * 4;
76
+ for (let offset = 0; offset < plane; offset += 4) {
77
+ const green = mapped.readFloatLE(offset);
78
+ const blue = mapped.readFloatLE(plane + offset);
79
+ const red = mapped.readFloatLE(2 * plane + offset);
80
+ lines.push(`${red.toFixed(6)} ${green.toFixed(6)} ${blue.toFixed(6)}`);
81
+ }
82
+ return `${lines.join("\n")}\n`;
83
+ }
84
+
85
+ /**
86
+ * Makes the transfer's LUT in `dir` unless it is there, and returns its file name. The lattice and ffmpeg's raw output
87
+ * are removed afterwards; the `.cube` is written under a temporary name and renamed, so a stopped run never leaves half
88
+ * a LUT. Throws (naming the step) when ffmpeg fails; an abort rejects with the signal's reason.
89
+ */
90
+ export async function ensureToneMapLut(transfer: ToneMapTransfer, dir: string, options: { signal?: AbortSignal } = {}): Promise<string> {
91
+ const name = getToneMapLutName(transfer);
92
+ const path = join(dir, name);
93
+ if (existsSync(path)) return name;
94
+ const lattice = `${path}.lattice.rgb48`;
95
+ const mapped = `${path}.mapped.gbrpf32`;
96
+ const partial = `${path}.partial`;
97
+ try {
98
+ writeFileSync(lattice, buildIdentityLattice(TONE_MAP_LUT_SIZE));
99
+ await runFfmpeg(`Making the ${transfer} tone map LUT (${path})`, buildToneMapLutArgs({ transfer, size: TONE_MAP_LUT_SIZE, lattice, output: mapped }), {
100
+ ...(options.signal === undefined ? {} : { signal: options.signal }),
101
+ output: mapped,
102
+ });
103
+ writeFileSync(partial, formatCube(TONE_MAP_LUT_SIZE, readFileSync(mapped)));
104
+ renameSync(partial, path);
105
+ } finally {
106
+ for (const file of [lattice, mapped, partial]) rmSync(file, { force: true });
107
+ }
108
+ return name;
109
+ }
@@ -34,7 +34,7 @@ export interface FootageToolsOptions {
34
34
 
35
35
  /** What the footage blocks need from ffmpeg: decoders and filters, by the name ffmpeg lists them under. */
36
36
  export const REQUIRED_DECODERS = ["hevc", "h264"] as const;
37
- export const REQUIRED_FILTERS = ["zscale", "tonemap"] as const;
37
+ export const REQUIRED_FILTERS = ["zscale", "tonemap", "lut3d"] as const;
38
38
  /** What the fast draft needs on top: libass (with libfreetype) for the captions, `xfade` for fades, `zoompan` for Ken Burns. */
39
39
  export const DRAFT_FILTERS = ["ass", "xfade", "zoompan"] as const;
40
40
 
@@ -94,9 +94,9 @@ export function findBrowserProblem(env: NodeJS.ProcessEnv): string | null {
94
94
  }
95
95
 
96
96
  /**
97
- * Checks the machine for a footage run: ffmpeg and ffprobe run, ffmpeg decodes HEVC and H.264 and has `zscale` and
98
- * `tonemap` (HDR clips), for a draft (`needsDraft`) `ass`, `xfade` and `zoompan`, and, for a render, hyperframes runs
99
- * and has its browser, and its temp folder (and the build folder, when given) has the 1 GiB free hyperframes requires.
97
+ * Checks the machine for a footage run: ffmpeg and ffprobe run, ffmpeg decodes HEVC and H.264 and has `zscale`,
98
+ * `tonemap` and `lut3d` (HDR clips), for a draft (`needsDraft`) `ass`, `xfade` and `zoompan`, and, for a render,
99
+ * hyperframes runs and has its browser, and its temp folder (and the build folder, when given) has the 1 GiB free hyperframes requires.
100
100
  * Returns every problem found; an empty list means the machine is ready.
101
101
  */
102
102
  export async function checkFootageTools(options: FootageToolsOptions = {}): Promise<string[]> {
package/src/index.ts CHANGED
@@ -246,6 +246,7 @@ export {
246
246
  type NormalizeInput,
247
247
  type X264Preset,
248
248
  } from "./footage/normalize.js";
249
+ export { ensureToneMapLut, getToneMapLutName, getToneMapTransfer, TONE_MAP_LUT_SIZE, type ToneMapTransfer } from "./footage/tonemap-lut.js";
249
250
  export {
250
251
  describePaidSteps,
251
252
  toPaidAudio,
@@ -338,6 +339,7 @@ export { duckingKeyframes, getDuckingOptions, getSpeechSpans, volumeExpression,
338
339
  export { END_CARD_SECONDS, FADE_SECONDS, composeFootage, getFootageFilmSeconds, getSegmentScales, type FootageComposeAssets, type FootageComposeInput } from "./footage/compose.js";
339
340
  export { buildCutPreviewArgs, buildLastFrameArgs, buildMusicArgs, buildSpeechArgs, getSpeechCutOptions, type SpeechCutOptions } from "./footage/render.js";
340
341
  export {
342
+ FOOTAGE_DRAFT_CAPTION_COLORS,
341
343
  FOOTAGE_DRAFT_FONT,
342
344
  FOOTAGE_DRAFT_WIDTH,
343
345
  buildFootageDraftArgs,
@@ -345,12 +347,16 @@ export {
345
347
  getFootageDraftFrame,
346
348
  planFootageDraft,
347
349
  renderFootageDraft,
350
+ toAssColor,
348
351
  type DraftSegmentPlan,
349
352
  type FootageDraft,
350
353
  type FootageDraftArgsInput,
354
+ type FootageDraftCaptionColors,
351
355
  type FootageDraftCaptionsInput,
356
+ type FootageDraftMusic,
352
357
  type RenderFootageDraftOptions,
353
358
  } from "./footage/draft.js";
359
+ export { chooseFootageDraftFont, readFontFamilyName, type FootageDraftFontChoice } from "./footage/draft-font.js";
354
360
  export {
355
361
  buildPictureConcatArgs,
356
362
  buildPictureList,
@@ -407,6 +413,7 @@ export {
407
413
  cutFootage,
408
414
  cutFootageFilm,
409
415
  describeCutMeasures,
416
+ findFootageMusic,
410
417
  getEdlPath,
411
418
  getFrame,
412
419
  prepareFootage,
@@ -418,6 +425,7 @@ export {
418
425
  transcribeFootage,
419
426
  type FinishedFootage,
420
427
  type FootageBrand,
428
+ type FootageMusicLookup,
421
429
  type FootageResult,
422
430
  type FootageRunOptions,
423
431
  type PreparedClip,