@morshoto/framekit 0.1.14 → 0.1.17
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.
- package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +28 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical.js +144 -35
- package/dist-package/adapters/final-cut/typescript/src/connection.js +8 -5
- package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +36 -7
- package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +21 -7
- package/dist-package/adapters/final-cut/typescript/src/index.js +2 -0
- package/dist-package/adapters/final-cut/typescript/src/live.js +56 -1
- package/dist-package/adapters/final-cut/typescript/src/native.js +311 -20
- package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.js +312 -0
- package/dist-package/adapters/final-cut/typescript/src/publisher.js +68 -8
- package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.js +263 -0
- package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +179 -25
- package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +62 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +551 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +181 -0
- package/dist-package/adapters/headless/typescript/src/index.js +3 -0
- package/dist-package/apps/mcp-server/src/headless-projects.js +370 -0
- package/dist-package/apps/mcp-server/src/headless-sessions.js +3 -0
- package/dist-package/apps/mcp-server/src/main.js +28 -4
- package/dist-package/apps/mcp-server/src/materialization-jobs.js +233 -4
- package/dist-package/apps/mcp-server/src/readback-policy.js +26 -0
- package/dist-package/apps/mcp-server/src/routing.js +134 -5
- package/dist-package/apps/mcp-server/src/server.js +311 -34
- package/dist-package/packages/runtime/src/application/local-media.js +157 -0
- package/dist-package/packages/runtime/src/application/media-analysis-service.js +347 -27
- package/dist-package/packages/runtime/src/application/project-store.js +234 -0
- package/dist-package/packages/runtime/src/application/project-transactions.js +227 -0
- package/dist-package/packages/runtime/src/application/semantic-media-index-store.js +86 -0
- package/dist-package/packages/runtime/src/index.js +7 -0
- package/dist-package/packages/runtime/src/planning/rough-cut.js +103 -7
- package/dist-package/packages/runtime/src/render/render-and-verify.js +126 -0
- package/dist-package/packages/runtime/src/render/render-contract.js +146 -0
- package/dist-package/packages/runtime/src/runtime.js +5 -2
- package/dist-package/packages/runtime/src/timeline/editing-session.js +277 -9
- package/dist-package/packages/runtime/src/timeline/fast-observation.js +141 -0
- package/package.json +2 -1
|
@@ -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,370 @@
|
|
|
1
|
+
import { createHash, randomUUID } from "node:crypto";
|
|
2
|
+
import { readdir, readFile, rename, writeFile, mkdir } from "node:fs/promises";
|
|
3
|
+
import { dirname, join } from "node:path";
|
|
4
|
+
import { FramekitProjectStore, LocalMediaRegistrar, ProjectTransactionService, createFramekitRenderRequest, renderAndVerifyFramekitProject, } from "../../../packages/runtime/src/index.js";
|
|
5
|
+
import { compileTimelineIrToFcpxml, } from "../../../adapters/final-cut/typescript/src/index.js";
|
|
6
|
+
export class HeadlessProjectService {
|
|
7
|
+
directory;
|
|
8
|
+
mediaProbe;
|
|
9
|
+
renderer;
|
|
10
|
+
verifier;
|
|
11
|
+
clock;
|
|
12
|
+
constructor(options) {
|
|
13
|
+
this.directory = options.directory;
|
|
14
|
+
this.mediaProbe = options.mediaProbe;
|
|
15
|
+
this.renderer = options.renderer;
|
|
16
|
+
this.verifier = options.verifier;
|
|
17
|
+
this.clock = options.clock ?? (() => new Date().toISOString());
|
|
18
|
+
}
|
|
19
|
+
async create(timeline) {
|
|
20
|
+
const store = this.store(timeline.project.id);
|
|
21
|
+
const timestamp = this.clock();
|
|
22
|
+
return store.create({
|
|
23
|
+
schemaVersion: 1,
|
|
24
|
+
metadata: { createdAt: timestamp, updatedAt: timestamp },
|
|
25
|
+
timeline,
|
|
26
|
+
});
|
|
27
|
+
}
|
|
28
|
+
async list() {
|
|
29
|
+
await mkdir(this.directory, { recursive: true });
|
|
30
|
+
const entries = await readdir(this.directory, { withFileTypes: true });
|
|
31
|
+
const summaries = [];
|
|
32
|
+
for (const entry of entries.filter((candidate) => candidate.isFile() && candidate.name.endsWith(".json") && !candidate.name.startsWith("render-"))) {
|
|
33
|
+
const projectId = entry.name.slice(0, -".json".length);
|
|
34
|
+
const project = await this.store(projectId).load();
|
|
35
|
+
summaries.push(toSummary(project, this.projectPath(projectId)));
|
|
36
|
+
}
|
|
37
|
+
return summaries.sort((left, right) => left.projectId.localeCompare(right.projectId));
|
|
38
|
+
}
|
|
39
|
+
async open(projectId) {
|
|
40
|
+
const project = await this.store(projectId).load();
|
|
41
|
+
const hasLocalMedia = project.timeline.resources.some((resource) => resource.sourceKind === "local-file");
|
|
42
|
+
if (hasLocalMedia && !this.mediaProbe) {
|
|
43
|
+
throw new Error("HEADLESS_MEDIA_PROBE_UNAVAILABLE: local-file resources require a configured media probe");
|
|
44
|
+
}
|
|
45
|
+
if (this.mediaProbe)
|
|
46
|
+
await new LocalMediaRegistrar(this.store(projectId), this.mediaProbe).reopen();
|
|
47
|
+
return project;
|
|
48
|
+
}
|
|
49
|
+
async inspect(projectId) {
|
|
50
|
+
return this.open(projectId);
|
|
51
|
+
}
|
|
52
|
+
async registerMedia(projectId, sourcePath, expectedRevision) {
|
|
53
|
+
if (!this.mediaProbe)
|
|
54
|
+
throw new Error("HEADLESS_MEDIA_PROBE_UNAVAILABLE: no local media metadata probe is configured");
|
|
55
|
+
return new LocalMediaRegistrar(this.store(projectId), this.mediaProbe, { clock: this.clock }).register(sourcePath, expectedRevision);
|
|
56
|
+
}
|
|
57
|
+
async previewEdit(projectId, command, sequenceId) {
|
|
58
|
+
await this.open(projectId);
|
|
59
|
+
const transaction = new ProjectTransactionService(this.store(projectId), { clock: this.clock });
|
|
60
|
+
return transaction.preview({
|
|
61
|
+
...command,
|
|
62
|
+
target: command.target ?? { projectId, sequenceId },
|
|
63
|
+
});
|
|
64
|
+
}
|
|
65
|
+
async executeEdit(projectId, command, sequenceId) {
|
|
66
|
+
await this.open(projectId);
|
|
67
|
+
const transaction = new ProjectTransactionService(this.store(projectId), { clock: this.clock });
|
|
68
|
+
return transaction.execute({
|
|
69
|
+
...command,
|
|
70
|
+
target: command.target ?? { projectId, sequenceId },
|
|
71
|
+
});
|
|
72
|
+
}
|
|
73
|
+
async previewRoughCut(request) {
|
|
74
|
+
const prepared = await this.prepareRoughCut(request);
|
|
75
|
+
const transaction = new ProjectTransactionService(this.store(request.projectId), { clock: this.clock });
|
|
76
|
+
const preview = await transaction.preview(prepared.command);
|
|
77
|
+
const fcpxml = compileTimelineIrToFcpxml(preview.after.timeline, { target: request.fcpxml.target });
|
|
78
|
+
return {
|
|
79
|
+
...preview,
|
|
80
|
+
plan: structuredClone(request.plan),
|
|
81
|
+
planDigest: prepared.planDigest,
|
|
82
|
+
provenance: prepared.provenance,
|
|
83
|
+
outputIntent: prepared.outputIntent,
|
|
84
|
+
fcpxml: selectFcpxmlMetadata(fcpxml),
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
async executeRoughCut(request) {
|
|
88
|
+
if (request.approved !== true) {
|
|
89
|
+
throw new Error("HEADLESS_ROUGH_CUT_APPROVAL_REQUIRED: set approved=true after reviewing the preview");
|
|
90
|
+
}
|
|
91
|
+
const prepared = await this.prepareRoughCut(request);
|
|
92
|
+
if (request.planDigest !== prepared.planDigest) {
|
|
93
|
+
throw new Error("HEADLESS_ROUGH_CUT_PLAN_MISMATCH: planDigest does not match the submitted rough-cut plan");
|
|
94
|
+
}
|
|
95
|
+
const transaction = new ProjectTransactionService(this.store(request.projectId), { clock: this.clock });
|
|
96
|
+
const preview = await transaction.preview(prepared.command);
|
|
97
|
+
const fcpxml = compileTimelineIrToFcpxml(preview.after.timeline, { target: request.fcpxml.target });
|
|
98
|
+
const renderRequest = createFramekitRenderRequest({
|
|
99
|
+
timeline: preview.after.timeline,
|
|
100
|
+
target: { projectId: request.projectId, sequenceId: request.sequenceId },
|
|
101
|
+
revision: preview.after.timeline.revision,
|
|
102
|
+
parameters: request.render,
|
|
103
|
+
});
|
|
104
|
+
if (!this.renderer || !this.verifier) {
|
|
105
|
+
throw new Error("HEADLESS_ROUGH_CUT_RENDER_UNAVAILABLE: renderer and verifier are not configured");
|
|
106
|
+
}
|
|
107
|
+
const outcome = await renderAndVerifyFramekitProject(renderRequest, this.renderer, this.verifier);
|
|
108
|
+
const renderId = `render-${randomUUID()}`;
|
|
109
|
+
const renderRecord = {
|
|
110
|
+
renderId,
|
|
111
|
+
projectId: request.projectId,
|
|
112
|
+
sequenceId: request.sequenceId,
|
|
113
|
+
requestedRevision: renderRequest.projectRevision,
|
|
114
|
+
createdAt: this.clock(),
|
|
115
|
+
status: outcome.status,
|
|
116
|
+
outcome,
|
|
117
|
+
};
|
|
118
|
+
await this.saveRender(renderRecord);
|
|
119
|
+
if (outcome.status !== "passed") {
|
|
120
|
+
throw new Error(`HEADLESS_ROUGH_CUT_RENDER_FAILED: render verification status was ${outcome.status}; inspect ${renderId}`);
|
|
121
|
+
}
|
|
122
|
+
const fcpxmlArtifact = await writeVerifiedFcpxml(request.fcpxml.path, fcpxml.xml, fcpxml.digest, request.fcpxml.overwrite === true);
|
|
123
|
+
const committed = await transaction.execute(prepared.command);
|
|
124
|
+
return {
|
|
125
|
+
...preview,
|
|
126
|
+
plan: structuredClone(request.plan),
|
|
127
|
+
planDigest: prepared.planDigest,
|
|
128
|
+
provenance: prepared.provenance,
|
|
129
|
+
outputIntent: prepared.outputIntent,
|
|
130
|
+
fcpxml: selectFcpxmlMetadata(fcpxml),
|
|
131
|
+
committed: true,
|
|
132
|
+
render: { renderId, status: "passed", outcome },
|
|
133
|
+
fcpxmlArtifact,
|
|
134
|
+
transaction: committed,
|
|
135
|
+
};
|
|
136
|
+
}
|
|
137
|
+
async render(projectId, sequenceId, parameters, expectedRevision) {
|
|
138
|
+
if (!this.renderer || !this.verifier)
|
|
139
|
+
throw new Error("HEADLESS_RENDER_UNAVAILABLE: renderer and verifier are not configured");
|
|
140
|
+
const project = await this.open(projectId);
|
|
141
|
+
const request = createFramekitRenderRequest({
|
|
142
|
+
timeline: project.timeline,
|
|
143
|
+
target: { projectId, sequenceId },
|
|
144
|
+
...(expectedRevision ? { revision: expectedRevision } : {}),
|
|
145
|
+
parameters,
|
|
146
|
+
});
|
|
147
|
+
const outcome = await renderAndVerifyFramekitProject(request, this.renderer, this.verifier);
|
|
148
|
+
const renderId = `render-${randomUUID()}`;
|
|
149
|
+
const record = {
|
|
150
|
+
renderId,
|
|
151
|
+
projectId,
|
|
152
|
+
sequenceId,
|
|
153
|
+
requestedRevision: request.projectRevision,
|
|
154
|
+
createdAt: this.clock(),
|
|
155
|
+
status: outcome.status,
|
|
156
|
+
outcome,
|
|
157
|
+
};
|
|
158
|
+
await this.saveRender(record);
|
|
159
|
+
return record;
|
|
160
|
+
}
|
|
161
|
+
async inspectRender(renderId) {
|
|
162
|
+
validateRenderId(renderId);
|
|
163
|
+
try {
|
|
164
|
+
return JSON.parse(await readFile(join(this.directory, `${renderId}.json`), "utf8"));
|
|
165
|
+
}
|
|
166
|
+
catch (error) {
|
|
167
|
+
if (error.code === "ENOENT")
|
|
168
|
+
throw new Error(`HEADLESS_RENDER_NOT_FOUND: render record does not exist: ${renderId}`);
|
|
169
|
+
throw error;
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
store(projectId) {
|
|
173
|
+
return new FramekitProjectStore(this.projectPath(projectId));
|
|
174
|
+
}
|
|
175
|
+
projectPath(projectId) {
|
|
176
|
+
validateProjectId(projectId);
|
|
177
|
+
return join(this.directory, `${projectId}.json`);
|
|
178
|
+
}
|
|
179
|
+
async saveRender(record) {
|
|
180
|
+
await mkdir(this.directory, { recursive: true });
|
|
181
|
+
const path = join(this.directory, `${record.renderId}.json`);
|
|
182
|
+
const temporary = `${path}.${randomUUID()}.tmp`;
|
|
183
|
+
await writeFile(temporary, `${JSON.stringify(record)}\n`, { encoding: "utf8", flag: "wx" });
|
|
184
|
+
await rename(temporary, path);
|
|
185
|
+
}
|
|
186
|
+
async prepareRoughCut(request) {
|
|
187
|
+
await this.open(request.projectId);
|
|
188
|
+
const project = await this.store(request.projectId).load();
|
|
189
|
+
if (project.timeline.sequence.id !== request.sequenceId) {
|
|
190
|
+
throw new Error("HEADLESS_ROUGH_CUT_TARGET_MISMATCH: sequenceId does not match the persisted project");
|
|
191
|
+
}
|
|
192
|
+
if (!sameRevision(project.timeline.revision, request.plan.revision)) {
|
|
193
|
+
throw new Error("HEADLESS_ROUGH_CUT_STALE_REVISION: rough-cut plan revision does not match the persisted project");
|
|
194
|
+
}
|
|
195
|
+
if (!request.plan.shots.length)
|
|
196
|
+
throw new Error("HEADLESS_ROUGH_CUT_EMPTY_PLAN: rough-cut plan must contain at least one shot");
|
|
197
|
+
const operations = structuredClone(request.operations ?? []);
|
|
198
|
+
const sourceAudioPolicy = request.sourceAudioPolicy ?? "preserve-and-mix";
|
|
199
|
+
const outputIntent = {
|
|
200
|
+
sourceAudioPolicy,
|
|
201
|
+
render: structuredClone(request.render),
|
|
202
|
+
fcpxml: {
|
|
203
|
+
path: request.fcpxml.path,
|
|
204
|
+
target: structuredClone(request.fcpxml.target),
|
|
205
|
+
overwrite: request.fcpxml.overwrite === true,
|
|
206
|
+
},
|
|
207
|
+
};
|
|
208
|
+
const planDigest = digestRoughCutPlan(request.plan, operations, outputIntent);
|
|
209
|
+
const existingOccurrenceIds = new Set(project.timeline.sequence.occurrences.map(({ id }) => id));
|
|
210
|
+
const resourceByMediaId = new Map(project.timeline.resources.map((resource) => [resource.id, resource]));
|
|
211
|
+
const provenance = [];
|
|
212
|
+
const planOperations = [];
|
|
213
|
+
for (const shot of request.plan.shots) {
|
|
214
|
+
const shotWithEvidence = shot;
|
|
215
|
+
const occurrenceId = `rough-cut-${shot.order}`;
|
|
216
|
+
if (existingOccurrenceIds.has(occurrenceId)) {
|
|
217
|
+
throw new Error(`HEADLESS_ROUGH_CUT_OCCURRENCE_COLLISION: ${occurrenceId} already exists`);
|
|
218
|
+
}
|
|
219
|
+
existingOccurrenceIds.add(occurrenceId);
|
|
220
|
+
const resource = resourceByMediaId.get(shot.sourceIdentity.mediaId);
|
|
221
|
+
if (!resource)
|
|
222
|
+
throw new Error(`HEADLESS_ROUGH_CUT_SOURCE_NOT_FOUND: ${shot.sourceIdentity.mediaId}`);
|
|
223
|
+
assertSourceIdentity(resource, shot.sourceIdentity);
|
|
224
|
+
const sourceStartTime = shot.range.startTime ?? secondsToRational(shot.range.start);
|
|
225
|
+
const durationTime = shot.range.durationTime ?? secondsToRational(shot.range.end - shot.range.start);
|
|
226
|
+
assertSourceRange(resource, shot.range, sourceStartTime, durationTime);
|
|
227
|
+
planOperations.push({
|
|
228
|
+
type: "insert-occurrence",
|
|
229
|
+
placement: "append",
|
|
230
|
+
occurrence: {
|
|
231
|
+
id: occurrenceId,
|
|
232
|
+
name: `Rough cut ${shot.order}: ${shot.rationale}`,
|
|
233
|
+
startTime: { value: "0", timescale: "1" },
|
|
234
|
+
durationTime,
|
|
235
|
+
sourceStartTime,
|
|
236
|
+
track: 0,
|
|
237
|
+
role: "video",
|
|
238
|
+
mediaId: resource.id,
|
|
239
|
+
binding: { provider: "framekit.rough-cut", kind: "occurrence", identity: `${planDigest}:${shot.order}` },
|
|
240
|
+
},
|
|
241
|
+
});
|
|
242
|
+
provenance.push({
|
|
243
|
+
order: shot.order,
|
|
244
|
+
occurrenceId,
|
|
245
|
+
mediaId: resource.id,
|
|
246
|
+
sourceIdentity: structuredClone(shot.sourceIdentity),
|
|
247
|
+
sourceRange: structuredClone(shot.range),
|
|
248
|
+
confidence: shot.confidence,
|
|
249
|
+
matchedProperties: [...shot.matchedProperties],
|
|
250
|
+
rationale: shot.rationale,
|
|
251
|
+
...(shotWithEvidence.evidence ? { evidence: structuredClone(shotWithEvidence.evidence) } : {}),
|
|
252
|
+
});
|
|
253
|
+
}
|
|
254
|
+
const editOperations = [...planOperations, ...operations];
|
|
255
|
+
const command = {
|
|
256
|
+
schemaVersion: 1,
|
|
257
|
+
target: { projectId: request.projectId, sequenceId: request.sequenceId },
|
|
258
|
+
expectedRevision: structuredClone(request.plan.revision),
|
|
259
|
+
operations: editOperations,
|
|
260
|
+
};
|
|
261
|
+
return { command, planDigest, provenance, outputIntent };
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
function digestRoughCutPlan(plan, operations, outputIntent) {
|
|
265
|
+
return createHash("sha256").update(stableJson({ plan, operations, outputIntent })).digest("hex");
|
|
266
|
+
}
|
|
267
|
+
function stableJson(value) {
|
|
268
|
+
if (value === null || typeof value !== "object")
|
|
269
|
+
return JSON.stringify(value);
|
|
270
|
+
if (Array.isArray(value))
|
|
271
|
+
return `[${value.map(stableJson).join(",")}]`;
|
|
272
|
+
return `{${Object.entries(value).filter(([, child]) => child !== undefined).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => `${JSON.stringify(key)}:${stableJson(child)}`).join(",")}}`;
|
|
273
|
+
}
|
|
274
|
+
function assertSourceIdentity(resource, source) {
|
|
275
|
+
if (resource.source !== source.source)
|
|
276
|
+
throw new Error(`HEADLESS_ROUGH_CUT_SOURCE_MISMATCH: source path differs for ${source.mediaId}`);
|
|
277
|
+
if (source.sourceDigest !== undefined && resource.sourceDigest !== source.sourceDigest) {
|
|
278
|
+
throw new Error(`HEADLESS_ROUGH_CUT_SOURCE_MISMATCH: source digest differs for ${source.mediaId}`);
|
|
279
|
+
}
|
|
280
|
+
if (source.mediaKind !== undefined && resource.mediaKind !== source.mediaKind) {
|
|
281
|
+
throw new Error(`HEADLESS_ROUGH_CUT_SOURCE_MISMATCH: media kind differs for ${source.mediaId}`);
|
|
282
|
+
}
|
|
283
|
+
if (resource.mediaKind !== "video")
|
|
284
|
+
throw new Error(`HEADLESS_ROUGH_CUT_VIDEO_REQUIRED: ${source.mediaId}`);
|
|
285
|
+
if (source.duration !== undefined && resource.metadata?.durationTime !== undefined
|
|
286
|
+
&& Math.abs(source.duration - rationalSeconds(resource.metadata.durationTime)) > 0.01) {
|
|
287
|
+
throw new Error(`HEADLESS_ROUGH_CUT_SOURCE_MISMATCH: source duration differs for ${source.mediaId}`);
|
|
288
|
+
}
|
|
289
|
+
}
|
|
290
|
+
function assertSourceRange(resource, range, sourceStartTime, durationTime) {
|
|
291
|
+
if (!Number.isFinite(range.start) || !Number.isFinite(range.end) || range.start < 0 || range.end <= range.start) {
|
|
292
|
+
throw new Error("HEADLESS_ROUGH_CUT_RANGE_INVALID: source range must be finite and non-empty");
|
|
293
|
+
}
|
|
294
|
+
if (resource.metadata?.durationTime !== undefined && range.end > rationalSeconds(resource.metadata.durationTime) + 0.001) {
|
|
295
|
+
throw new Error(`HEADLESS_ROUGH_CUT_RANGE_INVALID: source range exceeds ${resource.id}`);
|
|
296
|
+
}
|
|
297
|
+
if (rationalSeconds(sourceStartTime) < 0 || rationalSeconds(durationTime) <= 0
|
|
298
|
+
|| Math.abs(rationalSeconds(sourceStartTime) - range.start) > 0.001
|
|
299
|
+
|| Math.abs(rationalSeconds(durationTime) - (range.end - range.start)) > 0.001) {
|
|
300
|
+
throw new Error("HEADLESS_ROUGH_CUT_RANGE_INVALID: rational source range must be non-negative and non-empty");
|
|
301
|
+
}
|
|
302
|
+
}
|
|
303
|
+
function secondsToRational(seconds) {
|
|
304
|
+
const timescale = 1_000_000;
|
|
305
|
+
const value = Math.round(seconds * timescale);
|
|
306
|
+
const divisor = greatestCommonDivisor(Math.abs(value), timescale);
|
|
307
|
+
return { value: String(value / divisor), timescale: String(timescale / divisor) };
|
|
308
|
+
}
|
|
309
|
+
function rationalSeconds(time) {
|
|
310
|
+
return Number(time.value) / Number(time.timescale);
|
|
311
|
+
}
|
|
312
|
+
function greatestCommonDivisor(left, right) {
|
|
313
|
+
while (right !== 0) {
|
|
314
|
+
const remainder = left % right;
|
|
315
|
+
left = right;
|
|
316
|
+
right = remainder;
|
|
317
|
+
}
|
|
318
|
+
return left || 1;
|
|
319
|
+
}
|
|
320
|
+
function sameRevision(left, right) {
|
|
321
|
+
return left.id === right.id && left.sequence === right.sequence && left.timestamp === right.timestamp;
|
|
322
|
+
}
|
|
323
|
+
function selectFcpxmlMetadata(result) {
|
|
324
|
+
return {
|
|
325
|
+
digest: result.digest,
|
|
326
|
+
target: structuredClone(result.target),
|
|
327
|
+
destination: structuredClone(result.destination),
|
|
328
|
+
coverage: structuredClone(result.coverage),
|
|
329
|
+
provenance: structuredClone(result.provenance),
|
|
330
|
+
};
|
|
331
|
+
}
|
|
332
|
+
async function writeVerifiedFcpxml(path, xml, digest, overwrite) {
|
|
333
|
+
await mkdir(dirname(path), { recursive: true });
|
|
334
|
+
if (!overwrite) {
|
|
335
|
+
try {
|
|
336
|
+
await readFile(path);
|
|
337
|
+
throw new Error(`HEADLESS_ROUGH_CUT_FCPXML_EXISTS: refusing to overwrite ${path}`);
|
|
338
|
+
}
|
|
339
|
+
catch (error) {
|
|
340
|
+
if (error.code !== "ENOENT")
|
|
341
|
+
throw error;
|
|
342
|
+
}
|
|
343
|
+
}
|
|
344
|
+
const temporary = `${path}.${randomUUID()}.tmp`;
|
|
345
|
+
await writeFile(temporary, xml, { encoding: "utf8", flag: "wx" });
|
|
346
|
+
await rename(temporary, path);
|
|
347
|
+
const persisted = await readFile(path, "utf8");
|
|
348
|
+
const persistedDigest = createHash("sha256").update(persisted).digest("hex");
|
|
349
|
+
if (persistedDigest !== digest)
|
|
350
|
+
throw new Error("HEADLESS_ROUGH_CUT_FCPXML_VERIFY_FAILED: persisted XML digest differs from the compiled artifact");
|
|
351
|
+
return { path, digest, bytes: Buffer.byteLength(persisted), verified: true };
|
|
352
|
+
}
|
|
353
|
+
function toSummary(project, path) {
|
|
354
|
+
return {
|
|
355
|
+
projectId: project.timeline.project.id,
|
|
356
|
+
projectName: project.timeline.project.name,
|
|
357
|
+
sequenceId: project.timeline.sequence.id,
|
|
358
|
+
sequenceName: project.timeline.sequence.name,
|
|
359
|
+
revision: project.timeline.revision,
|
|
360
|
+
path,
|
|
361
|
+
};
|
|
362
|
+
}
|
|
363
|
+
function validateProjectId(projectId) {
|
|
364
|
+
if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(projectId))
|
|
365
|
+
throw new Error("HEADLESS_PROJECT_INVALID: projectId must be a safe logical identifier");
|
|
366
|
+
}
|
|
367
|
+
function validateRenderId(renderId) {
|
|
368
|
+
if (!/^render-[0-9a-f-]{36}$/.test(renderId))
|
|
369
|
+
throw new Error("HEADLESS_RENDER_INVALID: renderId is invalid");
|
|
370
|
+
}
|
|
@@ -99,6 +99,9 @@ export class EditingSessionRepository {
|
|
|
99
99
|
await this.refreshLoaded(sessionId, session);
|
|
100
100
|
return session;
|
|
101
101
|
}
|
|
102
|
+
hasChangeSource() {
|
|
103
|
+
return this.changeSource !== undefined;
|
|
104
|
+
}
|
|
102
105
|
checkpoint(sessionId, session) {
|
|
103
106
|
return this.save(sessionId, session);
|
|
104
107
|
}
|
|
@@ -4,9 +4,11 @@ import { join } from "node:path";
|
|
|
4
4
|
import { InMemoryEditorAdapter } from "../../../packages/testkit/src/index.js";
|
|
5
5
|
import { createCommandAnalyzers, createFinalCutLiveAdapter, FcpxmlDocumentAdapter, FinalCutAssetRegistry, FinalCutMediaRegistry, FinalCutConnectionManager, assertCanonicalProviderConfiguration, FinalCutCanonicalNativeProvider, FinalCutCanonicalSnapshotSource, FinalCutLibraryInspectionProvider, FinalCutNativeAutomationAdapter, createFinalCutNativeTargetResolver, DisposableNativeEditWorkflow, FinalCutBackgroundMaterializationPublisher, FinalCutProjectPublisher, FinalCutSqliteInspectionProvider, FinalCutVideoExporter, FinalCutSessionAdapter, createNativeOperationLease, createDisposableNativeOperationSession, isFinalCutVideoProbeAvailable, } from "../../../adapters/final-cut/typescript/src/index.js";
|
|
6
6
|
import { FixtureAudioAnalyzer, FixtureMetadataAnalyzer, FixtureSpeechAnalyzer, FixtureVisualAnalyzer } from "../../../packages/testkit/src/index.js";
|
|
7
|
-
import { AgentVideoRuntime } from "../../../packages/runtime/src/index.js";
|
|
7
|
+
import { AgentVideoRuntime, JsonSemanticMediaIndexStore } from "../../../packages/runtime/src/index.js";
|
|
8
8
|
import { createMcpServer } from "./server.js";
|
|
9
9
|
import { createCanonicalSessionChangeSource } from "./headless-sessions.js";
|
|
10
|
+
import { HeadlessProjectService } from "./headless-projects.js";
|
|
11
|
+
import { FfmpegMediaMetadataProbe, FfmpegRenderVerifier, FfmpegTimelineRenderer } from "../../../adapters/headless/typescript/src/index.js";
|
|
10
12
|
const fixture = new InMemoryEditorAdapter({
|
|
11
13
|
projectId: "project-1",
|
|
12
14
|
projectName: "Phase 2 Fixture",
|
|
@@ -90,6 +92,9 @@ const canonicalNativeMutationEditor = canonicalNativeProviderEnabled
|
|
|
90
92
|
nativeOperationLease,
|
|
91
93
|
})
|
|
92
94
|
: nativeEditor;
|
|
95
|
+
const canonicalNativeTargetResolver = canonicalNativeProviderEnabled
|
|
96
|
+
? createFinalCutNativeTargetResolver(nativeEditor)
|
|
97
|
+
: undefined;
|
|
93
98
|
const canonicalNativeProvider = canonicalNativeProviderEnabled
|
|
94
99
|
? new FinalCutCanonicalNativeProvider({
|
|
95
100
|
live: liveAdapter,
|
|
@@ -131,7 +136,7 @@ const canonicalNativeProvider = canonicalNativeProviderEnabled
|
|
|
131
136
|
target: { projectId, projectUid: projectId, sequenceId },
|
|
132
137
|
}).readSnapshot();
|
|
133
138
|
},
|
|
134
|
-
resolveTarget:
|
|
139
|
+
resolveTarget: canonicalNativeTargetResolver,
|
|
135
140
|
backgroundCatalog: backgroundLibraryProvider,
|
|
136
141
|
})
|
|
137
142
|
: undefined;
|
|
@@ -159,6 +164,7 @@ const editor = liveMode
|
|
|
159
164
|
: {}),
|
|
160
165
|
})
|
|
161
166
|
: fixture;
|
|
167
|
+
const framekitStateDirectory = process.env.FRAMEKIT_STATE_DIR ?? join(homedir(), ".framekit");
|
|
162
168
|
const analyzers = liveMode
|
|
163
169
|
? createCommandAnalyzers({
|
|
164
170
|
speechCommand: process.env.FRAMEKIT_SPEECH_ANALYZER,
|
|
@@ -175,14 +181,28 @@ const analyzers = liveMode
|
|
|
175
181
|
visualAnalyzer: new FixtureVisualAnalyzer(),
|
|
176
182
|
metadataAnalyzer: new FixtureMetadataAnalyzer(),
|
|
177
183
|
};
|
|
178
|
-
const runtime = new AgentVideoRuntime(editor,
|
|
179
|
-
|
|
184
|
+
const runtime = new AgentVideoRuntime(editor, {
|
|
185
|
+
...analyzers,
|
|
186
|
+
semanticMediaIndexStore: new JsonSemanticMediaIndexStore(join(framekitStateDirectory, "semantic-media-index.json")),
|
|
187
|
+
});
|
|
188
|
+
const headlessProjects = new HeadlessProjectService({
|
|
189
|
+
directory: join(framekitStateDirectory, "projects"),
|
|
190
|
+
mediaProbe: new FfmpegMediaMetadataProbe(),
|
|
191
|
+
renderer: new FfmpegTimelineRenderer(),
|
|
192
|
+
verifier: new FfmpegRenderVerifier(),
|
|
193
|
+
});
|
|
180
194
|
const sqliteObservationProvider = new FinalCutSqliteInspectionProvider();
|
|
181
195
|
const disposableNative = liveMode && !headlessFinalCut && !fcpxmlPath && nativeEditor
|
|
182
196
|
? new DisposableNativeEditWorkflow({
|
|
183
197
|
native: nativeEditor,
|
|
184
198
|
readCanonicalSnapshot: () => runtime.inspectProject(),
|
|
185
199
|
readCanonicalCapabilities: async () => (await runtime.inspectEditor()).capabilities,
|
|
200
|
+
...(nativeEditor ? {
|
|
201
|
+
prepareTarget: async (target, snapshot) => {
|
|
202
|
+
const occurrenceIndex = snapshot.timeline.clips.findIndex((clip) => clip.id === target.id) + 1;
|
|
203
|
+
await nativeEditor.selectCanonicalOccurrence(target.name, occurrenceIndex);
|
|
204
|
+
},
|
|
205
|
+
} : {}),
|
|
186
206
|
})
|
|
187
207
|
: undefined;
|
|
188
208
|
const nativeOperationSession = disposableNative && nativeEditor
|
|
@@ -192,6 +212,9 @@ const projectPublisher = liveMode && fcpxmlPath
|
|
|
192
212
|
? new FinalCutProjectPublisher({
|
|
193
213
|
enabled: !headlessFinalCut && process.env.FRAMEKIT_FINAL_CUT_NATIVE_WRITES === "1",
|
|
194
214
|
sourcePath: fcpxmlPath,
|
|
215
|
+
documentDelivery: liveAdapter,
|
|
216
|
+
targetLibraryUid: process.env.FRAMEKIT_FINAL_CUT_LIBRARY_UID,
|
|
217
|
+
allowHeadedFallback: process.env.FRAMEKIT_FINAL_CUT_ALLOW_HEADED_IMPORT === "1",
|
|
195
218
|
liveState: () => liveAdapter.readLiveState(),
|
|
196
219
|
})
|
|
197
220
|
: undefined;
|
|
@@ -225,6 +248,7 @@ const server = createMcpServer(runtime, {
|
|
|
225
248
|
sessionChangeSource: createCanonicalSessionChangeSource(() => runtime.inspectProject()),
|
|
226
249
|
materializationDirectory: join(framekitStateDirectory, "materializations"),
|
|
227
250
|
sqliteObservationProvider,
|
|
251
|
+
headlessProjects,
|
|
228
252
|
});
|
|
229
253
|
const transport = new StdioServerTransport();
|
|
230
254
|
let shuttingDown = false;
|