@morshoto/framekit 0.1.5 → 0.1.6

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.
@@ -66,7 +66,8 @@ export class FcpxmlDocumentAdapter {
66
66
  projectCatalogRead: true,
67
67
  projectSelection: true,
68
68
  compositeTransactions: true,
69
- semanticOperations: { "add-marker": true },
69
+ pictureInPicture: true,
70
+ semanticOperations: { "add-marker": true, "set-gain": true, "timeline.picture-in-picture.add": true },
70
71
  },
71
72
  analyzers: emptyAnalyzerCapabilities(),
72
73
  }, { backend: "fcpxml-document" });
@@ -95,6 +96,7 @@ export class FcpxmlDocumentAdapter {
95
96
  const clips = elements
96
97
  .filter(({ kind }) => CLIP_KINDS.has(kind))
97
98
  .map((entry) => this.clipFromXml(entry, timelineId));
99
+ const frameDuration = sequenceFrameDuration(sequence, this.xml ?? []);
98
100
  const durationValue = attribute(sequence, "duration")
99
101
  ?? formatSeconds(Math.max(0, ...storyElements.map((element) => element.start + element.duration)));
100
102
  return {
@@ -105,6 +107,7 @@ export class FcpxmlDocumentAdapter {
105
107
  name: sequenceName,
106
108
  duration: parseSeconds(durationValue),
107
109
  durationTime: parseRational(durationValue),
110
+ ...(frameDuration ? { frameDuration } : {}),
108
111
  clips,
109
112
  storyElements,
110
113
  markers: this.markersFromXml(elements),
@@ -166,7 +169,8 @@ export class FcpxmlDocumentAdapter {
166
169
  const originalSignature = this.fileSignature;
167
170
  try {
168
171
  for (const operation of operations) {
169
- if (operation.type === "media.import" || operation.type.startsWith("timeline.")) {
172
+ if (operation.type === "media.import"
173
+ || operation.type.startsWith("timeline.") && operation.type !== "timeline.picture-in-picture.add") {
170
174
  throw new Error(`CAPABILITY_UNAVAILABLE: FCPXML preview does not support ${operation.type}`);
171
175
  }
172
176
  this.applyOperation(operation);
@@ -185,15 +189,27 @@ export class FcpxmlDocumentAdapter {
185
189
  if (!sameRevision(expectedRevision, this.revision())) {
186
190
  throw new Error("STALE_CONTEXT: FCPXML document changed before transaction");
187
191
  }
192
+ const originalXml = structuredClone(this.xml);
193
+ const originalSequence = this.sequence;
194
+ const originalSignature = this.fileSignature;
188
195
  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}`);
196
+ try {
197
+ for (const operation of operations) {
198
+ if (operation.type === "media.import"
199
+ || operation.type.startsWith("timeline.") && operation.type !== "timeline.picture-in-picture.add") {
200
+ throw new Error(`CAPABILITY_UNAVAILABLE: FCPXML transaction does not support ${operation.type}`);
201
+ }
202
+ this.applyOperation(operation);
192
203
  }
193
- this.applyOperation(operation);
204
+ this.sequence += 1;
205
+ await this.persist();
206
+ }
207
+ catch (error) {
208
+ this.xml = originalXml;
209
+ this.sequence = originalSequence;
210
+ this.fileSignature = originalSignature;
211
+ throw error;
194
212
  }
195
- this.sequence += 1;
196
- await this.persist();
197
213
  }
198
214
  applyOperation(operation) {
199
215
  const project = this.projectNode();
@@ -201,6 +217,11 @@ export class FcpxmlDocumentAdapter {
201
217
  const sequence = sequenceNode ?? {};
202
218
  const spine = findElement(sequence, "spine") ?? {};
203
219
  const timelineId = stableTimelineId(project, sequenceNode);
220
+ if (operation.type === "timeline.picture-in-picture.add") {
221
+ this.applyPictureInPicture(spine, timelineId, operation);
222
+ this.updateSequenceDuration(sequence, spine);
223
+ return;
224
+ }
204
225
  switch (operation.type) {
205
226
  case "rename-clip": {
206
227
  const node = this.findClipNode(spine, operation.clipId, timelineId);
@@ -249,6 +270,69 @@ export class FcpxmlDocumentAdapter {
249
270
  }
250
271
  this.updateSequenceDuration(sequence, spine);
251
272
  }
273
+ applyPictureInPicture(spine, timelineId, operation) {
274
+ const media = this.mediaFromResources().find((candidate) => candidate.mediaId === operation.mediaId);
275
+ if (!media)
276
+ throw new Error(`MEDIA_NOT_FOUND: ${operation.mediaId}`);
277
+ if (media.mediaKind !== undefined && media.mediaKind !== "video") {
278
+ throw new Error(`MEDIA_KIND_MISMATCH: ${operation.mediaId}`);
279
+ }
280
+ if (this.findClipNode(spine, operation.occurrenceId, timelineId)) {
281
+ throw new Error(`OCCURRENCE_ALREADY_EXISTS: ${operation.occurrenceId}`);
282
+ }
283
+ const anchorEntry = timelineEntries(spine)
284
+ .find(({ kind, node, path }) => CLIP_KINDS.has(kind)
285
+ && this.instanceId(node, kind, path, timelineId) === operation.attachedTo);
286
+ if (!anchorEntry)
287
+ throw new Error(`CLIP_NOT_FOUND: ${operation.attachedTo}`);
288
+ if (anchorEntry.kind !== "asset-clip" && anchorEntry.kind !== "clip"
289
+ && anchorEntry.kind !== "ref-clip" && anchorEntry.kind !== "sync-clip"
290
+ && anchorEntry.kind !== "mc-clip") {
291
+ throw new Error("INVALID_OPERATION: PIP anchor must be a video occurrence");
292
+ }
293
+ if (operation.frame) {
294
+ throw new Error("CAPABILITY_UNAVAILABLE: FCPXML picture-in-picture frame requires the native Final Cut provider");
295
+ }
296
+ validatePictureInPictureOperation(operation, anchorEntry.startTime, anchorEntry.durationTime, media.duration);
297
+ const connected = {
298
+ "asset-clip": [],
299
+ ":@": {
300
+ "@_id": operation.occurrenceId,
301
+ "@_name": media.source.split("/").pop() || operation.mediaId,
302
+ "@_ref": operation.mediaId,
303
+ "@_offset": formatSeconds(operation.start - rationalSeconds(anchorEntry.startTime)),
304
+ "@_start": "0s",
305
+ "@_duration": formatSeconds(operation.duration),
306
+ "@_lane": String(operation.targetLane),
307
+ "@_framekit-attached-to": operation.attachedTo,
308
+ },
309
+ };
310
+ appendChild(anchorEntry.node, "asset-clip", connected);
311
+ appendChild(connected, "adjust-transform", {
312
+ ":@": {
313
+ "@_position": `${operation.position.x} ${operation.position.y}`,
314
+ "@_scale": `${operation.scale * 100} ${operation.scale * 100}`,
315
+ },
316
+ });
317
+ if (operation.crop) {
318
+ appendChild(connected, "adjust-crop", {
319
+ ":@": {
320
+ "@_mode": "crop",
321
+ },
322
+ });
323
+ const crop = firstChild(connected, "adjust-crop");
324
+ if (!crop)
325
+ throw new Error("FCPXML_INVALID_PIP: crop adjustment could not be created");
326
+ appendChild(crop, "crop-rect", {
327
+ ":@": {
328
+ "@_top": formatPictureInPicturePercentage(operation.crop.top),
329
+ "@_right": formatPictureInPicturePercentage(operation.crop.right),
330
+ "@_bottom": formatPictureInPicturePercentage(operation.crop.bottom),
331
+ "@_left": formatPictureInPicturePercentage(operation.crop.left),
332
+ },
333
+ });
334
+ }
335
+ }
252
336
  async restore(snapshot, expectedRevision) {
253
337
  await this.ensureLoaded();
254
338
  if (!sameRevision(expectedRevision, this.revision())) {
@@ -281,6 +365,7 @@ export class FcpxmlDocumentAdapter {
281
365
  }
282
366
  storyElementFromXml(entry, timelineId) {
283
367
  const { node, kind, path, startTime, durationTime } = entry;
368
+ const visual = pictureInPictureProperties(node);
284
369
  return {
285
370
  id: this.instanceId(node, kind, path, timelineId),
286
371
  kind,
@@ -290,11 +375,14 @@ export class FcpxmlDocumentAdapter {
290
375
  durationTime,
291
376
  ...(attribute(node, "lane") !== undefined ? { lane: Number(attribute(node, "lane")) } : {}),
292
377
  ...(attribute(node, "ref") !== undefined ? { mediaId: String(attribute(node, "ref")) } : {}),
378
+ ...(attribute(node, "framekit-attached-to") !== undefined ? { attachedTo: String(attribute(node, "framekit-attached-to")) } : {}),
379
+ ...visual,
293
380
  };
294
381
  }
295
382
  clipFromXml(entry, timelineId) {
296
383
  const { node, kind, path, startTime, durationTime } = entry;
297
384
  const gain = firstChild(node, "adjust-volume");
385
+ const visual = pictureInPictureProperties(node);
298
386
  const sourceStartValue = attribute(node, "start");
299
387
  const sourceStartTime = sourceStartValue === undefined ? undefined : parseRational(sourceStartValue);
300
388
  const sourceStart = sourceStartTime === undefined ? undefined : rationalSeconds(sourceStartTime);
@@ -308,9 +396,11 @@ export class FcpxmlDocumentAdapter {
308
396
  duration: rationalSeconds(durationTime),
309
397
  ...(sourceStart !== undefined ? { sourceStart, sourceStartTime } : {}),
310
398
  track: Number(attribute(node, "lane") ?? 0),
399
+ ...(attribute(node, "framekit-attached-to") !== undefined ? { attachedTo: String(attribute(node, "framekit-attached-to")) } : {}),
311
400
  startTime,
312
401
  durationTime,
313
402
  ...(gain ? { gainDb: parseDb(attribute(gain, "amount") ?? "0dB") } : {}),
403
+ ...visual,
314
404
  };
315
405
  }
316
406
  instanceId(node, kind, path, timelineId) {
@@ -371,9 +461,11 @@ export class FcpxmlDocumentAdapter {
371
461
  .filter(({ kind }) => kind === "asset" || kind === "media" || kind === "effect")
372
462
  .map(({ node }) => {
373
463
  const durationValue = attribute(node, "duration");
464
+ const mediaKind = mediaKindFromResource(node);
374
465
  return {
375
466
  mediaId: String(attribute(node, "id") ?? ""),
376
467
  source: resolveMediaSource(String(attribute(node, "src") ?? attribute(node, "name") ?? attribute(node, "id") ?? ""), this.filePath),
468
+ ...(mediaKind ? { mediaKind } : {}),
377
469
  ...(durationValue !== undefined ? { duration: parseSeconds(durationValue) } : {}),
378
470
  };
379
471
  })
@@ -457,6 +549,15 @@ function attributes(node) {
457
549
  function attribute(node, name) {
458
550
  return attributes(node)[`@_${name}`];
459
551
  }
552
+ function sequenceFrameDuration(sequence, document) {
553
+ const formatId = attribute(sequence, "format");
554
+ if (formatId === undefined)
555
+ return undefined;
556
+ const resources = findElement(document, "resources");
557
+ const format = storyEntries(resources ?? {}).find((entry) => entry.kind === "format" && attribute(entry.node, "id") === String(formatId))?.node;
558
+ const value = attribute(format ?? {}, "frameDuration");
559
+ return value === undefined ? undefined : parseRational(value);
560
+ }
460
561
  function setAttribute(node, name, value) {
461
562
  node[":@"] = { ...attributes(node), [`@_${name}`]: value };
462
563
  }
@@ -536,6 +637,93 @@ function decimalToRational(value) {
536
637
  function formatDb(value) {
537
638
  return `${value}dB`;
538
639
  }
640
+ function mediaKindFromResource(node) {
641
+ const hasVideo = attribute(node, "hasVideo");
642
+ const hasAudio = attribute(node, "hasAudio");
643
+ if (hasVideo === "1" || hasVideo === "true")
644
+ return "video";
645
+ if ((hasVideo === "0" || hasVideo === "false") && (hasAudio === "1" || hasAudio === "true"))
646
+ return "audio";
647
+ return undefined;
648
+ }
649
+ function validatePictureInPictureOperation(operation, anchorStartTime, anchorDurationTime, mediaDuration) {
650
+ const anchorStart = rationalSeconds(anchorStartTime);
651
+ const anchorEnd = anchorStart + rationalSeconds(anchorDurationTime);
652
+ if (!Number.isFinite(operation.start) || !Number.isFinite(operation.duration)
653
+ || operation.start < anchorStart
654
+ || operation.duration <= 0
655
+ || operation.start + operation.duration > anchorEnd
656
+ || !Number.isInteger(operation.targetLane)
657
+ || operation.targetLane === 0
658
+ || !Number.isFinite(operation.position.x)
659
+ || !Number.isFinite(operation.position.y)
660
+ || !Number.isFinite(operation.scale)
661
+ || operation.scale <= 0
662
+ || mediaDuration !== undefined && operation.duration > mediaDuration) {
663
+ throw new Error("INVALID_OPERATION: PIP timing, connected lane, position, and scale are invalid");
664
+ }
665
+ if (operation.crop)
666
+ validatePictureInPictureCrop(operation.crop);
667
+ }
668
+ function validatePictureInPictureCrop(crop) {
669
+ const values = [crop.top, crop.right, crop.bottom, crop.left];
670
+ if (!values.every((value) => Number.isFinite(value) && value >= 0 && value < 1)
671
+ || crop.left + crop.right >= 1
672
+ || crop.top + crop.bottom >= 1) {
673
+ throw new Error("INVALID_OPERATION: PIP crop must leave a positive source rectangle");
674
+ }
675
+ }
676
+ function pictureInPictureProperties(node) {
677
+ const transform = firstChild(node, "adjust-transform");
678
+ const crop = firstChild(node, "adjust-crop");
679
+ const positionValue = transform ? attribute(transform, "position") : undefined;
680
+ const scaleValue = transform ? attribute(transform, "scale") : undefined;
681
+ const position = positionValue === undefined ? undefined : parsePictureInPicturePosition(positionValue);
682
+ const scale = scaleValue === undefined ? undefined : parsePictureInPictureScale(scaleValue);
683
+ const cropRect = crop ? firstChild(crop, "crop-rect") : undefined;
684
+ const cropKeys = ["top", "right", "bottom", "left"];
685
+ const hasCrop = cropRect !== undefined && cropKeys.some((key) => attribute(cropRect, key) !== undefined);
686
+ const parsedCrop = hasCrop
687
+ ? {
688
+ top: parsePictureInPictureNumber(cropRect && attribute(cropRect, "top"), "top crop"),
689
+ right: parsePictureInPictureNumber(cropRect && attribute(cropRect, "right"), "right crop"),
690
+ bottom: parsePictureInPictureNumber(cropRect && attribute(cropRect, "bottom"), "bottom crop"),
691
+ left: parsePictureInPictureNumber(cropRect && attribute(cropRect, "left"), "left crop"),
692
+ }
693
+ : undefined;
694
+ if (parsedCrop)
695
+ validatePictureInPictureCrop(parsedCrop);
696
+ return {
697
+ ...(position ? { position } : {}),
698
+ ...(scale !== undefined ? { scale } : {}),
699
+ ...(parsedCrop ? { crop: parsedCrop } : {}),
700
+ };
701
+ }
702
+ function parsePictureInPicturePosition(value) {
703
+ const values = String(value).trim().split(/\s+/).map(Number);
704
+ if (values.length !== 2 || !values.every(Number.isFinite)) {
705
+ throw new Error(`FCPXML_INVALID_PIP: position ${String(value)} is not a finite pair`);
706
+ }
707
+ return { x: values[0], y: values[1] };
708
+ }
709
+ function parsePictureInPictureScale(value) {
710
+ const values = String(value).trim().split(/\s+/).map(Number);
711
+ if (values.length !== 2 || !values.every((candidate) => Number.isFinite(candidate) && candidate > 0)
712
+ || values[0] !== values[1]) {
713
+ throw new Error(`FCPXML_INVALID_PIP: scale ${String(value)} is not a positive uniform pair`);
714
+ }
715
+ return values[0] / 100;
716
+ }
717
+ function parsePictureInPictureNumber(value, label) {
718
+ const text = String(value ?? "").trim();
719
+ const parsed = Number(text.replace(/%$/, ""));
720
+ if (!Number.isFinite(parsed))
721
+ throw new Error(`FCPXML_INVALID_PIP: ${label} is not finite`);
722
+ return text.endsWith("%") ? parsed / 100 : parsed;
723
+ }
724
+ function formatPictureInPicturePercentage(value) {
725
+ return `${value * 100}%`;
726
+ }
539
727
  function emptyAnalyzerCapabilities() {
540
728
  return { speechTranscribe: false, speechVad: false, audioLoudness: false, visualTrack: false };
541
729
  }
@@ -1,6 +1,7 @@
1
1
  export * from "./fcpxml.js";
2
2
  export * from "./live.js";
3
3
  export * from "./connection.js";
4
+ export * from "./canonical.js";
4
5
  export * from "./session.js";
5
6
  export * from "./analyzers.js";
6
7
  export * from "./assets.js";