@morshoto/framekit 0.1.17 → 0.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (26) hide show
  1. package/README.md +10 -4
  2. package/dist-package/adapters/final-cut/typescript/src/canonical.js +19 -7
  3. package/dist-package/adapters/final-cut/typescript/src/connection.js +5 -3
  4. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +128 -29
  5. package/dist-package/adapters/final-cut/typescript/src/index.js +1 -0
  6. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +60 -1
  7. package/dist-package/adapters/final-cut/typescript/src/live.js +2 -2
  8. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +213 -0
  9. package/dist-package/adapters/final-cut/typescript/src/publisher.js +762 -238
  10. package/dist-package/adapters/final-cut/typescript/src/session.js +6 -1
  11. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +200 -48
  12. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +17 -7
  13. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +2 -2
  14. package/dist-package/apps/cli/src/main.js +34 -19
  15. package/dist-package/apps/mcp-server/src/build-alignment.js +59 -0
  16. package/dist-package/apps/mcp-server/src/build-identity.js +30 -0
  17. package/dist-package/apps/mcp-server/src/build-identity.json +5 -0
  18. package/dist-package/apps/mcp-server/src/headless-project-snapshot.js +101 -0
  19. package/dist-package/apps/mcp-server/src/headless-projects.js +255 -16
  20. package/dist-package/apps/mcp-server/src/main.js +27 -3
  21. package/dist-package/apps/mcp-server/src/server.js +270 -49
  22. package/dist-package/apps/mcp-server/src/version.js +21 -2
  23. package/dist-package/packages/runtime/src/application/media-analysis-service.js +15 -5
  24. package/dist-package/packages/runtime/src/runtime.js +6 -0
  25. package/dist-package/packages/runtime/src/timeline/editing-session.js +7 -2
  26. package/package.json +9 -9
@@ -9,7 +9,12 @@ export class FinalCutSessionAdapter {
9
9
  if (this.options.snapshot && this.options.live) {
10
10
  try {
11
11
  const live = await this.options.live.getIdentity();
12
- return { name: "Final Cut Pro", version: live.version, backend: "final-cut-session" };
12
+ return {
13
+ name: "Final Cut Pro",
14
+ version: live.version,
15
+ backend: "final-cut-session",
16
+ ...(live.buildFingerprint ? { buildFingerprint: live.buildFingerprint } : {}),
17
+ };
13
18
  }
14
19
  catch {
15
20
  return { name: "Final Cut Pro", version: "FCPXML + live", backend: "final-cut-session" };
@@ -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,30 @@ 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"?>',
43
46
  `<fcpxml version="${FRAMEKIT_FCPXML_VERSION}">`,
44
47
  " <resources>",
45
- ` <format id="${formatId}" frameDuration="${formatRational(timeline.sequence.frameDuration, "sequence.frameDuration")}" />`,
48
+ ` <format id="${formatId}"${projectFormatName ? ` name="${projectFormatName}"` : ""} frameDuration="${formatRational(timeline.sequence.frameDuration, "sequence.frameDuration")}"${projectDimensions} />`,
49
+ ...(resources.some((resource) => resource.mediaKind === "audio")
50
+ ? [` <format id="${AUDIO_FORMAT_ID}" name="FFFrameRateUndefined" />`]
51
+ : []),
52
+ ...resources.flatMap((resource) => renderResourceFormat(resource, resourceIds.get(resource.id))),
46
53
  ...(timeline.sequence.titles?.length
47
54
  ? [` <effect id="${BASIC_TITLE_EFFECT_ID}" name="Basic Title" uid="${BASIC_TITLE_EFFECT_UID}" />`]
48
55
  : []),
@@ -51,17 +58,9 @@ export function compileTimelineIrToFcpxml(timeline, options) {
51
58
  " <library>",
52
59
  ` <event uid="${xmlEscape(options.target.eventUid)}" name="${xmlEscape(options.target.eventName ?? "Framekit Event")}">`,
53
60
  ` <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")}">`,
61
+ ` <sequence format="${formatId}" duration="${formatRational(timeline.sequence.durationTime, "sequence.durationTime")}">`,
55
62
  " <spine>",
56
63
  ...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
64
  " </spine>",
66
65
  " </sequence>",
67
66
  " </project>",
@@ -132,6 +131,12 @@ function materializationCoverage(timeline, destinationMode, elements) {
132
131
  "primary-storyline-order",
133
132
  "provenance",
134
133
  ]);
134
+ const degraded = new Set();
135
+ if (elements.some(({ frameAlignmentAdjusted }) => frameAlignmentAdjusted)) {
136
+ degraded.add("video-edit-frame-rounding");
137
+ }
138
+ if (elements.some(({ sourceRangeAdjusted }) => sourceRangeAdjusted))
139
+ exact.delete("source-ranges");
135
140
  if (elements.some(({ parentId }) => parentId !== undefined))
136
141
  exact.add("connected-elements");
137
142
  if (timeline.sequence.occurrences.some(({ role }) => role !== undefined))
@@ -149,7 +154,80 @@ function materializationCoverage(timeline, destinationMode, elements) {
149
154
  exact.add("markers");
150
155
  if (timeline.sequence.captions.length > 0)
151
156
  exact.add("captions");
152
- return { exact: [...exact].sort(), degraded: [], unsupported: [] };
157
+ return { exact: [...exact].sort(), degraded: [...degraded].sort(), unsupported: [] };
158
+ }
159
+ function alignRenderableElements(elements, frameDuration, audioResourceIds) {
160
+ return elements.map((element) => {
161
+ if (element.kind === "asset-clip" && element.resourceId !== undefined && audioResourceIds.has(element.resourceId)) {
162
+ return element;
163
+ }
164
+ const endTime = addExactTimes(element.startTime, element.durationTime);
165
+ const startTime = snapTimeToFrame(element.startTime, frameDuration);
166
+ const alignedEndTime = snapTimeToFrame(endTime, frameDuration);
167
+ const durationTime = subtractRational(alignedEndTime, startTime, `${element.id}.durationTime`);
168
+ const zero = { value: "0", timescale: "1" };
169
+ if (compareExactTimes(element.durationTime, zero) > 0 && compareExactTimes(durationTime, zero) === 0) {
170
+ throw new Error(`FCPXML_EDIT_BELOW_FRAME_RESOLUTION: ${element.id}`);
171
+ }
172
+ const sourceStartTime = element.sourceStartTime
173
+ ? snapTimeToFrame(element.sourceStartTime, frameDuration)
174
+ : undefined;
175
+ const adjusted = compareExactTimes(startTime, element.startTime) !== 0
176
+ || compareExactTimes(durationTime, element.durationTime) !== 0
177
+ || sourceStartTime !== undefined && compareExactTimes(sourceStartTime, element.sourceStartTime) !== 0;
178
+ const sourceRangeAdjusted = element.kind === "asset-clip"
179
+ && (compareExactTimes(durationTime, element.durationTime) !== 0
180
+ || sourceStartTime !== undefined && compareExactTimes(sourceStartTime, element.sourceStartTime) !== 0);
181
+ return {
182
+ ...element,
183
+ startTime,
184
+ durationTime,
185
+ ...(sourceStartTime ? { sourceStartTime } : {}),
186
+ ...(adjusted ? { frameAlignmentAdjusted: true } : {}),
187
+ ...(sourceRangeAdjusted ? { sourceRangeAdjusted: true } : {}),
188
+ };
189
+ });
190
+ }
191
+ function snapTimeToFrame(value, frameDuration) {
192
+ const time = parseExactRational(value);
193
+ const frame = parseExactRational(frameDuration);
194
+ if (time.value < 0n || frame.value <= 0n)
195
+ throw new Error("FCPXML_INVALID_TIME: frame alignment requires non-negative time and positive frame duration");
196
+ const frameNumerator = time.value * frame.timescale;
197
+ const frameDenominator = time.timescale * frame.value;
198
+ let frames = frameNumerator / frameDenominator;
199
+ if ((frameNumerator % frameDenominator) * 2n >= frameDenominator)
200
+ frames += 1n;
201
+ const numerator = frames * frame.value;
202
+ const denominator = frame.timescale;
203
+ const divisor = greatestCommonDivisor(numerator, denominator);
204
+ return { value: String(numerator / divisor), timescale: String(denominator / divisor) };
205
+ }
206
+ function predefinedVideoFormatName(width, height, frameDuration) {
207
+ const raster = width === 1280 && height === 720
208
+ ? "720p"
209
+ : width === 1920 && height === 1080
210
+ ? "1080p"
211
+ : width === 3840 && height === 2160 || width === 4096 && height === 2160
212
+ ? `${width}x${height}p`
213
+ : undefined;
214
+ if (!raster)
215
+ return undefined;
216
+ const parts = parseExactRational(frameDuration);
217
+ const divisor = greatestCommonDivisor(parts.value, parts.timescale);
218
+ const rate = `${parts.value / divisor}/${parts.timescale / divisor}`;
219
+ const suffix = {
220
+ "1001/24000": "2398",
221
+ "1/24": "24",
222
+ "1/25": "25",
223
+ "1001/30000": "2997",
224
+ "1/30": "30",
225
+ "1/50": "50",
226
+ "1001/60000": "5994",
227
+ "1/60": "60",
228
+ };
229
+ const frameRate = suffix[rate];
230
+ return frameRate ? `FFVideoFormat${raster}${frameRate}` : undefined;
153
231
  }
154
232
  function validateTarget(target) {
155
233
  if (!target || target.provider !== "final-cut")
@@ -171,17 +249,18 @@ function resolveDestination(timeline, target) {
171
249
  projectUid: target.projectUid,
172
250
  sequenceUid: target.sequenceUid,
173
251
  projectName: timeline.project.name,
174
- sequenceName: timeline.sequence.name,
252
+ sequenceName: timeline.project.name,
175
253
  };
176
254
  }
177
255
  const revisionKey = shortHash(`${timeline.project.id}:${timeline.sequence.id}:${timeline.revision.id}:${timeline.revision.sequence}:${timeline.revision.timestamp}:${timelineIrDigest(timeline)}`);
178
256
  const revisionName = `${safeId(timeline.revision.id)}-${timeline.revision.sequence}`;
257
+ const projectName = `${timeline.project.name} (Framekit ${revisionName}-${revisionKey})`;
179
258
  return {
180
259
  mode: "versioned",
181
260
  projectUid: `${safeId(target.projectUid)}-framekit-${revisionKey}`,
182
261
  sequenceUid: `${safeId(target.sequenceUid)}-framekit-${revisionKey}`,
183
- projectName: `${timeline.project.name} (Framekit ${revisionName}-${revisionKey})`,
184
- sequenceName: `${timeline.sequence.name} (Framekit ${revisionName}-${revisionKey})`,
262
+ projectName,
263
+ sequenceName: projectName,
185
264
  };
186
265
  }
187
266
  function createResourceIds(timeline) {
@@ -228,12 +307,35 @@ function renderResource(resource, id, name) {
228
307
  throw new Error(`FCPXML_RESOURCE_SOURCE_UNSUPPORTED: resource ${resource.id} has an invalid file URL: ${error instanceof Error ? error.message : String(error)}`);
229
308
  }
230
309
  const videoAttribute = resource.mediaKind === "video" ? ' hasVideo="1"' : ' hasVideo="0"';
310
+ const metadata = resource.metadata;
311
+ const video = metadata?.streams.find((stream) => stream.kind === "video");
312
+ const audio = metadata?.streams.find((stream) => stream.kind === "audio");
313
+ const timingAttributes = metadata
314
+ ? ` start="0s" duration="${formatRational(metadata.durationTime, `resource ${resource.id}.durationTime`)}"`
315
+ : "";
316
+ const formatAttribute = video?.width && video.height && video.frameRate
317
+ ? ` format="format-${id}"`
318
+ : resource.mediaKind === "audio"
319
+ ? ` format="${AUDIO_FORMAT_ID}"`
320
+ : "";
231
321
  const audioAttribute = resource.mediaKind === "audio"
232
322
  ? ' hasAudio="1"'
233
- : resource.metadata?.streams
234
- ? ` hasAudio="${resource.metadata.streams.some((stream) => stream.kind === "audio") ? "1" : "0"}"`
323
+ : metadata?.streams
324
+ ? ` hasAudio="${audio ? "1" : "0"}"`
235
325
  : "";
236
- return ` <asset id="${xmlEscape(id)}" name="${xmlEscape(name)}" src="${xmlEscape(src)}"${videoAttribute}${audioAttribute} />`;
326
+ const sourceAttributes = `${video ? ' videoSources="1"' : ""}${audio ? ' audioSources="1"' : ""}`;
327
+ const audioDetails = audio?.channels && audio.sampleRate
328
+ ? ` audioChannels="${audio.channels}" audioRate="${audio.sampleRate}"`
329
+ : "";
330
+ return ` <asset id="${xmlEscape(id)}" name="${xmlEscape(name)}"${timingAttributes}${videoAttribute}${formatAttribute}${audioAttribute}${sourceAttributes}${audioDetails}><media-rep kind="original-media" src="${xmlEscape(src)}" /></asset>`;
331
+ }
332
+ function renderResourceFormat(resource, id) {
333
+ const video = resource.metadata?.streams.find((stream) => stream.kind === "video");
334
+ if (!video?.width || !video.height || !video.frameRate)
335
+ return [];
336
+ const frameDuration = { value: video.frameRate.timescale, timescale: video.frameRate.value };
337
+ const formatName = predefinedVideoFormatName(video.width, video.height, frameDuration);
338
+ return [` <format id="format-${id}"${formatName ? ` name="${formatName}"` : ""} frameDuration="${formatRational(frameDuration, `resource ${resource.id}.frameRate`)}" width="${video.width}" height="${video.height}" />`];
237
339
  }
238
340
  function renderableElements(timeline, resourceIds) {
239
341
  const occurrenceIds = new Set(timeline.sequence.occurrences.map(({ id }) => id));
@@ -258,8 +360,40 @@ function renderableElements(timeline, resourceIds) {
258
360
  for (const title of timeline.sequence.titles ?? []) {
259
361
  elements.push(renderableTitle(title, timeline));
260
362
  }
363
+ for (const marker of timeline.sequence.markers) {
364
+ elements.push({
365
+ id: marker.id,
366
+ kind: "marker",
367
+ startTime: marker.startTime,
368
+ durationTime: marker.durationTime,
369
+ parentId: primaryAnchorForTime("marker", marker.id, marker.startTime, marker.durationTime, elements),
370
+ name: marker.name,
371
+ });
372
+ }
373
+ for (const caption of timeline.sequence.captions) {
374
+ elements.push({
375
+ id: caption.id,
376
+ kind: "caption",
377
+ startTime: caption.startTime,
378
+ durationTime: caption.durationTime,
379
+ parentId: primaryAnchorForTime("caption", caption.id, caption.startTime, caption.durationTime, elements),
380
+ text: caption.text,
381
+ });
382
+ }
261
383
  return elements;
262
384
  }
385
+ function primaryAnchorForTime(kind, id, startTime, durationTime, elements) {
386
+ const endTime = addExactTimes(startTime, durationTime);
387
+ const anchor = elements
388
+ .filter((element) => element.parentId === undefined
389
+ && (element.kind === "gap" || (element.kind === "asset-clip" && element.role === undefined)))
390
+ .filter((element) => compareExactTimes(startTime, element.startTime) >= 0
391
+ && compareExactTimes(endTime, addExactTimes(element.startTime, element.durationTime)) <= 0)
392
+ .sort((left, right) => compareExactTimes(right.startTime, left.startTime))[0];
393
+ if (!anchor)
394
+ throw new Error(`FCPXML_${kind.toUpperCase()}_ANCHOR_NOT_FOUND: ${id}`);
395
+ return anchor.id;
396
+ }
263
397
  function renderableTitle(title, timeline) {
264
398
  const titleEnd = addExactTimes(title.startTime, title.durationTime);
265
399
  const parent = timeline.sequence.occurrences.find((occurrence) => {
@@ -341,8 +475,15 @@ function renderElements(elements) {
341
475
  siblings.push(element);
342
476
  byParent.set(element.parentId, siblings);
343
477
  }
344
- for (const siblings of byParent.values())
345
- siblings.sort(compareTimedItems);
478
+ for (const siblings of byParent.values()) {
479
+ siblings.sort((left, right) => {
480
+ if (left.kind === "marker" && right.kind !== "marker")
481
+ return 1;
482
+ if (right.kind === "marker" && left.kind !== "marker")
483
+ return -1;
484
+ return compareTimedItems(left, right);
485
+ });
486
+ }
346
487
  const rendered = new Set();
347
488
  const lines = [];
348
489
  const render = (parentId, indent) => {
@@ -350,7 +491,6 @@ function renderElements(elements) {
350
491
  if (rendered.has(element.id))
351
492
  throw new Error(`FCPXML_CYCLIC_ATTACHMENT: ${element.id}`);
352
493
  rendered.add(element.id);
353
- const children = byParent.get(element.id) ?? [];
354
494
  const parentElement = element.parentId === undefined ? undefined : byId.get(element.parentId);
355
495
  const parentStartTime = element.parentId === undefined
356
496
  ? { value: "0", timescale: "1" }
@@ -359,13 +499,12 @@ function renderElements(elements) {
359
499
  throw new Error(`FCPXML_ATTACHMENT_TARGET_NOT_FOUND: ${element.id} -> ${element.parentId}`);
360
500
  const localStartTime = subtractRational(element.startTime, parentStartTime, `${element.id}.startTime`);
361
501
  const offsetTime = parentElement?.kind === "asset-clip"
362
- && (element.kind === "title" || element.role === "music")
502
+ && (element.kind === "title" || element.kind === "caption" || element.kind === "marker" || element.role === "music")
363
503
  && parentElement.sourceStartTime !== undefined
364
504
  ? addExactTimes(localStartTime, parentElement.sourceStartTime)
365
505
  : localStartTime;
366
506
  const attributes = element.kind === "asset-clip"
367
507
  ? [
368
- `id="${xmlEscape(element.id)}"`,
369
508
  `ref="${xmlEscape(element.resourceId)}"`,
370
509
  `name="${xmlEscape(element.name)}"`,
371
510
  `offset="${formatRational(offsetTime, `${element.id}.startTime`)}"`,
@@ -377,34 +516,47 @@ function renderElements(elements) {
377
516
  ]
378
517
  : element.kind === "title"
379
518
  ? [
380
- `id="${xmlEscape(element.id)}"`,
381
519
  `ref="${xmlEscape(element.resourceId)}"`,
382
520
  `name="${xmlEscape(element.name)}"`,
383
521
  `offset="${formatRational(offsetTime, `${element.id}.startTime`)}"`,
384
522
  `duration="${formatRational(element.durationTime, `${element.id}.durationTime`)}"`,
385
523
  ...(element.lane !== undefined ? [`lane="${String(element.lane)}"`] : []),
386
524
  ]
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(" ")} />`);
525
+ : element.kind === "gap"
526
+ ? [
527
+ `offset="${formatRational(offsetTime, `${element.id}.startTime`)}"`,
528
+ `duration="${formatRational(element.durationTime, `${element.id}.durationTime`)}"`,
529
+ ...(element.lane !== undefined ? [`lane="${String(element.lane)}"`] : []),
530
+ ]
531
+ : element.kind === "marker"
532
+ ? [
533
+ `start="${formatRational(offsetTime, `${element.id}.startTime`)}"`,
534
+ `duration="${formatRational(element.durationTime, `${element.id}.durationTime`)}"`,
535
+ `value="${xmlEscape(element.name)}"`,
536
+ `note="com.framekit.id:${xmlEscape(element.id)}"`,
537
+ ]
538
+ : [
539
+ `offset="${formatRational(offsetTime, `${element.id}.startTime`)}"`,
540
+ `duration="${formatRational(element.durationTime, `${element.id}.durationTime`)}"`,
541
+ ];
542
+ if (element.kind === "marker") {
543
+ lines.push(`${indent}<marker ${attributes.join(" ")} />`);
403
544
  continue;
404
545
  }
405
- lines.push(`${indent}${opening}`);
406
- lines.push(...childStart);
546
+ lines.push(`${indent}<${element.kind} ${attributes.join(" ")}>`);
547
+ if (element.kind === "title" || element.kind === "caption") {
548
+ lines.push(`${indent} <text>${xmlEscape(element.text ?? "")}</text>`);
549
+ }
550
+ if (element.gainDb !== undefined) {
551
+ lines.push(`${indent} <adjust-volume amount="${formatDb(element.gainDb, element.id)}" />`);
552
+ }
407
553
  render(element.id, `${indent} `);
554
+ if (element.kind === "caption") {
555
+ lines.push(`${indent} <note>com.framekit.id:${xmlEscape(element.id)}</note>`);
556
+ }
557
+ else {
558
+ lines.push(`${indent} <metadata><md key="com.framekit.id" value="${xmlEscape(element.id)}" /></metadata>`);
559
+ }
408
560
  lines.push(`${indent}</${element.kind}>`);
409
561
  }
410
562
  };
@@ -126,8 +126,8 @@ async function prepareRenderModel(plan) {
126
126
  throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", "occurrence roles and lanes do not form a primary video storyline with connected audio layers");
127
127
  }
128
128
  const duration = rationalSeconds(sequence.durationTime, "sequence duration");
129
- const frameRate = 1 / rationalSeconds(sequence.frameDuration, "sequence frame duration");
130
- if (!Number.isFinite(duration) || duration <= 0 || !Number.isFinite(frameRate) || frameRate <= 0) {
129
+ const sequenceFrameRate = 1 / rationalSeconds(sequence.frameDuration, "sequence frame duration");
130
+ if (!Number.isFinite(duration) || duration <= 0 || !Number.isFinite(sequenceFrameRate) || sequenceFrameRate <= 0) {
131
131
  throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", "sequence duration and frame rate must be finite and positive");
132
132
  }
133
133
  if (!Number.isSafeInteger(plan.parameters.width) || !Number.isSafeInteger(plan.parameters.height)) {
@@ -190,8 +190,9 @@ async function prepareRenderModel(plan) {
190
190
  if (audioAvailability.size > 1) {
191
191
  throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", "all primary occurrences must agree on audio availability");
192
192
  }
193
- if (Math.abs(previousEnd - duration) > 1e-7) {
194
- throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", "occurrences do not cover the sequence duration");
193
+ const tailDuration = duration - previousEnd;
194
+ if (tailDuration < -1e-7) {
195
+ throw new FfmpegRenderError("HEADLESS_RENDER_UNSUPPORTED", "primary occurrences exceed the sequence duration");
195
196
  }
196
197
  const transitions = timeline.sequence.transitions ?? [];
197
198
  if (transitions.length > 1) {
@@ -204,7 +205,8 @@ async function prepareRenderModel(plan) {
204
205
  resources,
205
206
  sourcePaths,
206
207
  duration,
207
- frameRate,
208
+ tailDuration: Math.max(0, tailDuration),
209
+ frameRate: structuredClone(plan.parameters.frameRate),
208
210
  width: plan.parameters.width,
209
211
  height: plan.parameters.height,
210
212
  format: plan.parameters.format,
@@ -296,7 +298,7 @@ function buildFfmpegArguments(model, stagingPath, fontFile) {
296
298
  const videoLabels = [];
297
299
  const audioLabels = [];
298
300
  const musicLabels = [];
299
- const fps = formatNumber(model.frameRate);
301
+ const fps = `${model.frameRate.value}/${model.frameRate.timescale}`;
300
302
  const inputIndices = new Map();
301
303
  for (const [index, occurrence] of [...model.occurrences, ...model.audioOccurrences].entries()) {
302
304
  const resource = model.resources.get(occurrence.mediaId);
@@ -334,7 +336,8 @@ function buildFfmpegArguments(model, stagingPath, fontFile) {
334
336
  }
335
337
  const transition = model.timeline.sequence.transitions?.[0];
336
338
  const videoBase = addVideoComposition(filters, videoLabels, model, transition);
337
- const videoOutput = addTitleOverlays(filters, videoBase, model, fontFile);
339
+ const videoWithTail = addBlackVideoTail(filters, videoBase, model.tailDuration);
340
+ const videoOutput = addTitleOverlays(filters, videoWithTail, model, fontFile);
338
341
  let audioOutput;
339
342
  if (audioLabels.length > 0)
340
343
  audioOutput = addAudioComposition(filters, audioLabels, model, transition);
@@ -357,6 +360,13 @@ function addAudioMix(filters, labels, duration) {
357
360
  filters.push(`${labels.join("")}amix=inputs=${labels.length}:duration=longest:dropout_transition=0:normalize=0,apad,atrim=duration=${formatNumber(duration)},asetpts=PTS-STARTPTS[${output}]`);
358
361
  return output;
359
362
  }
363
+ function addBlackVideoTail(filters, input, duration) {
364
+ if (duration <= 1e-7)
365
+ return input;
366
+ const output = "video-black-tail";
367
+ filters.push(`[${input}]tpad=stop_mode=add:stop_duration=${formatNumber(duration)}:color=black[${output}]`);
368
+ return output;
369
+ }
360
370
  function addVideoComposition(filters, labels, model, transition) {
361
371
  if (labels.length === 1) {
362
372
  const output = "video-base";
@@ -79,7 +79,7 @@ export class FfmpegRenderVerifier {
79
79
  const audioPassed = expectedAudio === undefined || (audio !== undefined
80
80
  && (expectedAudio.sampleRate === undefined || Number(audio.sample_rate) === expectedAudio.sampleRate)
81
81
  && (expectedAudio.channels === undefined || audio.channels === expectedAudio.channels));
82
- checks.push({ name: "audio-stream", passed: audioPassed, detail: "canonical audio stream presence and metadata are preserved", expected: expectedAudio ?? { kind: "none" }, observed: audio ?? { kind: "none" } });
82
+ checks.push({ name: "audio-stream", passed: audioPassed, detail: "timeline audio is present in the renderer's normalized format", expected: expectedAudio ?? { kind: "none" }, observed: audio ?? { kind: "none" } });
83
83
  checks.push({ name: "duration", passed: durationPassed, detail: `output duration is within ${tolerance} seconds of the canonical sequence`, expected: expectedDuration, observed: probe.format.duration });
84
84
  const artifact = {
85
85
  path: result.output.path,
@@ -119,7 +119,7 @@ function expectedAudioStream(plan) {
119
119
  const resource = occurrence.mediaId ? resources.get(occurrence.mediaId) : undefined;
120
120
  const stream = resource?.metadata?.streams.find((candidate) => candidate.kind === "audio");
121
121
  if (stream)
122
- return { sampleRate: stream.sampleRate, channels: stream.channels };
122
+ return { sampleRate: 48_000, channels: 1 };
123
123
  }
124
124
  return undefined;
125
125
  }
@@ -1,7 +1,7 @@
1
1
  import { execFile as execFileCallback, spawn } from "node:child_process";
2
2
  import { access } from "node:fs/promises";
3
3
  import { fileURLToPath } from "node:url";
4
- import { dirname, join } from "node:path";
4
+ import { dirname, join, resolve } from "node:path";
5
5
  import { promisify } from "node:util";
6
6
  import { FinalCutConnectionManager } from "../../../adapters/final-cut/typescript/src/index.js";
7
7
  const execFile = promisify(execFileCallback);
@@ -26,7 +26,7 @@ async function main() {
26
26
  if (command !== "help")
27
27
  process.exitCode = 1;
28
28
  }
29
- async function connectFinalCut(args) {
29
+ async function connectFinalCut(args, output = process.stdout) {
30
30
  if (args[0] !== "finalcut") {
31
31
  throw new Error("Usage: framekit connect finalcut [--development] [--json]");
32
32
  }
@@ -40,11 +40,13 @@ async function connectFinalCut(args) {
40
40
  const manager = new FinalCutConnectionManager({
41
41
  extensionSourcePath,
42
42
  restartAfterInstall: true,
43
+ installBeforeProbe: development,
43
44
  });
44
45
  const status = await manager.ensureConnected();
45
- printStatus(status, json);
46
+ printStatus(status, json, output);
46
47
  if (status.state !== "ready")
47
48
  process.exitCode = 1;
49
+ return status;
48
50
  }
49
51
  async function doctorFinalCut(args) {
50
52
  if (args[0] !== "finalcut")
@@ -54,24 +56,35 @@ async function doctorFinalCut(args) {
54
56
  if (status.state !== "ready")
55
57
  process.exitCode = 1;
56
58
  }
57
- async function runMcp(args) {
59
+ export async function runMcp(args, dependencies = {}) {
58
60
  const editorIndex = args.indexOf("--editor");
59
61
  const editor = editorIndex >= 0 ? args[editorIndex + 1] : "final-cut-live";
60
62
  const headless = args.includes("--headless");
63
+ const development = args.includes("--development");
61
64
  if (editor !== "final-cut-live" && editor !== "fixture") {
62
- throw new Error("Usage: framekit mcp [--editor final-cut-live|fixture] [--headless]");
65
+ throw new Error("Usage: framekit mcp [--editor final-cut-live|fixture] [--headless] [--development]");
63
66
  }
64
67
  if (headless && editor !== "final-cut-live") {
65
68
  throw new Error("Usage: --headless is only supported with --editor final-cut-live");
66
69
  }
70
+ if (development && editor !== "final-cut-live") {
71
+ throw new Error("Usage: --development is only supported with --editor final-cut-live");
72
+ }
73
+ if (development) {
74
+ const connect = dependencies.connectDevelopmentExtension ?? connectFinalCut;
75
+ const status = await connect(["finalcut", "--development", "--json"], dependencies.stderr ?? process.stderr);
76
+ if (status.state !== "ready")
77
+ return;
78
+ }
67
79
  const root = repoRoot();
68
80
  const compiled = fileURLToPath(import.meta.url).endsWith(".js");
69
81
  const entrypoint = join(root, `apps/mcp-server/src/main.${compiled ? "js" : "ts"}`);
70
- const child = spawn(process.execPath, [...(compiled ? [] : ["--import", "tsx"]), entrypoint], {
82
+ const child = (dependencies.spawnChild ?? spawn)(process.execPath, [...(compiled ? [] : ["--import", "tsx"]), entrypoint], {
71
83
  stdio: "inherit",
72
84
  env: {
73
85
  ...process.env,
74
86
  FRAMEKIT_EDITOR: editor,
87
+ ...(development ? { FRAMEKIT_REQUIRE_BUILD_ALIGNMENT: "1" } : {}),
75
88
  ...(headless
76
89
  ? {
77
90
  FRAMEKIT_FINAL_CUT_HEADLESS: "1",
@@ -97,19 +110,19 @@ async function buildDevelopmentExtension() {
97
110
  function repoRoot() {
98
111
  return join(dirname(fileURLToPath(import.meta.url)), "../../..");
99
112
  }
100
- function printStatus(status, json) {
113
+ function printStatus(status, json, output = process.stdout) {
101
114
  if (json) {
102
- process.stdout.write(`${JSON.stringify(status)}\n`);
115
+ output.write(`${JSON.stringify(status)}\n`);
103
116
  return;
104
117
  }
105
- process.stdout.write(`Framekit Final Cut: ${status.state}\n`);
106
- process.stdout.write(`Final Cut detected: ${status.editorDetected ? "yes" : "no"}\n`);
107
- process.stdout.write(`Extension: ${status.extensionInstalled ? status.extensionPath : "not installed"}\n`);
108
- process.stdout.write(`Socket: ${status.socketPath}\n`);
118
+ output.write(`Framekit Final Cut: ${status.state}\n`);
119
+ output.write(`Final Cut detected: ${status.editorDetected ? "yes" : "no"}\n`);
120
+ output.write(`Extension: ${status.extensionInstalled ? status.extensionPath : "not installed"}\n`);
121
+ output.write(`Socket: ${status.socketPath}\n`);
109
122
  if (status.identity)
110
- process.stdout.write(`Editor: ${status.identity.name} (${status.identity.backend})\n`);
123
+ output.write(`Editor: ${status.identity.name} (${status.identity.backend})\n`);
111
124
  if (status.lastError)
112
- process.stdout.write(`Reason: ${status.lastError.code}: ${status.lastError.message}\n`);
125
+ output.write(`Reason: ${status.lastError.code}: ${status.lastError.message}\n`);
113
126
  }
114
127
  function printHelp() {
115
128
  process.stdout.write([
@@ -117,14 +130,16 @@ function printHelp() {
117
130
  "",
118
131
  " framekit connect finalcut [--development] [--json]",
119
132
  " framekit doctor finalcut [--json]",
120
- " framekit mcp --editor final-cut-live [--headless]",
133
+ " framekit mcp --editor final-cut-live [--headless] [--development]",
121
134
  "",
122
135
  "Codex registration:",
123
136
  " codex mcp add framekit -- framekit mcp --editor final-cut-live --headless",
124
137
  "",
125
138
  ].join("\n"));
126
139
  }
127
- void main().catch((error) => {
128
- process.stderr.write(`${String(error)}\n`);
129
- process.exitCode = 1;
130
- });
140
+ if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
141
+ void main().catch((error) => {
142
+ process.stderr.write(`${String(error)}\n`);
143
+ process.exitCode = 1;
144
+ });
145
+ }
@@ -0,0 +1,59 @@
1
+ export function assessBuildAlignment(runtime, extension, targetCommit = runtime.commit) {
2
+ const target = { version: runtime.version, commit: targetCommit };
3
+ const unavailableCommit = [
4
+ ["runtime", runtime.commit],
5
+ ["target", target.commit],
6
+ ...(extension ? [["extension", extension.commit]] : []),
7
+ ].find(([, commit]) => !commit.trim() || commit.trim().toLowerCase() === "unknown");
8
+ if (unavailableCommit) {
9
+ return {
10
+ status: "missing",
11
+ target,
12
+ runtime,
13
+ ...(extension ? { extension } : {}),
14
+ message: `${unavailableCommit[0]} commit identity is unavailable`,
15
+ };
16
+ }
17
+ if (runtime.commit !== target.commit) {
18
+ return {
19
+ status: "mismatched",
20
+ target,
21
+ runtime,
22
+ ...(extension ? { extension } : {}),
23
+ message: `runtime commit ${runtime.commit} does not match target commit ${target.commit}`,
24
+ };
25
+ }
26
+ if (!extension) {
27
+ return {
28
+ status: "missing",
29
+ target,
30
+ runtime,
31
+ message: "extension fingerprint is unavailable",
32
+ };
33
+ }
34
+ if (extension.version !== runtime.version) {
35
+ return {
36
+ status: "mismatched",
37
+ target,
38
+ runtime,
39
+ extension,
40
+ message: `extension version ${extension.version} does not match runtime version ${runtime.version}`,
41
+ };
42
+ }
43
+ if (extension.commit !== runtime.commit) {
44
+ return {
45
+ status: "mismatched",
46
+ target,
47
+ runtime,
48
+ extension,
49
+ message: `extension commit ${extension.commit} does not match runtime commit ${runtime.commit}`,
50
+ };
51
+ }
52
+ return {
53
+ status: "matched",
54
+ target,
55
+ runtime,
56
+ extension,
57
+ message: "runtime and extension fingerprints match",
58
+ };
59
+ }