@morshoto/framekit 0.1.4 → 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.
Files changed (37) hide show
  1. package/README.md +2 -2
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +29 -2
  3. package/dist-package/adapters/final-cut/typescript/src/assets.js +89 -3
  4. package/dist-package/adapters/final-cut/typescript/src/canonical.js +431 -0
  5. package/dist-package/adapters/final-cut/typescript/src/connection.js +19 -4
  6. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +212 -13
  7. package/dist-package/adapters/final-cut/typescript/src/index.js +1 -0
  8. package/dist-package/adapters/final-cut/typescript/src/native.js +1026 -7
  9. package/dist-package/adapters/final-cut/typescript/src/publisher.js +207 -30
  10. package/dist-package/adapters/final-cut/typescript/src/session.js +69 -8
  11. package/dist-package/apps/mcp-server/src/main.js +49 -11
  12. package/dist-package/apps/mcp-server/src/routing.js +15 -0
  13. package/dist-package/apps/mcp-server/src/server.js +289 -68
  14. package/dist-package/apps/mcp-server/src/version.js +34 -0
  15. package/dist-package/packages/runtime/src/application/media-analysis-service.js +119 -15
  16. package/dist-package/packages/runtime/src/application/project-service.js +21 -2
  17. package/dist-package/packages/runtime/src/audio/dialogue-normalization.js +9 -0
  18. package/dist-package/packages/runtime/src/capabilities.js +90 -10
  19. package/dist-package/packages/runtime/src/context/context-engine.js +10 -1
  20. package/dist-package/packages/runtime/src/domain/editing.js +27 -1
  21. package/dist-package/packages/runtime/src/domain/media.js +1 -0
  22. package/dist-package/packages/runtime/src/domain/skills.js +2 -0
  23. package/dist-package/packages/runtime/src/editing/edit-service.js +82 -4
  24. package/dist-package/packages/runtime/src/editing/filler-removal-service.js +31 -7
  25. package/dist-package/packages/runtime/src/index.js +2 -0
  26. package/dist-package/packages/runtime/src/planning/rough-cut.js +9 -3
  27. package/dist-package/packages/runtime/src/runtime.js +2 -2
  28. package/dist-package/packages/runtime/src/skills/builtin.js +314 -39
  29. package/dist-package/packages/runtime/src/skills/requirements.js +1 -0
  30. package/dist-package/packages/runtime/src/skills/runtime.js +33 -8
  31. package/dist-package/packages/runtime/src/speech/analysis.js +301 -0
  32. package/dist-package/packages/runtime/src/speech/mapping.js +227 -0
  33. package/dist-package/packages/runtime/src/timeline/rational-time.js +5 -0
  34. package/dist-package/packages/runtime/src/verification/verification.js +81 -4
  35. package/dist-package/packages/testkit/src/fixture-analyzers.js +1 -0
  36. package/dist-package/packages/testkit/src/in-memory-editor.js +126 -0
  37. package/package.json +8 -2
@@ -1,4 +1,6 @@
1
1
  import { planRoughCut } from "../planning/rough-cut.js";
2
+ import { bindSpeechAnalysis } from "../speech/analysis.js";
3
+ import { parseRational } from "../timeline/rational-time.js";
2
4
  export class MediaAnalysisService {
3
5
  project;
4
6
  context;
@@ -13,7 +15,7 @@ export class MediaAnalysisService {
13
15
  throw new Error("CAPABILITY_UNAVAILABLE: speech analysis");
14
16
  const project = await this.project.inspectProject();
15
17
  const media = findMedia(project, mediaId);
16
- return this.options.speechAnalyzer.analyze({ project, media }, range);
18
+ return this.analyzeSpeechForProject(project, media, range);
17
19
  }
18
20
  async analyzeAudio(mediaId) {
19
21
  if (!this.options.audioAnalyzer)
@@ -40,7 +42,8 @@ export class MediaAnalysisService {
40
42
  throw new Error(`TARGET_MISMATCH: occurrence ${occurrenceId} does not reference media ${mediaId}`);
41
43
  }
42
44
  const media = findMedia(project, mediaId);
43
- const requestedRange = { start: 0, end: clip.duration };
45
+ const sourceStart = clip.sourceStart ?? 0;
46
+ const requestedRange = { start: sourceStart, end: sourceStart + clip.duration };
44
47
  const analysis = await this.options.audioAnalyzer.analyze({ project, media }, requestedRange);
45
48
  const analyzedDurationSeconds = analysis.analyzedDurationSeconds ?? clip.duration;
46
49
  const valid = analysis.valid !== false
@@ -119,7 +122,7 @@ export class MediaAnalysisService {
119
122
  const media = findMedia(project, mediaId);
120
123
  const input = { project, media };
121
124
  const [speechResult, audioResult, noiseResult, visualResult, metadataResult] = await Promise.all([
122
- settle(() => this.options.speechAnalyzer?.analyze(input)),
125
+ settle(() => this.options.speechAnalyzer ? this.analyzeSpeechForProject(project, media) : undefined),
123
126
  settle(() => this.options.audioAnalyzer?.analyze(input)),
124
127
  settle(() => this.options.noiseAnalyzer?.analyze(input)),
125
128
  settle(() => this.options.visualAnalyzer?.analyze(input)),
@@ -187,17 +190,18 @@ export class MediaAnalysisService {
187
190
  }))
188
191
  .filter((entry) => matchesMediaIndexQuery(entry, query));
189
192
  }
190
- async reanalyzeAffectedRanges(transaction) {
193
+ async reanalyzeAffectedRanges(transaction, requirements) {
191
194
  const affectedMediaRanges = transaction.diff.affectedRanges.flatMap((range) => transaction.attemptedAfter.timeline.clips.flatMap((clip) => {
192
195
  const intersectionStart = Math.max(range.start, clip.start);
193
196
  const intersectionEnd = Math.min(range.end, clip.start + clip.duration);
194
197
  if (!clip.mediaId || intersectionStart >= intersectionEnd)
195
198
  return [];
199
+ const sourceStart = clip.sourceStart ?? 0;
196
200
  return [{
197
201
  mediaId: clip.mediaId,
198
202
  range: {
199
- start: intersectionStart - clip.start,
200
- end: intersectionEnd - clip.start,
203
+ start: sourceStart + intersectionStart - clip.start,
204
+ end: sourceStart + intersectionEnd - clip.start,
201
205
  },
202
206
  }];
203
207
  }));
@@ -209,25 +213,31 @@ export class MediaAnalysisService {
209
213
  const media = next.media.find((candidate) => candidate.mediaId === mediaId);
210
214
  if (!media)
211
215
  continue;
212
- const ranges = affectedMediaRanges
216
+ const ranges = mergeRanges(affectedMediaRanges
213
217
  .filter((affected) => affected.mediaId === mediaId)
214
- .map((affected) => affected.range);
218
+ .map((affected) => affected.range));
215
219
  const input = { project: next, media };
216
- if (this.options.speechAnalyzer) {
217
- const analyses = await Promise.all(ranges.map((range) => this.options.speechAnalyzer.analyze(input, range)));
218
- media.speech = { words: analyses.flatMap((analysis) => analysis.words) };
220
+ if (requirements.speech && this.options.speechAnalyzer) {
221
+ const analyses = await Promise.all(ranges.map(async (range) => bindSpeechAnalysis(await this.options.speechAnalyzer.analyze(input, range), { input, range, provider: this.options.speechAnalyzer.descriptor })));
222
+ const latest = analyses[analyses.length - 1];
223
+ if (latest) {
224
+ media.speech = mergeSpeechAnalyses(media.speech, analyses, ranges, {
225
+ input,
226
+ provider: this.options.speechAnalyzer.descriptor,
227
+ });
228
+ }
219
229
  }
220
- if (this.options.audioAnalyzer) {
230
+ if (requirements.audio && this.options.audioAnalyzer) {
221
231
  const analyses = await Promise.all(ranges.map((range) => this.options.audioAnalyzer.analyze(input, range)));
222
232
  if (analyses[analyses.length - 1])
223
233
  media.audio = analyses[analyses.length - 1];
224
234
  }
225
- if (this.options.noiseAnalyzer) {
235
+ if (requirements.noise && this.options.noiseAnalyzer) {
226
236
  const analyses = await Promise.all(ranges.map((range) => this.options.noiseAnalyzer.analyze(input, range)));
227
237
  if (analyses[analyses.length - 1])
228
238
  media.noise = analyses[analyses.length - 1];
229
239
  }
230
- if (this.options.visualAnalyzer) {
240
+ if (requirements.visual && this.options.visualAnalyzer) {
231
241
  const analyses = await Promise.all(ranges.map((range) => this.options.visualAnalyzer.analyze(input, range)));
232
242
  media.visual = {
233
243
  scenes: analyses.flatMap((analysis) => analysis.scenes),
@@ -236,7 +246,10 @@ export class MediaAnalysisService {
236
246
  motion: analyses[analyses.length - 1]?.motion,
237
247
  };
238
248
  }
239
- if (this.options.speechAnalyzer || this.options.audioAnalyzer || this.options.noiseAnalyzer || this.options.visualAnalyzer) {
249
+ if ((requirements.speech && this.options.speechAnalyzer)
250
+ || (requirements.audio && this.options.audioAnalyzer)
251
+ || (requirements.noise && this.options.noiseAnalyzer)
252
+ || (requirements.visual && this.options.visualAnalyzer)) {
240
253
  for (const candidate of next.media) {
241
254
  if (candidate.mediaId === mediaId)
242
255
  candidate.analysisRevision = next.revision.id;
@@ -245,6 +258,18 @@ export class MediaAnalysisService {
245
258
  }
246
259
  return next;
247
260
  }
261
+ async analyzeSpeechForProject(project, media, range) {
262
+ const analyzer = this.options.speechAnalyzer;
263
+ if (!analyzer)
264
+ throw new Error("CAPABILITY_UNAVAILABLE: speech analysis");
265
+ const input = { project, media };
266
+ const analysis = await analyzer.analyze(input, range);
267
+ return bindSpeechAnalysis(analysis, {
268
+ input,
269
+ range,
270
+ provider: analyzer.descriptor,
271
+ });
272
+ }
248
273
  }
249
274
  function sourceIdentityOf(media) {
250
275
  return {
@@ -255,6 +280,85 @@ function sourceIdentityOf(media) {
255
280
  ...(media.duration !== undefined ? { duration: media.duration } : {}),
256
281
  };
257
282
  }
283
+ function mergeSpeechAnalyses(previous, analyses, updatedRanges, context) {
284
+ const latest = analyses[analyses.length - 1];
285
+ if (!latest)
286
+ throw new Error("ANALYSIS_INVALID: speech reanalysis returned no results");
287
+ if (previous?.provider && !sameDescriptor(previous.provider, latest.provider)) {
288
+ throw new Error("ANALYSIS_INVALID: speech evidence providers cannot be combined");
289
+ }
290
+ if (previous?.sourceTimebase && !sameRational(previous.sourceTimebase, latest.sourceTimebase)) {
291
+ throw new Error("ANALYSIS_INVALID: speech evidence timebases cannot be combined");
292
+ }
293
+ const requestedRange = encompassingRange([
294
+ ...(previous?.requestedRange ? [previous.requestedRange] : []),
295
+ ...analyses.map((analysis) => analysis.requestedRange),
296
+ ]);
297
+ const observedRange = encompassingRange([
298
+ ...(previous?.observedRange ? [previous.observedRange] : []),
299
+ ...analyses.map((analysis) => analysis.observedRange),
300
+ ]);
301
+ const words = mergeSpeechEvidence(previous?.words, analyses.map((analysis) => analysis.words), updatedRanges);
302
+ const hasVad = previous?.vadSegments !== undefined || analyses.some((analysis) => analysis.vadSegments !== undefined);
303
+ const vadSegments = hasVad
304
+ ? mergeSpeechEvidence(previous?.vadSegments, analyses.map((analysis) => analysis.vadSegments ?? []), updatedRanges)
305
+ : undefined;
306
+ const hasSilence = previous?.silenceSegments !== undefined || analyses.some((analysis) => analysis.silenceSegments !== undefined);
307
+ const silenceSegments = hasSilence
308
+ ? mergeSpeechEvidence(previous?.silenceSegments, analyses.map((analysis) => analysis.silenceSegments ?? []), updatedRanges)
309
+ : undefined;
310
+ const hasProtected = previous?.protectedSegments !== undefined || analyses.some((analysis) => analysis.protectedSegments !== undefined);
311
+ const protectedSegments = hasProtected
312
+ ? mergeSpeechEvidence(previous?.protectedSegments, analyses.map((analysis) => analysis.protectedSegments ?? []), updatedRanges)
313
+ : undefined;
314
+ return bindSpeechAnalysis({
315
+ ...latest,
316
+ requestedRange,
317
+ observedRange,
318
+ capability: vadSegments ? "transcription-plus-vad" : latest.capability,
319
+ words,
320
+ ...(vadSegments ? { vadSegments } : {}),
321
+ ...(silenceSegments ? { silenceSegments } : {}),
322
+ ...(protectedSegments ? { protectedSegments } : {}),
323
+ }, context);
324
+ }
325
+ function mergeSpeechEvidence(previous, fresh, updatedRanges) {
326
+ return [
327
+ ...(previous ?? []).filter((evidence) => !updatedRanges.some((range) => rangesOverlap(evidence, range))),
328
+ ...fresh.flat(),
329
+ ].sort((left, right) => left.start - right.start || left.end - right.end);
330
+ }
331
+ function rangesOverlap(left, right) {
332
+ return left.end > right.start && left.start < right.end;
333
+ }
334
+ function encompassingRange(ranges) {
335
+ if (ranges.length === 0)
336
+ throw new Error("ANALYSIS_INVALID: speech evidence needs a range");
337
+ return {
338
+ start: Math.min(...ranges.map((range) => range.start)),
339
+ end: Math.max(...ranges.map((range) => range.end)),
340
+ };
341
+ }
342
+ function mergeRanges(ranges) {
343
+ const merged = [];
344
+ for (const range of [...ranges].sort((left, right) => left.start - right.start || left.end - right.end)) {
345
+ const previous = merged[merged.length - 1];
346
+ if (!previous || range.start > previous.end) {
347
+ merged.push({ start: range.start, end: range.end });
348
+ continue;
349
+ }
350
+ previous.end = Math.max(previous.end, range.end);
351
+ }
352
+ return merged;
353
+ }
354
+ function sameDescriptor(left, right) {
355
+ return left.id === right.id && left.provider === right.provider && left.version === right.version;
356
+ }
357
+ function sameRational(left, right) {
358
+ const leftParts = parseRational(left, "ANALYSIS_INVALID");
359
+ const rightParts = parseRational(right, "ANALYSIS_INVALID");
360
+ return leftParts.value * rightParts.timescale === rightParts.value * leftParts.timescale;
361
+ }
258
362
  function semanticFromAnalyses(speech, audio, visual, metadata) {
259
363
  return {
260
364
  subjects: [
@@ -88,18 +88,37 @@ export class ProjectService {
88
88
  async inspectEditor() {
89
89
  const identity = await this.adapter.getIdentity();
90
90
  const capabilities = withCapabilityFamilies(await this.adapter.getCapabilities(), { backend: identity.backend });
91
+ const speechAnalyzer = this.options.speechAnalyzer;
92
+ const speechTranscribe = capabilities.analyzers.speechTranscribe
93
+ || (speechAnalyzer ? speechAnalyzer.capabilities?.transcription ?? true : false);
94
+ const speechVad = capabilities.analyzers.speechVad
95
+ || (speechAnalyzer?.capabilities?.vad ?? false);
91
96
  const analyzers = {
92
97
  ...capabilities.analyzers,
93
- speechTranscribe: capabilities.analyzers.speechTranscribe || Boolean(this.options.speechAnalyzer),
98
+ speechTranscribe,
99
+ speechVad,
100
+ speechCapability: speechTranscribe
101
+ ? speechVad ? "transcription-plus-vad" : "transcription-only"
102
+ : "unavailable",
94
103
  audioLoudness: capabilities.analyzers.audioLoudness || Boolean(this.options.audioAnalyzer),
95
104
  audioNoise: capabilities.analyzers.audioNoise || Boolean(this.options.noiseAnalyzer),
96
105
  visualTrack: capabilities.analyzers.visualTrack || Boolean(this.options.visualAnalyzer),
97
106
  metadataDescribe: capabilities.analyzers.metadataDescribe || Boolean(this.options.metadataAnalyzer),
98
107
  };
108
+ const analyzerBackends = {
109
+ speechTranscribe: speechAnalyzer?.descriptor?.provider,
110
+ speechVad: speechAnalyzer?.descriptor?.provider,
111
+ audioLoudness: this.options.audioAnalyzer?.descriptor?.provider,
112
+ audioNoise: this.options.noiseAnalyzer?.descriptor?.provider,
113
+ visualTrack: this.options.visualAnalyzer?.descriptor?.provider,
114
+ };
99
115
  return {
100
116
  identity,
101
117
  capabilities: {
102
- ...withCapabilityFamilies({ ...capabilities, analyzers }, { backend: identity.backend }),
118
+ ...withCapabilityFamilies({ ...capabilities, analyzers }, {
119
+ backend: identity.backend,
120
+ analyzerBackends,
121
+ }),
103
122
  },
104
123
  };
105
124
  }
@@ -1,3 +1,12 @@
1
+ /** Defaults for the version 1.0.0 dialogue-normalization Skill. */
2
+ export const DIALOGUE_NORMALIZATION_DEFAULTS = {
3
+ targetLufs: -16,
4
+ toleranceDb: 0.5,
5
+ maxTruePeakDb: -1,
6
+ minGainDb: -6,
7
+ maxGainDb: 6,
8
+ minDialogueDurationSeconds: 1,
9
+ };
1
10
  /** Plan a bounded clip-level gain change without mutating an editor. */
2
11
  export function planDialogueGain(measurement, options) {
3
12
  validateOptions(options);
@@ -25,18 +25,49 @@ export function withCanonicalTimelineMode(capabilities) {
25
25
  const previous = capabilities.families;
26
26
  if (!previous)
27
27
  return normalized;
28
+ const canonicalRead = normalized.editor.canonicalTimelineMode === "canonical-read"
29
+ || normalized.editor.canonicalTimelineMode === "canonical-write";
30
+ const canonicalWrite = normalized.editor.canonicalTimelineMode === "canonical-write";
31
+ const compositeTransactions = Boolean(normalized.editor.compositeTransactions
32
+ && normalized.editor.timelineSnapshotRead
33
+ && normalized.editor.readAfterWrite
34
+ && normalized.editor.rollback
35
+ && (normalized.editor.timelineArtifactWrite || canonicalWrite));
28
36
  return withCapabilityFamilies(normalized, {
29
37
  backend: previous.connection.status.backend,
30
38
  nativeBackend: previous.native.selectionWrite.backend,
31
39
  publishingBackend: previous.publishing.projectCreation.backend,
32
40
  exportBackend: previous.export.timeline.backend,
33
- analyzerBackend: previous.analyzers.speechTranscribe.backend,
41
+ analyzerBackends: {
42
+ speechTranscribe: previous.analyzers.speechTranscribe.backend,
43
+ speechVad: previous.analyzers.speechVad.backend,
44
+ audioLoudness: previous.analyzers.audioLoudness.backend,
45
+ audioNoise: previous.analyzers.audioNoise?.backend,
46
+ visualTrack: previous.analyzers.visualTrack.backend,
47
+ },
34
48
  connection: previous.connection.status,
49
+ canonicalDocument: {
50
+ read: refreshDescriptor(canonicalRead, previous.canonicalDocument.read, "canonical-read", "canonical timeline reads are unavailable"),
51
+ write: refreshDescriptor(canonicalWrite, previous.canonicalDocument.write, "canonical-write", "canonical timeline writes are unavailable"),
52
+ artifactWrite: refreshDescriptor(normalized.editor.timelineArtifactWrite, previous.canonicalDocument.artifactWrite, "artifact-write", "canonical artifact writes are unavailable"),
53
+ },
54
+ editing: {
55
+ compositeTransactions: refreshDescriptor(compositeTransactions, previous.editing.compositeTransactions, "verified", "composite editing transactions are unavailable"),
56
+ titlePlacement: refreshDescriptor(Boolean(normalized.editor.titlePlacement), previous.editing.titlePlacement, "verified", "title placement is unavailable"),
57
+ pictureInPicture: previous.editing.pictureInPicture,
58
+ masking: previous.editing.masking,
59
+ personCutout: previous.editing.personCutout,
60
+ },
35
61
  native: nativeAvailability(previous.native),
36
62
  publishing: previous.publishing.projectCreation,
37
63
  export: previous.export.timeline,
38
64
  });
39
65
  }
66
+ function refreshDescriptor(available, previous, guarantee, unavailableReason) {
67
+ if (available && previous.available)
68
+ return previous;
69
+ return descriptorFrom(available, previous.backend, guarantee, unavailableReason);
70
+ }
40
71
  /**
41
72
  * Adds the versioned operation-level contract while retaining the legacy
42
73
  * boolean fields used by existing runtime consumers.
@@ -53,10 +84,22 @@ export function withCapabilityFamilies(capabilities, options = {}) {
53
84
  },
54
85
  };
55
86
  const editor = normalized.editor;
87
+ const analyzerBackend = (operation) => options.analyzerBackends?.[operation]
88
+ ?? options.analyzerBackend
89
+ ?? previous?.analyzers[operation]?.backend
90
+ ?? backend;
56
91
  const native = {
57
92
  ...nativeAvailability(previous?.native),
58
93
  ...options.native,
59
94
  };
95
+ const canonicalDocument = {
96
+ ...previous?.canonicalDocument,
97
+ ...options.canonicalDocument,
98
+ };
99
+ const editing = {
100
+ ...previous?.editing,
101
+ ...options.editing,
102
+ };
60
103
  const families = {
61
104
  connection: {
62
105
  status: descriptorFrom(options.connection ?? previous?.connection.status ?? true, options.connectionBackend ?? backend, "observed", "editor connection is unavailable"),
@@ -66,11 +109,12 @@ export function withCapabilityFamilies(capabilities, options = {}) {
66
109
  media: descriptorFrom(editor.timelineSnapshotRead && editor.projectRead, backend, "canonical-read", "media observation is unavailable"),
67
110
  },
68
111
  canonicalDocument: {
69
- read: descriptorFrom(editor.canonicalTimelineMode === "canonical-read"
70
- || editor.canonicalTimelineMode === "canonical-write", backend, "canonical-read", "canonical timeline reads are unavailable"),
71
- write: descriptorFrom(editor.canonicalTimelineMode === "canonical-write", backend, "canonical-write", "canonical timeline writes are unavailable"),
72
- artifactWrite: descriptorFrom(editor.timelineArtifactWrite, backend, "artifact-write", "canonical artifact writes are unavailable"),
112
+ read: descriptorFrom(canonicalDocument.read ?? (editor.canonicalTimelineMode === "canonical-read"
113
+ || editor.canonicalTimelineMode === "canonical-write"), backend, "canonical-read", "canonical timeline reads are unavailable"),
114
+ write: descriptorFrom(canonicalDocument.write ?? (editor.canonicalTimelineMode === "canonical-write"), backend, "canonical-write", "canonical timeline writes are unavailable"),
115
+ artifactWrite: descriptorFrom(canonicalDocument.artifactWrite ?? editor.timelineArtifactWrite, backend, "artifact-write", "canonical artifact writes are unavailable"),
73
116
  },
117
+ editing: editingFamily(editor, editing, options.editingBackend ?? previous?.editing?.compositeTransactions.backend ?? backend),
74
118
  native: nativeFamily(native, options.nativeBackend ?? previous?.native.selectionWrite.backend ?? backend),
75
119
  publishing: {
76
120
  projectCreation: descriptorFrom(options.publishing ?? previous?.publishing.projectCreation ?? false, options.publishingBackend ?? backend, "verified", "new project publishing is unavailable"),
@@ -79,15 +123,48 @@ export function withCapabilityFamilies(capabilities, options = {}) {
79
123
  timeline: descriptorFrom(options.export ?? previous?.export.timeline ?? false, options.exportBackend ?? backend, "verified", "timeline export is unavailable"),
80
124
  },
81
125
  analyzers: {
82
- speechTranscribe: analyzerDescriptor(capabilities.analyzers.speechTranscribe, options.analyzerBackend ?? backend, "speech transcription"),
83
- speechVad: analyzerDescriptor(capabilities.analyzers.speechVad, options.analyzerBackend ?? backend, "speech VAD"),
84
- audioLoudness: analyzerDescriptor(capabilities.analyzers.audioLoudness, options.analyzerBackend ?? backend, "audio loudness analysis"),
85
- audioNoise: analyzerDescriptor(Boolean(capabilities.analyzers.audioNoise), options.analyzerBackend ?? backend, "audio noise analysis"),
86
- visualTrack: analyzerDescriptor(capabilities.analyzers.visualTrack, options.analyzerBackend ?? backend, "visual analysis"),
126
+ speechTranscribe: analyzerDescriptor(capabilities.analyzers.speechTranscribe, analyzerBackend("speechTranscribe"), "speech transcription"),
127
+ speechVad: analyzerDescriptor(capabilities.analyzers.speechVad, analyzerBackend("speechVad"), "speech VAD"),
128
+ audioLoudness: analyzerDescriptor(capabilities.analyzers.audioLoudness, analyzerBackend("audioLoudness"), "audio loudness analysis"),
129
+ audioNoise: analyzerDescriptor(Boolean(capabilities.analyzers.audioNoise), analyzerBackend("audioNoise"), "audio noise analysis"),
130
+ visualTrack: analyzerDescriptor(capabilities.analyzers.visualTrack, analyzerBackend("visualTrack"), "visual analysis"),
87
131
  },
88
132
  };
89
133
  return { ...normalized, families };
90
134
  }
135
+ function editingFamily(editor, overrides, backend) {
136
+ return {
137
+ compositeTransactions: descriptorFrom(overrides.compositeTransactions ?? Boolean(editor.compositeTransactions), backend, "verified", "composite editing transactions are unavailable"),
138
+ titlePlacement: descriptorFrom(overrides.titlePlacement ?? Boolean(editor.titlePlacement), backend, "verified", "title placement is unavailable"),
139
+ pictureInPicture: descriptorFrom(overrides.pictureInPicture ?? Boolean(editor.pictureInPicture), backend, "verified", "picture-in-picture editing is unavailable"),
140
+ masking: descriptorFrom(overrides.masking ?? Boolean(editor.masking), backend, "verified", "masking is unavailable"),
141
+ personCutout: descriptorFrom(overrides.personCutout ?? Boolean(editor.personCutout), backend, "verified", "person cutout is unavailable"),
142
+ };
143
+ }
144
+ export function createCapabilityPreflight(identity, capabilities, options = {}) {
145
+ const normalized = capabilities.families
146
+ ? capabilities
147
+ : withCapabilityFamilies(capabilities, { backend: identity.backend });
148
+ const editor = normalized.editor;
149
+ const documentMode = identity.backend === "fixture"
150
+ ? "fixture"
151
+ : editor.timelineArtifactWrite && !editor.timelineWrite
152
+ ? "fcpxml-artifact"
153
+ : editor.canonicalTimelineMode === "metadata-only"
154
+ ? "metadata-only"
155
+ : "canonical-live";
156
+ const processMode = options.processMode ?? "headless";
157
+ const mode = options.nativeWrite && processMode === "headed"
158
+ ? "native-write"
159
+ : documentMode;
160
+ return {
161
+ mode,
162
+ documentMode,
163
+ processMode,
164
+ backend: identity.backend,
165
+ capabilities: normalized.families,
166
+ };
167
+ }
91
168
  function descriptorFrom(value, backend, guarantee, unavailableReason) {
92
169
  if (typeof value !== "boolean")
93
170
  return value;
@@ -113,12 +190,15 @@ function nativeFamily(native, backend) {
113
190
  "mediaAppend",
114
191
  "mediaInsert",
115
192
  "titlePlacement",
193
+ "titleDiscovery",
116
194
  "timelineFocus",
117
195
  "projectCreation",
118
196
  "clipInsertion",
119
197
  "clipMovement",
120
198
  "transitionDiscovery",
121
199
  "transitionPlacement",
200
+ "pictureInPicture",
201
+ "masking",
122
202
  ];
123
203
  return Object.fromEntries(nativeOperations.map((operation) => [
124
204
  operation,
@@ -1,5 +1,6 @@
1
1
  import { diffSnapshots } from "../timeline/snapshot-diff.js";
2
2
  import { sameMediaSourceIdentity } from "../domain/media.js";
3
+ import { sameRevision } from "./revision.js";
3
4
  export class ContextEngine {
4
5
  editor;
5
6
  snapshots = new Map();
@@ -110,8 +111,12 @@ export class ContextEngine {
110
111
  const next = structuredClone(snapshot);
111
112
  next.media = next.media.map((media) => {
112
113
  const understanding = this.mediaUnderstanding.get(media.mediaId);
113
- if (!understanding || !sameMediaSourceIdentity(understanding.sourceIdentity, media))
114
+ if (!understanding)
114
115
  return media;
116
+ if (!isCurrentUnderstanding(understanding, media, snapshot.revision)) {
117
+ this.mediaUnderstanding.delete(media.mediaId);
118
+ return media;
119
+ }
115
120
  const attached = structuredClone(understanding);
116
121
  return {
117
122
  ...media,
@@ -127,6 +132,10 @@ export class ContextEngine {
127
132
  return next;
128
133
  }
129
134
  }
135
+ function isCurrentUnderstanding(understanding, media, revision) {
136
+ return sameMediaSourceIdentity(understanding.sourceIdentity, media)
137
+ && sameRevision(understanding.analysisRevision, revision);
138
+ }
130
139
  function isOptionalLiveUnavailable(error) {
131
140
  const message = String(error);
132
141
  return message.includes("FINAL_CUT_LIVE_UNAVAILABLE") || message.includes("CAPABILITY_UNAVAILABLE: live Final Cut editor state");
@@ -1 +1,27 @@
1
- export {};
1
+ export function assertValidMaskConfiguration(mask) {
2
+ if (!mask || typeof mask !== "object") {
3
+ throw new Error("INVALID_OPERATION: mask configuration is required");
4
+ }
5
+ if (mask.mode === "rectangle") {
6
+ if (!mask.bounds)
7
+ throw new Error("INVALID_OPERATION: rectangle mask bounds are required");
8
+ const { x, y, width, height } = mask.bounds;
9
+ if (![x, y, width, height].every(Number.isFinite)
10
+ || x < 0 || y < 0 || width <= 0 || height <= 0
11
+ || x + width > 1 || y + height > 1) {
12
+ throw new Error("INVALID_OPERATION: rectangle mask bounds must be normalized");
13
+ }
14
+ return;
15
+ }
16
+ if (mask.mode === "supplied-alpha") {
17
+ if (!mask.alphaMediaId?.trim()) {
18
+ throw new Error("INVALID_OPERATION: supplied-alpha masking requires alphaMediaId");
19
+ }
20
+ if (mask.bounds)
21
+ assertValidMaskConfiguration({ mode: "rectangle", bounds: mask.bounds });
22
+ return;
23
+ }
24
+ if (mask.mode === "person-cutout")
25
+ return;
26
+ throw new Error("INVALID_OPERATION: unsupported mask mode");
27
+ }
@@ -1,3 +1,4 @@
1
+ export const SPEECH_ANALYSIS_SCHEMA_VERSION = 1;
1
2
  export function sameMediaSourceIdentity(left, right) {
2
3
  return left.mediaId === right.mediaId
3
4
  && left.source === right.source
@@ -22,6 +22,7 @@ export const SKILL_OPERATIONS = [
22
22
  "add-marker",
23
23
  "media.import",
24
24
  "timeline.media.add",
25
+ "timeline.picture-in-picture.add",
25
26
  "timeline.audio.fades",
26
27
  "timeline.title.add",
27
28
  "timeline.media.move",
@@ -30,4 +31,5 @@ export const SKILL_OPERATIONS = [
30
31
  "timeline.transition.add",
31
32
  "timeline.audio.attach",
32
33
  "timeline.audio.mix",
34
+ "timeline.mask.add",
33
35
  ];