@morshoto/framekit 0.1.5 → 0.1.10

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 (40) hide show
  1. package/bin/framekit.mjs +2 -1
  2. package/dist-package/adapters/final-cut/typescript/src/assets.js +223 -15
  3. package/dist-package/adapters/final-cut/typescript/src/background-export.js +384 -0
  4. package/dist-package/adapters/final-cut/typescript/src/canonical.js +588 -0
  5. package/dist-package/adapters/final-cut/typescript/src/connection.js +20 -5
  6. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +33 -7
  7. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +805 -51
  8. package/dist-package/adapters/final-cut/typescript/src/index.js +5 -0
  9. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +390 -0
  10. package/dist-package/adapters/final-cut/typescript/src/live.js +6 -3
  11. package/dist-package/adapters/final-cut/typescript/src/media.js +151 -0
  12. package/dist-package/adapters/final-cut/typescript/src/native-session.js +412 -0
  13. package/dist-package/adapters/final-cut/typescript/src/native.js +2271 -424
  14. package/dist-package/adapters/final-cut/typescript/src/publisher.js +225 -32
  15. package/dist-package/adapters/final-cut/typescript/src/session.js +145 -17
  16. package/dist-package/apps/mcp-server/src/main.js +73 -17
  17. package/dist-package/apps/mcp-server/src/routing.js +242 -39
  18. package/dist-package/apps/mcp-server/src/server.js +677 -89
  19. package/dist-package/apps/mcp-server/src/version.js +109 -1
  20. package/dist-package/packages/runtime/src/application/media-analysis-service.js +3 -4
  21. package/dist-package/packages/runtime/src/application/project-service.js +46 -7
  22. package/dist-package/packages/runtime/src/audio/dialogue-normalization.js +9 -0
  23. package/dist-package/packages/runtime/src/capabilities.js +62 -9
  24. package/dist-package/packages/runtime/src/context/project-catalog.js +159 -0
  25. package/dist-package/packages/runtime/src/domain/capabilities.js +33 -0
  26. package/dist-package/packages/runtime/src/domain/context.js +14 -1
  27. package/dist-package/packages/runtime/src/domain/editing.js +27 -1
  28. package/dist-package/packages/runtime/src/domain/index.js +1 -0
  29. package/dist-package/packages/runtime/src/domain/skills.js +2 -0
  30. package/dist-package/packages/runtime/src/domain/timeline-target.js +217 -0
  31. package/dist-package/packages/runtime/src/editing/edit-service.js +57 -1
  32. package/dist-package/packages/runtime/src/editing/intent.js +178 -2
  33. package/dist-package/packages/runtime/src/index.js +1 -0
  34. package/dist-package/packages/runtime/src/runtime.js +2 -2
  35. package/dist-package/packages/runtime/src/skills/builtin.js +314 -39
  36. package/dist-package/packages/runtime/src/skills/requirements.js +1 -0
  37. package/dist-package/packages/runtime/src/skills/runtime.js +33 -8
  38. package/dist-package/packages/runtime/src/verification/verification.js +81 -4
  39. package/dist-package/packages/testkit/src/in-memory-editor.js +130 -4
  40. package/package.json +12 -2
@@ -1,9 +1,9 @@
1
- import { createHash } from "node:crypto";
2
- import { readFile, writeFile } from "node:fs/promises";
1
+ import { createHash, randomUUID } from "node:crypto";
2
+ import { readFile, rename, unlink, writeFile } from "node:fs/promises";
3
3
  import { fileURLToPath } from "node:url";
4
4
  import { dirname, isAbsolute, resolve } from "node:path";
5
5
  import { XMLBuilder, XMLParser } from "fast-xml-parser";
6
- import { withCapabilityFamilies } from "../../../../packages/runtime/src/index.js";
6
+ import { createProjectSelectionResult, withCapabilityFamilies } from "../../../../packages/runtime/src/index.js";
7
7
  const CLIP_KINDS = new Set(["asset-clip", "clip", "ref-clip", "sync-clip", "mc-clip", "audio", "video"]);
8
8
  const TIMELINE_KINDS = new Set([
9
9
  ...CLIP_KINDS,
@@ -50,6 +50,14 @@ export class FcpxmlDocumentAdapter {
50
50
  return hash(await readFile(this.filePath, "utf8"));
51
51
  }
52
52
  async getCapabilities() {
53
+ let hasStableEffects = false;
54
+ try {
55
+ await this.ensureLoaded();
56
+ hasStableEffects = effectResources(this.xml ?? []).some((resource) => stableEffectIdentity(resource) !== undefined);
57
+ }
58
+ catch {
59
+ // Capability inspection remains useful before an artifact is created.
60
+ }
53
61
  return withCapabilityFamilies({
54
62
  editor: {
55
63
  projectRead: true,
@@ -59,20 +67,53 @@ export class FcpxmlDocumentAdapter {
59
67
  readAfterWrite: true,
60
68
  incrementalChanges: false,
61
69
  rollback: true,
62
- assetDiscovery: false,
63
70
  liveStateRead: false,
64
71
  playheadWrite: false,
65
72
  frameCapture: false,
66
73
  projectCatalogRead: true,
67
74
  projectSelection: true,
68
75
  compositeTransactions: true,
69
- semanticOperations: { "add-marker": true },
76
+ assetDiscovery: hasStableEffects,
77
+ mediaImport: false,
78
+ mediaPlacement: true,
79
+ pictureInPicture: true,
80
+ titlePlacement: hasStableEffects,
81
+ clipMove: true,
82
+ clipReplace: true,
83
+ clipRemoval: true,
84
+ transitionPlacement: hasStableEffects,
85
+ audioAttachment: true,
86
+ audioMixing: true,
87
+ masking: false,
88
+ personCutout: false,
89
+ semanticOperations: { "add-marker": true, "set-gain": true, "timeline.picture-in-picture.add": true },
70
90
  },
71
91
  analyzers: emptyAnalyzerCapabilities(),
72
92
  }, { backend: "fcpxml-document" });
73
93
  }
74
94
  async listAssets() {
75
- return [];
95
+ await this.ensureLoaded();
96
+ return effectResources(this.xml ?? [])
97
+ .map((resource) => {
98
+ const identity = stableEffectIdentity(resource);
99
+ const localId = String(attribute(resource, "id") ?? "");
100
+ if (!identity || !localId)
101
+ return undefined;
102
+ return {
103
+ id: `fcpxml:effect:${identity}`,
104
+ kind: "effect",
105
+ name: String(attribute(resource, "name") ?? identity),
106
+ vendor: "Final Cut Pro",
107
+ metadata: {
108
+ identity,
109
+ localId,
110
+ provider: "fcpxml-document",
111
+ source: "fcpxml-resources",
112
+ discovery: { backend: "fcpxml-document", guarantee: "canonical-read" },
113
+ },
114
+ };
115
+ })
116
+ .filter((asset) => asset !== undefined);
76
117
  }
77
118
  async read() {
78
119
  return this.readProject();
@@ -95,16 +136,19 @@ export class FcpxmlDocumentAdapter {
95
136
  const clips = elements
96
137
  .filter(({ kind }) => CLIP_KINDS.has(kind))
97
138
  .map((entry) => this.clipFromXml(entry, timelineId));
98
- const durationValue = attribute(sequence, "duration")
99
- ?? formatSeconds(Math.max(0, ...storyElements.map((element) => element.start + element.duration)));
139
+ const frameDuration = sequenceFrameDuration(sequence, this.xml ?? []);
140
+ const durationTime = attribute(sequence, "duration") === undefined
141
+ ? timelineDuration(elements)
142
+ : parseRational(attribute(sequence, "duration"));
100
143
  return {
101
144
  projectId,
102
145
  projectName,
103
146
  timeline: {
104
147
  id: timelineId,
105
148
  name: sequenceName,
106
- duration: parseSeconds(durationValue),
107
- durationTime: parseRational(durationValue),
149
+ duration: rationalSeconds(durationTime),
150
+ durationTime,
151
+ ...(frameDuration ? { frameDuration } : {}),
108
152
  clips,
109
153
  storyElements,
110
154
  markers: this.markersFromXml(elements),
@@ -143,18 +187,29 @@ export class FcpxmlDocumentAdapter {
143
187
  if (!project.sequences.some((sequence) => sequence.id === sequenceId)) {
144
188
  throw new Error(`SEQUENCE_NOT_FOUND: ${sequenceId}`);
145
189
  }
146
- return { ...catalog, activeProjectId: project.id, activeSequenceId: sequenceId };
190
+ return createProjectSelectionResult({ ...catalog, activeProjectId: project.id, activeSequenceId: sequenceId }, selection, this.revision());
147
191
  }
148
192
  async apply(operation, expectedRevision) {
149
193
  await this.ensureLoaded();
150
194
  if (!sameRevision(expectedRevision, this.revision())) {
151
195
  throw new Error("STALE_CONTEXT: FCPXML document changed before write");
152
196
  }
197
+ const originalXml = structuredClone(this.xml);
198
+ const originalSequence = this.sequence;
199
+ const originalSignature = this.fileSignature;
153
200
  this.history.set(expectedRevision.id, structuredClone(this.xml));
154
- this.applyOperation(operation);
155
- this.sequence += 1;
156
- await this.persist();
157
- return this.revision();
201
+ try {
202
+ this.applyOperation(operation);
203
+ this.sequence += 1;
204
+ await this.persist();
205
+ return this.revision();
206
+ }
207
+ catch (error) {
208
+ this.xml = originalXml;
209
+ this.sequence = originalSequence;
210
+ this.fileSignature = originalSignature;
211
+ throw error;
212
+ }
158
213
  }
159
214
  async previewTransaction(operations, expectedRevision) {
160
215
  await this.ensureLoaded();
@@ -166,9 +221,7 @@ export class FcpxmlDocumentAdapter {
166
221
  const originalSignature = this.fileSignature;
167
222
  try {
168
223
  for (const operation of operations) {
169
- if (operation.type === "media.import" || operation.type.startsWith("timeline.")) {
170
- throw new Error(`CAPABILITY_UNAVAILABLE: FCPXML preview does not support ${operation.type}`);
171
- }
224
+ this.assertArtifactOperationSupported(operation, "preview");
172
225
  this.applyOperation(operation);
173
226
  }
174
227
  const preview = await this.readProject();
@@ -185,53 +238,98 @@ export class FcpxmlDocumentAdapter {
185
238
  if (!sameRevision(expectedRevision, this.revision())) {
186
239
  throw new Error("STALE_CONTEXT: FCPXML document changed before transaction");
187
240
  }
241
+ const originalXml = structuredClone(this.xml);
242
+ const originalSequence = this.sequence;
243
+ const originalSignature = this.fileSignature;
188
244
  this.history.set(expectedRevision.id, structuredClone(this.xml));
189
- for (const operation of operations) {
190
- if (operation.type === "media.import" || operation.type.startsWith("timeline.")) {
191
- throw new Error(`CAPABILITY_UNAVAILABLE: FCPXML transaction does not support ${operation.type}`);
245
+ try {
246
+ for (const operation of operations) {
247
+ this.assertArtifactOperationSupported(operation, "transaction");
248
+ this.applyOperation(operation);
192
249
  }
193
- this.applyOperation(operation);
250
+ this.sequence += 1;
251
+ await this.persist();
252
+ }
253
+ catch (error) {
254
+ this.xml = originalXml;
255
+ this.sequence = originalSequence;
256
+ this.fileSignature = originalSignature;
257
+ throw error;
258
+ }
259
+ }
260
+ assertArtifactOperationSupported(operation, phase) {
261
+ const supported = new Set([
262
+ "rename-clip",
263
+ "trim-clip",
264
+ "set-gain",
265
+ "ripple-delete",
266
+ "add-marker",
267
+ "timeline.media.add",
268
+ "timeline.picture-in-picture.add",
269
+ "timeline.audio.fades",
270
+ "timeline.title.add",
271
+ "timeline.media.move",
272
+ "timeline.media.replace",
273
+ "timeline.media.remove",
274
+ "timeline.transition.add",
275
+ "timeline.audio.attach",
276
+ "timeline.audio.mix",
277
+ ]);
278
+ if (!supported.has(operation.type)) {
279
+ throw new Error(`CAPABILITY_UNAVAILABLE: FCPXML ${phase} does not support ${operation.type}`);
194
280
  }
195
- this.sequence += 1;
196
- await this.persist();
197
281
  }
198
282
  applyOperation(operation) {
199
283
  const project = this.projectNode();
200
284
  const sequenceNode = findElement(project, "sequence");
201
- const sequence = sequenceNode ?? {};
202
- const spine = findElement(sequence, "spine") ?? {};
285
+ if (!sequenceNode)
286
+ throw new Error("FCPXML_SCHEMA_UNSUPPORTED: project sequence is required");
287
+ const spine = findElement(sequenceNode, "spine");
288
+ if (!spine)
289
+ throw new Error("FCPXML_SCHEMA_UNSUPPORTED: sequence spine is required");
290
+ const sequence = sequenceNode;
203
291
  const timelineId = stableTimelineId(project, sequenceNode);
292
+ if (operation.type === "timeline.picture-in-picture.add") {
293
+ this.applyPictureInPicture(spine, timelineId, operation);
294
+ this.updateSequenceDuration(sequence, spine);
295
+ return;
296
+ }
204
297
  switch (operation.type) {
205
298
  case "rename-clip": {
206
- const node = this.findClipNode(spine, operation.clipId, timelineId);
207
- if (!node)
299
+ const entry = this.findClipEntry(spine, operation.clipId, timelineId);
300
+ if (!entry)
208
301
  throw new Error(`CLIP_NOT_FOUND: ${operation.clipId}`);
209
302
  if (operation.name.trim().length === 0)
210
303
  throw new Error("INVALID_OPERATION: clip name cannot be empty");
211
- setAttribute(node, "name", operation.name);
304
+ setAttribute(entry.node, "name", operation.name);
212
305
  break;
213
306
  }
214
307
  case "trim-clip": {
215
- const node = this.findClipNode(spine, operation.clipId, timelineId);
216
- if (!node)
308
+ const entry = this.findClipEntry(spine, operation.clipId, timelineId);
309
+ if (!entry)
217
310
  throw new Error(`CLIP_NOT_FOUND: ${operation.clipId}`);
218
311
  if ((!Number.isFinite(operation.duration) || operation.duration <= 0) && !operation.durationTime) {
219
312
  throw new Error("INVALID_OPERATION: clip duration must be positive");
220
313
  }
221
- setAttribute(node, "duration", operation.durationTime ? formatRational(operation.durationTime) : formatSeconds(operation.duration));
314
+ const duration = operation.durationTime ? rationalSeconds(operation.durationTime) : operation.duration;
315
+ this.assertSourceRange(entry.node, duration);
316
+ setAttribute(entry.node, "duration", operation.durationTime ? formatRational(operation.durationTime) : formatSeconds(duration));
222
317
  break;
223
318
  }
224
319
  case "set-gain": {
225
- const node = this.findClipNode(spine, operation.clipId, timelineId);
226
- if (!node)
320
+ const entry = this.findClipEntry(spine, operation.clipId, timelineId);
321
+ if (!entry)
227
322
  throw new Error(`CLIP_NOT_FOUND: ${operation.clipId}`);
228
323
  if (!Number.isFinite(operation.gainDb))
229
324
  throw new Error("INVALID_OPERATION: gain must be finite");
230
- this.setAdjustVolume(node, operation.gainDb);
325
+ this.setAdjustVolume(entry.node, operation.gainDb);
231
326
  break;
232
327
  }
233
328
  case "ripple-delete":
234
- throw new Error("CAPABILITY_UNAVAILABLE: FCPXML ripple-delete requires story-element source-range transforms");
329
+ if (operation.timelineId !== timelineId)
330
+ throw new Error(`TIMELINE_NOT_FOUND: ${operation.timelineId}`);
331
+ this.applyRippleDelete(spine, operation.range.start, operation.range.end);
332
+ break;
235
333
  case "add-marker": {
236
334
  if (operation.timelineId !== timelineId) {
237
335
  throw new Error(`TIMELINE_NOT_FOUND: ${operation.timelineId}`);
@@ -246,9 +344,408 @@ export class FcpxmlDocumentAdapter {
246
344
  });
247
345
  break;
248
346
  }
347
+ case "timeline.media.add":
348
+ this.applyMediaAdd(spine, timelineId, operation);
349
+ break;
350
+ case "timeline.audio.fades":
351
+ this.applyAudioFades(spine, timelineId, operation);
352
+ break;
353
+ case "timeline.title.add":
354
+ this.applyTitleAdd(spine, timelineId, operation);
355
+ break;
356
+ case "timeline.media.move":
357
+ this.applyMediaMove(spine, timelineId, operation);
358
+ break;
359
+ case "timeline.media.replace":
360
+ this.applyMediaReplace(spine, timelineId, operation);
361
+ break;
362
+ case "timeline.media.remove":
363
+ this.applyMediaRemove(spine, timelineId, operation);
364
+ break;
365
+ case "timeline.transition.add":
366
+ this.applyTransitionAdd(spine, timelineId, operation);
367
+ break;
368
+ case "timeline.audio.attach":
369
+ this.applyAudioAttach(spine, timelineId, operation);
370
+ break;
371
+ case "timeline.audio.mix":
372
+ this.applyAudioMix(spine, timelineId, operation);
373
+ break;
249
374
  }
250
375
  this.updateSequenceDuration(sequence, spine);
251
376
  }
377
+ findClipEntry(spine, clipId, timelineId) {
378
+ return timelineEntries(spine)
379
+ .filter(({ kind }) => CLIP_KINDS.has(kind))
380
+ .find(({ kind, node, path }) => this.instanceId(node, kind, path, timelineId) === clipId);
381
+ }
382
+ mediaResource(mediaId) {
383
+ const media = this.mediaFromResources().find((candidate) => candidate.mediaId === mediaId);
384
+ if (!media)
385
+ throw new Error(`MEDIA_NOT_FOUND: ${mediaId}`);
386
+ return media;
387
+ }
388
+ effectResource(assetId, operation) {
389
+ const resource = effectResources(this.xml ?? []).find((candidate) => {
390
+ const localId = String(attribute(candidate, "id") ?? "");
391
+ const identity = stableEffectIdentity(candidate);
392
+ return assetId === localId || assetId === identity || assetId === `fcpxml:effect:${identity}`;
393
+ });
394
+ if (!resource)
395
+ throw new Error(`${operation === "title" ? "TITLE" : "TRANSITION"}_ASSET_NOT_FOUND: ${assetId}`);
396
+ if (!stableEffectIdentity(resource)) {
397
+ throw new Error(`FCPXML_EFFECT_IDENTITY_UNAVAILABLE: ${assetId}`);
398
+ }
399
+ return resource;
400
+ }
401
+ applyMediaAdd(spine, timelineId, operation) {
402
+ const media = this.mediaResource(operation.mediaId);
403
+ if (timelineEntries(spine).some(({ kind, node, path }) => this.instanceId(node, kind, path, timelineId) === operation.occurrenceId)) {
404
+ throw new Error(`OCCURRENCE_ALREADY_EXISTS: ${operation.occurrenceId}`);
405
+ }
406
+ if (!Number.isFinite(operation.start) || !Number.isFinite(operation.duration)
407
+ || operation.start < 0 || operation.duration <= 0) {
408
+ throw new Error("INVALID_OPERATION: media placement timing");
409
+ }
410
+ if (!mediaKindCompatible(operation.role, media.mediaKind)) {
411
+ throw new Error(`MEDIA_KIND_MISMATCH: ${operation.mediaId}`);
412
+ }
413
+ if (media.duration !== undefined && operation.duration > media.duration) {
414
+ throw new Error("INVALID_OPERATION: media placement duration must fit the source");
415
+ }
416
+ const lane = operation.targetLane ?? (operation.role === "video" ? "primary" : undefined);
417
+ if (operation.role === "video" && lane !== "primary") {
418
+ throw new Error("INVALID_OPERATION: video must target the primary storyline");
419
+ }
420
+ if (operation.role !== "video" && (typeof lane !== "number" || lane === 0)) {
421
+ throw new Error("INVALID_OPERATION: audio requires an explicit non-primary lane");
422
+ }
423
+ const kind = operation.role === "video" ? "asset-clip" : "audio";
424
+ const node = elementNode(kind, {
425
+ id: operation.occurrenceId,
426
+ ref: operation.mediaId,
427
+ offset: formatSeconds(operation.start),
428
+ start: "0s",
429
+ duration: formatSeconds(operation.duration),
430
+ ...(lane === "primary" ? {} : { lane: String(lane) }),
431
+ ...(operation.role === "video" ? {} : { role: operation.role }),
432
+ });
433
+ appendChild(spine, kind, node);
434
+ }
435
+ applyAudioFades(spine, timelineId, operation) {
436
+ const entry = this.findClipEntry(spine, operation.clipId, timelineId);
437
+ if (!entry)
438
+ throw new Error(`CLIP_NOT_FOUND: ${operation.clipId}`);
439
+ if (!Number.isFinite(operation.fadeIn) || !Number.isFinite(operation.fadeOut)
440
+ || operation.fadeIn < 0 || operation.fadeOut < 0
441
+ || operation.fadeIn + operation.fadeOut > rationalSeconds(entry.durationTime)) {
442
+ throw new Error("INVALID_OPERATION: audio fades must be non-negative and fit within the clip duration");
443
+ }
444
+ this.setAudioFades(entry.node, operation.fadeIn, operation.fadeOut);
445
+ }
446
+ applyTitleAdd(spine, timelineId, operation) {
447
+ const effect = this.effectResource(operation.assetId, "title");
448
+ this.assertNewOccurrence(spine, timelineId, operation.occurrenceId);
449
+ if (!operation.text.trim() || !Number.isFinite(operation.start) || !Number.isFinite(operation.duration)
450
+ || operation.start < 0 || operation.duration <= 0 || !Number.isInteger(operation.targetLane) || operation.targetLane === 0) {
451
+ throw new Error("INVALID_OPERATION: title text, timing, and non-primary lane are required");
452
+ }
453
+ const node = elementNode("title", {
454
+ id: operation.occurrenceId,
455
+ ref: String(attribute(effect, "id")),
456
+ name: String(attribute(effect, "name") ?? operation.assetId),
457
+ offset: formatSeconds(operation.start),
458
+ duration: formatSeconds(operation.duration),
459
+ lane: String(operation.targetLane),
460
+ });
461
+ appendTextChild(node, "text", operation.text);
462
+ appendChild(spine, "title", node);
463
+ }
464
+ applyMediaMove(spine, timelineId, operation) {
465
+ const entry = this.findClipEntry(spine, operation.occurrenceId, timelineId);
466
+ if (!entry)
467
+ throw new Error(`CLIP_NOT_FOUND: ${operation.occurrenceId}`);
468
+ if (!Number.isFinite(operation.start) || operation.start < 0) {
469
+ throw new Error("INVALID_OPERATION: media move start must be non-negative");
470
+ }
471
+ const existingLane = attribute(entry.node, "lane");
472
+ const lane = operation.targetLane ?? (existingLane === undefined ? "primary" : Number(existingLane));
473
+ if (lane === "primary" && entry.parent !== spine) {
474
+ throw new Error("CAPABILITY_UNAVAILABLE: moving nested FCPXML media to the primary storyline");
475
+ }
476
+ if (lane !== "primary" && (!Number.isInteger(lane) || lane === 0)) {
477
+ throw new Error("INVALID_OPERATION: media move requires a valid lane");
478
+ }
479
+ const parentStart = rationalSeconds(entry.parentStartTime);
480
+ if (operation.start < parentStart) {
481
+ throw new Error("INVALID_OPERATION: media move cannot precede its FCPXML parent");
482
+ }
483
+ setAttribute(entry.node, "offset", formatSeconds(operation.start - parentStart));
484
+ if (lane === "primary")
485
+ removeAttribute(entry.node, "lane");
486
+ else
487
+ setAttribute(entry.node, "lane", String(lane));
488
+ }
489
+ applyMediaReplace(spine, timelineId, operation) {
490
+ const entry = this.findClipEntry(spine, operation.occurrenceId, timelineId);
491
+ if (!entry)
492
+ throw new Error(`CLIP_NOT_FOUND: ${operation.occurrenceId}`);
493
+ const media = this.mediaResource(operation.mediaId);
494
+ const currentMediaId = attribute(entry.node, "ref");
495
+ const currentMedia = currentMediaId === undefined
496
+ ? undefined
497
+ : this.mediaFromResources().find((candidate) => candidate.mediaId === String(currentMediaId));
498
+ const currentKind = entry.kind === "audio" ? "audio" : currentMedia?.mediaKind;
499
+ if ((currentKind !== undefined && media.mediaKind !== undefined && currentKind !== media.mediaKind)
500
+ || entry.kind === "audio" && media.mediaKind === "video") {
501
+ throw new Error(`MEDIA_KIND_MISMATCH: ${operation.mediaId}`);
502
+ }
503
+ const duration = operation.duration ?? rationalSeconds(entry.durationTime);
504
+ if (!Number.isFinite(duration) || duration <= 0 || media.duration !== undefined
505
+ && sourceStart(entry.node) + duration > media.duration) {
506
+ throw new Error("INVALID_OPERATION: replacement duration must fit the source");
507
+ }
508
+ setAttribute(entry.node, "ref", operation.mediaId);
509
+ setAttribute(entry.node, "duration", formatSeconds(duration));
510
+ setAttribute(entry.node, "name", media.source.split("/").pop() || media.mediaId);
511
+ }
512
+ applyMediaRemove(spine, timelineId, operation) {
513
+ const entry = this.findClipEntry(spine, operation.occurrenceId, timelineId);
514
+ if (!entry)
515
+ throw new Error(`CLIP_NOT_FOUND: ${operation.occurrenceId}`);
516
+ removeChild(entry.parent, entry.node);
517
+ }
518
+ applyTransitionAdd(spine, timelineId, operation) {
519
+ const effect = this.effectResource(operation.assetId, "transition");
520
+ this.assertNewOccurrence(spine, timelineId, operation.transitionId);
521
+ const before = this.findClipEntry(spine, operation.beforeClipId, timelineId);
522
+ const after = this.findClipEntry(spine, operation.afterClipId, timelineId);
523
+ if (!before || !after || before.parent !== spine || after.parent !== spine) {
524
+ throw new Error("EDIT_POINT_NOT_FOUND: transition clips are required on the primary storyline");
525
+ }
526
+ const beforeIndex = childIndex(spine, before.node);
527
+ const afterIndex = childIndex(spine, after.node);
528
+ if (beforeIndex < 0 || afterIndex !== beforeIndex + 1) {
529
+ throw new Error("EDIT_POINT_INVALID: transition clips must be adjacent");
530
+ }
531
+ const beforeEnd = rationalSeconds(before.startTime) + rationalSeconds(before.durationTime);
532
+ if (Math.abs(beforeEnd - rationalSeconds(after.startTime)) > 1e-6) {
533
+ throw new Error("EDIT_POINT_INVALID: transition clips must meet on one lane");
534
+ }
535
+ if (!Number.isFinite(operation.duration) || operation.duration <= 0
536
+ || operation.duration > Math.min(rationalSeconds(before.durationTime), rationalSeconds(after.durationTime))) {
537
+ throw new Error("INVALID_OPERATION: transition duration must fit both clips");
538
+ }
539
+ const node = elementNode("transition", {
540
+ id: operation.transitionId,
541
+ name: String(attribute(effect, "name") ?? operation.assetId),
542
+ offset: formatSeconds(rationalSeconds(after.startTime) - operation.duration / 2),
543
+ duration: formatSeconds(operation.duration),
544
+ "framekit-before-clip": operation.beforeClipId,
545
+ "framekit-after-clip": operation.afterClipId,
546
+ });
547
+ appendChild(node, "filter-video", elementNode("filter-video", {
548
+ ref: String(attribute(effect, "id")),
549
+ name: String(attribute(effect, "name") ?? operation.assetId),
550
+ }));
551
+ insertChildAt(spine, "transition", node, afterIndex);
552
+ }
553
+ applyAudioAttach(spine, timelineId, operation) {
554
+ const target = this.findClipEntry(spine, operation.targetClipId, timelineId);
555
+ if (!target)
556
+ throw new Error(`CLIP_NOT_FOUND: ${operation.targetClipId}`);
557
+ const media = this.mediaResource(operation.mediaId);
558
+ if (media.mediaKind !== "audio")
559
+ throw new Error(`AUDIO_MEDIA_REQUIRED: ${operation.mediaId}`);
560
+ this.assertNewOccurrence(spine, timelineId, operation.occurrenceId);
561
+ const startOffset = operation.startOffset ?? 0;
562
+ const duration = operation.duration ?? media.duration;
563
+ if (!Number.isFinite(startOffset) || startOffset < 0 || duration === undefined
564
+ || !Number.isFinite(duration) || duration <= 0 || media.duration !== undefined && duration > media.duration
565
+ || startOffset + duration > rationalSeconds(target.durationTime)) {
566
+ throw new Error("INVALID_OPERATION: attached audio must fit within the target clip");
567
+ }
568
+ const node = elementNode("audio", {
569
+ id: operation.occurrenceId,
570
+ ref: operation.mediaId,
571
+ offset: formatSeconds(startOffset),
572
+ start: "0s",
573
+ duration: formatSeconds(duration),
574
+ lane: "-1",
575
+ role: "audio",
576
+ "framekit-attached-to": operation.targetClipId,
577
+ });
578
+ appendChild(target.node, "audio", node);
579
+ }
580
+ applyAudioMix(spine, timelineId, operation) {
581
+ const entry = this.findClipEntry(spine, operation.clipId, timelineId);
582
+ if (!entry)
583
+ throw new Error(`CLIP_NOT_FOUND: ${operation.clipId}`);
584
+ const mediaId = attribute(entry.node, "ref");
585
+ const media = mediaId === undefined ? undefined : this.mediaFromResources().find((candidate) => candidate.mediaId === String(mediaId));
586
+ if (entry.kind !== "audio" && media?.mediaKind !== "audio") {
587
+ throw new Error("INVALID_OPERATION: audio mix requires an audio clip");
588
+ }
589
+ if (operation.gainDb === undefined && operation.fadeIn === undefined && operation.fadeOut === undefined) {
590
+ throw new Error("INVALID_OPERATION: audio mix requires a gain or fade change");
591
+ }
592
+ if (operation.gainDb !== undefined) {
593
+ if (!Number.isFinite(operation.gainDb))
594
+ throw new Error("INVALID_OPERATION: gain must be finite");
595
+ this.setAdjustVolume(entry.node, operation.gainDb);
596
+ }
597
+ if (operation.fadeIn !== undefined || operation.fadeOut !== undefined) {
598
+ const existing = audioFadeProperties(entry.node);
599
+ const fadeIn = operation.fadeIn ?? existing.fadeIn ?? 0;
600
+ const fadeOut = operation.fadeOut ?? existing.fadeOut ?? 0;
601
+ if (!Number.isFinite(fadeIn) || !Number.isFinite(fadeOut) || fadeIn < 0 || fadeOut < 0
602
+ || fadeIn + fadeOut > rationalSeconds(entry.durationTime)) {
603
+ throw new Error("INVALID_OPERATION: audio mix values must fit the clip");
604
+ }
605
+ this.setAudioFades(entry.node, fadeIn, fadeOut);
606
+ }
607
+ }
608
+ setAudioFades(node, fadeIn, fadeOut) {
609
+ const volume = firstChild(node, "adjust-volume") ?? elementNode("adjust-volume", {});
610
+ if (!firstChild(node, "adjust-volume"))
611
+ appendChild(node, "adjust-volume", volume);
612
+ const param = firstChild(volume, "param") ?? elementNode("param", { name: "amount" });
613
+ if (!firstChild(volume, "param"))
614
+ appendChild(volume, "param", param);
615
+ removeChildren(param, "fadeIn");
616
+ removeChildren(param, "fadeOut");
617
+ appendChild(param, "fadeIn", elementNode("fadeIn", { duration: formatSeconds(fadeIn) }));
618
+ appendChild(param, "fadeOut", elementNode("fadeOut", { duration: formatSeconds(fadeOut) }));
619
+ }
620
+ assertNewOccurrence(spine, timelineId, occurrenceId) {
621
+ if (timelineEntries(spine).some(({ kind, node, path }) => this.instanceId(node, kind, path, timelineId) === occurrenceId)) {
622
+ throw new Error(`OCCURRENCE_ALREADY_EXISTS: ${occurrenceId}`);
623
+ }
624
+ }
625
+ assertSourceRange(node, duration) {
626
+ const mediaId = attribute(node, "ref");
627
+ if (mediaId === undefined)
628
+ return;
629
+ const media = this.mediaFromResources().find((candidate) => candidate.mediaId === String(mediaId));
630
+ if (media?.duration !== undefined && sourceStart(node) + duration > media.duration) {
631
+ throw new Error("INVALID_OPERATION: clip duration must fit the source");
632
+ }
633
+ }
634
+ applyRippleDelete(spine, start, end) {
635
+ if (!Number.isFinite(start) || !Number.isFinite(end) || start < 0 || end <= start) {
636
+ throw new Error("INVALID_OPERATION: ripple-delete range must be finite and increasing");
637
+ }
638
+ const direct = storyEntries(spine)
639
+ .map(({ kind, node }) => timelineEntries(spine).find((entry) => entry.node === node && entry.kind === kind))
640
+ .filter((entry) => entry !== undefined);
641
+ const delta = end - start;
642
+ for (const entry of direct) {
643
+ const entryStart = rationalSeconds(entry.startTime);
644
+ const entryEnd = entryStart + rationalSeconds(entry.durationTime);
645
+ if (entryEnd <= start || entryStart >= end)
646
+ continue;
647
+ if (entry.kind === "transition") {
648
+ throw new Error("CAPABILITY_UNAVAILABLE: FCPXML ripple-delete cannot transform transitions safely");
649
+ }
650
+ if (storyEntries(entry.node).length > 0) {
651
+ throw new Error("CAPABILITY_UNAVAILABLE: FCPXML ripple-delete cannot split anchored story elements safely");
652
+ }
653
+ if (entryStart < start && entryEnd > end) {
654
+ throw new Error("CAPABILITY_UNAVAILABLE: FCPXML ripple-delete requires a source-preserving clip split");
655
+ }
656
+ }
657
+ for (const entry of direct) {
658
+ const entryStart = rationalSeconds(entry.startTime);
659
+ const entryEnd = entryStart + rationalSeconds(entry.durationTime);
660
+ if (entryEnd <= start)
661
+ continue;
662
+ if (entryStart >= end) {
663
+ setAttribute(entry.node, "offset", formatSeconds(entryStart - delta));
664
+ continue;
665
+ }
666
+ if (entryStart < start && entryEnd <= end) {
667
+ const duration = start - entryStart;
668
+ if (duration <= 0)
669
+ removeChild(entry.parent, entry.node);
670
+ else
671
+ setAttribute(entry.node, "duration", formatSeconds(duration));
672
+ continue;
673
+ }
674
+ if (entryStart >= start && entryEnd > end) {
675
+ const duration = entryEnd - end;
676
+ const sourceAdvance = end - entryStart;
677
+ setAttribute(entry.node, "offset", formatSeconds(start));
678
+ setAttribute(entry.node, "duration", formatSeconds(duration));
679
+ if (CLIP_KINDS.has(entry.kind))
680
+ setAttribute(entry.node, "start", formatSeconds(sourceStart(entry.node) + sourceAdvance));
681
+ continue;
682
+ }
683
+ removeChild(entry.parent, entry.node);
684
+ }
685
+ }
686
+ applyPictureInPicture(spine, timelineId, operation) {
687
+ const media = this.mediaFromResources().find((candidate) => candidate.mediaId === operation.mediaId);
688
+ if (!media)
689
+ throw new Error(`MEDIA_NOT_FOUND: ${operation.mediaId}`);
690
+ if (media.mediaKind !== undefined && media.mediaKind !== "video") {
691
+ throw new Error(`MEDIA_KIND_MISMATCH: ${operation.mediaId}`);
692
+ }
693
+ if (this.findClipNode(spine, operation.occurrenceId, timelineId)) {
694
+ throw new Error(`OCCURRENCE_ALREADY_EXISTS: ${operation.occurrenceId}`);
695
+ }
696
+ const anchorEntry = timelineEntries(spine)
697
+ .find(({ kind, node, path }) => CLIP_KINDS.has(kind)
698
+ && this.instanceId(node, kind, path, timelineId) === operation.attachedTo);
699
+ if (!anchorEntry)
700
+ throw new Error(`CLIP_NOT_FOUND: ${operation.attachedTo}`);
701
+ if (anchorEntry.kind !== "asset-clip" && anchorEntry.kind !== "clip"
702
+ && anchorEntry.kind !== "ref-clip" && anchorEntry.kind !== "sync-clip"
703
+ && anchorEntry.kind !== "mc-clip") {
704
+ throw new Error("INVALID_OPERATION: PIP anchor must be a video occurrence");
705
+ }
706
+ if (operation.frame) {
707
+ throw new Error("CAPABILITY_UNAVAILABLE: FCPXML picture-in-picture frame requires the native Final Cut provider");
708
+ }
709
+ validatePictureInPictureOperation(operation, anchorEntry.startTime, anchorEntry.durationTime, media.duration);
710
+ const connected = {
711
+ "asset-clip": [],
712
+ ":@": {
713
+ "@_id": operation.occurrenceId,
714
+ "@_name": media.source.split("/").pop() || operation.mediaId,
715
+ "@_ref": operation.mediaId,
716
+ "@_offset": formatSeconds(operation.start - rationalSeconds(anchorEntry.startTime)),
717
+ "@_start": "0s",
718
+ "@_duration": formatSeconds(operation.duration),
719
+ "@_lane": String(operation.targetLane),
720
+ "@_framekit-attached-to": operation.attachedTo,
721
+ },
722
+ };
723
+ appendChild(anchorEntry.node, "asset-clip", connected);
724
+ appendChild(connected, "adjust-transform", {
725
+ ":@": {
726
+ "@_position": `${operation.position.x} ${operation.position.y}`,
727
+ "@_scale": `${operation.scale * 100} ${operation.scale * 100}`,
728
+ },
729
+ });
730
+ if (operation.crop) {
731
+ appendChild(connected, "adjust-crop", {
732
+ ":@": {
733
+ "@_mode": "crop",
734
+ },
735
+ });
736
+ const crop = firstChild(connected, "adjust-crop");
737
+ if (!crop)
738
+ throw new Error("FCPXML_INVALID_PIP: crop adjustment could not be created");
739
+ appendChild(crop, "crop-rect", {
740
+ ":@": {
741
+ "@_top": formatPictureInPicturePercentage(operation.crop.top),
742
+ "@_right": formatPictureInPicturePercentage(operation.crop.right),
743
+ "@_bottom": formatPictureInPicturePercentage(operation.crop.bottom),
744
+ "@_left": formatPictureInPicturePercentage(operation.crop.left),
745
+ },
746
+ });
747
+ }
748
+ }
252
749
  async restore(snapshot, expectedRevision) {
253
750
  await this.ensureLoaded();
254
751
  if (!sameRevision(expectedRevision, this.revision())) {
@@ -273,14 +770,27 @@ export class FcpxmlDocumentAdapter {
273
770
  }
274
771
  async persist() {
275
772
  const content = this.builder.build(this.xml);
276
- await writeFile(this.filePath, content, "utf8");
277
- this.fileSignature = hash(content);
773
+ const temporaryPath = `${this.filePath}.framekit-${randomUUID()}.tmp`;
774
+ try {
775
+ await writeFile(temporaryPath, content, "utf8");
776
+ await rename(temporaryPath, this.filePath);
777
+ this.fileSignature = hash(content);
778
+ }
779
+ finally {
780
+ await unlink(temporaryPath).catch(() => undefined);
781
+ }
278
782
  }
279
783
  projectNode() {
280
784
  return findElement(this.xml ?? [], "project") ?? {};
281
785
  }
282
786
  storyElementFromXml(entry, timelineId) {
283
787
  const { node, kind, path, startTime, durationTime } = entry;
788
+ const visual = pictureInPictureProperties(node);
789
+ const referencedEffect = kind === "title"
790
+ ? attribute(node, "ref")
791
+ : kind === "transition" ? attribute(firstChild(node, "filter-video") ?? {}, "ref") : undefined;
792
+ const assetId = referencedEffect === undefined ? undefined : this.effectAssetId(String(referencedEffect));
793
+ const text = kind === "title" ? textChildValue(node, "text") : undefined;
284
794
  return {
285
795
  id: this.instanceId(node, kind, path, timelineId),
286
796
  kind,
@@ -289,12 +799,27 @@ export class FcpxmlDocumentAdapter {
289
799
  startTime,
290
800
  durationTime,
291
801
  ...(attribute(node, "lane") !== undefined ? { lane: Number(attribute(node, "lane")) } : {}),
292
- ...(attribute(node, "ref") !== undefined ? { mediaId: String(attribute(node, "ref")) } : {}),
802
+ ...(CLIP_KINDS.has(kind) && attribute(node, "ref") !== undefined
803
+ ? { mediaId: String(attribute(node, "ref")) }
804
+ : {}),
805
+ ...(attribute(node, "framekit-attached-to") !== undefined ? { attachedTo: String(attribute(node, "framekit-attached-to")) } : {}),
806
+ ...(assetId ? { assetId } : {}),
807
+ ...(text !== undefined ? { text } : {}),
808
+ ...(attribute(node, "framekit-before-clip") !== undefined
809
+ ? { beforeClipId: String(attribute(node, "framekit-before-clip")) }
810
+ : {}),
811
+ ...(attribute(node, "framekit-after-clip") !== undefined
812
+ ? { afterClipId: String(attribute(node, "framekit-after-clip")) }
813
+ : {}),
814
+ ...visual,
293
815
  };
294
816
  }
295
817
  clipFromXml(entry, timelineId) {
296
818
  const { node, kind, path, startTime, durationTime } = entry;
297
819
  const gain = firstChild(node, "adjust-volume");
820
+ const visual = pictureInPictureProperties(node);
821
+ const fades = audioFadeProperties(node);
822
+ const role = kind === "audio" ? audioRoleFromXml(node) : undefined;
298
823
  const sourceStartValue = attribute(node, "start");
299
824
  const sourceStartTime = sourceStartValue === undefined ? undefined : parseRational(sourceStartValue);
300
825
  const sourceStart = sourceStartTime === undefined ? undefined : rationalSeconds(sourceStartTime);
@@ -308,9 +833,14 @@ export class FcpxmlDocumentAdapter {
308
833
  duration: rationalSeconds(durationTime),
309
834
  ...(sourceStart !== undefined ? { sourceStart, sourceStartTime } : {}),
310
835
  track: Number(attribute(node, "lane") ?? 0),
836
+ ...(role !== undefined ? { role } : {}),
837
+ ...(attribute(node, "framekit-attached-to") !== undefined ? { attachedTo: String(attribute(node, "framekit-attached-to")) } : {}),
311
838
  startTime,
312
839
  durationTime,
313
840
  ...(gain ? { gainDb: parseDb(attribute(gain, "amount") ?? "0dB") } : {}),
841
+ ...(fades.fadeIn !== undefined ? { fadeIn: fades.fadeIn } : {}),
842
+ ...(fades.fadeOut !== undefined ? { fadeOut: fades.fadeOut } : {}),
843
+ ...visual,
314
844
  };
315
845
  }
316
846
  instanceId(node, kind, path, timelineId) {
@@ -318,10 +848,12 @@ export class FcpxmlDocumentAdapter {
318
848
  return String(explicit ?? `${timelineId}:spine:${path}:${kind}`);
319
849
  }
320
850
  findClipNode(spine, clipId, timelineId) {
321
- return timelineEntries(spine)
322
- .filter(({ kind }) => CLIP_KINDS.has(kind))
323
- .find(({ kind, node, path }) => this.instanceId(node, kind, path, timelineId) === clipId)
324
- ?.node;
851
+ return this.findClipEntry(spine, clipId, timelineId)?.node;
852
+ }
853
+ effectAssetId(ref) {
854
+ const effect = effectResources(this.xml ?? []).find((candidate) => attribute(candidate, "id") === ref);
855
+ const identity = effect === undefined ? undefined : stableEffectIdentity(effect);
856
+ return identity === undefined ? undefined : `fcpxml:effect:${identity}`;
325
857
  }
326
858
  setAdjustVolume(node, gainDb) {
327
859
  const existing = firstChild(node, "adjust-volume");
@@ -360,20 +892,19 @@ export class FcpxmlDocumentAdapter {
360
892
  });
361
893
  }
362
894
  updateSequenceDuration(sequence, spine) {
363
- const duration = Math.max(0, ...timelineEntries(spine)
364
- .filter(({ kind }) => kind !== "marker" && kind !== "caption")
365
- .map(({ startTime, durationTime }) => rationalSeconds(startTime) + rationalSeconds(durationTime)));
366
- setAttribute(sequence, "duration", formatSeconds(duration));
895
+ setAttribute(sequence, "duration", formatRational(timelineDuration(timelineEntries(spine))));
367
896
  }
368
897
  mediaFromResources() {
369
898
  const resources = findElement(this.xml ?? [], "resources");
370
899
  return storyEntries(resources ?? {})
371
- .filter(({ kind }) => kind === "asset" || kind === "media" || kind === "effect")
900
+ .filter(({ kind }) => kind === "asset" || kind === "media")
372
901
  .map(({ node }) => {
373
902
  const durationValue = attribute(node, "duration");
903
+ const mediaKind = mediaKindFromResource(node);
374
904
  return {
375
905
  mediaId: String(attribute(node, "id") ?? ""),
376
906
  source: resolveMediaSource(String(attribute(node, "src") ?? attribute(node, "name") ?? attribute(node, "id") ?? ""), this.filePath),
907
+ ...(mediaKind ? { mediaKind } : {}),
377
908
  ...(durationValue !== undefined ? { duration: parseSeconds(durationValue) } : {}),
378
909
  };
379
910
  })
@@ -404,6 +935,98 @@ function storyEntries(node) {
404
935
  .map((child) => ({ kind: Object.keys(child).find((key) => key !== ":@") ?? kind, node: child }))
405
936
  : []);
406
937
  }
938
+ function effectResources(document) {
939
+ const resources = findElement(document, "resources");
940
+ return storyEntries(resources ?? {})
941
+ .filter(({ kind }) => kind === "effect")
942
+ .map(({ node }) => node);
943
+ }
944
+ function stableEffectIdentity(node) {
945
+ const uid = attribute(node, "uid");
946
+ return uid === undefined || String(uid).trim().length === 0 ? undefined : String(uid);
947
+ }
948
+ function elementNode(kind, values) {
949
+ return {
950
+ [kind]: [],
951
+ ":@": Object.fromEntries(Object.entries(values).map(([name, value]) => [`@_${name}`, value])),
952
+ };
953
+ }
954
+ function appendTextChild(node, kind, value) {
955
+ const elementKey = Object.keys(node).find((key) => key !== ":@");
956
+ const child = { [kind]: [{ "#text": value }] };
957
+ if (elementKey) {
958
+ node[elementKey] = [...(Array.isArray(node[elementKey]) ? node[elementKey] : []), child];
959
+ }
960
+ else {
961
+ node[kind] = [child];
962
+ }
963
+ }
964
+ function childIndex(parent, child) {
965
+ for (const value of Object.values(parent)) {
966
+ if (!Array.isArray(value))
967
+ continue;
968
+ const index = value.indexOf(child);
969
+ if (index >= 0)
970
+ return index;
971
+ }
972
+ return -1;
973
+ }
974
+ function removeChild(parent, child) {
975
+ for (const [key, value] of Object.entries(parent)) {
976
+ if (key === ":@" || !Array.isArray(value))
977
+ continue;
978
+ const index = value.indexOf(child);
979
+ if (index >= 0) {
980
+ value.splice(index, 1);
981
+ return;
982
+ }
983
+ }
984
+ }
985
+ function removeChildren(parent, kind) {
986
+ for (const [key, value] of Object.entries(parent)) {
987
+ if (key === ":@" || !Array.isArray(value))
988
+ continue;
989
+ parent[key] = value.filter((child) => Object.keys(child).find((name) => name !== ":@") !== kind);
990
+ }
991
+ }
992
+ function sourceStart(node) {
993
+ const value = attribute(node, "start");
994
+ return value === undefined ? 0 : parseSeconds(value);
995
+ }
996
+ function audioFadeProperties(node) {
997
+ const volume = firstChild(node, "adjust-volume");
998
+ const param = volume === undefined ? undefined : firstChild(volume, "param");
999
+ const fadeIn = param === undefined ? undefined : firstChild(param, "fadeIn");
1000
+ const fadeOut = param === undefined ? undefined : firstChild(param, "fadeOut");
1001
+ return {
1002
+ ...(fadeIn ? { fadeIn: parseSeconds(attribute(fadeIn, "duration") ?? "0s") } : {}),
1003
+ ...(fadeOut ? { fadeOut: parseSeconds(attribute(fadeOut, "duration") ?? "0s") } : {}),
1004
+ };
1005
+ }
1006
+ function audioRoleFromXml(node) {
1007
+ const role = attribute(node, "role");
1008
+ if (role === undefined || role === "audio")
1009
+ return "audio";
1010
+ if (role === "music")
1011
+ return "music";
1012
+ throw new Error(`FCPXML_UNSUPPORTED_AUDIO_ROLE: ${role}`);
1013
+ }
1014
+ function textChildValue(node, kind) {
1015
+ const text = firstChild(node, kind);
1016
+ if (!text)
1017
+ return undefined;
1018
+ const value = Array.isArray(text[kind]) ? text[kind][0]?.["#text"] : undefined;
1019
+ if (Array.isArray(value) && value.length > 0)
1020
+ return String(value[0]);
1021
+ if (typeof value === "string" || typeof value === "number")
1022
+ return String(value);
1023
+ return undefined;
1024
+ }
1025
+ function mediaKindCompatible(role, mediaKind) {
1026
+ if (mediaKind === undefined)
1027
+ return true;
1028
+ return role === "video" ? mediaKind === "video" : mediaKind === "audio";
1029
+ }
407
1030
  function timelineEntries(spine) {
408
1031
  const entries = [];
409
1032
  const visit = (node, parentStart, parentPath) => {
@@ -415,7 +1038,7 @@ function timelineEntries(spine) {
415
1038
  const durationTime = parseRational(attribute(child, "duration") ?? "0s");
416
1039
  const startTime = addRational(parentStart, localStart);
417
1040
  if (TIMELINE_KINDS.has(kind)) {
418
- entries.push({ kind, node: child, path, startTime, durationTime });
1041
+ entries.push({ kind, node: child, path, startTime, durationTime, parent: node, parentStartTime: parentStart });
419
1042
  }
420
1043
  visit(child, startTime, path);
421
1044
  });
@@ -423,6 +1046,15 @@ function timelineEntries(spine) {
423
1046
  visit(spine, { value: "0", timescale: "1" }, "");
424
1047
  return entries;
425
1048
  }
1049
+ function timelineDuration(entries) {
1050
+ return entries
1051
+ .filter(({ kind }) => kind !== "marker" && kind !== "caption")
1052
+ .map(({ startTime, durationTime }) => addRational(startTime, durationTime))
1053
+ .reduce((maximum, endTime) => compareRational(endTime, maximum) > 0 ? endTime : maximum, {
1054
+ value: "0",
1055
+ timescale: "1",
1056
+ });
1057
+ }
426
1058
  function findElement(nodes, kind) {
427
1059
  const containers = Array.isArray(nodes) ? nodes : [nodes];
428
1060
  for (const container of containers) {
@@ -457,9 +1089,39 @@ function attributes(node) {
457
1089
  function attribute(node, name) {
458
1090
  return attributes(node)[`@_${name}`];
459
1091
  }
1092
+ function sequenceFrameDuration(sequence, document) {
1093
+ const formatId = attribute(sequence, "format");
1094
+ if (formatId === undefined)
1095
+ return undefined;
1096
+ const resources = findElement(document, "resources");
1097
+ const format = storyEntries(resources ?? {}).find((entry) => entry.kind === "format" && attribute(entry.node, "id") === String(formatId))?.node;
1098
+ const value = attribute(format ?? {}, "frameDuration");
1099
+ return value === undefined ? undefined : parseRational(value);
1100
+ }
460
1101
  function setAttribute(node, name, value) {
461
1102
  node[":@"] = { ...attributes(node), [`@_${name}`]: value };
462
1103
  }
1104
+ function removeAttribute(node, name) {
1105
+ const next = { ...attributes(node) };
1106
+ delete next[`@_${name}`];
1107
+ if (Object.keys(next).length === 0)
1108
+ delete node[":@"];
1109
+ else
1110
+ node[":@"] = next;
1111
+ }
1112
+ function insertChildAt(parent, kind, child, index) {
1113
+ const elementKey = Object.keys(parent).find((key) => key !== ":@");
1114
+ const wrapper = Object.prototype.hasOwnProperty.call(child, kind)
1115
+ ? child
1116
+ : { [kind]: [], ...child };
1117
+ if (!elementKey) {
1118
+ parent[kind] = [wrapper];
1119
+ return;
1120
+ }
1121
+ const children = Array.isArray(parent[elementKey]) ? parent[elementKey] : [];
1122
+ children.splice(index, 0, wrapper);
1123
+ parent[elementKey] = children;
1124
+ }
463
1125
  function parseSeconds(value) {
464
1126
  return rationalSeconds(parseRational(value));
465
1127
  }
@@ -503,6 +1165,11 @@ function addRational(left, right) {
503
1165
  denominator: BigInt(left.timescale) * BigInt(right.timescale),
504
1166
  });
505
1167
  }
1168
+ function compareRational(left, right) {
1169
+ const difference = BigInt(left.value) * BigInt(right.timescale)
1170
+ - BigInt(right.value) * BigInt(left.timescale);
1171
+ return difference < 0n ? -1 : difference > 0n ? 1 : 0;
1172
+ }
506
1173
  function greatestCommonDivisor(left, right) {
507
1174
  let a = left < 0n ? -left : left;
508
1175
  let b = right < 0n ? -right : right;
@@ -528,14 +1195,101 @@ function formatSeconds(value) {
528
1195
  function decimalToRational(value) {
529
1196
  const text = value.toFixed(6).replace(/0+$/, "").replace(/\.$/, "");
530
1197
  if (!text.includes("."))
531
- return { value: text, timescale: "1" };
1198
+ return rationalTime({ numerator: BigInt(text), denominator: 1n });
532
1199
  const decimals = text.split(".")[1].length;
533
1200
  const scale = 10 ** decimals;
534
- return { value: String(Math.round(value * scale)), timescale: String(scale) };
1201
+ return rationalTime({ numerator: BigInt(Math.round(value * scale)), denominator: BigInt(scale) });
535
1202
  }
536
1203
  function formatDb(value) {
537
1204
  return `${value}dB`;
538
1205
  }
1206
+ function mediaKindFromResource(node) {
1207
+ const hasVideo = attribute(node, "hasVideo");
1208
+ const hasAudio = attribute(node, "hasAudio");
1209
+ if (hasVideo === "1" || hasVideo === "true")
1210
+ return "video";
1211
+ if ((hasVideo === "0" || hasVideo === "false") && (hasAudio === "1" || hasAudio === "true"))
1212
+ return "audio";
1213
+ return undefined;
1214
+ }
1215
+ function validatePictureInPictureOperation(operation, anchorStartTime, anchorDurationTime, mediaDuration) {
1216
+ const anchorStart = rationalSeconds(anchorStartTime);
1217
+ const anchorEnd = anchorStart + rationalSeconds(anchorDurationTime);
1218
+ if (!Number.isFinite(operation.start) || !Number.isFinite(operation.duration)
1219
+ || operation.start < anchorStart
1220
+ || operation.duration <= 0
1221
+ || operation.start + operation.duration > anchorEnd
1222
+ || !Number.isInteger(operation.targetLane)
1223
+ || operation.targetLane === 0
1224
+ || !Number.isFinite(operation.position.x)
1225
+ || !Number.isFinite(operation.position.y)
1226
+ || !Number.isFinite(operation.scale)
1227
+ || operation.scale <= 0
1228
+ || mediaDuration !== undefined && operation.duration > mediaDuration) {
1229
+ throw new Error("INVALID_OPERATION: PIP timing, connected lane, position, and scale are invalid");
1230
+ }
1231
+ if (operation.crop)
1232
+ validatePictureInPictureCrop(operation.crop);
1233
+ }
1234
+ function validatePictureInPictureCrop(crop) {
1235
+ const values = [crop.top, crop.right, crop.bottom, crop.left];
1236
+ if (!values.every((value) => Number.isFinite(value) && value >= 0 && value < 1)
1237
+ || crop.left + crop.right >= 1
1238
+ || crop.top + crop.bottom >= 1) {
1239
+ throw new Error("INVALID_OPERATION: PIP crop must leave a positive source rectangle");
1240
+ }
1241
+ }
1242
+ function pictureInPictureProperties(node) {
1243
+ const transform = firstChild(node, "adjust-transform");
1244
+ const crop = firstChild(node, "adjust-crop");
1245
+ const positionValue = transform ? attribute(transform, "position") : undefined;
1246
+ const scaleValue = transform ? attribute(transform, "scale") : undefined;
1247
+ const position = positionValue === undefined ? undefined : parsePictureInPicturePosition(positionValue);
1248
+ const scale = scaleValue === undefined ? undefined : parsePictureInPictureScale(scaleValue);
1249
+ const cropRect = crop ? firstChild(crop, "crop-rect") : undefined;
1250
+ const cropKeys = ["top", "right", "bottom", "left"];
1251
+ const hasCrop = cropRect !== undefined && cropKeys.some((key) => attribute(cropRect, key) !== undefined);
1252
+ const parsedCrop = hasCrop
1253
+ ? {
1254
+ top: parsePictureInPictureNumber(cropRect && attribute(cropRect, "top"), "top crop"),
1255
+ right: parsePictureInPictureNumber(cropRect && attribute(cropRect, "right"), "right crop"),
1256
+ bottom: parsePictureInPictureNumber(cropRect && attribute(cropRect, "bottom"), "bottom crop"),
1257
+ left: parsePictureInPictureNumber(cropRect && attribute(cropRect, "left"), "left crop"),
1258
+ }
1259
+ : undefined;
1260
+ if (parsedCrop)
1261
+ validatePictureInPictureCrop(parsedCrop);
1262
+ return {
1263
+ ...(position ? { position } : {}),
1264
+ ...(scale !== undefined ? { scale } : {}),
1265
+ ...(parsedCrop ? { crop: parsedCrop } : {}),
1266
+ };
1267
+ }
1268
+ function parsePictureInPicturePosition(value) {
1269
+ const values = String(value).trim().split(/\s+/).map(Number);
1270
+ if (values.length !== 2 || !values.every(Number.isFinite)) {
1271
+ throw new Error(`FCPXML_INVALID_PIP: position ${String(value)} is not a finite pair`);
1272
+ }
1273
+ return { x: values[0], y: values[1] };
1274
+ }
1275
+ function parsePictureInPictureScale(value) {
1276
+ const values = String(value).trim().split(/\s+/).map(Number);
1277
+ if (values.length !== 2 || !values.every((candidate) => Number.isFinite(candidate) && candidate > 0)
1278
+ || values[0] !== values[1]) {
1279
+ throw new Error(`FCPXML_INVALID_PIP: scale ${String(value)} is not a positive uniform pair`);
1280
+ }
1281
+ return values[0] / 100;
1282
+ }
1283
+ function parsePictureInPictureNumber(value, label) {
1284
+ const text = String(value ?? "").trim();
1285
+ const parsed = Number(text.replace(/%$/, ""));
1286
+ if (!Number.isFinite(parsed))
1287
+ throw new Error(`FCPXML_INVALID_PIP: ${label} is not finite`);
1288
+ return text.endsWith("%") ? parsed / 100 : parsed;
1289
+ }
1290
+ function formatPictureInPicturePercentage(value) {
1291
+ return `${value * 100}%`;
1292
+ }
539
1293
  function emptyAnalyzerCapabilities() {
540
1294
  return { speechTranscribe: false, speechVad: false, audioLoudness: false, visualTrack: false };
541
1295
  }