@softure-ai/marketing-kit 0.9.1 → 0.10.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 (41) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +24 -0
  3. package/dist/config/actions-schema.d.ts +14 -14
  4. package/dist/config/schema.d.ts +68 -68
  5. package/dist/config/shot-steps.d.ts +16 -16
  6. package/dist/footage/draft.d.ts +1 -1
  7. package/dist/footage/draft.d.ts.map +1 -1
  8. package/dist/footage/draft.js +10 -4
  9. package/dist/footage/draft.js.map +1 -1
  10. package/dist/footage/ffmpeg-command.d.ts +31 -0
  11. package/dist/footage/ffmpeg-command.d.ts.map +1 -0
  12. package/dist/footage/ffmpeg-command.js +60 -0
  13. package/dist/footage/ffmpeg-command.js.map +1 -0
  14. package/dist/footage/ffmpeg-failure.d.ts +36 -0
  15. package/dist/footage/ffmpeg-failure.d.ts.map +1 -0
  16. package/dist/footage/ffmpeg-failure.js +75 -0
  17. package/dist/footage/ffmpeg-failure.js.map +1 -0
  18. package/dist/footage/picture.d.ts +3 -1
  19. package/dist/footage/picture.d.ts.map +1 -1
  20. package/dist/footage/picture.js +13 -5
  21. package/dist/footage/picture.js.map +1 -1
  22. package/dist/footage/pipeline.d.ts +12 -1
  23. package/dist/footage/pipeline.d.ts.map +1 -1
  24. package/dist/footage/pipeline.js +31 -7
  25. package/dist/footage/pipeline.js.map +1 -1
  26. package/dist/footage/process.d.ts +19 -1
  27. package/dist/footage/process.d.ts.map +1 -1
  28. package/dist/footage/process.js +57 -6
  29. package/dist/footage/process.js.map +1 -1
  30. package/dist/index.d.ts +3 -1
  31. package/dist/index.d.ts.map +1 -1
  32. package/dist/index.js +3 -1
  33. package/dist/index.js.map +1 -1
  34. package/package.json +1 -1
  35. package/src/footage/draft.ts +12 -5
  36. package/src/footage/ffmpeg-command.ts +78 -0
  37. package/src/footage/ffmpeg-failure.ts +89 -0
  38. package/src/footage/picture.ts +16 -6
  39. package/src/footage/pipeline.ts +45 -7
  40. package/src/footage/process.ts +66 -6
  41. package/src/index.ts +13 -1
@@ -1,6 +1,9 @@
1
+ import { AsyncLocalStorage } from "node:async_hooks";
1
2
  import { spawn } from "node:child_process";
2
3
  import { rmSync } from "node:fs";
3
4
 
5
+ import { FFMPEG_FAILURE_STDERR_LINES, findFfmpegInputs, formatFfmpegCommand, type FfmpegFailure } from "./ffmpeg-command.js";
6
+
4
7
  /**
5
8
  * Child processes of the footage blocks (ffmpeg, ffprobe, hyperframes), run without blocking the event loop, so a jobs
6
9
  * worker keeps its lease heartbeat during a long normalize or render. An abort kills the child, removes the partial
@@ -103,6 +106,28 @@ export function readFfmpegProgressSeconds(line: string): number | null {
103
106
  return match === null ? null : Number(match[1]) / 1_000_000;
104
107
  }
105
108
 
109
+ /** Called with a failed ffmpeg step before it throws; a promise is awaited, so the app can write the failure out. */
110
+ export type FfmpegFailureHook = (failure: FfmpegFailure) => void | Promise<void>;
111
+
112
+ export interface FfmpegFailureReporting {
113
+ onFailure?: FfmpegFailureHook;
114
+ /** Gets one line naming the failed step and its full command. */
115
+ log?: (line: string) => void;
116
+ }
117
+
118
+ const failureReporting = new AsyncLocalStorage<FfmpegFailureReporting>();
119
+
120
+ /**
121
+ * Runs `run` with `onFailure` and `log` set for every ffmpeg step inside it, however deep (the footage entry points
122
+ * wrap their body in it). A value it does not set keeps the one of an enclosing call.
123
+ */
124
+ export function withFfmpegFailureReporting<T>(reporting: FfmpegFailureReporting, run: () => Promise<T>): Promise<T> {
125
+ const outer = failureReporting.getStore();
126
+ const onFailure = reporting.onFailure ?? outer?.onFailure;
127
+ const log = reporting.log ?? outer?.log;
128
+ return failureReporting.run({ ...(onFailure === undefined ? {} : { onFailure }), ...(log === undefined ? {} : { log }) }, run);
129
+ }
130
+
106
131
  export interface FfmpegRunOptions {
107
132
  signal?: AbortSignal;
108
133
  /** The file the run writes, removed on abort. */
@@ -111,14 +136,38 @@ export interface FfmpegRunOptions {
111
136
  onSeconds?: (seconds: number) => void;
112
137
  /** The folder ffmpeg runs in, so relative names in the arguments and the filter graph resolve there. */
113
138
  cwd?: string;
139
+ /** Called when the run fails, before it throws; by default the one `withFfmpegFailureReporting` set. */
140
+ onFailure?: FfmpegFailureHook;
141
+ }
142
+
143
+ /** Logs the failure and hands it to the hook; an error of the hook itself is logged, never thrown over ffmpeg's. */
144
+ async function reportFfmpegFailure(failure: FfmpegFailure, onFailure: FfmpegFailureHook | undefined): Promise<void> {
145
+ const reporting = failureReporting.getStore();
146
+ const log = reporting?.log;
147
+ log?.(`ffmpeg failed: ${failure.step}, in ${failure.cwd}: ${formatFfmpegCommand(failure.args)}`);
148
+ const hook = onFailure ?? reporting?.onFailure;
149
+ if (hook === undefined) return;
150
+ try {
151
+ await hook(failure);
152
+ } catch (error) {
153
+ const message = `ffmpeg failed: the failure hook of "${failure.step}" threw: ${error instanceof Error ? error.message : String(error)}`;
154
+ if (log === undefined) console.error(message);
155
+ else log(message);
156
+ }
114
157
  }
115
158
 
116
- /** Runs ffmpeg with its progress on stdout; throws naming the step when it fails (a broken input or machine). */
159
+ /**
160
+ * Runs ffmpeg with its progress on stdout; throws naming the step when it fails (a broken input or machine), after
161
+ * handing the whole failure (`FfmpegFailure`) to `onFailure` and one line with the command to the reporting `log`.
162
+ */
117
163
  export async function runFfmpeg(step: string, args: string[], options: FfmpegRunOptions = {}): Promise<void> {
118
164
  const errors: string[] = [];
165
+ const stderr: string[] = [];
166
+ const spawned = ["-progress", "pipe:1", "-nostats", ...args];
167
+ const cwd = options.cwd ?? process.cwd();
119
168
  const outcome = await runProcess({
120
169
  command: "ffmpeg",
121
- args: ["-progress", "pipe:1", "-nostats", ...args],
170
+ args: spawned,
122
171
  ...(options.signal === undefined ? {} : { signal: options.signal }),
123
172
  ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
124
173
  removeOnAbort: options.output === undefined ? [] : [options.output],
@@ -127,12 +176,23 @@ export async function runFfmpeg(step: string, args: string[], options: FfmpegRun
127
176
  if (seconds !== null) options.onSeconds?.(seconds);
128
177
  },
129
178
  onStderrLine: (line) => {
179
+ stderr.push(line);
180
+ if (stderr.length > FFMPEG_FAILURE_STDERR_LINES) stderr.shift();
130
181
  if (line.trim().length > 0) errors.push(line);
131
182
  },
132
183
  });
184
+ if (outcome.kind === "exited" && outcome.code === 0) return;
185
+ const failure: FfmpegFailure = {
186
+ step,
187
+ args: spawned,
188
+ cwd,
189
+ code: outcome.kind === "exited" ? outcome.code : null,
190
+ signal: outcome.kind === "exited" ? outcome.signal : null,
191
+ stderr: outcome.kind === "exited" ? stderr : [outcome.error],
192
+ inputs: findFfmpegInputs(spawned, cwd),
193
+ };
194
+ await reportFfmpegFailure(failure, options.onFailure);
133
195
  if (outcome.kind === "not-started") throw new Error(`${step}: ffmpeg did not start (${outcome.error}).`);
134
- if (outcome.code !== 0) {
135
- const detail = errors.slice(-5).join(" | ");
136
- throw new Error(`${step}: ffmpeg ended with code ${String(outcome.code)} (signal ${outcome.signal ?? "-"})${detail.length > 0 ? `: ${detail}` : ""}.`);
137
- }
196
+ const detail = errors.slice(-5).join(" | ");
197
+ throw new Error(`${step}: ffmpeg ended with code ${String(outcome.code)} (signal ${outcome.signal ?? "-"})${detail.length > 0 ? `: ${detail}` : ""}.`);
138
198
  }
package/src/index.ts CHANGED
@@ -397,7 +397,19 @@ export {
397
397
  readTopLevelBoxes,
398
398
  type FilmFacts,
399
399
  } from "./footage/publish.js";
400
- export { readFfmpegProgressSeconds, runFfmpeg, runProcess, type FfmpegRunOptions, type ProcessOptions, type ProcessOutcome } from "./footage/process.js";
400
+ export {
401
+ readFfmpegProgressSeconds,
402
+ runFfmpeg,
403
+ runProcess,
404
+ withFfmpegFailureReporting,
405
+ type FfmpegFailureHook,
406
+ type FfmpegFailureReporting,
407
+ type FfmpegRunOptions,
408
+ type ProcessOptions,
409
+ type ProcessOutcome,
410
+ } from "./footage/process.js";
411
+ export { FFMPEG_FAILURE_STDERR_LINES, formatFfmpegCommand, splitFilterGraph, type FfmpegFailure } from "./footage/ffmpeg-command.js";
412
+ export { buildFfmpegFailureScript, FFMPEG_FAILURE_FILES, writeFfmpegFailure, type FfmpegFailureInput } from "./footage/ffmpeg-failure.js";
401
413
  export {
402
414
  estimateFootageFilm,
403
415
  findCachedStep,