@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,263 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import { readFile as readFileCallback, stat as statCallback } from "node:fs";
|
|
3
|
+
import { promisify } from "node:util";
|
|
4
|
+
import { normalizeFastTimelineObservation, } from "../../../../packages/runtime/src/index.js";
|
|
5
|
+
import { FinalCutSqliteInspectionProvider, } from "./sqlite-inspection.js";
|
|
6
|
+
const readFile = promisify(readFileCallback);
|
|
7
|
+
const stat = promisify(statCallback);
|
|
8
|
+
export const FINAL_CUT_SQLITE_WAL_BACKEND = "final-cut-sqlite-wal-read-only";
|
|
9
|
+
export const FINAL_CUT_SQLITE_WAL_SCHEMA_VERSION = 1;
|
|
10
|
+
/** Read-only DB/WAL/SHM observation. This provider never opens a writable SQLite handle. */
|
|
11
|
+
export class FinalCutSqliteWalObservationProvider {
|
|
12
|
+
inspectionProvider;
|
|
13
|
+
readFile;
|
|
14
|
+
statFile;
|
|
15
|
+
timestamp;
|
|
16
|
+
constructor(options = {}) {
|
|
17
|
+
this.inspectionProvider = options.inspectionProvider ?? new FinalCutSqliteInspectionProvider();
|
|
18
|
+
this.readFile = options.readFile ?? (async (path) => readFile(path));
|
|
19
|
+
this.statFile = options.statFile ?? (async (path) => {
|
|
20
|
+
const result = await stat(path);
|
|
21
|
+
return { size: result.size, mtimeMs: result.mtimeMs };
|
|
22
|
+
});
|
|
23
|
+
this.timestamp = options.timestamp ?? (() => new Date().toISOString());
|
|
24
|
+
}
|
|
25
|
+
async capture(request) {
|
|
26
|
+
try {
|
|
27
|
+
const target = parseTarget(request.target);
|
|
28
|
+
const provenance = parseProvenance(request.provenance, target);
|
|
29
|
+
const finalCutVersion = nonEmpty(request.finalCutVersion, "finalCutVersion");
|
|
30
|
+
const databasePath = nonEmpty(request.databasePath, "databasePath");
|
|
31
|
+
const inspection = await this.inspectionProvider.inspect(databasePath);
|
|
32
|
+
if (inspection.status !== "partial")
|
|
33
|
+
return inspectionFailure(inspection);
|
|
34
|
+
const storage = await Promise.all([
|
|
35
|
+
this.fingerprint(databasePath, true),
|
|
36
|
+
this.fingerprint(request.walPath ?? `${databasePath}-wal`, false),
|
|
37
|
+
this.fingerprint(request.shmPath ?? `${databasePath}-shm`, false),
|
|
38
|
+
]);
|
|
39
|
+
const observation = {
|
|
40
|
+
schemaVersion: FINAL_CUT_SQLITE_WAL_SCHEMA_VERSION,
|
|
41
|
+
backend: FINAL_CUT_SQLITE_WAL_BACKEND,
|
|
42
|
+
canonical: false,
|
|
43
|
+
target,
|
|
44
|
+
provenance,
|
|
45
|
+
finalCutVersion,
|
|
46
|
+
database: inspection.observation,
|
|
47
|
+
storage: {
|
|
48
|
+
database: storage[0],
|
|
49
|
+
wal: storage[1],
|
|
50
|
+
shm: storage[2],
|
|
51
|
+
capturedAt: this.timestamp(),
|
|
52
|
+
freshness: "storage-observed",
|
|
53
|
+
},
|
|
54
|
+
coverage: {
|
|
55
|
+
storage: "observed",
|
|
56
|
+
structuralRows: "partial",
|
|
57
|
+
archivedPayloads: "opaque",
|
|
58
|
+
semanticOperation: "not-observable",
|
|
59
|
+
editorFreshness: "unknown",
|
|
60
|
+
canonicalTimeline: "unavailable",
|
|
61
|
+
},
|
|
62
|
+
};
|
|
63
|
+
return {
|
|
64
|
+
status: "observed",
|
|
65
|
+
observation,
|
|
66
|
+
issues: [
|
|
67
|
+
"SQLite/WAL/SHM state proves storage observation only; it does not prove the latest in-memory Final Cut edit was flushed.",
|
|
68
|
+
"Undocumented archived payloads remain opaque and are not promoted to Timeline IR or canonicalDocument.read.",
|
|
69
|
+
],
|
|
70
|
+
};
|
|
71
|
+
}
|
|
72
|
+
catch (error) {
|
|
73
|
+
return { status: "unavailable", error: unavailable(error) };
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
async fingerprint(path, required) {
|
|
77
|
+
try {
|
|
78
|
+
const [bytes, metadata] = await Promise.all([this.readFile(path), this.statFile(path)]);
|
|
79
|
+
return {
|
|
80
|
+
path,
|
|
81
|
+
present: true,
|
|
82
|
+
bytes: metadata.size,
|
|
83
|
+
digest: createHash("sha256").update(bytes).digest("hex"),
|
|
84
|
+
modifiedAt: new Date(metadata.mtimeMs).toISOString(),
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
catch (error) {
|
|
88
|
+
if (!required && isMissingFile(error))
|
|
89
|
+
return { path, present: false };
|
|
90
|
+
throw new Error(`FINAL_CUT_SQLITE_STORAGE_UNAVAILABLE: ${path}: ${error instanceof Error ? error.message : String(error)}`);
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
export function diffFinalCutSqliteWalObservations(previous, current) {
|
|
95
|
+
const reasons = [];
|
|
96
|
+
const targetMatches = sameTarget(previous.target, current.target)
|
|
97
|
+
&& sameTarget(previous.provenance.target, current.provenance.target);
|
|
98
|
+
if (!targetMatches)
|
|
99
|
+
reasons.push("target identity changed between SQLite observations");
|
|
100
|
+
const provenanceMatches = sameRevision(previous.provenance.framekitRevision, current.provenance.framekitRevision)
|
|
101
|
+
&& previous.provenance.artifactDigest === current.provenance.artifactDigest;
|
|
102
|
+
if (!provenanceMatches)
|
|
103
|
+
reasons.push("Framekit materialization provenance changed between SQLite observations");
|
|
104
|
+
if (previous.finalCutVersion !== current.finalCutVersion)
|
|
105
|
+
reasons.push("Final Cut version changed");
|
|
106
|
+
if (previous.database.schemaVersion !== current.database.schemaVersion)
|
|
107
|
+
reasons.push("SQLite schema version changed");
|
|
108
|
+
if (previous.database.sourcePath !== current.database.sourcePath)
|
|
109
|
+
reasons.push("SQLite source path changed");
|
|
110
|
+
const collections = diffRows(previous.database.collectionRows, current.database.collectionRows);
|
|
111
|
+
const metadata = diffRows(previous.database.metadataRows, current.database.metadataRows);
|
|
112
|
+
if (collections.added.length || collections.removed.length || collections.modified.length)
|
|
113
|
+
reasons.push("structural collection rows changed");
|
|
114
|
+
if (metadata.added.length || metadata.removed.length || metadata.modified.length)
|
|
115
|
+
reasons.push("metadata rows changed");
|
|
116
|
+
const storage = {
|
|
117
|
+
database: fingerprintChange(previous.storage.database, current.storage.database),
|
|
118
|
+
wal: optionalFingerprintChange(previous.storage.wal, current.storage.wal),
|
|
119
|
+
shm: optionalFingerprintChange(previous.storage.shm, current.storage.shm),
|
|
120
|
+
};
|
|
121
|
+
if (storage.database === "changed")
|
|
122
|
+
reasons.push("SQLite database bytes changed");
|
|
123
|
+
if (storage.wal === "changed")
|
|
124
|
+
reasons.push("SQLite WAL bytes changed");
|
|
125
|
+
if (storage.shm === "changed")
|
|
126
|
+
reasons.push("SQLite SHM bytes changed");
|
|
127
|
+
const changed = reasons.length > 0;
|
|
128
|
+
const ambiguous = !targetMatches || !provenanceMatches || previous.finalCutVersion !== current.finalCutVersion;
|
|
129
|
+
return {
|
|
130
|
+
schemaVersion: FINAL_CUT_SQLITE_WAL_SCHEMA_VERSION,
|
|
131
|
+
status: ambiguous ? "ambiguous" : changed ? "changed" : "unchanged",
|
|
132
|
+
canonical: false,
|
|
133
|
+
target: current.target,
|
|
134
|
+
from: { revision: previous.database.revision, storage: previous.storage },
|
|
135
|
+
to: { revision: current.database.revision, storage: current.storage },
|
|
136
|
+
collections,
|
|
137
|
+
metadata,
|
|
138
|
+
storage,
|
|
139
|
+
coverage: {
|
|
140
|
+
...current.coverage,
|
|
141
|
+
semanticOperation: ambiguous || changed ? "ambiguous" : "not-observable",
|
|
142
|
+
},
|
|
143
|
+
recommendation: changed || ambiguous ? "canonical-resync-required" : "no-change-observed",
|
|
144
|
+
reasons: reasons.length > 0 ? reasons : ["no SQLite/WAL/SHM change observed"],
|
|
145
|
+
};
|
|
146
|
+
}
|
|
147
|
+
/** Convert SQLite/WAL evidence into the provider-neutral envelope without inventing Timeline IR. */
|
|
148
|
+
export function normalizeFinalCutSqliteWalObservation(observation) {
|
|
149
|
+
return normalizeFastTimelineObservation({
|
|
150
|
+
schemaVersion: 1,
|
|
151
|
+
provider: "final-cut",
|
|
152
|
+
sourceType: "sqlite-wal",
|
|
153
|
+
canonical: false,
|
|
154
|
+
target: structuredClone(observation.target),
|
|
155
|
+
provenance: structuredClone(observation.provenance),
|
|
156
|
+
observedAt: observation.storage.capturedAt,
|
|
157
|
+
trust: "structural",
|
|
158
|
+
freshness: "storage-observed",
|
|
159
|
+
revision: structuredClone(observation.database.revision),
|
|
160
|
+
observationDigest: observation.database.digest,
|
|
161
|
+
coverage: {
|
|
162
|
+
occurrences: "partial",
|
|
163
|
+
resources: "partial",
|
|
164
|
+
timing: "unknown",
|
|
165
|
+
roles: "unknown",
|
|
166
|
+
storylineRelationships: "unknown",
|
|
167
|
+
markersCaptions: "unknown",
|
|
168
|
+
},
|
|
169
|
+
unknowns: [
|
|
170
|
+
"timeline.semanticOperation",
|
|
171
|
+
"timeline.editorFreshness",
|
|
172
|
+
"timeline.canonicalTimeline",
|
|
173
|
+
"archivedPayloads",
|
|
174
|
+
],
|
|
175
|
+
});
|
|
176
|
+
}
|
|
177
|
+
/** The initial safe matrix intentionally exposes no unproven semantic mappings. */
|
|
178
|
+
const FINAL_CUT_SQLITE_CONTROLLED_OPERATIONS = [
|
|
179
|
+
"trim-start", "trim-end", "move", "delete", "reorder", "add-existing-source",
|
|
180
|
+
"repeated-occurrence", "connected-clip", "marker", "project-rename",
|
|
181
|
+
];
|
|
182
|
+
export const FINAL_CUT_SQLITE_OPERATION_MATRIX = [
|
|
183
|
+
...FINAL_CUT_SQLITE_CONTROLLED_OPERATIONS,
|
|
184
|
+
].map((operation) => ({
|
|
185
|
+
operation,
|
|
186
|
+
coverage: "not-observable",
|
|
187
|
+
evidence: "fixture-matrix",
|
|
188
|
+
canonical: false,
|
|
189
|
+
reason: "No target-version repeated native before/after corpus has proven a semantic SQLite/WAL mapping",
|
|
190
|
+
}));
|
|
191
|
+
function diffRows(before, after) {
|
|
192
|
+
const beforeMap = new Map(before.map((row) => [row.primaryKey, row]));
|
|
193
|
+
const afterMap = new Map(after.map((row) => [row.primaryKey, row]));
|
|
194
|
+
const added = [];
|
|
195
|
+
const removed = [];
|
|
196
|
+
const modified = [];
|
|
197
|
+
for (const [key, row] of afterMap) {
|
|
198
|
+
const old = beforeMap.get(key);
|
|
199
|
+
if (!old)
|
|
200
|
+
added.push(row);
|
|
201
|
+
else if (JSON.stringify(old) !== JSON.stringify(row))
|
|
202
|
+
modified.push({ before: old, after: row });
|
|
203
|
+
}
|
|
204
|
+
for (const [key, row] of beforeMap)
|
|
205
|
+
if (!afterMap.has(key))
|
|
206
|
+
removed.push(row);
|
|
207
|
+
return { added, removed, modified };
|
|
208
|
+
}
|
|
209
|
+
function fingerprintChange(before, after) {
|
|
210
|
+
return before.present === after.present && before.digest === after.digest ? "unchanged" : "changed";
|
|
211
|
+
}
|
|
212
|
+
function optionalFingerprintChange(before, after) {
|
|
213
|
+
if (!before.present && !after.present)
|
|
214
|
+
return "absent";
|
|
215
|
+
return fingerprintChange(before, after);
|
|
216
|
+
}
|
|
217
|
+
function parseTarget(value) {
|
|
218
|
+
return {
|
|
219
|
+
projectId: nonEmpty(value?.projectId, "target.projectId"),
|
|
220
|
+
sequenceId: nonEmpty(value?.sequenceId, "target.sequenceId"),
|
|
221
|
+
};
|
|
222
|
+
}
|
|
223
|
+
function parseProvenance(value, target) {
|
|
224
|
+
const artifactDigest = nonEmpty(value?.artifactDigest, "provenance.artifactDigest");
|
|
225
|
+
if (!value?.framekitRevision || typeof value.framekitRevision.id !== "string"
|
|
226
|
+
|| !Number.isSafeInteger(value.framekitRevision.sequence) || typeof value.framekitRevision.timestamp !== "string") {
|
|
227
|
+
throw new Error("FINAL_CUT_SQLITE_PROVENANCE_INVALID: framekit revision is incomplete");
|
|
228
|
+
}
|
|
229
|
+
const provenanceTarget = parseTarget(value.target);
|
|
230
|
+
if (!sameTarget(target, provenanceTarget)) {
|
|
231
|
+
throw new Error("FINAL_CUT_SQLITE_TARGET_MISMATCH: capture target and provenance target differ");
|
|
232
|
+
}
|
|
233
|
+
return {
|
|
234
|
+
framekitRevision: { ...value.framekitRevision },
|
|
235
|
+
artifactDigest,
|
|
236
|
+
target: provenanceTarget,
|
|
237
|
+
};
|
|
238
|
+
}
|
|
239
|
+
function inspectionFailure(inspection) {
|
|
240
|
+
return { status: inspection.status, error: inspection.error };
|
|
241
|
+
}
|
|
242
|
+
function unavailable(error) {
|
|
243
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
244
|
+
return {
|
|
245
|
+
code: "FINAL_CUT_SQLITE_WAL_UNAVAILABLE",
|
|
246
|
+
message,
|
|
247
|
+
retryable: /busy|locked|timed out|timeout|temporar|unavailable/i.test(message),
|
|
248
|
+
};
|
|
249
|
+
}
|
|
250
|
+
function isMissingFile(error) {
|
|
251
|
+
return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
|
|
252
|
+
}
|
|
253
|
+
function nonEmpty(value, name) {
|
|
254
|
+
if (typeof value !== "string" || !value.trim())
|
|
255
|
+
throw new Error(`FINAL_CUT_SQLITE_INPUT_INVALID: ${name} is required`);
|
|
256
|
+
return value.trim();
|
|
257
|
+
}
|
|
258
|
+
function sameTarget(left, right) {
|
|
259
|
+
return left.projectId === right.projectId && left.sequenceId === right.sequenceId;
|
|
260
|
+
}
|
|
261
|
+
function sameRevision(left, right) {
|
|
262
|
+
return left.id === right.id && left.sequence === right.sequence && left.timestamp === right.timestamp;
|
|
263
|
+
}
|
|
@@ -3,6 +3,8 @@ import { isAbsolute } from "node:path";
|
|
|
3
3
|
import { pathToFileURL } from "node:url";
|
|
4
4
|
import { timelineIrDigest, validateTimelineIr } from "../../../../packages/runtime/src/index.js";
|
|
5
5
|
export const FRAMEKIT_FCPXML_VERSION = "1.11";
|
|
6
|
+
const BASIC_TITLE_EFFECT_ID = "effect-basic-title";
|
|
7
|
+
const BASIC_TITLE_EFFECT_UID = ".../Titles.localized/Bumper:Opener.localized/Basic Title.localized/Basic Title.moti";
|
|
6
8
|
/**
|
|
7
9
|
* Compiles a complete provider-neutral Timeline IR into a new FCPXML
|
|
8
10
|
* document. The target binding is mandatory because names are not stable
|
|
@@ -15,6 +17,10 @@ export function compileTimelineIrToFcpxml(timeline, options) {
|
|
|
15
17
|
throw new Error(`FCPXML_VERSION_UNSUPPORTED: ${String(version)}`);
|
|
16
18
|
}
|
|
17
19
|
validateTarget(options.target);
|
|
20
|
+
const unsupported = unsupportedFeatures(timeline);
|
|
21
|
+
if (unsupported.length > 0) {
|
|
22
|
+
throw new Error(`FCPXML_UNSUPPORTED_TIMELINE_FEATURE: ${unsupported.join(", ")}`);
|
|
23
|
+
}
|
|
18
24
|
const destination = resolveDestination(timeline, options.target);
|
|
19
25
|
const resourceIds = createResourceIds(timeline);
|
|
20
26
|
const resourceNames = uniqueResourceNames(timeline);
|
|
@@ -37,6 +43,9 @@ export function compileTimelineIrToFcpxml(timeline, options) {
|
|
|
37
43
|
`<fcpxml version="${FRAMEKIT_FCPXML_VERSION}">`,
|
|
38
44
|
" <resources>",
|
|
39
45
|
` <format id="${formatId}" frameDuration="${formatRational(timeline.sequence.frameDuration, "sequence.frameDuration")}" />`,
|
|
46
|
+
...(timeline.sequence.titles?.length
|
|
47
|
+
? [` <effect id="${BASIC_TITLE_EFFECT_ID}" name="Basic Title" uid="${BASIC_TITLE_EFFECT_UID}" />`]
|
|
48
|
+
: []),
|
|
40
49
|
...resources.map((resource) => renderResource(resource, resourceIds.get(resource.id), resourceNames.get(resource.id))),
|
|
41
50
|
" </resources>",
|
|
42
51
|
" <library>",
|
|
@@ -62,6 +71,7 @@ export function compileTimelineIrToFcpxml(timeline, options) {
|
|
|
62
71
|
"",
|
|
63
72
|
];
|
|
64
73
|
const xml = lines.join("\n");
|
|
74
|
+
const timelineDigest = timelineIrDigest(timeline);
|
|
65
75
|
return {
|
|
66
76
|
format: "fcpxml",
|
|
67
77
|
version: FRAMEKIT_FCPXML_VERSION,
|
|
@@ -70,8 +80,77 @@ export function compileTimelineIrToFcpxml(timeline, options) {
|
|
|
70
80
|
target: structuredClone(options.target),
|
|
71
81
|
destination,
|
|
72
82
|
resourceIds: Object.fromEntries([...resourceIds.entries()].sort(([left], [right]) => left.localeCompare(right))),
|
|
83
|
+
coverage: materializationCoverage(timeline, destination.mode, elements),
|
|
84
|
+
provenance: {
|
|
85
|
+
source: "framekit-timeline-ir",
|
|
86
|
+
schemaVersion: 1,
|
|
87
|
+
projectId: timeline.project.id,
|
|
88
|
+
sequenceId: timeline.sequence.id,
|
|
89
|
+
revision: structuredClone(timeline.revision),
|
|
90
|
+
timelineDigest,
|
|
91
|
+
target: {
|
|
92
|
+
libraryUid: options.target.libraryUid,
|
|
93
|
+
eventUid: options.target.eventUid,
|
|
94
|
+
projectUid: options.target.projectUid,
|
|
95
|
+
sequenceUid: options.target.sequenceUid,
|
|
96
|
+
},
|
|
97
|
+
destination: {
|
|
98
|
+
projectUid: destination.projectUid,
|
|
99
|
+
sequenceUid: destination.sequenceUid,
|
|
100
|
+
},
|
|
101
|
+
},
|
|
73
102
|
};
|
|
74
103
|
}
|
|
104
|
+
function unsupportedFeatures(timeline) {
|
|
105
|
+
const unsupported = new Set();
|
|
106
|
+
if (timeline.sequence.titles?.some(({ style, position }) => style !== undefined || position !== undefined)) {
|
|
107
|
+
unsupported.add("styled-or-positioned-titles");
|
|
108
|
+
}
|
|
109
|
+
if (timeline.sequence.transitions?.length)
|
|
110
|
+
unsupported.add("transitions");
|
|
111
|
+
for (const occurrence of timeline.sequence.occurrences) {
|
|
112
|
+
if (occurrence.transform !== undefined)
|
|
113
|
+
unsupported.add("transforms");
|
|
114
|
+
if (occurrence.fadeIn !== undefined || occurrence.fadeOut !== undefined)
|
|
115
|
+
unsupported.add("audio-fades");
|
|
116
|
+
if (occurrence.role === "title")
|
|
117
|
+
unsupported.add("title-occurrences");
|
|
118
|
+
}
|
|
119
|
+
for (const element of timeline.sequence.storyElements) {
|
|
120
|
+
if (element.kind !== "gap")
|
|
121
|
+
unsupported.add(`story-element:${element.kind}`);
|
|
122
|
+
}
|
|
123
|
+
return [...unsupported].sort((left, right) => left.localeCompare(right));
|
|
124
|
+
}
|
|
125
|
+
function materializationCoverage(timeline, destinationMode, elements) {
|
|
126
|
+
const exact = new Set([
|
|
127
|
+
"artifact",
|
|
128
|
+
"project",
|
|
129
|
+
"sequence",
|
|
130
|
+
"resources",
|
|
131
|
+
"source-ranges",
|
|
132
|
+
"primary-storyline-order",
|
|
133
|
+
"provenance",
|
|
134
|
+
]);
|
|
135
|
+
if (elements.some(({ parentId }) => parentId !== undefined))
|
|
136
|
+
exact.add("connected-elements");
|
|
137
|
+
if (timeline.sequence.occurrences.some(({ role }) => role !== undefined))
|
|
138
|
+
exact.add("roles");
|
|
139
|
+
if (timeline.sequence.occurrences.some(({ gainDb }) => gainDb !== undefined))
|
|
140
|
+
exact.add("gain");
|
|
141
|
+
if (timeline.sequence.occurrences.some(({ enabled }) => enabled !== undefined))
|
|
142
|
+
exact.add("enabled");
|
|
143
|
+
if (timeline.sequence.titles?.length) {
|
|
144
|
+
exact.add("editable-titles");
|
|
145
|
+
}
|
|
146
|
+
if (destinationMode === "versioned")
|
|
147
|
+
exact.add("versioned-destination");
|
|
148
|
+
if (timeline.sequence.markers.length > 0)
|
|
149
|
+
exact.add("markers");
|
|
150
|
+
if (timeline.sequence.captions.length > 0)
|
|
151
|
+
exact.add("captions");
|
|
152
|
+
return { exact: [...exact].sort(), degraded: [], unsupported: [] };
|
|
153
|
+
}
|
|
75
154
|
function validateTarget(target) {
|
|
76
155
|
if (!target || target.provider !== "final-cut")
|
|
77
156
|
throw new Error("FCPXML_TARGET_BINDING_INVALID: provider must be final-cut");
|
|
@@ -95,13 +174,14 @@ function resolveDestination(timeline, target) {
|
|
|
95
174
|
sequenceName: timeline.sequence.name,
|
|
96
175
|
};
|
|
97
176
|
}
|
|
98
|
-
const revisionKey = shortHash(`${timeline.project.id}:${timeline.sequence.id}:${timelineIrDigest(timeline)}`);
|
|
177
|
+
const revisionKey = shortHash(`${timeline.project.id}:${timeline.sequence.id}:${timeline.revision.id}:${timeline.revision.sequence}:${timeline.revision.timestamp}:${timelineIrDigest(timeline)}`);
|
|
178
|
+
const revisionName = `${safeId(timeline.revision.id)}-${timeline.revision.sequence}`;
|
|
99
179
|
return {
|
|
100
180
|
mode: "versioned",
|
|
101
181
|
projectUid: `${safeId(target.projectUid)}-framekit-${revisionKey}`,
|
|
102
182
|
sequenceUid: `${safeId(target.sequenceUid)}-framekit-${revisionKey}`,
|
|
103
|
-
projectName: `${timeline.project.name} (Framekit ${revisionKey})`,
|
|
104
|
-
sequenceName: `${timeline.sequence.name} (Framekit ${revisionKey})`,
|
|
183
|
+
projectName: `${timeline.project.name} (Framekit ${revisionName}-${revisionKey})`,
|
|
184
|
+
sequenceName: `${timeline.sequence.name} (Framekit ${revisionName}-${revisionKey})`,
|
|
105
185
|
};
|
|
106
186
|
}
|
|
107
187
|
function createResourceIds(timeline) {
|
|
@@ -147,10 +227,13 @@ function renderResource(resource, id, name) {
|
|
|
147
227
|
catch (error) {
|
|
148
228
|
throw new Error(`FCPXML_RESOURCE_SOURCE_UNSUPPORTED: resource ${resource.id} has an invalid file URL: ${error instanceof Error ? error.message : String(error)}`);
|
|
149
229
|
}
|
|
150
|
-
const
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
230
|
+
const videoAttribute = resource.mediaKind === "video" ? ' hasVideo="1"' : ' hasVideo="0"';
|
|
231
|
+
const audioAttribute = resource.mediaKind === "audio"
|
|
232
|
+
? ' hasAudio="1"'
|
|
233
|
+
: resource.metadata?.streams
|
|
234
|
+
? ` hasAudio="${resource.metadata.streams.some((stream) => stream.kind === "audio") ? "1" : "0"}"`
|
|
235
|
+
: "";
|
|
236
|
+
return ` <asset id="${xmlEscape(id)}" name="${xmlEscape(name)}" src="${xmlEscape(src)}"${videoAttribute}${audioAttribute} />`;
|
|
154
237
|
}
|
|
155
238
|
function renderableElements(timeline, resourceIds) {
|
|
156
239
|
const occurrenceIds = new Set(timeline.sequence.occurrences.map(({ id }) => id));
|
|
@@ -172,8 +255,35 @@ function renderableElements(timeline, resourceIds) {
|
|
|
172
255
|
...(element.attachedTo !== undefined ? { parentId: element.attachedTo } : {}),
|
|
173
256
|
});
|
|
174
257
|
}
|
|
258
|
+
for (const title of timeline.sequence.titles ?? []) {
|
|
259
|
+
elements.push(renderableTitle(title, timeline));
|
|
260
|
+
}
|
|
175
261
|
return elements;
|
|
176
262
|
}
|
|
263
|
+
function renderableTitle(title, timeline) {
|
|
264
|
+
const titleEnd = addExactTimes(title.startTime, title.durationTime);
|
|
265
|
+
const parent = timeline.sequence.occurrences.find((occurrence) => {
|
|
266
|
+
if (occurrence.track !== 0 || occurrence.role !== undefined && occurrence.role !== "video")
|
|
267
|
+
return false;
|
|
268
|
+
const occurrenceEnd = addExactTimes(occurrence.startTime, occurrence.durationTime);
|
|
269
|
+
return compareExactTimes(title.startTime, occurrence.startTime) >= 0
|
|
270
|
+
&& compareExactTimes(titleEnd, occurrenceEnd) <= 0;
|
|
271
|
+
});
|
|
272
|
+
if (!parent) {
|
|
273
|
+
throw new Error(`FCPXML_TITLE_ANCHOR_NOT_FOUND: title ${title.id} must fit within one primary video occurrence`);
|
|
274
|
+
}
|
|
275
|
+
return {
|
|
276
|
+
id: title.id,
|
|
277
|
+
kind: "title",
|
|
278
|
+
startTime: title.startTime,
|
|
279
|
+
durationTime: title.durationTime,
|
|
280
|
+
lane: title.lane,
|
|
281
|
+
parentId: parent.id,
|
|
282
|
+
name: title.id,
|
|
283
|
+
resourceId: BASIC_TITLE_EFFECT_ID,
|
|
284
|
+
text: title.text,
|
|
285
|
+
};
|
|
286
|
+
}
|
|
177
287
|
function renderOccurrence(occurrence, timeline, resourceIds, occurrenceIds) {
|
|
178
288
|
if (occurrence.role === "title")
|
|
179
289
|
throw new Error("FCPXML_UNSUPPORTED_OCCURRENCE_ROLE: title");
|
|
@@ -193,13 +303,14 @@ function renderOccurrence(occurrence, timeline, resourceIds, occurrenceIds) {
|
|
|
193
303
|
if (occurrence.attachedTo !== undefined && !occurrenceIds.has(occurrence.attachedTo)) {
|
|
194
304
|
throw new Error(`FCPXML_ATTACHMENT_TARGET_NOT_FOUND: ${occurrence.id} -> ${occurrence.attachedTo}`);
|
|
195
305
|
}
|
|
306
|
+
const parentId = occurrence.attachedTo ?? musicAttachmentTarget(occurrence, timeline);
|
|
196
307
|
return {
|
|
197
308
|
id: occurrence.id,
|
|
198
309
|
kind: "asset-clip",
|
|
199
310
|
startTime: occurrence.startTime,
|
|
200
311
|
durationTime: occurrence.durationTime,
|
|
201
312
|
...(occurrence.track > 0 ? { lane: occurrence.track } : {}),
|
|
202
|
-
...(
|
|
313
|
+
...(parentId !== undefined ? { parentId } : {}),
|
|
203
314
|
name: occurrence.name,
|
|
204
315
|
resourceId: resource,
|
|
205
316
|
...(occurrence.sourceStartTime ? { sourceStartTime: occurrence.sourceStartTime } : {}),
|
|
@@ -208,6 +319,19 @@ function renderOccurrence(occurrence, timeline, resourceIds, occurrenceIds) {
|
|
|
208
319
|
...(occurrence.enabled !== undefined ? { enabled: occurrence.enabled } : {}),
|
|
209
320
|
};
|
|
210
321
|
}
|
|
322
|
+
function musicAttachmentTarget(occurrence, timeline) {
|
|
323
|
+
if (occurrence.role !== "music" || occurrence.track <= 0)
|
|
324
|
+
return undefined;
|
|
325
|
+
const parent = timeline.sequence.occurrences
|
|
326
|
+
.filter((candidate) => candidate.track === 0
|
|
327
|
+
&& candidate.role === "video"
|
|
328
|
+
&& compareExactTimes(candidate.startTime, occurrence.startTime) <= 0)
|
|
329
|
+
.sort((left, right) => compareExactTimes(right.startTime, left.startTime))[0];
|
|
330
|
+
if (!parent) {
|
|
331
|
+
throw new Error(`FCPXML_MUSIC_ANCHOR_NOT_FOUND: ${occurrence.id} must start at or after a primary video occurrence`);
|
|
332
|
+
}
|
|
333
|
+
return parent.id;
|
|
334
|
+
}
|
|
211
335
|
function renderElements(elements) {
|
|
212
336
|
const byParent = new Map();
|
|
213
337
|
const byId = new Map();
|
|
@@ -227,34 +351,52 @@ function renderElements(elements) {
|
|
|
227
351
|
throw new Error(`FCPXML_CYCLIC_ATTACHMENT: ${element.id}`);
|
|
228
352
|
rendered.add(element.id);
|
|
229
353
|
const children = byParent.get(element.id) ?? [];
|
|
354
|
+
const parentElement = element.parentId === undefined ? undefined : byId.get(element.parentId);
|
|
230
355
|
const parentStartTime = element.parentId === undefined
|
|
231
356
|
? { value: "0", timescale: "1" }
|
|
232
|
-
:
|
|
357
|
+
: parentElement?.startTime;
|
|
233
358
|
if (!parentStartTime)
|
|
234
359
|
throw new Error(`FCPXML_ATTACHMENT_TARGET_NOT_FOUND: ${element.id} -> ${element.parentId}`);
|
|
235
360
|
const localStartTime = subtractRational(element.startTime, parentStartTime, `${element.id}.startTime`);
|
|
361
|
+
const offsetTime = parentElement?.kind === "asset-clip"
|
|
362
|
+
&& (element.kind === "title" || element.role === "music")
|
|
363
|
+
&& parentElement.sourceStartTime !== undefined
|
|
364
|
+
? addExactTimes(localStartTime, parentElement.sourceStartTime)
|
|
365
|
+
: localStartTime;
|
|
236
366
|
const attributes = element.kind === "asset-clip"
|
|
237
367
|
? [
|
|
238
368
|
`id="${xmlEscape(element.id)}"`,
|
|
239
369
|
`ref="${xmlEscape(element.resourceId)}"`,
|
|
240
370
|
`name="${xmlEscape(element.name)}"`,
|
|
241
|
-
`offset="${formatRational(
|
|
371
|
+
`offset="${formatRational(offsetTime, `${element.id}.startTime`)}"`,
|
|
242
372
|
...(element.sourceStartTime ? [`start="${formatRational(element.sourceStartTime, `${element.id}.sourceStartTime`)}"`] : []),
|
|
243
373
|
`duration="${formatRational(element.durationTime, `${element.id}.durationTime`)}"`,
|
|
244
374
|
...(element.lane !== undefined ? [`lane="${String(element.lane)}"`] : []),
|
|
245
|
-
...(element.role ? [`
|
|
375
|
+
...(element.role ? [`audioRole="${element.role}"`] : []),
|
|
246
376
|
...(element.enabled !== undefined ? [`enabled="${element.enabled ? "1" : "0"}"`] : []),
|
|
247
377
|
]
|
|
248
|
-
:
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
378
|
+
: element.kind === "title"
|
|
379
|
+
? [
|
|
380
|
+
`id="${xmlEscape(element.id)}"`,
|
|
381
|
+
`ref="${xmlEscape(element.resourceId)}"`,
|
|
382
|
+
`name="${xmlEscape(element.name)}"`,
|
|
383
|
+
`offset="${formatRational(offsetTime, `${element.id}.startTime`)}"`,
|
|
384
|
+
`duration="${formatRational(element.durationTime, `${element.id}.durationTime`)}"`,
|
|
385
|
+
...(element.lane !== undefined ? [`lane="${String(element.lane)}"`] : []),
|
|
386
|
+
]
|
|
387
|
+
: [
|
|
388
|
+
`id="${xmlEscape(element.id)}"`,
|
|
389
|
+
`offset="${formatRational(offsetTime, `${element.id}.startTime`)}"`,
|
|
390
|
+
`duration="${formatRational(element.durationTime, `${element.id}.durationTime`)}"`,
|
|
391
|
+
...(element.lane !== undefined ? [`lane="${String(element.lane)}"`] : []),
|
|
392
|
+
];
|
|
254
393
|
const opening = `<${element.kind} ${attributes.join(" ")}>`;
|
|
255
|
-
const childLines =
|
|
256
|
-
|
|
257
|
-
|
|
394
|
+
const childLines = [
|
|
395
|
+
...(element.gainDb !== undefined
|
|
396
|
+
? [`${indent} <adjust-volume amount="${formatDb(element.gainDb, element.id)}" />`]
|
|
397
|
+
: []),
|
|
398
|
+
...(element.kind === "title" ? [`${indent} <text>${xmlEscape(element.text ?? "")}</text>`] : []),
|
|
399
|
+
];
|
|
258
400
|
const childStart = childLines.length > 0 ? childLines : [];
|
|
259
401
|
if (children.length === 0 && childStart.length === 0) {
|
|
260
402
|
lines.push(`${indent}<${element.kind} ${attributes.join(" ")} />`);
|
|
@@ -274,15 +416,27 @@ function renderElements(elements) {
|
|
|
274
416
|
return lines;
|
|
275
417
|
}
|
|
276
418
|
function compareTimedItems(left, right) {
|
|
277
|
-
const
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
if (difference !== 0n)
|
|
281
|
-
return difference < 0n ? -1 : 1;
|
|
419
|
+
const difference = compareExactTimes(left.startTime, right.startTime);
|
|
420
|
+
if (difference !== 0)
|
|
421
|
+
return difference;
|
|
282
422
|
if ((left.lane ?? 0) !== (right.lane ?? 0))
|
|
283
423
|
return (left.lane ?? 0) - (right.lane ?? 0);
|
|
284
424
|
return left.id.localeCompare(right.id);
|
|
285
425
|
}
|
|
426
|
+
function addExactTimes(left, right) {
|
|
427
|
+
const leftValue = parseExactRational(left);
|
|
428
|
+
const rightValue = parseExactRational(right);
|
|
429
|
+
return {
|
|
430
|
+
value: (leftValue.value * rightValue.timescale + rightValue.value * leftValue.timescale).toString(),
|
|
431
|
+
timescale: (leftValue.timescale * rightValue.timescale).toString(),
|
|
432
|
+
};
|
|
433
|
+
}
|
|
434
|
+
function compareExactTimes(left, right) {
|
|
435
|
+
const leftTime = parseExactRational(left);
|
|
436
|
+
const rightTime = parseExactRational(right);
|
|
437
|
+
const difference = leftTime.value * rightTime.timescale - rightTime.value * leftTime.timescale;
|
|
438
|
+
return difference === 0n ? 0 : difference < 0n ? -1 : 1;
|
|
439
|
+
}
|
|
286
440
|
function formatRational(value, field) {
|
|
287
441
|
const parsed = parseExactRational(value);
|
|
288
442
|
if (parsed.value < 0n)
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
import { execFile } from "node:child_process";
|
|
2
|
+
import { lstat } from "node:fs/promises";
|
|
3
|
+
import { promisify } from "node:util";
|
|
4
|
+
const execFileAsync = promisify(execFile);
|
|
5
|
+
export class FfmpegMediaMetadataProbe {
|
|
6
|
+
ffprobePath;
|
|
7
|
+
environment;
|
|
8
|
+
constructor(options = {}) {
|
|
9
|
+
this.ffprobePath = options.ffprobePath ?? process.env.FFPROBE_BIN ?? "ffprobe";
|
|
10
|
+
this.environment = { ...process.env, ...options.env };
|
|
11
|
+
}
|
|
12
|
+
async probe(sourcePath) {
|
|
13
|
+
const details = await lstat(sourcePath);
|
|
14
|
+
if (!details.isFile() || details.isSymbolicLink())
|
|
15
|
+
throw new Error(`HEADLESS_MEDIA_INVALID: source is not a regular file: ${sourcePath}`);
|
|
16
|
+
const result = await execFileAsync(this.ffprobePath, [
|
|
17
|
+
"-v", "error",
|
|
18
|
+
"-show_entries", "stream=codec_type,codec_name,width,height,r_frame_rate,sample_rate,channels",
|
|
19
|
+
"-show_entries", "format=duration",
|
|
20
|
+
"-of", "json",
|
|
21
|
+
sourcePath,
|
|
22
|
+
], { env: this.environment, maxBuffer: 2 * 1024 * 1024 });
|
|
23
|
+
const parsed = JSON.parse(result.stdout);
|
|
24
|
+
const duration = decimalToRational(Number(parsed.format?.duration));
|
|
25
|
+
if (!parsed.streams || !duration)
|
|
26
|
+
throw new Error("HEADLESS_MEDIA_INVALID: ffprobe returned incomplete metadata");
|
|
27
|
+
const streams = parsed.streams.flatMap((stream) => {
|
|
28
|
+
if (stream.codec_type !== "video" && stream.codec_type !== "audio")
|
|
29
|
+
return [];
|
|
30
|
+
return [{
|
|
31
|
+
kind: stream.codec_type,
|
|
32
|
+
...(stream.codec_name ? { codec: stream.codec_name } : {}),
|
|
33
|
+
...(stream.width !== undefined ? { width: stream.width } : {}),
|
|
34
|
+
...(stream.height !== undefined ? { height: stream.height } : {}),
|
|
35
|
+
...(stream.r_frame_rate ? { frameRate: parseRate(stream.r_frame_rate) } : {}),
|
|
36
|
+
...(stream.sample_rate ? { sampleRate: Number(stream.sample_rate) } : {}),
|
|
37
|
+
...(stream.channels !== undefined ? { channels: stream.channels } : {}),
|
|
38
|
+
}];
|
|
39
|
+
});
|
|
40
|
+
return { durationTime: duration, streams };
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
function parseRate(value) {
|
|
44
|
+
const [numerator, denominator] = value.split("/").map(BigInt);
|
|
45
|
+
const divisor = gcd(numerator, denominator);
|
|
46
|
+
return { value: String(numerator / divisor), timescale: String(denominator / divisor) };
|
|
47
|
+
}
|
|
48
|
+
function decimalToRational(value) {
|
|
49
|
+
if (!Number.isFinite(value) || value <= 0)
|
|
50
|
+
return undefined;
|
|
51
|
+
const scaled = Math.round(value * 1_000_000);
|
|
52
|
+
const divisor = gcd(BigInt(scaled), 1000000n);
|
|
53
|
+
return { value: String(BigInt(scaled) / divisor), timescale: String(1000000n / divisor) };
|
|
54
|
+
}
|
|
55
|
+
function gcd(left, right) {
|
|
56
|
+
while (right !== 0n) {
|
|
57
|
+
const remainder = left % right;
|
|
58
|
+
left = right;
|
|
59
|
+
right = remainder;
|
|
60
|
+
}
|
|
61
|
+
return left || 1n;
|
|
62
|
+
}
|