@morshoto/framekit 0.1.13 → 0.1.16

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 (30) hide show
  1. package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +28 -0
  2. package/dist-package/adapters/final-cut/typescript/src/canonical.js +144 -35
  3. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +36 -7
  4. package/dist-package/adapters/final-cut/typescript/src/index.js +2 -0
  5. package/dist-package/adapters/final-cut/typescript/src/live.js +56 -1
  6. package/dist-package/adapters/final-cut/typescript/src/native.js +311 -20
  7. package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.js +312 -0
  8. package/dist-package/adapters/final-cut/typescript/src/publisher.js +68 -8
  9. package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.js +263 -0
  10. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +75 -3
  11. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +62 -0
  12. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +443 -0
  13. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +181 -0
  14. package/dist-package/adapters/headless/typescript/src/index.js +3 -0
  15. package/dist-package/apps/mcp-server/src/headless-projects.js +139 -0
  16. package/dist-package/apps/mcp-server/src/headless-sessions.js +3 -0
  17. package/dist-package/apps/mcp-server/src/main.js +22 -1
  18. package/dist-package/apps/mcp-server/src/materialization-jobs.js +233 -4
  19. package/dist-package/apps/mcp-server/src/readback-policy.js +26 -0
  20. package/dist-package/apps/mcp-server/src/routing.js +134 -5
  21. package/dist-package/apps/mcp-server/src/server.js +214 -31
  22. package/dist-package/packages/runtime/src/application/local-media.js +157 -0
  23. package/dist-package/packages/runtime/src/application/project-store.js +234 -0
  24. package/dist-package/packages/runtime/src/application/project-transactions.js +227 -0
  25. package/dist-package/packages/runtime/src/index.js +6 -0
  26. package/dist-package/packages/runtime/src/render/render-and-verify.js +126 -0
  27. package/dist-package/packages/runtime/src/render/render-contract.js +143 -0
  28. package/dist-package/packages/runtime/src/timeline/editing-session.js +277 -9
  29. package/dist-package/packages/runtime/src/timeline/fast-observation.js +141 -0
  30. package/package.json +2 -1
@@ -0,0 +1,443 @@
1
+ import { createHash } from "node:crypto";
2
+ import { execFile } from "node:child_process";
3
+ import { createReadStream } from "node:fs";
4
+ import { access, link, lstat, mkdtemp, rename, rm, unlink } from "node:fs/promises";
5
+ import { existsSync } from "node:fs";
6
+ import { dirname, join, resolve } from "node:path";
7
+ import { promisify } from "node:util";
8
+ import { createFramekitRenderResult, } from "../../../../packages/runtime/src/index.js";
9
+ const execFileAsync = promisify(execFile);
10
+ export class FfmpegRenderError extends Error {
11
+ code;
12
+ constructor(code, message) {
13
+ super(`${code}: ${message}`);
14
+ this.code = code;
15
+ this.name = "FfmpegRenderError";
16
+ }
17
+ }
18
+ /**
19
+ * The first provider-neutral concrete renderer. It consumes only a validated
20
+ * Timeline IR render plan and treats local source files as immutable inputs.
21
+ */
22
+ export class FfmpegTimelineRenderer {
23
+ id = "ffmpeg-headless";
24
+ version;
25
+ ffmpegPath;
26
+ environment;
27
+ fontFile;
28
+ constructor(options = {}) {
29
+ this.ffmpegPath = options.ffmpegPath ?? process.env.FFMPEG_BIN ?? "ffmpeg";
30
+ this.version = options.version ?? "0.1.0";
31
+ this.environment = { ...process.env, ...options.env };
32
+ this.fontFile = resolveFontFile(options.env?.FRAMEKIT_RENDER_FONT ?? process.env.FRAMEKIT_RENDER_FONT);
33
+ }
34
+ capabilities(request) {
35
+ const timeline = request.timeline;
36
+ return {
37
+ renderer: { id: this.id, version: this.version },
38
+ features: {
39
+ "local-media": supportsLocalMedia(timeline) ? "supported" : "unsupported",
40
+ "structural-edits": supportsStructuralEdits(timeline) ? "supported" : "unsupported",
41
+ "audio-gain": supportsAudioGain(timeline) ? "supported" : "unsupported",
42
+ transform: supportsTransforms(timeline) ? "supported" : "unsupported",
43
+ titles: supportsTitles(timeline) ? "supported" : "unsupported",
44
+ "cross-dissolve": supportsCrossDissolve(timeline) ? "supported" : "unsupported",
45
+ },
46
+ };
47
+ }
48
+ async render(plan) {
49
+ if (plan.renderer.id !== this.id || plan.renderer.version !== this.version) {
50
+ throw new FfmpegRenderError("HEADLESS_RENDER_PLAN_MISMATCH", "render plan is bound to another renderer version");
51
+ }
52
+ const unavailable = plan.requiredFeatures.filter((feature) => plan.capabilities.features[feature] !== "supported");
53
+ if (unavailable.length > 0) {
54
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `required features are unavailable: ${unavailable.join(", ")}`);
55
+ }
56
+ const model = await prepareRenderModel(plan);
57
+ const outputPath = resolve(plan.parameters.outputPath);
58
+ await assertOutputPath(outputPath, plan.parameters.overwrite ?? false, model.sourcePaths);
59
+ const outputDirectory = dirname(outputPath);
60
+ await access(outputDirectory).catch(() => {
61
+ throw new FfmpegRenderError("HEADLESS_RENDER_OUTPUT_INVALID", `output directory does not exist: ${outputDirectory}`);
62
+ });
63
+ const stagingDirectory = await mkdtemp(join(outputDirectory, ".framekit-render-"));
64
+ const stagingPath = join(stagingDirectory, `render.${plan.parameters.format}`);
65
+ try {
66
+ const args = buildFfmpegArguments(model, stagingPath, this.fontFile);
67
+ try {
68
+ await execFileAsync(this.ffmpegPath, args, {
69
+ cwd: process.cwd(),
70
+ env: this.environment,
71
+ maxBuffer: 8 * 1024 * 1024,
72
+ });
73
+ }
74
+ catch (error) {
75
+ const detail = error instanceof Error ? error.message : String(error);
76
+ throw new FfmpegRenderError("HEADLESS_RENDER_FAILED", detail);
77
+ }
78
+ if (!(await isRegularFile(stagingPath))) {
79
+ throw new FfmpegRenderError("HEADLESS_RENDER_FAILED", "FFmpeg completed without producing an output file");
80
+ }
81
+ await assertSourcesUnchanged(model);
82
+ if (plan.parameters.overwrite ?? false) {
83
+ await rename(stagingPath, outputPath);
84
+ }
85
+ else {
86
+ try {
87
+ await link(stagingPath, outputPath);
88
+ }
89
+ catch (error) {
90
+ if (error.code === "EEXIST") {
91
+ throw new FfmpegRenderError("HEADLESS_RENDER_OUTPUT_EXISTS", `render output already exists: ${outputPath}`);
92
+ }
93
+ throw error;
94
+ }
95
+ await unlink(stagingPath);
96
+ }
97
+ return createFramekitRenderResult(plan, {
98
+ path: plan.parameters.outputPath,
99
+ format: plan.parameters.format,
100
+ });
101
+ }
102
+ finally {
103
+ await rm(stagingDirectory, { recursive: true, force: true });
104
+ }
105
+ }
106
+ }
107
+ async function prepareRenderModel(plan) {
108
+ const timeline = structuredClone(plan.timeline);
109
+ const sequence = timeline.sequence;
110
+ const occurrences = [...sequence.occurrences].sort((left, right) => compareSeconds(left.startTime, right.startTime));
111
+ if (!supportsStructuralEdits(timeline)) {
112
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", "markers, captions, story elements, disabled clips, and non-primary tracks are not supported");
113
+ }
114
+ if (!supportsTransforms(timeline) || !supportsTitles(timeline) || !supportsCrossDissolve(timeline)) {
115
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", "Timeline IR contains unsupported renderer semantics");
116
+ }
117
+ if (occurrences.length === 0)
118
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", "at least one video occurrence is required");
119
+ const duration = rationalSeconds(sequence.durationTime, "sequence duration");
120
+ const frameRate = 1 / rationalSeconds(sequence.frameDuration, "sequence frame duration");
121
+ if (!Number.isFinite(duration) || duration <= 0 || !Number.isFinite(frameRate) || frameRate <= 0) {
122
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", "sequence duration and frame rate must be finite and positive");
123
+ }
124
+ if (!Number.isSafeInteger(plan.parameters.width) || !Number.isSafeInteger(plan.parameters.height)) {
125
+ throw new FfmpegRenderError("HEADLESS_RENDER_OUTPUT_INVALID", "output dimensions must be safe integers");
126
+ }
127
+ const resources = new Map(timeline.resources.map((resource) => [resource.id, resource]));
128
+ const sourcePaths = [];
129
+ const sourceIdentities = [];
130
+ const audioAvailability = new Set();
131
+ let previousEnd = 0;
132
+ for (const occurrence of occurrences) {
133
+ if (occurrence.track !== 0 || occurrence.role === "audio" || occurrence.role === "music" || occurrence.role === "title") {
134
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `occurrence role or track is not renderable: ${occurrence.id}`);
135
+ }
136
+ if (occurrence.enabled === false || occurrence.attachedTo) {
137
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `occurrence has unsupported state: ${occurrence.id}`);
138
+ }
139
+ const start = rationalSeconds(occurrence.startTime, `${occurrence.id}.startTime`);
140
+ const clipDuration = rationalSeconds(occurrence.durationTime, `${occurrence.id}.durationTime`);
141
+ if (Math.abs(start - previousEnd) > 1e-7) {
142
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `primary occurrences must be contiguous: ${occurrence.id}`);
143
+ }
144
+ previousEnd = start + clipDuration;
145
+ const resource = occurrence.mediaId ? resources.get(occurrence.mediaId) : undefined;
146
+ if (!resource)
147
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `occurrence has no registered media: ${occurrence.id}`);
148
+ const source = await verifyResource(resource, occurrence, clipDuration);
149
+ const sourcePath = source.path;
150
+ audioAvailability.add(resource.metadata?.streams.some((stream) => stream.kind === "audio") ?? false);
151
+ if (!sourcePaths.includes(sourcePath))
152
+ sourcePaths.push(sourcePath);
153
+ if (!sourceIdentities.some((identity) => identity.path === source.path && identity.digest === source.digest)) {
154
+ sourceIdentities.push(source);
155
+ }
156
+ }
157
+ if (audioAvailability.size > 1) {
158
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", "all primary occurrences must agree on audio availability");
159
+ }
160
+ if (Math.abs(previousEnd - duration) > 1e-7) {
161
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", "occurrences do not cover the sequence duration");
162
+ }
163
+ const transitions = timeline.sequence.transitions ?? [];
164
+ if (transitions.length > 1) {
165
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", "the first FFmpeg provider supports one canonical cross-dissolve");
166
+ }
167
+ return {
168
+ timeline,
169
+ occurrences,
170
+ resources,
171
+ sourcePaths,
172
+ duration,
173
+ frameRate,
174
+ width: plan.parameters.width,
175
+ height: plan.parameters.height,
176
+ format: plan.parameters.format,
177
+ sourceIdentities,
178
+ };
179
+ }
180
+ async function verifyResource(resource, occurrence, duration) {
181
+ if (resource.sourceKind !== "local-file" || !resource.source || !resource.sourceDigest) {
182
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `resource is not a registered local file: ${resource.id}`);
183
+ }
184
+ const sourcePath = resolve(resource.source);
185
+ let details;
186
+ try {
187
+ details = await lstat(sourcePath);
188
+ }
189
+ catch (error) {
190
+ if (error.code === "ENOENT") {
191
+ throw new FfmpegRenderError("HEADLESS_RENDER_MEDIA_MISSING", `registered source is missing: ${sourcePath}`);
192
+ }
193
+ throw error;
194
+ }
195
+ if (!details.isFile() || details.isSymbolicLink()) {
196
+ throw new FfmpegRenderError("HEADLESS_RENDER_MEDIA_MISSING", `registered source is not a regular file: ${sourcePath}`);
197
+ }
198
+ const actualDigest = await digestFile(sourcePath);
199
+ if (actualDigest !== resource.sourceDigest) {
200
+ throw new FfmpegRenderError("HEADLESS_RENDER_MEDIA_CHANGED", `registered source changed: ${sourcePath}`);
201
+ }
202
+ const video = resource.metadata?.streams.find((stream) => stream.kind === "video");
203
+ if (!video?.width || !video.height) {
204
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `resource is missing video dimensions: ${resource.id}`);
205
+ }
206
+ const sourceStart = occurrence.sourceStartTime ? rationalSeconds(occurrence.sourceStartTime, `${occurrence.id}.sourceStartTime`) : 0;
207
+ const sourceDuration = resource.metadata ? rationalSeconds(resource.metadata.durationTime, `${resource.id}.durationTime`) : 0;
208
+ if (sourceStart < 0 || duration <= 0 || sourceStart + duration > sourceDuration + 1e-7) {
209
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `source range exceeds registered media: ${occurrence.id}`);
210
+ }
211
+ return { path: sourcePath, digest: actualDigest };
212
+ }
213
+ async function assertSourcesUnchanged(model) {
214
+ for (const identity of model.sourceIdentities) {
215
+ let details;
216
+ try {
217
+ details = await lstat(identity.path);
218
+ }
219
+ catch {
220
+ throw new FfmpegRenderError("HEADLESS_RENDER_MEDIA_CHANGED", `registered source changed during rendering: ${identity.path}`);
221
+ }
222
+ if (!details.isFile() || details.isSymbolicLink() || await digestFile(identity.path) !== identity.digest) {
223
+ throw new FfmpegRenderError("HEADLESS_RENDER_MEDIA_CHANGED", `registered source changed during rendering: ${identity.path}`);
224
+ }
225
+ }
226
+ }
227
+ function buildFfmpegArguments(model, stagingPath, fontFile) {
228
+ const filters = [];
229
+ const inputArguments = [];
230
+ const videoLabels = [];
231
+ const audioLabels = [];
232
+ const fps = formatNumber(model.frameRate);
233
+ for (const [index, occurrence] of model.occurrences.entries()) {
234
+ const resource = model.resources.get(occurrence.mediaId);
235
+ const inputPath = resolve(resource.source);
236
+ inputArguments.push("-i", inputPath);
237
+ const sourceStart = occurrence.sourceStartTime ? rationalSeconds(occurrence.sourceStartTime, `${occurrence.id}.sourceStartTime`) : 0;
238
+ const duration = rationalSeconds(occurrence.durationTime, `${occurrence.id}.durationTime`);
239
+ const videoInput = `[${index}:v]`;
240
+ const videoLabel = `clipv${index}`;
241
+ filters.push(`${videoInput}trim=start=${formatNumber(sourceStart)}:duration=${formatNumber(duration)},setpts=PTS-STARTPTS,settb=AVTB,fps=${fps},${transformFilter(occurrence, resource, model.width, model.height)}[${videoLabel}]`);
242
+ videoLabels.push(`[${videoLabel}]`);
243
+ const hasAudio = resource.metadata?.streams.some((stream) => stream.kind === "audio") ?? false;
244
+ if (hasAudio) {
245
+ const audioLabel = `clipa${index}`;
246
+ const gain = occurrence.gainDb ?? 0;
247
+ filters.push(`${`[${index}:a]`}atrim=start=${formatNumber(sourceStart)}:duration=${formatNumber(duration)},asetpts=PTS-STARTPTS,aresample=48000,volume=${formatNumber(Math.pow(10, gain / 20))}[${audioLabel}]`);
248
+ audioLabels.push(`[${audioLabel}]`);
249
+ }
250
+ }
251
+ const transition = model.timeline.sequence.transitions?.[0];
252
+ const videoBase = addVideoComposition(filters, videoLabels, model, transition);
253
+ const videoOutput = addTitleOverlays(filters, videoBase, model, fontFile);
254
+ let audioOutput;
255
+ if (audioLabels.length > 0)
256
+ audioOutput = addAudioComposition(filters, audioLabels, model, transition);
257
+ const args = ["-hide_banner", "-loglevel", "error", "-nostdin", "-y", ...inputArguments, "-filter_complex", filters.join(";")];
258
+ args.push("-map", `[${videoOutput}]`, "-c:v", "libx264", "-preset", "ultrafast", "-threads", "1", "-pix_fmt", "yuv420p", "-r", fps);
259
+ if (audioOutput) {
260
+ args.push("-map", `[${audioOutput}]`, "-c:a", "aac", "-b:a", "128k", "-ar", "48000", "-ac", "1");
261
+ }
262
+ args.push("-map_metadata", "-1", "-t", formatNumber(model.duration), "-movflags", "+faststart", stagingPath);
263
+ return args;
264
+ }
265
+ function addVideoComposition(filters, labels, model, transition) {
266
+ if (labels.length === 1) {
267
+ const output = "video-base";
268
+ filters.push(`${labels[0]}tpad=stop_mode=clone:stop_duration=0[${output}]`);
269
+ return output;
270
+ }
271
+ if (transition) {
272
+ const duration = rationalSeconds(transition.durationTime, `${transition.id}.durationTime`);
273
+ const offset = rationalSeconds(model.occurrences[0].durationTime, "transition offset") - duration;
274
+ if (offset < 0)
275
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", "transition duration exceeds the first occurrence duration");
276
+ const output = "video-xfade";
277
+ filters.push(`${labels[0]}${labels[1]}xfade=transition=fade:duration=${formatNumber(duration)}:offset=${formatNumber(offset)}[${output}]`);
278
+ const padding = Math.max(0, model.duration - (model.duration - duration));
279
+ filters.push(`[${output}]tpad=stop_mode=clone:stop_duration=${formatNumber(padding)}[${output}-padded]`);
280
+ return `${output}-padded`;
281
+ }
282
+ const output = "video-concat";
283
+ filters.push(`${labels.join("")}concat=n=${labels.length}:v=1:a=0[${output}]`);
284
+ return output;
285
+ }
286
+ function addAudioComposition(filters, labels, model, transition) {
287
+ if (labels.length === 1) {
288
+ const output = "audio-base";
289
+ filters.push(`${labels[0]}apad,atrim=duration=${formatNumber(model.duration)},asetpts=PTS-STARTPTS[${output}]`);
290
+ return output;
291
+ }
292
+ if (transition) {
293
+ const duration = rationalSeconds(transition.durationTime, `${transition.id}.durationTime`);
294
+ const output = "audio-crossfade";
295
+ filters.push(`${labels[0]}${labels[1]}acrossfade=d=${formatNumber(duration)}:c1=tri:c2=tri[${output}]`);
296
+ filters.push(`[${output}]apad,atrim=duration=${formatNumber(model.duration)},asetpts=PTS-STARTPTS[${output}-padded]`);
297
+ return `${output}-padded`;
298
+ }
299
+ const output = "audio-concat";
300
+ filters.push(`${labels.join("")}concat=n=${labels.length}:v=0:a=1[${output}]`);
301
+ return output;
302
+ }
303
+ function addTitleOverlays(filters, input, model, fontFile) {
304
+ let current = input;
305
+ for (const [index, title] of (model.timeline.sequence.titles ?? []).entries()) {
306
+ const start = rationalSeconds(title.startTime, `${title.id}.startTime`);
307
+ const end = start + rationalSeconds(title.durationTime, `${title.id}.durationTime`);
308
+ const style = title.style;
309
+ const color = escapeFilterValue(style?.color ?? "white");
310
+ const size = formatNumber(style?.fontSize ?? 32);
311
+ const x = title.position
312
+ ? `${formatNumber(model.width / 2 + title.position.x * model.width / 2)}-(text_w/2)`
313
+ : style?.alignment === "left" ? "20" : style?.alignment === "right" ? "w-text_w-20" : "(w-text_w)/2";
314
+ const y = title.position
315
+ ? `${formatNumber(model.height / 2 - title.position.y * model.height / 2)}-(text_h/2)`
316
+ : "(h-text_h)/2";
317
+ const output = `title-${index}`;
318
+ const font = fontFile ? `fontfile='${escapeFilterValue(fontFile)}':` : "";
319
+ filters.push(`[${current}]drawtext=${font}text='${escapeFilterValue(title.text)}':fontcolor=${color}:fontsize=${size}:x=${x}:y=${y}:enable='between(t,${formatNumber(start)},${formatNumber(end)})'[${output}]`);
320
+ current = output;
321
+ }
322
+ return current;
323
+ }
324
+ function transformFilter(occurrence, resource, width, height) {
325
+ const transform = occurrence.transform;
326
+ if (!transform)
327
+ return `scale=${width}:${height}:force_original_aspect_ratio=disable`;
328
+ const sourceVideo = resource.metadata.streams.find((stream) => stream.kind === "video");
329
+ const scaledWidth = evenDimension(sourceVideo.width * transform.scaleX);
330
+ const scaledHeight = evenDimension(sourceVideo.height * transform.scaleY);
331
+ const positionX = transform.positionX ?? 0;
332
+ const positionY = -(transform.positionY ?? 0);
333
+ if (scaledWidth >= width && scaledHeight >= height) {
334
+ const cropX = clamp((scaledWidth - width) / 2 - positionX, 0, scaledWidth - width);
335
+ const cropY = clamp((scaledHeight - height) / 2 - positionY, 0, scaledHeight - height);
336
+ return `scale=${scaledWidth}:${scaledHeight},crop=${width}:${height}:${formatNumber(cropX)}:${formatNumber(cropY)}`;
337
+ }
338
+ return `scale=${scaledWidth}:${scaledHeight},pad=${width}:${height}:${formatNumber((width - scaledWidth) / 2 + positionX)}:${formatNumber((height - scaledHeight) / 2 + positionY)}:color=black`;
339
+ }
340
+ function supportsLocalMedia(timeline) {
341
+ const resources = new Map(timeline.resources.map((resource) => [resource.id, resource]));
342
+ return timeline.sequence.occurrences.every((occurrence) => {
343
+ const resource = occurrence.mediaId ? resources.get(occurrence.mediaId) : undefined;
344
+ return resource?.sourceKind === "local-file" && Boolean(resource.source) && Boolean(resource.sourceDigest);
345
+ });
346
+ }
347
+ function supportsStructuralEdits(timeline) {
348
+ return timeline.sequence.storyElements.length === 0
349
+ && timeline.sequence.markers.length === 0
350
+ && timeline.sequence.captions.length === 0
351
+ && timeline.sequence.occurrences.length > 0
352
+ && timeline.sequence.occurrences.every((occurrence) => occurrence.track === 0
353
+ && occurrence.role !== "audio"
354
+ && occurrence.role !== "music"
355
+ && occurrence.role !== "title"
356
+ && occurrence.enabled !== false
357
+ && !occurrence.attachedTo);
358
+ }
359
+ function supportsAudioGain(timeline) {
360
+ return timeline.sequence.occurrences.every((occurrence) => occurrence.gainDb === undefined || Number.isFinite(occurrence.gainDb));
361
+ }
362
+ function supportsTransforms(timeline) {
363
+ return timeline.sequence.occurrences.every((occurrence) => !occurrence.transform || (Number.isFinite(occurrence.transform.scaleX)
364
+ && Number.isFinite(occurrence.transform.scaleY)
365
+ && occurrence.transform.scaleX > 0
366
+ && occurrence.transform.scaleY > 0
367
+ && [occurrence.transform.positionX, occurrence.transform.positionY, occurrence.transform.rotationDegrees].every((value) => value === undefined || Number.isFinite(value))
368
+ && occurrence.transform.rotationDegrees === undefined));
369
+ }
370
+ function supportsTitles(timeline) {
371
+ return (timeline.sequence.titles ?? []).every((title) => !title.style || (title.style.fontFamily === undefined
372
+ && (title.style.fontSize === undefined || (Number.isFinite(title.style.fontSize) && title.style.fontSize > 0))));
373
+ }
374
+ function supportsCrossDissolve(timeline) {
375
+ const transitions = timeline.sequence.transitions ?? [];
376
+ return transitions.length <= 1
377
+ && transitions.every((transition) => transition.kind === "cross-dissolve")
378
+ && (transitions.length === 0 || timeline.sequence.occurrences.length === 2);
379
+ }
380
+ async function assertOutputPath(outputPath, overwrite, sourcePaths) {
381
+ if (sourcePaths.includes(outputPath)) {
382
+ throw new FfmpegRenderError("HEADLESS_RENDER_OUTPUT_INVALID", "render output must not overwrite a source media file");
383
+ }
384
+ if (!overwrite && await isRegularFile(outputPath)) {
385
+ throw new FfmpegRenderError("HEADLESS_RENDER_OUTPUT_EXISTS", `render output already exists: ${outputPath}`);
386
+ }
387
+ }
388
+ async function isRegularFile(path) {
389
+ try {
390
+ const details = await lstat(path);
391
+ return details.isFile() && !details.isSymbolicLink();
392
+ }
393
+ catch (error) {
394
+ if (error.code === "ENOENT")
395
+ return false;
396
+ throw error;
397
+ }
398
+ }
399
+ async function digestFile(path) {
400
+ const digest = createHash("sha256");
401
+ await new Promise((resolvePromise, reject) => {
402
+ const stream = createReadStream(path);
403
+ stream.on("data", (chunk) => digest.update(chunk));
404
+ stream.once("error", reject);
405
+ stream.once("end", resolvePromise);
406
+ });
407
+ return digest.digest("hex");
408
+ }
409
+ function rationalSeconds(time, field) {
410
+ if (!/^-?\d+$/.test(time.value) || !/^\d+$/.test(time.timescale) || BigInt(time.timescale) <= 0n) {
411
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `invalid rational time: ${field}`);
412
+ }
413
+ const result = Number(BigInt(time.value)) / Number(BigInt(time.timescale));
414
+ if (!Number.isFinite(result))
415
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", `rational time is too large: ${field}`);
416
+ return result;
417
+ }
418
+ function compareSeconds(left, right) {
419
+ const leftValue = BigInt(left.value) * BigInt(right.timescale);
420
+ const rightValue = BigInt(right.value) * BigInt(left.timescale);
421
+ return leftValue < rightValue ? -1 : leftValue > rightValue ? 1 : 0;
422
+ }
423
+ function evenDimension(value) {
424
+ return Math.max(2, Math.round(value / 2) * 2);
425
+ }
426
+ function clamp(value, minimum, maximum) {
427
+ return Math.min(maximum, Math.max(minimum, value));
428
+ }
429
+ function formatNumber(value) {
430
+ return Number(value.toFixed(6)).toString();
431
+ }
432
+ function escapeFilterValue(value) {
433
+ return value.replaceAll("\\", "\\\\").replaceAll("'", "\\'").replaceAll(":", "\\:").replaceAll(",", "\\,").replaceAll("[", "\\[").replaceAll("]", "\\]").replaceAll("\n", "\\n");
434
+ }
435
+ function resolveFontFile(preferred) {
436
+ const candidates = [
437
+ preferred,
438
+ "/System/Library/Fonts/HelveticaNeue.ttc",
439
+ "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
440
+ "/usr/share/fonts/truetype/liberation2/LiberationSans-Regular.ttf",
441
+ ].filter((candidate) => Boolean(candidate));
442
+ return candidates.find((candidate) => existsSync(candidate));
443
+ }
@@ -0,0 +1,181 @@
1
+ import { createHash } from "node:crypto";
2
+ import { execFile } from "node:child_process";
3
+ import { createReadStream } from "node:fs";
4
+ import { lstat, stat } from "node:fs/promises";
5
+ import { resolve } from "node:path";
6
+ import { promisify } from "node:util";
7
+ const execFileAsync = promisify(execFile);
8
+ /** Independently verifies the committed output; it does not trust provider metadata. */
9
+ export class FfmpegRenderVerifier {
10
+ ffprobePath;
11
+ durationToleranceSeconds;
12
+ environment;
13
+ constructor(options = {}) {
14
+ this.ffprobePath = options.ffprobePath ?? process.env.FFPROBE_BIN ?? "ffprobe";
15
+ this.durationToleranceSeconds = options.durationToleranceSeconds;
16
+ this.environment = { ...process.env, ...options.env };
17
+ }
18
+ async verify(plan, result) {
19
+ const outputPath = resolve(result.output.path);
20
+ const checks = [];
21
+ let details;
22
+ try {
23
+ details = await lstat(outputPath);
24
+ }
25
+ catch {
26
+ return failed([], `render output does not exist: ${outputPath}`, "RENDER_OUTPUT_MISSING");
27
+ }
28
+ if (!details.isFile() || details.isSymbolicLink()) {
29
+ return failed(checks, "render output is not a regular file", "RENDER_OUTPUT_INVALID");
30
+ }
31
+ const fileStats = await stat(outputPath);
32
+ const fileDigest = await digestFile(outputPath);
33
+ const fileIdentity = { device: fileStats.dev, inode: fileStats.ino, size: fileStats.size };
34
+ checks.push({ name: "output-exists", passed: true, detail: "render output is a regular file", observed: { path: outputPath } });
35
+ checks.push({ name: "output-digest", passed: /^[a-f0-9]{64}$/.test(fileDigest), detail: "render output has a SHA-256 digest", observed: fileDigest });
36
+ let probe;
37
+ try {
38
+ probe = await this.probe(outputPath);
39
+ }
40
+ catch (error) {
41
+ if (error.code === "ENOENT" || (error instanceof Error && /spawn ffprobe ENOENT/.test(error.message))) {
42
+ return unavailable("ffprobe is not configured", "RENDER_VERIFIER_UNAVAILABLE");
43
+ }
44
+ return failed(checks, error instanceof Error ? error.message : String(error), "RENDER_OUTPUT_UNPLAYABLE");
45
+ }
46
+ let finalDetails;
47
+ try {
48
+ finalDetails = await lstat(outputPath);
49
+ }
50
+ catch {
51
+ return failed(checks, `render output changed during verification: ${outputPath}`, "RENDER_OUTPUT_CHANGED");
52
+ }
53
+ if (!finalDetails.isFile() || finalDetails.isSymbolicLink()) {
54
+ return failed(checks, "render output changed into a non-regular file during verification", "RENDER_OUTPUT_CHANGED");
55
+ }
56
+ const finalDigest = await digestFile(outputPath);
57
+ if (finalDetails.dev !== fileIdentity.device || finalDetails.ino !== fileIdentity.inode || finalDetails.size !== fileIdentity.size || finalDigest !== fileDigest) {
58
+ return failed(checks, "render output bytes or file identity changed during verification", "RENDER_OUTPUT_CHANGED");
59
+ }
60
+ checks.push({ name: "output-stability", passed: true, detail: "the verified metadata and digest refer to one unchanged output file" });
61
+ const video = probe.streams.find((stream) => stream.codec_type === "video");
62
+ if (!video || video.width === undefined || video.height === undefined || !video.r_frame_rate) {
63
+ return failed(checks, "render output has no complete video stream", "RENDER_OUTPUT_UNPLAYABLE");
64
+ }
65
+ const expectedFrameRate = parseRational(plan.parameters.frameRate);
66
+ const expectedAudio = expectedAudioStream(plan);
67
+ const audio = probe.streams.find((stream) => stream.codec_type === "audio");
68
+ const observedFrameRate = parseFfmpegRate(video.r_frame_rate);
69
+ const expectedDuration = rationalSeconds(plan.timeline.sequence.durationTime);
70
+ const tolerance = this.durationToleranceSeconds ?? Math.max(0.05, rationalSeconds(plan.timeline.sequence.frameDuration) * 1.5);
71
+ const durationPassed = Number.isFinite(probe.format.duration)
72
+ && Math.abs(probe.format.duration - expectedDuration) <= tolerance;
73
+ const frameRatePassed = observedFrameRate !== undefined && sameRational(observedFrameRate, expectedFrameRate);
74
+ const formatPassed = probe.format.format_name.split(",").some((format) => format === plan.parameters.format);
75
+ checks.push({ name: "playable", passed: true, detail: "ffprobe read the output streams and duration" });
76
+ checks.push({ name: "format", passed: formatPassed, detail: "output container matches the explicit request", expected: plan.parameters.format, observed: probe.format.format_name });
77
+ checks.push({ name: "dimensions", passed: video.width === plan.parameters.width && video.height === plan.parameters.height, detail: "output dimensions match the explicit request", expected: { width: plan.parameters.width, height: plan.parameters.height }, observed: { width: video.width, height: video.height } });
78
+ checks.push({ name: "frame-rate", passed: frameRatePassed, detail: "output rational frame rate matches the explicit request", expected: expectedFrameRate, observed: observedFrameRate });
79
+ const audioPassed = expectedAudio === undefined || (audio !== undefined
80
+ && (expectedAudio.sampleRate === undefined || Number(audio.sample_rate) === expectedAudio.sampleRate)
81
+ && (expectedAudio.channels === undefined || audio.channels === expectedAudio.channels));
82
+ checks.push({ name: "audio-stream", passed: audioPassed, detail: "canonical audio stream presence and metadata are preserved", expected: expectedAudio ?? { kind: "none" }, observed: audio ?? { kind: "none" } });
83
+ checks.push({ name: "duration", passed: durationPassed, detail: `output duration is within ${tolerance} seconds of the canonical sequence`, expected: expectedDuration, observed: probe.format.duration });
84
+ const artifact = {
85
+ path: result.output.path,
86
+ format: probe.format.format_name,
87
+ sizeBytes: fileStats.size,
88
+ fileDigest,
89
+ durationSeconds: probe.format.duration,
90
+ width: video.width,
91
+ height: video.height,
92
+ frameRate: observedFrameRate ?? expectedFrameRate,
93
+ streams: probe.streams.map(toArtifactStream),
94
+ };
95
+ const passed = checks.every((check) => check.passed);
96
+ return { status: passed ? "passed" : "failed", checks, artifact };
97
+ }
98
+ async probe(path) {
99
+ const result = await execFileAsync(this.ffprobePath, [
100
+ "-v", "error",
101
+ "-show_entries", "stream=codec_type,codec_name,width,height,r_frame_rate,sample_rate,channels",
102
+ "-show_entries", "format=format_name,duration",
103
+ "-of", "json",
104
+ path,
105
+ ], { env: this.environment, maxBuffer: 2 * 1024 * 1024 });
106
+ const parsed = JSON.parse(result.stdout);
107
+ if (!Array.isArray(parsed.streams) || !parsed.format || typeof parsed.format.duration !== "string" || !Number.isFinite(Number(parsed.format.duration))) {
108
+ throw new Error("ffprobe returned incomplete output metadata");
109
+ }
110
+ return {
111
+ streams: parsed.streams,
112
+ format: { format_name: String(parsed.format.format_name ?? ""), duration: Number(parsed.format.duration) },
113
+ };
114
+ }
115
+ }
116
+ function expectedAudioStream(plan) {
117
+ const resources = new Map(plan.timeline.resources.map((resource) => [resource.id, resource]));
118
+ for (const occurrence of plan.timeline.sequence.occurrences) {
119
+ const resource = occurrence.mediaId ? resources.get(occurrence.mediaId) : undefined;
120
+ const stream = resource?.metadata?.streams.find((candidate) => candidate.kind === "audio");
121
+ if (stream)
122
+ return { sampleRate: stream.sampleRate, channels: stream.channels };
123
+ }
124
+ return undefined;
125
+ }
126
+ function toArtifactStream(stream) {
127
+ return {
128
+ kind: stream.codec_type,
129
+ ...(stream.codec_name ? { codec: stream.codec_name } : {}),
130
+ ...(stream.width !== undefined ? { width: stream.width } : {}),
131
+ ...(stream.height !== undefined ? { height: stream.height } : {}),
132
+ ...(stream.r_frame_rate ? { frameRate: parseFfmpegRate(stream.r_frame_rate) } : {}),
133
+ ...(stream.sample_rate ? { sampleRate: Number(stream.sample_rate) } : {}),
134
+ ...(stream.channels !== undefined ? { channels: stream.channels } : {}),
135
+ };
136
+ }
137
+ function parseFfmpegRate(value) {
138
+ if (!value || !/^\d+\/\d+$/.test(value))
139
+ return undefined;
140
+ const [numerator, denominator] = value.split("/").map(BigInt);
141
+ if (denominator <= 0n)
142
+ return undefined;
143
+ const divisor = gcd(numerator, denominator);
144
+ return { value: String(numerator / divisor), timescale: String(denominator / divisor) };
145
+ }
146
+ function parseRational(value) {
147
+ const numerator = BigInt(value.value);
148
+ const denominator = BigInt(value.timescale);
149
+ const divisor = gcd(numerator < 0n ? -numerator : numerator, denominator);
150
+ return { value: String(numerator / divisor), timescale: String(denominator / divisor) };
151
+ }
152
+ function sameRational(left, right) {
153
+ return left.value === right.value && left.timescale === right.timescale;
154
+ }
155
+ function rationalSeconds(value) {
156
+ return Number(BigInt(value.value)) / Number(BigInt(value.timescale));
157
+ }
158
+ function gcd(left, right) {
159
+ while (right !== 0n) {
160
+ const remainder = left % right;
161
+ left = right;
162
+ right = remainder;
163
+ }
164
+ return left || 1n;
165
+ }
166
+ async function digestFile(path) {
167
+ const digest = createHash("sha256");
168
+ await new Promise((resolvePromise, reject) => {
169
+ const stream = createReadStream(path);
170
+ stream.on("data", (chunk) => digest.update(chunk));
171
+ stream.once("error", reject);
172
+ stream.once("end", resolvePromise);
173
+ });
174
+ return digest.digest("hex");
175
+ }
176
+ function failed(checks, message, code) {
177
+ return { status: "failed", checks: [...checks, { name: code.toLowerCase(), passed: false, detail: message }], error: { code, message } };
178
+ }
179
+ function unavailable(message, code) {
180
+ return { status: "unavailable", checks: [{ name: code.toLowerCase(), passed: false, detail: message }], error: { code, message } };
181
+ }
@@ -0,0 +1,3 @@
1
+ export * from "./ffmpeg-renderer.js";
2
+ export * from "./ffmpeg-verifier.js";
3
+ export * from "./ffmpeg-media-probe.js";