@morshoto/framekit 0.1.0 → 0.1.5

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 (65) hide show
  1. package/README.md +42 -17
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +86 -2
  3. package/dist-package/adapters/final-cut/typescript/src/connection.js +5 -1
  4. package/dist-package/adapters/final-cut/typescript/src/export.js +231 -8
  5. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +70 -9
  6. package/dist-package/adapters/final-cut/typescript/src/live.js +2 -2
  7. package/dist-package/adapters/final-cut/typescript/src/native.js +1000 -100
  8. package/dist-package/adapters/final-cut/typescript/src/publisher.js +242 -30
  9. package/dist-package/adapters/final-cut/typescript/src/session.js +86 -9
  10. package/dist-package/apps/mcp-server/src/main.js +10 -1
  11. package/dist-package/apps/mcp-server/src/routing.js +172 -0
  12. package/dist-package/apps/mcp-server/src/server.js +867 -52
  13. package/dist-package/apps/mcp-server/src/version.js +34 -0
  14. package/dist-package/packages/runtime/src/application/duration-policy-service.js +6 -0
  15. package/dist-package/packages/runtime/src/application/media-analysis-service.js +473 -0
  16. package/dist-package/packages/runtime/src/application/project-service.js +146 -0
  17. package/dist-package/packages/runtime/src/application/runtime-options.js +1 -0
  18. package/dist-package/packages/runtime/src/application/transaction-store.js +12 -0
  19. package/dist-package/packages/runtime/src/audio/dialogue-normalization.js +64 -0
  20. package/dist-package/packages/runtime/src/audio/noise-reduction.js +46 -0
  21. package/dist-package/packages/runtime/src/capabilities.js +187 -1
  22. package/dist-package/packages/runtime/src/color-correction.js +48 -0
  23. package/dist-package/packages/runtime/src/context/context-engine.js +20 -6
  24. package/dist-package/packages/runtime/src/context/context-service.js +30 -0
  25. package/dist-package/packages/runtime/src/context/revision.js +3 -0
  26. package/dist-package/packages/runtime/src/domain/capabilities.js +1 -0
  27. package/dist-package/packages/runtime/src/domain/context.js +1 -0
  28. package/dist-package/packages/runtime/src/domain/diff.js +1 -0
  29. package/dist-package/packages/runtime/src/domain/duration.js +1 -0
  30. package/dist-package/packages/runtime/src/domain/editing.js +1 -0
  31. package/dist-package/packages/runtime/src/domain/index.js +12 -0
  32. package/dist-package/packages/runtime/src/domain/media.js +8 -0
  33. package/dist-package/packages/runtime/src/domain/ports.js +1 -0
  34. package/dist-package/packages/runtime/src/domain/primitives.js +1 -0
  35. package/dist-package/packages/runtime/src/domain/project.js +1 -0
  36. package/dist-package/packages/runtime/src/domain/rough-cut.js +69 -0
  37. package/dist-package/packages/runtime/src/domain/skills.js +33 -0
  38. package/dist-package/packages/runtime/src/domain/types.js +5 -1
  39. package/dist-package/packages/runtime/src/domain/verification.js +1 -0
  40. package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.js +141 -0
  41. package/dist-package/packages/runtime/src/editing/duration-policy.js +187 -0
  42. package/dist-package/packages/runtime/src/editing/edit-service.js +449 -0
  43. package/dist-package/packages/runtime/src/editing/filler-removal-service.js +361 -0
  44. package/dist-package/packages/runtime/src/editing/music-service.js +85 -0
  45. package/dist-package/packages/runtime/src/index.js +14 -3
  46. package/dist-package/packages/runtime/src/planning/rough-cut.js +71 -0
  47. package/dist-package/packages/runtime/src/runtime.js +131 -826
  48. package/dist-package/packages/runtime/src/skills/builtin.js +339 -0
  49. package/dist-package/packages/runtime/src/skills/index.js +3 -0
  50. package/dist-package/packages/runtime/src/skills/registry.js +74 -0
  51. package/dist-package/packages/runtime/src/skills/requirements.js +170 -0
  52. package/dist-package/packages/runtime/src/skills/runtime.js +239 -0
  53. package/dist-package/packages/runtime/src/speech/analysis.js +301 -0
  54. package/dist-package/packages/runtime/src/speech/filler-detector.js +132 -0
  55. package/dist-package/packages/runtime/src/speech/mapping.js +227 -0
  56. package/dist-package/packages/runtime/src/speech/safe-cut-resolver.js +314 -0
  57. package/dist-package/packages/runtime/src/timeline/rational-time.js +63 -0
  58. package/dist-package/packages/runtime/src/verification/verification.js +712 -1
  59. package/dist-package/packages/testkit/src/fixture-analyzers.js +28 -0
  60. package/dist-package/packages/testkit/src/in-memory-editor.js +287 -3
  61. package/dist-package/packages/testkit/src/index.js +1 -0
  62. package/dist-package/packages/testkit/src/skill-fixtures.js +64 -0
  63. package/package.json +17 -8
  64. /package/dist-package/packages/runtime/src/{diff/diff.js → timeline/snapshot-diff.js} +0 -0
  65. /package/dist-package/packages/runtime/src/{snapshot-digest.js → timeline/snapshot-digest.js} +0 -0
package/README.md CHANGED
@@ -3,45 +3,59 @@
3
3
  </div>
4
4
 
5
5
  <p align="center">
6
- <img src="https://img.shields.io/badge/Swift-5.9%2B-F05138?logo=swift&logoColor=white" alt="Swift 5.9 or newer" />
7
- <img src="https://img.shields.io/badge/Python-3.13-3776AB?logo=python&logoColor=white" alt="Python 3.13" />
8
- <img src="https://img.shields.io/badge/platform-Apple%20Silicon%20macOS-000000?logo=apple&logoColor=white" alt="Apple Silicon macOS" />
6
+ <img src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white" alt="Node.js 20 or newer" />
7
+ <img src="https://img.shields.io/badge/pnpm-12.3.4-F69220?logo=pnpm&logoColor=white" alt="pnpm 12.3.4" />
8
+ <img src="https://img.shields.io/badge/Final%20Cut%20Pro-macOS-000000?logo=apple&logoColor=white" alt="Final Cut Pro on macOS" />
9
9
  <a href="https://discord.gg/Dmp8FSF4vg"><img src="https://img.shields.io/badge/Discord-Join%20Chat-5865F2?logo=discord&logoColor=white" alt="Join the Framekit Discord" /></a>
10
10
  </p>
11
11
 
12
12
  # Framekit
13
13
 
14
- Agentic video editing runtime.
14
+ Agentic video editing runtime and MCP server for Final Cut Pro.
15
15
 
16
- ## Installation
16
+ ## Get started
17
17
 
18
- Requirements:
18
+ For repository development, you need:
19
+
20
+ - Node.js 20 or newer;
21
+ - pnpm 12.3.4;
22
+ - Xcode 16.4 and the macOS 15.5 SDK for native Final Cut work.
23
+
24
+ The Xcode requirement is only needed for the native Workflow Extension. For the
25
+ pinned Node and shell toolchain, enter the optional Nix shell first:
26
+
27
+ ```sh
28
+ nix develop ./nix
29
+ ```
30
+
31
+ From the repository root, install dependencies and run the deterministic checks:
19
32
 
20
33
  ```sh
21
34
  pnpm install --frozen-lockfile
22
35
  pnpm run hooks:install
23
- pnpm run test
24
36
  pnpm run build
37
+ pnpm run test
38
+ pnpm run check:boundaries
25
39
  ```
26
40
 
27
- ## Quick Start
28
-
29
- The reproducible Node shell and native toolchain contract live under [`nix/`](nix/). Enter it with `nix develop ./nix`, then run `pnpm run xcode:check` before building the Final Cut Workflow Extension.
41
+ ## Try the local MCP server
30
42
 
31
- ## MCP server
32
-
33
- The local MCP server uses the deterministic in-memory Phase 2 fixture:
43
+ The local MCP server uses a deterministic in-memory fixture and communicates over
44
+ stdio. Start it from the repository root and connect it to an MCP client:
34
45
 
35
46
  ```sh
36
47
  pnpm run mcp
37
48
  ```
38
49
 
39
- The default `.env.example` starts the Diffusers visual service without the optional music stack. `Cmd-D` toggles Developer Mode and `Cmd-F` toggles the borderless exhibition presentation.
50
+ See the [MCP tools](./docs/mcp/tools.md) and [MCP documentation](./docs/mcp/README.md)
51
+ for the tool inventory and live-backend setup.
40
52
 
41
53
  ## Connect Codex to Final Cut
42
54
 
43
- Install the signed Framekit Workflow Extension from the latest release, then
44
- configure the Framekit marketplace once:
55
+ The Codex plugin provides the MCP integration; the Final Cut Workflow Extension
56
+ is installed separately. Download a signed extension from a
57
+ [Framekit GitHub release](https://github.com/morshoto/framekit/releases) when a
58
+ release asset is available, then configure the Framekit marketplace once:
45
59
 
46
60
  ```sh
47
61
  codex plugin marketplace add morshoto/framekit
@@ -56,12 +70,23 @@ existing Workflow Extension bridge and does not launch, activate, focus, or
56
70
  edit Final Cut through macOS UI automation. See the
57
71
  [first-run setup and capability boundaries](./docs/final-cut/installation.md).
58
72
 
73
+ For local native development, use the checkout's CLI wrapper from the repository
74
+ root:
75
+
76
+ ```sh
77
+ pnpm run xcode:check
78
+ bash adapters/final-cut/swift-bridge/FinalCutWorkflowExtension/build.sh
79
+ pnpm run framekit -- connect finalcut --development
80
+ ```
81
+
59
82
  ## Further Docs
60
83
 
61
84
  - [Documentation index](./docs/README.md)
85
+ - [Getting started](./docs/getting-started.md)
62
86
  - [Architecture](./docs/ARCHITECTURE.md)
63
87
  - [Clean Codex and Claude Code MCP validation](./docs/tests/clean-mcp-clients.md)
64
88
 
65
89
  ## Development
66
90
 
67
- Contributor setup, including the local pre-commit hook, is documented in [`CONTRIBUTOR.md`](CONTRIBUTOR.md).
91
+ Contributor setup, repository layout, native checks, and the local pre-commit
92
+ hook are documented in [CONTRIBUTING.md](CONTRIBUTING.md).
@@ -1,23 +1,34 @@
1
1
  import { spawn } from "node:child_process";
2
2
  import { access } from "node:fs/promises";
3
+ import { bindSpeechAnalysis } from "../../../../packages/runtime/src/index.js";
3
4
  export function createCommandAnalyzers(options) {
4
5
  return {
5
6
  ...(options.speechCommand ? { speechAnalyzer: new CommandSpeechAnalyzer({ command: options.speechCommand, timeoutMs: options.timeoutMs }) } : {}),
6
7
  ...(options.audioCommand ? { audioAnalyzer: new CommandAudioAnalyzer({ command: options.audioCommand, timeoutMs: options.timeoutMs }) } : {}),
7
8
  ...(options.visualCommand ? { visualAnalyzer: new CommandVisualAnalyzer({ command: options.visualCommand, timeoutMs: options.timeoutMs }) } : {}),
9
+ ...(options.metadataCommand ? { metadataAnalyzer: new CommandMetadataAnalyzer({ command: options.metadataCommand, timeoutMs: options.timeoutMs }) } : {}),
8
10
  };
9
11
  }
10
12
  export class CommandSpeechAnalyzer {
11
13
  options;
14
+ descriptor = { id: "command.speech", provider: "command" };
15
+ capabilities = { transcription: true, vad: false };
12
16
  constructor(options) {
13
17
  this.options = options;
14
18
  }
15
19
  async analyze(input, range) {
16
- return runCommand(this.options, { ...input, range }, "speech");
20
+ const result = await runCommand(this.options, { ...input, range }, "speech");
21
+ try {
22
+ return bindSpeechAnalysis(result, { input, range, provider: this.descriptor });
23
+ }
24
+ catch (error) {
25
+ throw new Error(`ANALYZER_INVALID_OUTPUT: speech analyzer returned invalid JSON or schema: ${String(error)}`);
26
+ }
17
27
  }
18
28
  }
19
29
  export class CommandAudioAnalyzer {
20
30
  options;
31
+ descriptor = { id: "command.audio", provider: "command" };
21
32
  constructor(options) {
22
33
  this.options = options;
23
34
  }
@@ -27,6 +38,7 @@ export class CommandAudioAnalyzer {
27
38
  }
28
39
  export class CommandVisualAnalyzer {
29
40
  options;
41
+ descriptor = { id: "command.visual", provider: "command" };
30
42
  constructor(options) {
31
43
  this.options = options;
32
44
  }
@@ -34,6 +46,16 @@ export class CommandVisualAnalyzer {
34
46
  return runCommand(this.options, { ...input, range }, "visual");
35
47
  }
36
48
  }
49
+ export class CommandMetadataAnalyzer {
50
+ options;
51
+ descriptor = { id: "command.metadata", provider: "command" };
52
+ constructor(options) {
53
+ this.options = options;
54
+ }
55
+ async analyze(input, range) {
56
+ return runCommand(this.options, { ...input, range }, "metadata");
57
+ }
58
+ }
37
59
  async function runCommand(options, request, kind) {
38
60
  const source = request.media.source;
39
61
  try {
@@ -83,9 +105,28 @@ async function runCommand(options, request, kind) {
83
105
  reject(new Error(`ANALYZER_INVALID_OUTPUT: ${kind} analyzer returned invalid JSON or schema: ${String(error)}`));
84
106
  }
85
107
  });
86
- child.stdin.end(JSON.stringify(request));
108
+ child.stdin.end(JSON.stringify(commandRequest(request, kind)));
87
109
  });
88
110
  }
111
+ function commandRequest(request, kind) {
112
+ if (kind !== "speech")
113
+ return request;
114
+ return {
115
+ schemaVersion: 1,
116
+ media: sourceIdentityOf(request.media),
117
+ revision: request.project.revision,
118
+ ...(request.range ? { range: structuredClone(request.range) } : {}),
119
+ };
120
+ }
121
+ function sourceIdentityOf(media) {
122
+ return {
123
+ mediaId: media.mediaId,
124
+ source: media.source,
125
+ ...(media.sourceDigest ? { sourceDigest: media.sourceDigest } : {}),
126
+ ...(media.mediaKind ? { mediaKind: media.mediaKind } : {}),
127
+ ...(media.duration !== undefined ? { duration: media.duration } : {}),
128
+ };
129
+ }
89
130
  function validateResult(value, kind) {
90
131
  if (!value || typeof value !== "object")
91
132
  throw new Error("result must be an object");
@@ -100,6 +141,21 @@ function validateResult(value, kind) {
100
141
  throw new Error("audio result requires loudness fields");
101
142
  return;
102
143
  }
144
+ if (kind === "metadata") {
145
+ for (const key of ["subjects", "scenes", "environments", "timeOfDay", "moods"]) {
146
+ if (record[key] !== undefined && (!Array.isArray(record[key]) || record[key].some((value) => !isSemanticTag(value)))) {
147
+ throw new Error(`metadata ${key} must contain typed tags`);
148
+ }
149
+ }
150
+ if (record.usableRanges !== undefined
151
+ && (!Array.isArray(record.usableRanges) || record.usableRanges.some((value) => !isTimeRange(value)))) {
152
+ throw new Error("metadata usableRanges must contain valid time ranges");
153
+ }
154
+ if (record.confidence !== undefined && !isFiniteNumber(record.confidence)) {
155
+ throw new Error("metadata confidence must be numeric");
156
+ }
157
+ return;
158
+ }
103
159
  if (!Array.isArray(record.scenes) || !Array.isArray(record.subjects) || !Array.isArray(record.keyframes)) {
104
160
  throw new Error("visual result requires scenes, subjects, and keyframes");
105
161
  }
@@ -114,3 +170,31 @@ function isSpeechWord(value) {
114
170
  && typeof word.confidence === "number"
115
171
  && (word.filler === undefined || typeof word.filler === "boolean");
116
172
  }
173
+ function isSemanticTag(value) {
174
+ if (!value || typeof value !== "object")
175
+ return false;
176
+ const tag = value;
177
+ return typeof tag.value === "string" && isFiniteNumber(tag.confidence);
178
+ }
179
+ function isTimeRange(value) {
180
+ if (!value || typeof value !== "object")
181
+ return false;
182
+ const range = value;
183
+ return isFiniteNumber(range.start)
184
+ && isFiniteNumber(range.end)
185
+ && range.start >= 0
186
+ && range.end > range.start
187
+ && isOptionalRationalTime(range.startTime)
188
+ && isOptionalRationalTime(range.durationTime);
189
+ }
190
+ function isOptionalRationalTime(value) {
191
+ if (value === undefined)
192
+ return true;
193
+ if (!value || typeof value !== "object")
194
+ return false;
195
+ const time = value;
196
+ return typeof time.value === "string" && typeof time.timescale === "string";
197
+ }
198
+ function isFiniteNumber(value) {
199
+ return typeof value === "number" && Number.isFinite(value);
200
+ }
@@ -4,6 +4,7 @@ import { existsSync } from "node:fs";
4
4
  import { promisify } from "node:util";
5
5
  import { homedir } from "node:os";
6
6
  import { dirname, join, resolve } from "node:path";
7
+ import { withCapabilityFamilies } from "../../../../packages/runtime/src/index.js";
7
8
  import { createFinalCutLiveAdapter, DEFAULT_FINAL_CUT_LIVE_SOCKET } from "./live.js";
8
9
  const execFile = promisify(execFileCallback);
9
10
  const DEFAULT_EXTENSION_NAME = "FramekitFinalCutWorkflow.app";
@@ -186,7 +187,10 @@ export class FinalCutConnectionManager {
186
187
  editorDetected: true,
187
188
  extensionInstalled: true,
188
189
  identity: result.identity,
189
- capabilities: result.capabilities,
190
+ capabilities: withCapabilityFamilies(result.capabilities, {
191
+ backend: result.identity.backend,
192
+ connectionBackend: result.identity.backend,
193
+ }),
190
194
  lastError: undefined,
191
195
  });
192
196
  return this.getStatus();
@@ -1,5 +1,7 @@
1
1
  import { randomUUID } from "node:crypto";
2
2
  import { execFile as execFileCallback } from "node:child_process";
3
+ import { createHash } from "node:crypto";
4
+ import { createReadStream } from "node:fs";
3
5
  import { access, constants, rename, stat, unlink } from "node:fs/promises";
4
6
  import { basename, dirname, extname, join, resolve } from "node:path";
5
7
  import { promisify } from "node:util";
@@ -77,13 +79,16 @@ export class FinalCutVideoExporter {
77
79
  await this.assertPreflight();
78
80
  await this.executor(exportScript(stagingPath, preset.menuItem));
79
81
  const output = await this.waitForOutput(stagingPath);
82
+ const outputDigest = await sha256File(stagingPath);
80
83
  const probed = await this.probeUntilReady(stagingPath, output.deadline);
81
84
  const metadata = {
82
85
  outputPath,
83
86
  sizeBytes: output.size,
87
+ format: outputFormat(outputPath),
88
+ outputDigest,
84
89
  ...probed,
85
90
  };
86
- verifyMetadata(metadata, request.expected);
91
+ const verification = verifyMetadata(metadata, request.expected);
87
92
  await commitOutput(stagingPath, outputPath, request.overwrite ?? false);
88
93
  committed = true;
89
94
  return {
@@ -92,6 +97,7 @@ export class FinalCutVideoExporter {
92
97
  completed: true,
93
98
  verified: true,
94
99
  metadata,
100
+ verification,
95
101
  };
96
102
  });
97
103
  return result;
@@ -181,6 +187,16 @@ export class FinalCutVideoExporter {
181
187
  }
182
188
  }
183
189
  }
190
+ async function sha256File(filePath) {
191
+ const hash = createHash("sha256");
192
+ for await (const chunk of createReadStream(filePath))
193
+ hash.update(chunk);
194
+ return `sha256:${hash.digest("hex")}`;
195
+ }
196
+ function outputFormat(outputPath) {
197
+ const extension = extname(outputPath).slice(1).toLowerCase();
198
+ return extension || "unknown";
199
+ }
184
200
  async function assertOutputDirectory(outputPath) {
185
201
  try {
186
202
  const parent = await stat(dirname(outputPath));
@@ -263,6 +279,41 @@ function validateExpectation(expectation) {
263
279
  && (!Number.isFinite(expectation.frameRateTolerance) || expectation.frameRateTolerance < 0)) {
264
280
  throw new Error("INVALID_EXPORT: frameRateTolerance must be a non-negative finite number");
265
281
  }
282
+ for (const assertion of expectation.assertions ?? [])
283
+ validateExportAssertion(assertion);
284
+ }
285
+ function validateExportAssertion(assertion) {
286
+ if (assertion.type === "audio-audibility") {
287
+ if (assertion.minAudibleSamples !== undefined
288
+ && (!Number.isInteger(assertion.minAudibleSamples) || assertion.minAudibleSamples <= 0)) {
289
+ throw new Error("INVALID_EXPORT: minAudibleSamples must be a positive integer");
290
+ }
291
+ if (assertion.maxSilenceMs !== undefined
292
+ && (!Number.isFinite(assertion.maxSilenceMs) || assertion.maxSilenceMs < 0)) {
293
+ throw new Error("INVALID_EXPORT: maxSilenceMs must be a non-negative finite number");
294
+ }
295
+ }
296
+ if (assertion.type === "audio-coverage"
297
+ && (!Number.isFinite(assertion.expectedSeconds) || assertion.expectedSeconds <= 0
298
+ || assertion.toleranceSeconds !== undefined
299
+ && (!Number.isFinite(assertion.toleranceSeconds) || assertion.toleranceSeconds < 0))) {
300
+ throw new Error("INVALID_EXPORT: audio coverage must use positive finite duration and non-negative tolerance");
301
+ }
302
+ if (assertion.type === "audio-loudness"
303
+ && (!Number.isFinite(assertion.targetLufs)
304
+ || assertion.toleranceDb !== undefined
305
+ && (!Number.isFinite(assertion.toleranceDb) || assertion.toleranceDb < 0))) {
306
+ throw new Error("INVALID_EXPORT: audio loudness must use finite target and non-negative tolerance");
307
+ }
308
+ if (assertion.type === "audio-source" && assertion.sourceDigest === undefined && assertion.source === undefined) {
309
+ throw new Error("INVALID_EXPORT: audio-source assertion requires sourceDigest or source");
310
+ }
311
+ if (assertion.type === "visual-content"
312
+ && (assertion.label.trim().length === 0
313
+ || assertion.minConfidence !== undefined
314
+ && (!Number.isFinite(assertion.minConfidence) || assertion.minConfidence < 0 || assertion.minConfidence > 1))) {
315
+ throw new Error("INVALID_EXPORT: visual content must use a label and confidence between 0 and 1");
316
+ }
266
317
  }
267
318
  function verifyMetadata(metadata, expectation) {
268
319
  if (!Number.isFinite(metadata.durationSeconds) || metadata.durationSeconds <= 0) {
@@ -277,25 +328,197 @@ function verifyMetadata(metadata, expectation) {
277
328
  if (typeof metadata.hasAudio !== "boolean") {
278
329
  throw new Error("FINAL_CUT_EXPORT_VERIFICATION_FAILED: output audio presence is missing or invalid");
279
330
  }
280
- if (!expectation)
281
- return;
282
- if (expectation.durationSeconds !== undefined
331
+ if (expectation?.durationSeconds !== undefined
283
332
  && Math.abs(metadata.durationSeconds - expectation.durationSeconds) > (expectation.durationToleranceSeconds ?? 0.05)) {
284
333
  throw new Error(`FINAL_CUT_EXPORT_VERIFICATION_FAILED: expected duration ${expectation.durationSeconds}s, observed ${metadata.durationSeconds}s`);
285
334
  }
286
- if (expectation.width !== undefined && metadata.width !== expectation.width) {
335
+ if (expectation?.width !== undefined && metadata.width !== expectation.width) {
287
336
  throw new Error(`FINAL_CUT_EXPORT_VERIFICATION_FAILED: expected width ${expectation.width}, observed ${metadata.width}`);
288
337
  }
289
- if (expectation.height !== undefined && metadata.height !== expectation.height) {
338
+ if (expectation?.height !== undefined && metadata.height !== expectation.height) {
290
339
  throw new Error(`FINAL_CUT_EXPORT_VERIFICATION_FAILED: expected height ${expectation.height}, observed ${metadata.height}`);
291
340
  }
292
- if (expectation.frameRate !== undefined
341
+ if (expectation?.frameRate !== undefined
293
342
  && Math.abs(metadata.frameRate - expectation.frameRate) > (expectation.frameRateTolerance ?? 0.01)) {
294
343
  throw new Error(`FINAL_CUT_EXPORT_VERIFICATION_FAILED: expected frame rate ${expectation.frameRate}, observed ${metadata.frameRate}`);
295
344
  }
296
- if (expectation.hasAudio !== undefined && metadata.hasAudio !== expectation.hasAudio) {
345
+ if (expectation?.hasAudio !== undefined && metadata.hasAudio !== expectation.hasAudio) {
297
346
  throw new Error(`FINAL_CUT_EXPORT_VERIFICATION_FAILED: expected audio presence ${expectation.hasAudio}, observed ${metadata.hasAudio}`);
298
347
  }
348
+ const checks = (expectation?.assertions ?? []).map((assertion) => verifySemanticAssertion(metadata, assertion));
349
+ const report = { passed: checks.every((check) => check.passed), checks };
350
+ if (!report.passed) {
351
+ const unavailable = checks.find((check) => check.status === "unavailable");
352
+ const failed = unavailable ?? checks.find((check) => !check.passed);
353
+ const code = unavailable
354
+ ? "FINAL_CUT_EXPORT_SEMANTIC_UNAVAILABLE"
355
+ : "FINAL_CUT_EXPORT_SEMANTIC_VERIFICATION_FAILED";
356
+ throw new Error(`${code}: ${failed.detail}; expected=${JSON.stringify(failed.expected)} observed=${JSON.stringify(failed.observed)}`);
357
+ }
358
+ return report;
359
+ }
360
+ function verifySemanticAssertion(metadata, assertion) {
361
+ if (assertion.type === "audio-audibility") {
362
+ const expected = {
363
+ minAudibleSamples: assertion.minAudibleSamples ?? 1,
364
+ ...(assertion.maxSilenceMs !== undefined ? { maxSilenceMs: assertion.maxSilenceMs } : {}),
365
+ };
366
+ const audio = metadata.semantic?.audio;
367
+ if (!audio)
368
+ return unavailableSemanticCheck(assertion.type, expected, "audio analyzer output is unavailable");
369
+ const duration = Number.isFinite(audio.analyzedDurationSeconds) && audio.analyzedDurationSeconds > 0
370
+ ? audio.analyzedDurationSeconds
371
+ : undefined;
372
+ if (audio.audibleSamples === undefined && duration === undefined) {
373
+ return unavailableSemanticCheck(assertion.type, expected, "audio analyzer duration evidence is unavailable");
374
+ }
375
+ if (audio.audibleSamples === undefined && (assertion.minAudibleSamples ?? 1) > 1) {
376
+ return unavailableSemanticCheck(assertion.type, expected, "audio analyzer sample-count evidence is unavailable");
377
+ }
378
+ const audible = audio.audibleSamples === undefined
379
+ ? audio.silenceMs < duration * 1000
380
+ : audio.audibleSamples >= (assertion.minAudibleSamples ?? 1);
381
+ const silenceWithinLimit = assertion.maxSilenceMs === undefined || audio.silenceMs <= assertion.maxSilenceMs;
382
+ const passed = audible && silenceWithinLimit;
383
+ return {
384
+ name: assertion.type,
385
+ passed,
386
+ status: passed ? "passed" : "failed",
387
+ expected,
388
+ observed: {
389
+ ...(audio.audibleSamples !== undefined ? { audibleSamples: audio.audibleSamples } : {}),
390
+ silenceMs: audio.silenceMs,
391
+ },
392
+ ...(passed ? {} : { reason: audible ? "AUDIO_SILENCE_EXCEEDED" : "AUDIO_NOT_AUDIBLE" }),
393
+ detail: passed
394
+ ? "observed audible audio in the exported file"
395
+ : audible
396
+ ? `expected at most ${assertion.maxSilenceMs}ms of silence, observed ${audio.silenceMs}ms`
397
+ : "expected audible audio samples, observed none",
398
+ };
399
+ }
400
+ if (assertion.type === "audio-coverage") {
401
+ const expected = {
402
+ expectedSeconds: assertion.expectedSeconds,
403
+ toleranceSeconds: assertion.toleranceSeconds ?? 0,
404
+ };
405
+ const audio = metadata.semantic?.audio;
406
+ if (!audio)
407
+ return unavailableSemanticCheck(assertion.type, expected, "audio analyzer output is unavailable");
408
+ const observed = Number.isFinite(audio.analyzedDurationSeconds) && audio.analyzedDurationSeconds > 0
409
+ ? audio.analyzedDurationSeconds
410
+ : undefined;
411
+ if (observed === undefined) {
412
+ return unavailableSemanticCheck(assertion.type, expected, "audio analyzer duration evidence is unavailable");
413
+ }
414
+ const passed = observed >= assertion.expectedSeconds - (assertion.toleranceSeconds ?? 0);
415
+ return {
416
+ name: assertion.type,
417
+ passed,
418
+ status: passed ? "passed" : "failed",
419
+ expected,
420
+ observed,
421
+ ...(passed ? {} : { reason: "AUDIO_COVERAGE_INCOMPLETE" }),
422
+ detail: passed
423
+ ? `observed ${observed}s of exported audio coverage`
424
+ : `expected ${assertion.expectedSeconds}s of exported audio coverage, observed ${observed}s`,
425
+ };
426
+ }
427
+ if (assertion.type === "audio-loudness") {
428
+ const expected = {
429
+ targetLufs: assertion.targetLufs,
430
+ toleranceDb: assertion.toleranceDb ?? 0.5,
431
+ };
432
+ const audio = metadata.semantic?.audio;
433
+ if (!audio)
434
+ return unavailableSemanticCheck(assertion.type, expected, "audio analyzer output is unavailable");
435
+ const observed = audio.integratedLufs;
436
+ const passed = Math.abs(observed - assertion.targetLufs) <= (assertion.toleranceDb ?? 0.5);
437
+ return {
438
+ name: assertion.type,
439
+ passed,
440
+ status: passed ? "passed" : "failed",
441
+ expected,
442
+ observed,
443
+ ...(passed ? {} : { reason: "AUDIO_LOUDNESS_OUT_OF_RANGE" }),
444
+ detail: passed
445
+ ? `observed ${observed} LUFS within the requested range`
446
+ : `expected ${assertion.targetLufs} LUFS ±${assertion.toleranceDb ?? 0.5} dB, observed ${observed} LUFS`,
447
+ };
448
+ }
449
+ if (assertion.type === "audio-source") {
450
+ const expected = {
451
+ ...(assertion.sourceDigest !== undefined ? { sourceDigest: assertion.sourceDigest } : {}),
452
+ ...(assertion.source !== undefined ? { source: assertion.source } : {}),
453
+ };
454
+ const observed = {
455
+ ...(metadata.semantic?.sourceDigest !== undefined ? { sourceDigest: metadata.semantic.sourceDigest } : {}),
456
+ ...(metadata.semantic?.source !== undefined ? { source: metadata.semantic.source } : {}),
457
+ };
458
+ if (Object.keys(observed).length === 0) {
459
+ return unavailableSemanticCheck(assertion.type, expected, "exported source identity evidence is unavailable");
460
+ }
461
+ const passed = (assertion.sourceDigest !== undefined && observed.sourceDigest === assertion.sourceDigest
462
+ || assertion.source !== undefined && observed.source === assertion.source)
463
+ && (assertion.sourceDigest === undefined || observed.sourceDigest === assertion.sourceDigest)
464
+ && (assertion.source === undefined || observed.source === assertion.source);
465
+ return {
466
+ name: assertion.type,
467
+ passed,
468
+ status: passed ? "passed" : "failed",
469
+ expected,
470
+ observed,
471
+ ...(passed ? {} : { reason: "AUDIO_SOURCE_MISMATCH" }),
472
+ detail: passed ? "observed the expected exported source identity" : "exported source identity did not match",
473
+ };
474
+ }
475
+ if (assertion.type === "stream") {
476
+ const observed = assertion.target === "audio" ? metadata.hasAudio : true;
477
+ const passed = observed === assertion.expected;
478
+ return {
479
+ name: assertion.type,
480
+ passed,
481
+ status: passed ? "passed" : "failed",
482
+ expected: { target: assertion.target, expected: assertion.expected },
483
+ observed,
484
+ ...(passed ? {} : { reason: "STREAM_PRESENCE_MISMATCH" }),
485
+ detail: passed ? "observed the expected exported stream presence" : "exported stream presence did not match",
486
+ };
487
+ }
488
+ const labelKind = assertion.labelKind ?? "subject";
489
+ const expected = {
490
+ label: assertion.label,
491
+ labelKind,
492
+ ...(assertion.minConfidence !== undefined ? { minConfidence: assertion.minConfidence } : {}),
493
+ };
494
+ const visual = metadata.semantic?.visual;
495
+ if (!visual)
496
+ return unavailableSemanticCheck(assertion.type, expected, "visual analyzer output is unavailable");
497
+ const candidates = labelKind === "scene"
498
+ ? visual.scenes.filter((scene) => scene.label !== undefined).map((scene) => ({ label: scene.label, confidence: scene.confidence ?? 0 }))
499
+ : visual.subjects.map((subject) => ({ label: subject.label, confidence: subject.confidence }));
500
+ const matching = candidates.find((candidate) => candidate.label.toLowerCase() === assertion.label.toLowerCase());
501
+ const passed = matching !== undefined && matching.confidence >= (assertion.minConfidence ?? 0);
502
+ return {
503
+ name: assertion.type,
504
+ passed,
505
+ status: passed ? "passed" : "failed",
506
+ expected,
507
+ observed: candidates,
508
+ ...(passed ? {} : { reason: "VISUAL_CONTENT_NOT_FOUND" }),
509
+ detail: passed ? "observed the expected exported visual content" : "expected exported visual content was not observed",
510
+ };
511
+ }
512
+ function unavailableSemanticCheck(name, expected, detail) {
513
+ return {
514
+ name,
515
+ passed: false,
516
+ status: "unavailable",
517
+ expected,
518
+ observed: null,
519
+ reason: "ANALYZER_UNAVAILABLE",
520
+ detail,
521
+ };
299
522
  }
300
523
  async function probeWithFfprobe(outputPath) {
301
524
  let stdout;