@morshoto/framekit 0.1.17 → 0.2.2

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 (58) hide show
  1. package/README.md +25 -14
  2. package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +8 -2
  3. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.js +275 -0
  4. package/dist-package/adapters/final-cut/typescript/src/canonical.js +557 -84
  5. package/dist-package/adapters/final-cut/typescript/src/connection.js +10 -3
  6. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +6 -0
  7. package/dist-package/adapters/final-cut/typescript/src/experimental.js +8 -0
  8. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +150 -37
  9. package/dist-package/adapters/final-cut/typescript/src/index.js +2 -7
  10. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +60 -1
  11. package/dist-package/adapters/final-cut/typescript/src/live.js +29 -4
  12. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.js +175 -0
  13. package/dist-package/adapters/final-cut/typescript/src/native-session.js +11 -6
  14. package/dist-package/adapters/final-cut/typescript/src/native.js +201 -82
  15. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +214 -0
  16. package/dist-package/adapters/final-cut/typescript/src/publisher.js +1008 -243
  17. package/dist-package/adapters/final-cut/typescript/src/session.js +49 -14
  18. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +203 -49
  19. package/dist-package/adapters/headless/typescript/src/audio-output.js +3 -0
  20. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +48 -20
  21. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +9 -4
  22. package/dist-package/apps/cli/src/dev-doctor.js +198 -0
  23. package/dist-package/apps/cli/src/headless-projects.js +5 -0
  24. package/dist-package/apps/cli/src/main.js +76 -19
  25. package/dist-package/apps/mcp-server/runtime/speech-analyzer-wrapper.mjs +54 -0
  26. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +181 -0
  27. package/dist-package/apps/mcp-server/src/build-alignment.js +59 -0
  28. package/dist-package/apps/mcp-server/src/build-identity.js +30 -0
  29. package/dist-package/apps/mcp-server/src/build-identity.json +5 -0
  30. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.js +18 -0
  31. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.js +3 -0
  32. package/dist-package/apps/mcp-server/src/headless-project-snapshot.js +101 -0
  33. package/dist-package/apps/mcp-server/src/main.js +50 -21
  34. package/dist-package/apps/mcp-server/src/materialization-jobs.js +143 -10
  35. package/dist-package/apps/mcp-server/src/routing.js +2 -0
  36. package/dist-package/apps/mcp-server/src/server.js +986 -180
  37. package/dist-package/apps/mcp-server/src/tools/skills/catalog.js +142 -0
  38. package/dist-package/apps/mcp-server/src/tools/skills/metadata.js +71 -0
  39. package/dist-package/apps/mcp-server/src/tools/skills/register.js +101 -0
  40. package/dist-package/apps/mcp-server/src/version.js +21 -2
  41. package/dist-package/packages/headless-application/src/headless-projects.js +942 -0
  42. package/dist-package/packages/headless-application/src/index.js +1 -0
  43. package/dist-package/packages/runtime/src/application/media-analysis-service.js +15 -5
  44. package/dist-package/packages/runtime/src/application/project-service.js +5 -1
  45. package/dist-package/packages/runtime/src/application/project-store.js +13 -36
  46. package/dist-package/packages/runtime/src/application/transaction-store.js +1 -1
  47. package/dist-package/packages/runtime/src/capabilities.js +1 -1
  48. package/dist-package/packages/runtime/src/context/context-engine.js +22 -16
  49. package/dist-package/packages/runtime/src/context/context-service.js +2 -2
  50. package/dist-package/packages/runtime/src/editing/edit-service.js +76 -10
  51. package/dist-package/packages/runtime/src/index.js +1 -0
  52. package/dist-package/packages/runtime/src/runtime.js +22 -7
  53. package/dist-package/packages/runtime/src/timeline/editing-session.js +23 -2
  54. package/dist-package/packages/testkit/src/in-memory-editor.js +3 -3
  55. package/dist-package/packages/testkit/src/index.js +1 -0
  56. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.js +192 -0
  57. package/package.json +36 -14
  58. package/dist-package/apps/mcp-server/src/headless-projects.js +0 -370
@@ -5,11 +5,20 @@ export class FinalCutSessionAdapter {
5
5
  constructor(options) {
6
6
  this.options = options;
7
7
  }
8
+ withCanonicalReadScope(operation) {
9
+ const provider = this.options.snapshot ?? this.options.live;
10
+ return provider?.withCanonicalReadScope?.(operation) ?? operation();
11
+ }
8
12
  async getIdentity() {
9
13
  if (this.options.snapshot && this.options.live) {
10
14
  try {
11
15
  const live = await this.options.live.getIdentity();
12
- return { name: "Final Cut Pro", version: live.version, backend: "final-cut-session" };
16
+ return {
17
+ name: "Final Cut Pro",
18
+ version: live.version,
19
+ backend: "final-cut-session",
20
+ ...(live.buildFingerprint ? { buildFingerprint: live.buildFingerprint } : {}),
21
+ };
13
22
  }
14
23
  catch {
15
24
  return { name: "Final Cut Pro", version: "FCPXML + live", backend: "final-cut-session" };
@@ -62,6 +71,7 @@ export class FinalCutSessionAdapter {
62
71
  ? live
63
72
  : snapshot;
64
73
  const operationCapabilities = operationRuntimeCapabilities?.editor;
74
+ const projectSelectionCapabilities = snapshot?.editor.projectSelection ? snapshot.editor : live?.editor;
65
75
  const operationAdapter = hasExplicitDocumentPair
66
76
  ? this.options.mutation
67
77
  : liveMutation
@@ -99,6 +109,18 @@ export class FinalCutSessionAdapter {
99
109
  guarantee: "observed",
100
110
  }
101
111
  : false;
112
+ const snapshotSelection = Boolean(snapshot?.editor.projectSelection
113
+ && this.options.snapshot?.selectProject
114
+ && projectSelectionMode(snapshot.editor) !== "unavailable");
115
+ const liveSelection = Boolean(!this.options.snapshot
116
+ && live?.editor.projectSelection
117
+ && this.options.live?.selectProject
118
+ && projectSelectionMode(live.editor) !== "unavailable");
119
+ const projectSelection = snapshotSelection || liveSelection;
120
+ const selectionCapabilities = this.options.snapshot ? snapshot?.editor : live?.editor;
121
+ const selectionMode = projectSelection && selectionCapabilities
122
+ ? projectSelectionMode(selectionCapabilities)
123
+ : "unavailable";
102
124
  return withCapabilityFamilies({
103
125
  editor: {
104
126
  ...operationCapabilities,
@@ -120,7 +142,8 @@ export class FinalCutSessionAdapter {
120
142
  projectCatalogRead: Boolean(snapshot?.editor.projectCatalogRead
121
143
  || (!this.options.snapshot && live?.editor.projectCatalogRead)
122
144
  || this.options.backgroundCatalog),
123
- projectSelection: Boolean(snapshot?.editor.projectSelection || (!this.options.snapshot && live?.editor.projectSelection)),
145
+ projectSelection,
146
+ projectSelectionMode: selectionMode,
124
147
  compositeTransactions,
125
148
  },
126
149
  analyzers: {
@@ -176,14 +199,16 @@ export class FinalCutSessionAdapter {
176
199
  async readProject() {
177
200
  if (this.options.snapshot)
178
201
  return this.options.snapshot.readProject();
179
- const liveCapabilities = await optionalCapabilities(this.options.live);
180
- if (liveCapabilities?.editor.canonicalTimelineMode !== "metadata-only"
181
- && !this.options.mutation
182
- && liveCapabilities?.editor.timelineSnapshotRead
183
- && this.options.live?.readProject) {
184
- return this.options.live.readProject();
185
- }
186
- throw new Error("CAPABILITY_UNAVAILABLE: Final Cut session has no snapshot provider");
202
+ return this.withCanonicalReadScope(async () => {
203
+ const liveCapabilities = await optionalCapabilities(this.options.live);
204
+ if (liveCapabilities?.editor.canonicalTimelineMode !== "metadata-only"
205
+ && !this.options.mutation
206
+ && liveCapabilities?.editor.timelineSnapshotRead
207
+ && this.options.live?.readProject) {
208
+ return this.options.live.readProject();
209
+ }
210
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut session has no snapshot provider");
211
+ });
187
212
  }
188
213
  async apply(operation, expectedRevision) {
189
214
  if (this.options.snapshot && this.options.mutation) {
@@ -294,6 +319,14 @@ export class FinalCutSessionAdapter {
294
319
  validateProjectCatalog(catalog);
295
320
  const after = await optionalLiveState(this.options.live);
296
321
  const identity = before && after ? await optionalIdentity(this.options.live) : undefined;
322
+ const selectionProvider = this.options.snapshot ?? this.options.live;
323
+ const selectionCapabilities = await optionalCapabilities(selectionProvider, { probeCanonicalSnapshot: false });
324
+ const selectionMode = selectionCapabilities
325
+ ? projectSelectionMode(selectionCapabilities.editor)
326
+ : "unavailable";
327
+ const selectionAvailable = Boolean(selectionProvider?.selectProject
328
+ && selectionCapabilities?.editor.projectSelection
329
+ && selectionMode !== "unavailable");
297
330
  return reconcileProjectCatalog(catalog, {
298
331
  ...(before && after ? { before, after } : {}),
299
332
  provenance: {
@@ -310,9 +343,11 @@ export class FinalCutSessionAdapter {
310
343
  },
311
344
  } : {}),
312
345
  selection: {
313
- available: false,
314
- mode: "unavailable",
315
- unavailableReason: "project selection is not exposed by the background provider",
346
+ available: selectionAvailable,
347
+ mode: selectionAvailable ? selectionMode : "unavailable",
348
+ ...(!selectionAvailable ? {
349
+ unavailableReason: "project selection is not exposed by the background provider",
350
+ } : {}),
316
351
  },
317
352
  },
318
353
  });
@@ -386,7 +421,7 @@ async function optionalIdentity(live) {
386
421
  }
387
422
  async function optionalProjectSelectionCapability(live) {
388
423
  try {
389
- return Boolean((await live?.getCapabilities())?.editor.projectSelection);
424
+ return Boolean((await live?.getCapabilities({ probeCanonicalSnapshot: false }))?.editor.projectSelection);
390
425
  }
391
426
  catch {
392
427
  return false;
@@ -4,6 +4,7 @@ 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
6
  const BASIC_TITLE_EFFECT_ID = "effect-basic-title";
7
+ const AUDIO_FORMAT_ID = "format-audio";
7
8
  const BASIC_TITLE_EFFECT_UID = ".../Titles.localized/Bumper:Opener.localized/Basic Title.localized/Basic Title.moti";
8
9
  /**
9
10
  * Compiles a complete provider-neutral Timeline IR into a new FCPXML
@@ -25,24 +26,31 @@ export function compileTimelineIrToFcpxml(timeline, options) {
25
26
  const resourceIds = createResourceIds(timeline);
26
27
  const resourceNames = uniqueResourceNames(timeline);
27
28
  const resources = [...timeline.resources].sort((left, right) => left.id.localeCompare(right.id));
28
- 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))));
29
30
  const elementIds = new Set();
30
31
  for (const element of elements) {
31
32
  if (elementIds.has(element.id))
32
33
  throw new Error(`FCPXML_DUPLICATE_ELEMENT_ID: ${element.id}`);
33
34
  elementIds.add(element.id);
34
35
  }
35
- for (const item of [...timeline.sequence.markers, ...timeline.sequence.captions]) {
36
- if (elementIds.has(item.id))
37
- throw new Error(`FCPXML_DUPLICATE_ELEMENT_ID: ${item.id}`);
38
- elementIds.add(item.id);
39
- }
40
- 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;
41
44
  const lines = [
42
45
  '<?xml version="1.0" encoding="UTF-8"?>',
46
+ "<!DOCTYPE fcpxml>",
43
47
  `<fcpxml version="${FRAMEKIT_FCPXML_VERSION}">`,
44
48
  " <resources>",
45
- ` <format id="${formatId}" frameDuration="${formatRational(timeline.sequence.frameDuration, "sequence.frameDuration")}" />`,
49
+ ` <format id="${formatId}"${projectFormatName ? ` name="${projectFormatName}"` : ""} frameDuration="${formatRational(timeline.sequence.frameDuration, "sequence.frameDuration")}"${projectDimensions} />`,
50
+ ...(resources.some((resource) => resource.mediaKind === "audio")
51
+ ? [` <format id="${AUDIO_FORMAT_ID}" name="FFFrameRateUndefined" />`]
52
+ : []),
53
+ ...resources.flatMap((resource) => renderResourceFormat(resource, resourceIds.get(resource.id))),
46
54
  ...(timeline.sequence.titles?.length
47
55
  ? [` <effect id="${BASIC_TITLE_EFFECT_ID}" name="Basic Title" uid="${BASIC_TITLE_EFFECT_UID}" />`]
48
56
  : []),
@@ -51,17 +59,9 @@ export function compileTimelineIrToFcpxml(timeline, options) {
51
59
  " <library>",
52
60
  ` <event uid="${xmlEscape(options.target.eventUid)}" name="${xmlEscape(options.target.eventName ?? "Framekit Event")}">`,
53
61
  ` <project uid="${xmlEscape(destination.projectUid)}" name="${xmlEscape(destination.projectName)}">`,
54
- ` <sequence uid="${xmlEscape(destination.sequenceUid)}" name="${xmlEscape(destination.sequenceName)}" format="${formatId}" duration="${formatRational(timeline.sequence.durationTime, "sequence.durationTime")}">`,
62
+ ` <sequence format="${formatId}" duration="${formatRational(timeline.sequence.durationTime, "sequence.durationTime")}">`,
55
63
  " <spine>",
56
64
  ...renderElements(elements),
57
- ...timeline.sequence.markers
58
- .slice()
59
- .sort(compareTimedItems)
60
- .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)}" />`),
61
- ...timeline.sequence.captions
62
- .slice()
63
- .sort(compareTimedItems)
64
- .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)}" />`),
65
65
  " </spine>",
66
66
  " </sequence>",
67
67
  " </project>",
@@ -132,6 +132,12 @@ function materializationCoverage(timeline, destinationMode, elements) {
132
132
  "primary-storyline-order",
133
133
  "provenance",
134
134
  ]);
135
+ const degraded = new Set();
136
+ if (elements.some(({ frameAlignmentAdjusted }) => frameAlignmentAdjusted)) {
137
+ degraded.add("video-edit-frame-rounding");
138
+ }
139
+ if (elements.some(({ sourceRangeAdjusted }) => sourceRangeAdjusted))
140
+ exact.delete("source-ranges");
135
141
  if (elements.some(({ parentId }) => parentId !== undefined))
136
142
  exact.add("connected-elements");
137
143
  if (timeline.sequence.occurrences.some(({ role }) => role !== undefined))
@@ -149,7 +155,80 @@ function materializationCoverage(timeline, destinationMode, elements) {
149
155
  exact.add("markers");
150
156
  if (timeline.sequence.captions.length > 0)
151
157
  exact.add("captions");
152
- return { exact: [...exact].sort(), degraded: [], unsupported: [] };
158
+ return { exact: [...exact].sort(), degraded: [...degraded].sort(), unsupported: [] };
159
+ }
160
+ function alignRenderableElements(elements, frameDuration, audioResourceIds) {
161
+ return elements.map((element) => {
162
+ if (element.kind === "asset-clip" && element.resourceId !== undefined && audioResourceIds.has(element.resourceId)) {
163
+ return element;
164
+ }
165
+ const endTime = addExactTimes(element.startTime, element.durationTime);
166
+ const startTime = snapTimeToFrame(element.startTime, frameDuration);
167
+ const alignedEndTime = snapTimeToFrame(endTime, frameDuration);
168
+ const durationTime = subtractRational(alignedEndTime, startTime, `${element.id}.durationTime`);
169
+ const zero = { value: "0", timescale: "1" };
170
+ if (compareExactTimes(element.durationTime, zero) > 0 && compareExactTimes(durationTime, zero) === 0) {
171
+ throw new Error(`FCPXML_EDIT_BELOW_FRAME_RESOLUTION: ${element.id}`);
172
+ }
173
+ const sourceStartTime = element.sourceStartTime
174
+ ? snapTimeToFrame(element.sourceStartTime, frameDuration)
175
+ : undefined;
176
+ const adjusted = compareExactTimes(startTime, element.startTime) !== 0
177
+ || compareExactTimes(durationTime, element.durationTime) !== 0
178
+ || sourceStartTime !== undefined && compareExactTimes(sourceStartTime, element.sourceStartTime) !== 0;
179
+ const sourceRangeAdjusted = element.kind === "asset-clip"
180
+ && (compareExactTimes(durationTime, element.durationTime) !== 0
181
+ || sourceStartTime !== undefined && compareExactTimes(sourceStartTime, element.sourceStartTime) !== 0);
182
+ return {
183
+ ...element,
184
+ startTime,
185
+ durationTime,
186
+ ...(sourceStartTime ? { sourceStartTime } : {}),
187
+ ...(adjusted ? { frameAlignmentAdjusted: true } : {}),
188
+ ...(sourceRangeAdjusted ? { sourceRangeAdjusted: true } : {}),
189
+ };
190
+ });
191
+ }
192
+ function snapTimeToFrame(value, frameDuration) {
193
+ const time = parseExactRational(value);
194
+ const frame = parseExactRational(frameDuration);
195
+ if (time.value < 0n || frame.value <= 0n)
196
+ throw new Error("FCPXML_INVALID_TIME: frame alignment requires non-negative time and positive frame duration");
197
+ const frameNumerator = time.value * frame.timescale;
198
+ const frameDenominator = time.timescale * frame.value;
199
+ let frames = frameNumerator / frameDenominator;
200
+ if ((frameNumerator % frameDenominator) * 2n >= frameDenominator)
201
+ frames += 1n;
202
+ const numerator = frames * frame.value;
203
+ const denominator = frame.timescale;
204
+ const divisor = greatestCommonDivisor(numerator, denominator);
205
+ return { value: String(numerator / divisor), timescale: String(denominator / divisor) };
206
+ }
207
+ function predefinedVideoFormatName(width, height, frameDuration) {
208
+ const raster = width === 1280 && height === 720
209
+ ? "720p"
210
+ : width === 1920 && height === 1080
211
+ ? "1080p"
212
+ : width === 3840 && height === 2160 || width === 4096 && height === 2160
213
+ ? `${width}x${height}p`
214
+ : undefined;
215
+ if (!raster)
216
+ return undefined;
217
+ const parts = parseExactRational(frameDuration);
218
+ const divisor = greatestCommonDivisor(parts.value, parts.timescale);
219
+ const rate = `${parts.value / divisor}/${parts.timescale / divisor}`;
220
+ const suffix = {
221
+ "1001/24000": "2398",
222
+ "1/24": "24",
223
+ "1/25": "25",
224
+ "1001/30000": "2997",
225
+ "1/30": "30",
226
+ "1/50": "50",
227
+ "1001/60000": "5994",
228
+ "1/60": "60",
229
+ };
230
+ const frameRate = suffix[rate];
231
+ return frameRate ? `FFVideoFormat${raster}${frameRate}` : undefined;
153
232
  }
154
233
  function validateTarget(target) {
155
234
  if (!target || target.provider !== "final-cut")
@@ -171,17 +250,18 @@ function resolveDestination(timeline, target) {
171
250
  projectUid: target.projectUid,
172
251
  sequenceUid: target.sequenceUid,
173
252
  projectName: timeline.project.name,
174
- sequenceName: timeline.sequence.name,
253
+ sequenceName: timeline.project.name,
175
254
  };
176
255
  }
177
256
  const revisionKey = shortHash(`${timeline.project.id}:${timeline.sequence.id}:${timeline.revision.id}:${timeline.revision.sequence}:${timeline.revision.timestamp}:${timelineIrDigest(timeline)}`);
178
257
  const revisionName = `${safeId(timeline.revision.id)}-${timeline.revision.sequence}`;
258
+ const projectName = `${timeline.project.name} (Framekit ${revisionName}-${revisionKey})`;
179
259
  return {
180
260
  mode: "versioned",
181
261
  projectUid: `${safeId(target.projectUid)}-framekit-${revisionKey}`,
182
262
  sequenceUid: `${safeId(target.sequenceUid)}-framekit-${revisionKey}`,
183
- projectName: `${timeline.project.name} (Framekit ${revisionName}-${revisionKey})`,
184
- sequenceName: `${timeline.sequence.name} (Framekit ${revisionName}-${revisionKey})`,
263
+ projectName,
264
+ sequenceName: projectName,
185
265
  };
186
266
  }
187
267
  function createResourceIds(timeline) {
@@ -228,12 +308,35 @@ function renderResource(resource, id, name) {
228
308
  throw new Error(`FCPXML_RESOURCE_SOURCE_UNSUPPORTED: resource ${resource.id} has an invalid file URL: ${error instanceof Error ? error.message : String(error)}`);
229
309
  }
230
310
  const videoAttribute = resource.mediaKind === "video" ? ' hasVideo="1"' : ' hasVideo="0"';
311
+ const metadata = resource.metadata;
312
+ const video = metadata?.streams.find((stream) => stream.kind === "video");
313
+ const audio = metadata?.streams.find((stream) => stream.kind === "audio");
314
+ const timingAttributes = metadata
315
+ ? ` start="0s" duration="${formatRational(metadata.durationTime, `resource ${resource.id}.durationTime`)}"`
316
+ : "";
317
+ const formatAttribute = video?.width && video.height && video.frameRate
318
+ ? ` format="format-${id}"`
319
+ : resource.mediaKind === "audio"
320
+ ? ` format="${AUDIO_FORMAT_ID}"`
321
+ : "";
231
322
  const audioAttribute = resource.mediaKind === "audio"
232
323
  ? ' hasAudio="1"'
233
- : resource.metadata?.streams
234
- ? ` hasAudio="${resource.metadata.streams.some((stream) => stream.kind === "audio") ? "1" : "0"}"`
324
+ : metadata?.streams
325
+ ? ` hasAudio="${audio ? "1" : "0"}"`
235
326
  : "";
236
- return ` <asset id="${xmlEscape(id)}" name="${xmlEscape(name)}" src="${xmlEscape(src)}"${videoAttribute}${audioAttribute} />`;
327
+ const sourceAttributes = `${video ? ' videoSources="1"' : ""}${audio ? ' audioSources="1"' : ""}`;
328
+ const audioDetails = audio?.channels && audio.sampleRate
329
+ ? ` audioChannels="${audio.channels}" audioRate="${audio.sampleRate}"`
330
+ : "";
331
+ return ` <asset id="${xmlEscape(id)}" name="${xmlEscape(name)}"${timingAttributes}${videoAttribute}${formatAttribute}${audioAttribute}${sourceAttributes}${audioDetails}><media-rep kind="original-media" src="${xmlEscape(src)}" /></asset>`;
332
+ }
333
+ function renderResourceFormat(resource, id) {
334
+ const video = resource.metadata?.streams.find((stream) => stream.kind === "video");
335
+ if (!video?.width || !video.height || !video.frameRate)
336
+ return [];
337
+ const frameDuration = { value: video.frameRate.timescale, timescale: video.frameRate.value };
338
+ const formatName = predefinedVideoFormatName(video.width, video.height, frameDuration);
339
+ return [` <format id="format-${id}"${formatName ? ` name="${formatName}"` : ""} frameDuration="${formatRational(frameDuration, `resource ${resource.id}.frameRate`)}" width="${video.width}" height="${video.height}" />`];
237
340
  }
238
341
  function renderableElements(timeline, resourceIds) {
239
342
  const occurrenceIds = new Set(timeline.sequence.occurrences.map(({ id }) => id));
@@ -258,8 +361,40 @@ function renderableElements(timeline, resourceIds) {
258
361
  for (const title of timeline.sequence.titles ?? []) {
259
362
  elements.push(renderableTitle(title, timeline));
260
363
  }
364
+ for (const marker of timeline.sequence.markers) {
365
+ elements.push({
366
+ id: marker.id,
367
+ kind: "marker",
368
+ startTime: marker.startTime,
369
+ durationTime: marker.durationTime,
370
+ parentId: primaryAnchorForTime("marker", marker.id, marker.startTime, marker.durationTime, elements),
371
+ name: marker.name,
372
+ });
373
+ }
374
+ for (const caption of timeline.sequence.captions) {
375
+ elements.push({
376
+ id: caption.id,
377
+ kind: "caption",
378
+ startTime: caption.startTime,
379
+ durationTime: caption.durationTime,
380
+ parentId: primaryAnchorForTime("caption", caption.id, caption.startTime, caption.durationTime, elements),
381
+ text: caption.text,
382
+ });
383
+ }
261
384
  return elements;
262
385
  }
386
+ function primaryAnchorForTime(kind, id, startTime, durationTime, elements) {
387
+ const endTime = addExactTimes(startTime, durationTime);
388
+ const anchor = elements
389
+ .filter((element) => element.parentId === undefined
390
+ && (element.kind === "gap" || (element.kind === "asset-clip" && element.role === undefined)))
391
+ .filter((element) => compareExactTimes(startTime, element.startTime) >= 0
392
+ && compareExactTimes(endTime, addExactTimes(element.startTime, element.durationTime)) <= 0)
393
+ .sort((left, right) => compareExactTimes(right.startTime, left.startTime))[0];
394
+ if (!anchor)
395
+ throw new Error(`FCPXML_${kind.toUpperCase()}_ANCHOR_NOT_FOUND: ${id}`);
396
+ return anchor.id;
397
+ }
263
398
  function renderableTitle(title, timeline) {
264
399
  const titleEnd = addExactTimes(title.startTime, title.durationTime);
265
400
  const parent = timeline.sequence.occurrences.find((occurrence) => {
@@ -315,6 +450,7 @@ function renderOccurrence(occurrence, timeline, resourceIds, occurrenceIds) {
315
450
  resourceId: resource,
316
451
  ...(occurrence.sourceStartTime ? { sourceStartTime: occurrence.sourceStartTime } : {}),
317
452
  ...(occurrence.role === "audio" || occurrence.role === "music" ? { role: occurrence.role } : {}),
453
+ ...(occurrence.nativeAudioRole ? { nativeAudioRole: occurrence.nativeAudioRole } : {}),
318
454
  ...(occurrence.gainDb !== undefined ? { gainDb: occurrence.gainDb } : {}),
319
455
  ...(occurrence.enabled !== undefined ? { enabled: occurrence.enabled } : {}),
320
456
  };
@@ -341,8 +477,15 @@ function renderElements(elements) {
341
477
  siblings.push(element);
342
478
  byParent.set(element.parentId, siblings);
343
479
  }
344
- for (const siblings of byParent.values())
345
- siblings.sort(compareTimedItems);
480
+ for (const siblings of byParent.values()) {
481
+ siblings.sort((left, right) => {
482
+ if (left.kind === "marker" && right.kind !== "marker")
483
+ return 1;
484
+ if (right.kind === "marker" && left.kind !== "marker")
485
+ return -1;
486
+ return compareTimedItems(left, right);
487
+ });
488
+ }
346
489
  const rendered = new Set();
347
490
  const lines = [];
348
491
  const render = (parentId, indent) => {
@@ -350,7 +493,6 @@ function renderElements(elements) {
350
493
  if (rendered.has(element.id))
351
494
  throw new Error(`FCPXML_CYCLIC_ATTACHMENT: ${element.id}`);
352
495
  rendered.add(element.id);
353
- const children = byParent.get(element.id) ?? [];
354
496
  const parentElement = element.parentId === undefined ? undefined : byId.get(element.parentId);
355
497
  const parentStartTime = element.parentId === undefined
356
498
  ? { value: "0", timescale: "1" }
@@ -359,52 +501,64 @@ function renderElements(elements) {
359
501
  throw new Error(`FCPXML_ATTACHMENT_TARGET_NOT_FOUND: ${element.id} -> ${element.parentId}`);
360
502
  const localStartTime = subtractRational(element.startTime, parentStartTime, `${element.id}.startTime`);
361
503
  const offsetTime = parentElement?.kind === "asset-clip"
362
- && (element.kind === "title" || element.role === "music")
504
+ && (element.kind === "title" || element.kind === "caption" || element.kind === "marker" || element.role === "music")
363
505
  && parentElement.sourceStartTime !== undefined
364
506
  ? addExactTimes(localStartTime, parentElement.sourceStartTime)
365
507
  : localStartTime;
366
508
  const attributes = element.kind === "asset-clip"
367
509
  ? [
368
- `id="${xmlEscape(element.id)}"`,
369
510
  `ref="${xmlEscape(element.resourceId)}"`,
370
511
  `name="${xmlEscape(element.name)}"`,
371
512
  `offset="${formatRational(offsetTime, `${element.id}.startTime`)}"`,
372
513
  ...(element.sourceStartTime ? [`start="${formatRational(element.sourceStartTime, `${element.id}.sourceStartTime`)}"`] : []),
373
514
  `duration="${formatRational(element.durationTime, `${element.id}.durationTime`)}"`,
374
515
  ...(element.lane !== undefined ? [`lane="${String(element.lane)}"`] : []),
375
- ...(element.role ? [`audioRole="${element.role}"`] : []),
516
+ ...(element.nativeAudioRole || element.role ? [`audioRole="${xmlEscape(element.nativeAudioRole ?? element.role)}"`] : []),
376
517
  ...(element.enabled !== undefined ? [`enabled="${element.enabled ? "1" : "0"}"`] : []),
377
518
  ]
378
519
  : element.kind === "title"
379
520
  ? [
380
- `id="${xmlEscape(element.id)}"`,
381
521
  `ref="${xmlEscape(element.resourceId)}"`,
382
522
  `name="${xmlEscape(element.name)}"`,
383
523
  `offset="${formatRational(offsetTime, `${element.id}.startTime`)}"`,
384
524
  `duration="${formatRational(element.durationTime, `${element.id}.durationTime`)}"`,
385
525
  ...(element.lane !== undefined ? [`lane="${String(element.lane)}"`] : []),
386
526
  ]
387
- : [
388
- `id="${xmlEscape(element.id)}"`,
389
- `offset="${formatRational(offsetTime, `${element.id}.startTime`)}"`,
390
- `duration="${formatRational(element.durationTime, `${element.id}.durationTime`)}"`,
391
- ...(element.lane !== undefined ? [`lane="${String(element.lane)}"`] : []),
392
- ];
393
- const opening = `<${element.kind} ${attributes.join(" ")}>`;
394
- const childLines = [
395
- ...(element.gainDb !== undefined
396
- ? [`${indent} <adjust-volume amount="${formatDb(element.gainDb, element.id)}" />`]
397
- : []),
398
- ...(element.kind === "title" ? [`${indent} <text>${xmlEscape(element.text ?? "")}</text>`] : []),
399
- ];
400
- const childStart = childLines.length > 0 ? childLines : [];
401
- if (children.length === 0 && childStart.length === 0) {
402
- lines.push(`${indent}<${element.kind} ${attributes.join(" ")} />`);
527
+ : element.kind === "gap"
528
+ ? [
529
+ `offset="${formatRational(offsetTime, `${element.id}.startTime`)}"`,
530
+ `duration="${formatRational(element.durationTime, `${element.id}.durationTime`)}"`,
531
+ ...(element.lane !== undefined ? [`lane="${String(element.lane)}"`] : []),
532
+ ]
533
+ : element.kind === "marker"
534
+ ? [
535
+ `start="${formatRational(offsetTime, `${element.id}.startTime`)}"`,
536
+ `duration="${formatRational(element.durationTime, `${element.id}.durationTime`)}"`,
537
+ `value="${xmlEscape(element.name)}"`,
538
+ `note="com.framekit.id:${xmlEscape(element.id)}"`,
539
+ ]
540
+ : [
541
+ `offset="${formatRational(offsetTime, `${element.id}.startTime`)}"`,
542
+ `duration="${formatRational(element.durationTime, `${element.id}.durationTime`)}"`,
543
+ ];
544
+ if (element.kind === "marker") {
545
+ lines.push(`${indent}<marker ${attributes.join(" ")} />`);
403
546
  continue;
404
547
  }
405
- lines.push(`${indent}${opening}`);
406
- lines.push(...childStart);
548
+ lines.push(`${indent}<${element.kind} ${attributes.join(" ")}>`);
549
+ if (element.kind === "title" || element.kind === "caption") {
550
+ lines.push(`${indent} <text>${xmlEscape(element.text ?? "")}</text>`);
551
+ }
552
+ if (element.gainDb !== undefined) {
553
+ lines.push(`${indent} <adjust-volume amount="${formatDb(element.gainDb, element.id)}" />`);
554
+ }
407
555
  render(element.id, `${indent} `);
556
+ if (element.kind === "caption") {
557
+ lines.push(`${indent} <note>com.framekit.id:${xmlEscape(element.id)}</note>`);
558
+ }
559
+ else {
560
+ lines.push(`${indent} <metadata><md key="com.framekit.id" value="${xmlEscape(element.id)}" /></metadata>`);
561
+ }
408
562
  lines.push(`${indent}</${element.kind}>`);
409
563
  }
410
564
  };
@@ -0,0 +1,3 @@
1
+ export const HEADLESS_AUDIO_CODEC = "aac";
2
+ export const HEADLESS_AUDIO_SAMPLE_RATE = 48_000;
3
+ export const HEADLESS_AUDIO_CHANNELS = 1;