@morshoto/framekit 0.1.16 → 0.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/README.md +10 -4
  2. package/dist-package/adapters/final-cut/typescript/src/canonical.js +19 -7
  3. package/dist-package/adapters/final-cut/typescript/src/connection.js +13 -8
  4. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +147 -34
  5. package/dist-package/adapters/final-cut/typescript/src/index.js +1 -0
  6. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +60 -1
  7. package/dist-package/adapters/final-cut/typescript/src/live.js +2 -2
  8. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +213 -0
  9. package/dist-package/adapters/final-cut/typescript/src/publisher.js +762 -238
  10. package/dist-package/adapters/final-cut/typescript/src/session.js +6 -1
  11. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +293 -59
  12. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +137 -19
  13. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +2 -2
  14. package/dist-package/apps/cli/src/main.js +34 -19
  15. package/dist-package/apps/mcp-server/src/build-alignment.js +59 -0
  16. package/dist-package/apps/mcp-server/src/build-identity.js +30 -0
  17. package/dist-package/apps/mcp-server/src/build-identity.json +5 -0
  18. package/dist-package/apps/mcp-server/src/headless-project-snapshot.js +101 -0
  19. package/dist-package/apps/mcp-server/src/headless-projects.js +473 -3
  20. package/dist-package/apps/mcp-server/src/main.js +33 -6
  21. package/dist-package/apps/mcp-server/src/server.js +367 -52
  22. package/dist-package/apps/mcp-server/src/version.js +21 -2
  23. package/dist-package/packages/runtime/src/application/media-analysis-service.js +360 -30
  24. package/dist-package/packages/runtime/src/application/semantic-media-index-store.js +86 -0
  25. package/dist-package/packages/runtime/src/index.js +1 -0
  26. package/dist-package/packages/runtime/src/planning/rough-cut.js +103 -7
  27. package/dist-package/packages/runtime/src/render/render-contract.js +3 -0
  28. package/dist-package/packages/runtime/src/runtime.js +11 -2
  29. package/dist-package/packages/runtime/src/timeline/editing-session.js +7 -2
  30. package/package.json +9 -9
@@ -9,7 +9,12 @@ export class FinalCutSessionAdapter {
9
9
  if (this.options.snapshot && this.options.live) {
10
10
  try {
11
11
  const live = await this.options.live.getIdentity();
12
- return { name: "Final Cut Pro", version: live.version, backend: "final-cut-session" };
12
+ return {
13
+ name: "Final Cut Pro",
14
+ version: live.version,
15
+ backend: "final-cut-session",
16
+ ...(live.buildFingerprint ? { buildFingerprint: live.buildFingerprint } : {}),
17
+ };
13
18
  }
14
19
  catch {
15
20
  return { name: "Final Cut Pro", version: "FCPXML + live", backend: "final-cut-session" };
@@ -3,6 +3,9 @@ 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 AUDIO_FORMAT_ID = "format-audio";
8
+ const BASIC_TITLE_EFFECT_UID = ".../Titles.localized/Bumper:Opener.localized/Basic Title.localized/Basic Title.moti";
6
9
  /**
7
10
  * Compiles a complete provider-neutral Timeline IR into a new FCPXML
8
11
  * document. The target binding is mandatory because names are not stable
@@ -23,40 +26,41 @@ export function compileTimelineIrToFcpxml(timeline, options) {
23
26
  const resourceIds = createResourceIds(timeline);
24
27
  const resourceNames = uniqueResourceNames(timeline);
25
28
  const resources = [...timeline.resources].sort((left, right) => left.id.localeCompare(right.id));
26
- const elements = renderableElements(timeline, resourceIds);
29
+ const elements = alignRenderableElements(renderableElements(timeline, resourceIds), timeline.sequence.frameDuration, new Set(resources.filter(({ mediaKind }) => mediaKind === "audio").map(({ id }) => resourceIds.get(id))));
27
30
  const elementIds = new Set();
28
31
  for (const element of elements) {
29
32
  if (elementIds.has(element.id))
30
33
  throw new Error(`FCPXML_DUPLICATE_ELEMENT_ID: ${element.id}`);
31
34
  elementIds.add(element.id);
32
35
  }
33
- for (const item of [...timeline.sequence.markers, ...timeline.sequence.captions]) {
34
- if (elementIds.has(item.id))
35
- throw new Error(`FCPXML_DUPLICATE_ELEMENT_ID: ${item.id}`);
36
- elementIds.add(item.id);
37
- }
38
- const formatId = "format-framekit";
36
+ const formatId = "r1";
37
+ const projectVideo = resources.flatMap((resource) => resource.metadata?.streams.filter((stream) => stream.kind === "video" && stream.width !== undefined && stream.height !== undefined) ?? [])[0];
38
+ const projectDimensions = projectVideo?.width && projectVideo.height
39
+ ? ` width="${projectVideo.width}" height="${projectVideo.height}"`
40
+ : "";
41
+ const projectFormatName = projectVideo?.width && projectVideo.height
42
+ ? predefinedVideoFormatName(projectVideo.width, projectVideo.height, timeline.sequence.frameDuration)
43
+ : undefined;
39
44
  const lines = [
40
45
  '<?xml version="1.0" encoding="UTF-8"?>',
41
46
  `<fcpxml version="${FRAMEKIT_FCPXML_VERSION}">`,
42
47
  " <resources>",
43
- ` <format id="${formatId}" frameDuration="${formatRational(timeline.sequence.frameDuration, "sequence.frameDuration")}" />`,
48
+ ` <format id="${formatId}"${projectFormatName ? ` name="${projectFormatName}"` : ""} frameDuration="${formatRational(timeline.sequence.frameDuration, "sequence.frameDuration")}"${projectDimensions} />`,
49
+ ...(resources.some((resource) => resource.mediaKind === "audio")
50
+ ? [` <format id="${AUDIO_FORMAT_ID}" name="FFFrameRateUndefined" />`]
51
+ : []),
52
+ ...resources.flatMap((resource) => renderResourceFormat(resource, resourceIds.get(resource.id))),
53
+ ...(timeline.sequence.titles?.length
54
+ ? [` <effect id="${BASIC_TITLE_EFFECT_ID}" name="Basic Title" uid="${BASIC_TITLE_EFFECT_UID}" />`]
55
+ : []),
44
56
  ...resources.map((resource) => renderResource(resource, resourceIds.get(resource.id), resourceNames.get(resource.id))),
45
57
  " </resources>",
46
58
  " <library>",
47
59
  ` <event uid="${xmlEscape(options.target.eventUid)}" name="${xmlEscape(options.target.eventName ?? "Framekit Event")}">`,
48
60
  ` <project uid="${xmlEscape(destination.projectUid)}" name="${xmlEscape(destination.projectName)}">`,
49
- ` <sequence uid="${xmlEscape(destination.sequenceUid)}" name="${xmlEscape(destination.sequenceName)}" format="${formatId}" duration="${formatRational(timeline.sequence.durationTime, "sequence.durationTime")}">`,
61
+ ` <sequence format="${formatId}" duration="${formatRational(timeline.sequence.durationTime, "sequence.durationTime")}">`,
50
62
  " <spine>",
51
63
  ...renderElements(elements),
52
- ...timeline.sequence.markers
53
- .slice()
54
- .sort(compareTimedItems)
55
- .map((marker) => ` <marker id="${xmlEscape(marker.id)}" start="${formatRational(marker.startTime, `marker ${marker.id}.startTime`)}" duration="${formatRational(marker.durationTime, `marker ${marker.id}.durationTime`)}" value="${xmlEscape(marker.name)}" />`),
56
- ...timeline.sequence.captions
57
- .slice()
58
- .sort(compareTimedItems)
59
- .map((caption) => ` <caption id="${xmlEscape(caption.id)}" start="${formatRational(caption.startTime, `caption ${caption.id}.startTime`)}" duration="${formatRational(caption.durationTime, `caption ${caption.id}.durationTime`)}" text="${xmlEscape(caption.text)}" />`),
60
64
  " </spine>",
61
65
  " </sequence>",
62
66
  " </project>",
@@ -75,7 +79,7 @@ export function compileTimelineIrToFcpxml(timeline, options) {
75
79
  target: structuredClone(options.target),
76
80
  destination,
77
81
  resourceIds: Object.fromEntries([...resourceIds.entries()].sort(([left], [right]) => left.localeCompare(right))),
78
- coverage: materializationCoverage(timeline, destination.mode),
82
+ coverage: materializationCoverage(timeline, destination.mode, elements),
79
83
  provenance: {
80
84
  source: "framekit-timeline-ir",
81
85
  schemaVersion: 1,
@@ -98,8 +102,9 @@ export function compileTimelineIrToFcpxml(timeline, options) {
98
102
  }
99
103
  function unsupportedFeatures(timeline) {
100
104
  const unsupported = new Set();
101
- if (timeline.sequence.titles?.length)
102
- unsupported.add("titles");
105
+ if (timeline.sequence.titles?.some(({ style, position }) => style !== undefined || position !== undefined)) {
106
+ unsupported.add("styled-or-positioned-titles");
107
+ }
103
108
  if (timeline.sequence.transitions?.length)
104
109
  unsupported.add("transitions");
105
110
  for (const occurrence of timeline.sequence.occurrences) {
@@ -116,7 +121,7 @@ function unsupportedFeatures(timeline) {
116
121
  }
117
122
  return [...unsupported].sort((left, right) => left.localeCompare(right));
118
123
  }
119
- function materializationCoverage(timeline, destinationMode) {
124
+ function materializationCoverage(timeline, destinationMode, elements) {
120
125
  const exact = new Set([
121
126
  "artifact",
122
127
  "project",
@@ -126,8 +131,13 @@ function materializationCoverage(timeline, destinationMode) {
126
131
  "primary-storyline-order",
127
132
  "provenance",
128
133
  ]);
129
- if (timeline.sequence.occurrences.some(({ attachedTo }) => attachedTo !== undefined)
130
- || timeline.sequence.storyElements.some(({ attachedTo }) => attachedTo !== undefined))
134
+ const degraded = new Set();
135
+ if (elements.some(({ frameAlignmentAdjusted }) => frameAlignmentAdjusted)) {
136
+ degraded.add("video-edit-frame-rounding");
137
+ }
138
+ if (elements.some(({ sourceRangeAdjusted }) => sourceRangeAdjusted))
139
+ exact.delete("source-ranges");
140
+ if (elements.some(({ parentId }) => parentId !== undefined))
131
141
  exact.add("connected-elements");
132
142
  if (timeline.sequence.occurrences.some(({ role }) => role !== undefined))
133
143
  exact.add("roles");
@@ -135,13 +145,89 @@ function materializationCoverage(timeline, destinationMode) {
135
145
  exact.add("gain");
136
146
  if (timeline.sequence.occurrences.some(({ enabled }) => enabled !== undefined))
137
147
  exact.add("enabled");
148
+ if (timeline.sequence.titles?.length) {
149
+ exact.add("editable-titles");
150
+ }
138
151
  if (destinationMode === "versioned")
139
152
  exact.add("versioned-destination");
140
153
  if (timeline.sequence.markers.length > 0)
141
154
  exact.add("markers");
142
155
  if (timeline.sequence.captions.length > 0)
143
156
  exact.add("captions");
144
- return { exact: [...exact].sort(), degraded: [], unsupported: [] };
157
+ return { exact: [...exact].sort(), degraded: [...degraded].sort(), unsupported: [] };
158
+ }
159
+ function alignRenderableElements(elements, frameDuration, audioResourceIds) {
160
+ return elements.map((element) => {
161
+ if (element.kind === "asset-clip" && element.resourceId !== undefined && audioResourceIds.has(element.resourceId)) {
162
+ return element;
163
+ }
164
+ const endTime = addExactTimes(element.startTime, element.durationTime);
165
+ const startTime = snapTimeToFrame(element.startTime, frameDuration);
166
+ const alignedEndTime = snapTimeToFrame(endTime, frameDuration);
167
+ const durationTime = subtractRational(alignedEndTime, startTime, `${element.id}.durationTime`);
168
+ const zero = { value: "0", timescale: "1" };
169
+ if (compareExactTimes(element.durationTime, zero) > 0 && compareExactTimes(durationTime, zero) === 0) {
170
+ throw new Error(`FCPXML_EDIT_BELOW_FRAME_RESOLUTION: ${element.id}`);
171
+ }
172
+ const sourceStartTime = element.sourceStartTime
173
+ ? snapTimeToFrame(element.sourceStartTime, frameDuration)
174
+ : undefined;
175
+ const adjusted = compareExactTimes(startTime, element.startTime) !== 0
176
+ || compareExactTimes(durationTime, element.durationTime) !== 0
177
+ || sourceStartTime !== undefined && compareExactTimes(sourceStartTime, element.sourceStartTime) !== 0;
178
+ const sourceRangeAdjusted = element.kind === "asset-clip"
179
+ && (compareExactTimes(durationTime, element.durationTime) !== 0
180
+ || sourceStartTime !== undefined && compareExactTimes(sourceStartTime, element.sourceStartTime) !== 0);
181
+ return {
182
+ ...element,
183
+ startTime,
184
+ durationTime,
185
+ ...(sourceStartTime ? { sourceStartTime } : {}),
186
+ ...(adjusted ? { frameAlignmentAdjusted: true } : {}),
187
+ ...(sourceRangeAdjusted ? { sourceRangeAdjusted: true } : {}),
188
+ };
189
+ });
190
+ }
191
+ function snapTimeToFrame(value, frameDuration) {
192
+ const time = parseExactRational(value);
193
+ const frame = parseExactRational(frameDuration);
194
+ if (time.value < 0n || frame.value <= 0n)
195
+ throw new Error("FCPXML_INVALID_TIME: frame alignment requires non-negative time and positive frame duration");
196
+ const frameNumerator = time.value * frame.timescale;
197
+ const frameDenominator = time.timescale * frame.value;
198
+ let frames = frameNumerator / frameDenominator;
199
+ if ((frameNumerator % frameDenominator) * 2n >= frameDenominator)
200
+ frames += 1n;
201
+ const numerator = frames * frame.value;
202
+ const denominator = frame.timescale;
203
+ const divisor = greatestCommonDivisor(numerator, denominator);
204
+ return { value: String(numerator / divisor), timescale: String(denominator / divisor) };
205
+ }
206
+ function predefinedVideoFormatName(width, height, frameDuration) {
207
+ const raster = width === 1280 && height === 720
208
+ ? "720p"
209
+ : width === 1920 && height === 1080
210
+ ? "1080p"
211
+ : width === 3840 && height === 2160 || width === 4096 && height === 2160
212
+ ? `${width}x${height}p`
213
+ : undefined;
214
+ if (!raster)
215
+ return undefined;
216
+ const parts = parseExactRational(frameDuration);
217
+ const divisor = greatestCommonDivisor(parts.value, parts.timescale);
218
+ const rate = `${parts.value / divisor}/${parts.timescale / divisor}`;
219
+ const suffix = {
220
+ "1001/24000": "2398",
221
+ "1/24": "24",
222
+ "1/25": "25",
223
+ "1001/30000": "2997",
224
+ "1/30": "30",
225
+ "1/50": "50",
226
+ "1001/60000": "5994",
227
+ "1/60": "60",
228
+ };
229
+ const frameRate = suffix[rate];
230
+ return frameRate ? `FFVideoFormat${raster}${frameRate}` : undefined;
145
231
  }
146
232
  function validateTarget(target) {
147
233
  if (!target || target.provider !== "final-cut")
@@ -163,17 +249,18 @@ function resolveDestination(timeline, target) {
163
249
  projectUid: target.projectUid,
164
250
  sequenceUid: target.sequenceUid,
165
251
  projectName: timeline.project.name,
166
- sequenceName: timeline.sequence.name,
252
+ sequenceName: timeline.project.name,
167
253
  };
168
254
  }
169
255
  const revisionKey = shortHash(`${timeline.project.id}:${timeline.sequence.id}:${timeline.revision.id}:${timeline.revision.sequence}:${timeline.revision.timestamp}:${timelineIrDigest(timeline)}`);
170
256
  const revisionName = `${safeId(timeline.revision.id)}-${timeline.revision.sequence}`;
257
+ const projectName = `${timeline.project.name} (Framekit ${revisionName}-${revisionKey})`;
171
258
  return {
172
259
  mode: "versioned",
173
260
  projectUid: `${safeId(target.projectUid)}-framekit-${revisionKey}`,
174
261
  sequenceUid: `${safeId(target.sequenceUid)}-framekit-${revisionKey}`,
175
- projectName: `${timeline.project.name} (Framekit ${revisionName}-${revisionKey})`,
176
- sequenceName: `${timeline.sequence.name} (Framekit ${revisionName}-${revisionKey})`,
262
+ projectName,
263
+ sequenceName: projectName,
177
264
  };
178
265
  }
179
266
  function createResourceIds(timeline) {
@@ -219,10 +306,36 @@ function renderResource(resource, id, name) {
219
306
  catch (error) {
220
307
  throw new Error(`FCPXML_RESOURCE_SOURCE_UNSUPPORTED: resource ${resource.id} has an invalid file URL: ${error instanceof Error ? error.message : String(error)}`);
221
308
  }
222
- const mediaAttributes = resource.mediaKind === "video"
223
- ? ' hasVideo="1" hasAudio="0"'
224
- : ' hasVideo="0" hasAudio="1"';
225
- return ` <asset id="${xmlEscape(id)}" name="${xmlEscape(name)}" src="${xmlEscape(src)}"${mediaAttributes} />`;
309
+ const videoAttribute = resource.mediaKind === "video" ? ' hasVideo="1"' : ' hasVideo="0"';
310
+ const metadata = resource.metadata;
311
+ const video = metadata?.streams.find((stream) => stream.kind === "video");
312
+ const audio = metadata?.streams.find((stream) => stream.kind === "audio");
313
+ const timingAttributes = metadata
314
+ ? ` start="0s" duration="${formatRational(metadata.durationTime, `resource ${resource.id}.durationTime`)}"`
315
+ : "";
316
+ const formatAttribute = video?.width && video.height && video.frameRate
317
+ ? ` format="format-${id}"`
318
+ : resource.mediaKind === "audio"
319
+ ? ` format="${AUDIO_FORMAT_ID}"`
320
+ : "";
321
+ const audioAttribute = resource.mediaKind === "audio"
322
+ ? ' hasAudio="1"'
323
+ : metadata?.streams
324
+ ? ` hasAudio="${audio ? "1" : "0"}"`
325
+ : "";
326
+ const sourceAttributes = `${video ? ' videoSources="1"' : ""}${audio ? ' audioSources="1"' : ""}`;
327
+ const audioDetails = audio?.channels && audio.sampleRate
328
+ ? ` audioChannels="${audio.channels}" audioRate="${audio.sampleRate}"`
329
+ : "";
330
+ return ` <asset id="${xmlEscape(id)}" name="${xmlEscape(name)}"${timingAttributes}${videoAttribute}${formatAttribute}${audioAttribute}${sourceAttributes}${audioDetails}><media-rep kind="original-media" src="${xmlEscape(src)}" /></asset>`;
331
+ }
332
+ function renderResourceFormat(resource, id) {
333
+ const video = resource.metadata?.streams.find((stream) => stream.kind === "video");
334
+ if (!video?.width || !video.height || !video.frameRate)
335
+ return [];
336
+ const frameDuration = { value: video.frameRate.timescale, timescale: video.frameRate.value };
337
+ const formatName = predefinedVideoFormatName(video.width, video.height, frameDuration);
338
+ return [` <format id="format-${id}"${formatName ? ` name="${formatName}"` : ""} frameDuration="${formatRational(frameDuration, `resource ${resource.id}.frameRate`)}" width="${video.width}" height="${video.height}" />`];
226
339
  }
227
340
  function renderableElements(timeline, resourceIds) {
228
341
  const occurrenceIds = new Set(timeline.sequence.occurrences.map(({ id }) => id));
@@ -244,8 +357,67 @@ function renderableElements(timeline, resourceIds) {
244
357
  ...(element.attachedTo !== undefined ? { parentId: element.attachedTo } : {}),
245
358
  });
246
359
  }
360
+ for (const title of timeline.sequence.titles ?? []) {
361
+ elements.push(renderableTitle(title, timeline));
362
+ }
363
+ for (const marker of timeline.sequence.markers) {
364
+ elements.push({
365
+ id: marker.id,
366
+ kind: "marker",
367
+ startTime: marker.startTime,
368
+ durationTime: marker.durationTime,
369
+ parentId: primaryAnchorForTime("marker", marker.id, marker.startTime, marker.durationTime, elements),
370
+ name: marker.name,
371
+ });
372
+ }
373
+ for (const caption of timeline.sequence.captions) {
374
+ elements.push({
375
+ id: caption.id,
376
+ kind: "caption",
377
+ startTime: caption.startTime,
378
+ durationTime: caption.durationTime,
379
+ parentId: primaryAnchorForTime("caption", caption.id, caption.startTime, caption.durationTime, elements),
380
+ text: caption.text,
381
+ });
382
+ }
247
383
  return elements;
248
384
  }
385
+ function primaryAnchorForTime(kind, id, startTime, durationTime, elements) {
386
+ const endTime = addExactTimes(startTime, durationTime);
387
+ const anchor = elements
388
+ .filter((element) => element.parentId === undefined
389
+ && (element.kind === "gap" || (element.kind === "asset-clip" && element.role === undefined)))
390
+ .filter((element) => compareExactTimes(startTime, element.startTime) >= 0
391
+ && compareExactTimes(endTime, addExactTimes(element.startTime, element.durationTime)) <= 0)
392
+ .sort((left, right) => compareExactTimes(right.startTime, left.startTime))[0];
393
+ if (!anchor)
394
+ throw new Error(`FCPXML_${kind.toUpperCase()}_ANCHOR_NOT_FOUND: ${id}`);
395
+ return anchor.id;
396
+ }
397
+ function renderableTitle(title, timeline) {
398
+ const titleEnd = addExactTimes(title.startTime, title.durationTime);
399
+ const parent = timeline.sequence.occurrences.find((occurrence) => {
400
+ if (occurrence.track !== 0 || occurrence.role !== undefined && occurrence.role !== "video")
401
+ return false;
402
+ const occurrenceEnd = addExactTimes(occurrence.startTime, occurrence.durationTime);
403
+ return compareExactTimes(title.startTime, occurrence.startTime) >= 0
404
+ && compareExactTimes(titleEnd, occurrenceEnd) <= 0;
405
+ });
406
+ if (!parent) {
407
+ throw new Error(`FCPXML_TITLE_ANCHOR_NOT_FOUND: title ${title.id} must fit within one primary video occurrence`);
408
+ }
409
+ return {
410
+ id: title.id,
411
+ kind: "title",
412
+ startTime: title.startTime,
413
+ durationTime: title.durationTime,
414
+ lane: title.lane,
415
+ parentId: parent.id,
416
+ name: title.id,
417
+ resourceId: BASIC_TITLE_EFFECT_ID,
418
+ text: title.text,
419
+ };
420
+ }
249
421
  function renderOccurrence(occurrence, timeline, resourceIds, occurrenceIds) {
250
422
  if (occurrence.role === "title")
251
423
  throw new Error("FCPXML_UNSUPPORTED_OCCURRENCE_ROLE: title");
@@ -265,13 +437,14 @@ function renderOccurrence(occurrence, timeline, resourceIds, occurrenceIds) {
265
437
  if (occurrence.attachedTo !== undefined && !occurrenceIds.has(occurrence.attachedTo)) {
266
438
  throw new Error(`FCPXML_ATTACHMENT_TARGET_NOT_FOUND: ${occurrence.id} -> ${occurrence.attachedTo}`);
267
439
  }
440
+ const parentId = occurrence.attachedTo ?? musicAttachmentTarget(occurrence, timeline);
268
441
  return {
269
442
  id: occurrence.id,
270
443
  kind: "asset-clip",
271
444
  startTime: occurrence.startTime,
272
445
  durationTime: occurrence.durationTime,
273
446
  ...(occurrence.track > 0 ? { lane: occurrence.track } : {}),
274
- ...(occurrence.attachedTo !== undefined ? { parentId: occurrence.attachedTo } : {}),
447
+ ...(parentId !== undefined ? { parentId } : {}),
275
448
  name: occurrence.name,
276
449
  resourceId: resource,
277
450
  ...(occurrence.sourceStartTime ? { sourceStartTime: occurrence.sourceStartTime } : {}),
@@ -280,6 +453,19 @@ function renderOccurrence(occurrence, timeline, resourceIds, occurrenceIds) {
280
453
  ...(occurrence.enabled !== undefined ? { enabled: occurrence.enabled } : {}),
281
454
  };
282
455
  }
456
+ function musicAttachmentTarget(occurrence, timeline) {
457
+ if (occurrence.role !== "music" || occurrence.track <= 0)
458
+ return undefined;
459
+ const parent = timeline.sequence.occurrences
460
+ .filter((candidate) => candidate.track === 0
461
+ && candidate.role === "video"
462
+ && compareExactTimes(candidate.startTime, occurrence.startTime) <= 0)
463
+ .sort((left, right) => compareExactTimes(right.startTime, left.startTime))[0];
464
+ if (!parent) {
465
+ throw new Error(`FCPXML_MUSIC_ANCHOR_NOT_FOUND: ${occurrence.id} must start at or after a primary video occurrence`);
466
+ }
467
+ return parent.id;
468
+ }
283
469
  function renderElements(elements) {
284
470
  const byParent = new Map();
285
471
  const byId = new Map();
@@ -289,8 +475,15 @@ function renderElements(elements) {
289
475
  siblings.push(element);
290
476
  byParent.set(element.parentId, siblings);
291
477
  }
292
- for (const siblings of byParent.values())
293
- siblings.sort(compareTimedItems);
478
+ for (const siblings of byParent.values()) {
479
+ siblings.sort((left, right) => {
480
+ if (left.kind === "marker" && right.kind !== "marker")
481
+ return 1;
482
+ if (right.kind === "marker" && left.kind !== "marker")
483
+ return -1;
484
+ return compareTimedItems(left, right);
485
+ });
486
+ }
294
487
  const rendered = new Set();
295
488
  const lines = [];
296
489
  const render = (parentId, indent) => {
@@ -298,43 +491,72 @@ function renderElements(elements) {
298
491
  if (rendered.has(element.id))
299
492
  throw new Error(`FCPXML_CYCLIC_ATTACHMENT: ${element.id}`);
300
493
  rendered.add(element.id);
301
- const children = byParent.get(element.id) ?? [];
494
+ const parentElement = element.parentId === undefined ? undefined : byId.get(element.parentId);
302
495
  const parentStartTime = element.parentId === undefined
303
496
  ? { value: "0", timescale: "1" }
304
- : byId.get(element.parentId)?.startTime;
497
+ : parentElement?.startTime;
305
498
  if (!parentStartTime)
306
499
  throw new Error(`FCPXML_ATTACHMENT_TARGET_NOT_FOUND: ${element.id} -> ${element.parentId}`);
307
500
  const localStartTime = subtractRational(element.startTime, parentStartTime, `${element.id}.startTime`);
501
+ const offsetTime = parentElement?.kind === "asset-clip"
502
+ && (element.kind === "title" || element.kind === "caption" || element.kind === "marker" || element.role === "music")
503
+ && parentElement.sourceStartTime !== undefined
504
+ ? addExactTimes(localStartTime, parentElement.sourceStartTime)
505
+ : localStartTime;
308
506
  const attributes = element.kind === "asset-clip"
309
507
  ? [
310
- `id="${xmlEscape(element.id)}"`,
311
508
  `ref="${xmlEscape(element.resourceId)}"`,
312
509
  `name="${xmlEscape(element.name)}"`,
313
- `offset="${formatRational(localStartTime, `${element.id}.startTime`)}"`,
510
+ `offset="${formatRational(offsetTime, `${element.id}.startTime`)}"`,
314
511
  ...(element.sourceStartTime ? [`start="${formatRational(element.sourceStartTime, `${element.id}.sourceStartTime`)}"`] : []),
315
512
  `duration="${formatRational(element.durationTime, `${element.id}.durationTime`)}"`,
316
513
  ...(element.lane !== undefined ? [`lane="${String(element.lane)}"`] : []),
317
- ...(element.role ? [`role="${element.role}"`] : []),
514
+ ...(element.role ? [`audioRole="${element.role}"`] : []),
318
515
  ...(element.enabled !== undefined ? [`enabled="${element.enabled ? "1" : "0"}"`] : []),
319
516
  ]
320
- : [
321
- `id="${xmlEscape(element.id)}"`,
322
- `offset="${formatRational(localStartTime, `${element.id}.startTime`)}"`,
323
- `duration="${formatRational(element.durationTime, `${element.id}.durationTime`)}"`,
324
- ...(element.lane !== undefined ? [`lane="${String(element.lane)}"`] : []),
325
- ];
326
- const opening = `<${element.kind} ${attributes.join(" ")}>`;
327
- const childLines = element.gainDb !== undefined
328
- ? [`${indent} <adjust-volume amount="${formatDb(element.gainDb, element.id)}" />`]
329
- : [];
330
- const childStart = childLines.length > 0 ? childLines : [];
331
- if (children.length === 0 && childStart.length === 0) {
332
- lines.push(`${indent}<${element.kind} ${attributes.join(" ")} />`);
517
+ : element.kind === "title"
518
+ ? [
519
+ `ref="${xmlEscape(element.resourceId)}"`,
520
+ `name="${xmlEscape(element.name)}"`,
521
+ `offset="${formatRational(offsetTime, `${element.id}.startTime`)}"`,
522
+ `duration="${formatRational(element.durationTime, `${element.id}.durationTime`)}"`,
523
+ ...(element.lane !== undefined ? [`lane="${String(element.lane)}"`] : []),
524
+ ]
525
+ : element.kind === "gap"
526
+ ? [
527
+ `offset="${formatRational(offsetTime, `${element.id}.startTime`)}"`,
528
+ `duration="${formatRational(element.durationTime, `${element.id}.durationTime`)}"`,
529
+ ...(element.lane !== undefined ? [`lane="${String(element.lane)}"`] : []),
530
+ ]
531
+ : element.kind === "marker"
532
+ ? [
533
+ `start="${formatRational(offsetTime, `${element.id}.startTime`)}"`,
534
+ `duration="${formatRational(element.durationTime, `${element.id}.durationTime`)}"`,
535
+ `value="${xmlEscape(element.name)}"`,
536
+ `note="com.framekit.id:${xmlEscape(element.id)}"`,
537
+ ]
538
+ : [
539
+ `offset="${formatRational(offsetTime, `${element.id}.startTime`)}"`,
540
+ `duration="${formatRational(element.durationTime, `${element.id}.durationTime`)}"`,
541
+ ];
542
+ if (element.kind === "marker") {
543
+ lines.push(`${indent}<marker ${attributes.join(" ")} />`);
333
544
  continue;
334
545
  }
335
- lines.push(`${indent}${opening}`);
336
- lines.push(...childStart);
546
+ lines.push(`${indent}<${element.kind} ${attributes.join(" ")}>`);
547
+ if (element.kind === "title" || element.kind === "caption") {
548
+ lines.push(`${indent} <text>${xmlEscape(element.text ?? "")}</text>`);
549
+ }
550
+ if (element.gainDb !== undefined) {
551
+ lines.push(`${indent} <adjust-volume amount="${formatDb(element.gainDb, element.id)}" />`);
552
+ }
337
553
  render(element.id, `${indent} `);
554
+ if (element.kind === "caption") {
555
+ lines.push(`${indent} <note>com.framekit.id:${xmlEscape(element.id)}</note>`);
556
+ }
557
+ else {
558
+ lines.push(`${indent} <metadata><md key="com.framekit.id" value="${xmlEscape(element.id)}" /></metadata>`);
559
+ }
338
560
  lines.push(`${indent}</${element.kind}>`);
339
561
  }
340
562
  };
@@ -346,15 +568,27 @@ function renderElements(elements) {
346
568
  return lines;
347
569
  }
348
570
  function compareTimedItems(left, right) {
349
- const leftTime = parseExactRational(left.startTime);
350
- const rightTime = parseExactRational(right.startTime);
351
- const difference = leftTime.value * rightTime.timescale - rightTime.value * leftTime.timescale;
352
- if (difference !== 0n)
353
- return difference < 0n ? -1 : 1;
571
+ const difference = compareExactTimes(left.startTime, right.startTime);
572
+ if (difference !== 0)
573
+ return difference;
354
574
  if ((left.lane ?? 0) !== (right.lane ?? 0))
355
575
  return (left.lane ?? 0) - (right.lane ?? 0);
356
576
  return left.id.localeCompare(right.id);
357
577
  }
578
+ function addExactTimes(left, right) {
579
+ const leftValue = parseExactRational(left);
580
+ const rightValue = parseExactRational(right);
581
+ return {
582
+ value: (leftValue.value * rightValue.timescale + rightValue.value * leftValue.timescale).toString(),
583
+ timescale: (leftValue.timescale * rightValue.timescale).toString(),
584
+ };
585
+ }
586
+ function compareExactTimes(left, right) {
587
+ const leftTime = parseExactRational(left);
588
+ const rightTime = parseExactRational(right);
589
+ const difference = leftTime.value * rightTime.timescale - rightTime.value * leftTime.timescale;
590
+ return difference === 0n ? 0 : difference < 0n ? -1 : 1;
591
+ }
358
592
  function formatRational(value, field) {
359
593
  const parsed = parseExactRational(value);
360
594
  if (parsed.value < 0n)