@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.
Files changed (36) 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/connection.js +8 -5
  4. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +36 -7
  5. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +21 -7
  6. package/dist-package/adapters/final-cut/typescript/src/index.js +2 -0
  7. package/dist-package/adapters/final-cut/typescript/src/live.js +56 -1
  8. package/dist-package/adapters/final-cut/typescript/src/native.js +311 -20
  9. package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.js +312 -0
  10. package/dist-package/adapters/final-cut/typescript/src/publisher.js +68 -8
  11. package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.js +263 -0
  12. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +179 -25
  13. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +62 -0
  14. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +551 -0
  15. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +181 -0
  16. package/dist-package/adapters/headless/typescript/src/index.js +3 -0
  17. package/dist-package/apps/mcp-server/src/headless-projects.js +370 -0
  18. package/dist-package/apps/mcp-server/src/headless-sessions.js +3 -0
  19. package/dist-package/apps/mcp-server/src/main.js +28 -4
  20. package/dist-package/apps/mcp-server/src/materialization-jobs.js +233 -4
  21. package/dist-package/apps/mcp-server/src/readback-policy.js +26 -0
  22. package/dist-package/apps/mcp-server/src/routing.js +134 -5
  23. package/dist-package/apps/mcp-server/src/server.js +311 -34
  24. package/dist-package/packages/runtime/src/application/local-media.js +157 -0
  25. package/dist-package/packages/runtime/src/application/media-analysis-service.js +347 -27
  26. package/dist-package/packages/runtime/src/application/project-store.js +234 -0
  27. package/dist-package/packages/runtime/src/application/project-transactions.js +227 -0
  28. package/dist-package/packages/runtime/src/application/semantic-media-index-store.js +86 -0
  29. package/dist-package/packages/runtime/src/index.js +7 -0
  30. package/dist-package/packages/runtime/src/planning/rough-cut.js +103 -7
  31. package/dist-package/packages/runtime/src/render/render-and-verify.js +126 -0
  32. package/dist-package/packages/runtime/src/render/render-contract.js +146 -0
  33. package/dist-package/packages/runtime/src/runtime.js +5 -2
  34. package/dist-package/packages/runtime/src/timeline/editing-session.js +277 -9
  35. package/dist-package/packages/runtime/src/timeline/fast-observation.js +141 -0
  36. 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 mediaAttributes = resource.mediaKind === "video"
151
- ? ' hasVideo="1" hasAudio="0"'
152
- : ' hasVideo="0" hasAudio="1"';
153
- return ` <asset id="${xmlEscape(id)}" name="${xmlEscape(name)}" src="${xmlEscape(src)}"${mediaAttributes} />`;
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
- ...(occurrence.attachedTo !== undefined ? { parentId: occurrence.attachedTo } : {}),
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
- : byId.get(element.parentId)?.startTime;
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(localStartTime, `${element.id}.startTime`)}"`,
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 ? [`role="${element.role}"`] : []),
375
+ ...(element.role ? [`audioRole="${element.role}"`] : []),
246
376
  ...(element.enabled !== undefined ? [`enabled="${element.enabled ? "1" : "0"}"`] : []),
247
377
  ]
248
- : [
249
- `id="${xmlEscape(element.id)}"`,
250
- `offset="${formatRational(localStartTime, `${element.id}.startTime`)}"`,
251
- `duration="${formatRational(element.durationTime, `${element.id}.durationTime`)}"`,
252
- ...(element.lane !== undefined ? [`lane="${String(element.lane)}"`] : []),
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 = element.gainDb !== undefined
256
- ? [`${indent} <adjust-volume amount="${formatDb(element.gainDb, element.id)}" />`]
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 leftTime = parseExactRational(left.startTime);
278
- const rightTime = parseExactRational(right.startTime);
279
- const difference = leftTime.value * rightTime.timescale - rightTime.value * leftTime.timescale;
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
+ }