@morshoto/framekit 0.1.0 → 0.1.4
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.
- package/README.md +42 -17
- package/dist-package/adapters/final-cut/typescript/src/analyzers.js +57 -0
- package/dist-package/adapters/final-cut/typescript/src/connection.js +5 -1
- package/dist-package/adapters/final-cut/typescript/src/export.js +231 -8
- package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +55 -5
- package/dist-package/adapters/final-cut/typescript/src/live.js +2 -2
- package/dist-package/adapters/final-cut/typescript/src/native.js +1000 -100
- package/dist-package/adapters/final-cut/typescript/src/publisher.js +40 -5
- package/dist-package/adapters/final-cut/typescript/src/session.js +21 -5
- package/dist-package/apps/mcp-server/src/main.js +9 -1
- package/dist-package/apps/mcp-server/src/routing.js +172 -0
- package/dist-package/apps/mcp-server/src/server.js +780 -33
- package/dist-package/packages/runtime/src/application/duration-policy-service.js +6 -0
- package/dist-package/packages/runtime/src/application/media-analysis-service.js +370 -0
- package/dist-package/packages/runtime/src/application/project-service.js +127 -0
- package/dist-package/packages/runtime/src/application/runtime-options.js +1 -0
- package/dist-package/packages/runtime/src/application/transaction-store.js +12 -0
- package/dist-package/packages/runtime/src/audio/dialogue-normalization.js +64 -0
- package/dist-package/packages/runtime/src/audio/noise-reduction.js +46 -0
- package/dist-package/packages/runtime/src/capabilities.js +112 -1
- package/dist-package/packages/runtime/src/color-correction.js +48 -0
- package/dist-package/packages/runtime/src/context/context-engine.js +11 -6
- package/dist-package/packages/runtime/src/context/context-service.js +30 -0
- package/dist-package/packages/runtime/src/context/revision.js +3 -0
- package/dist-package/packages/runtime/src/domain/capabilities.js +1 -0
- package/dist-package/packages/runtime/src/domain/context.js +1 -0
- package/dist-package/packages/runtime/src/domain/diff.js +1 -0
- package/dist-package/packages/runtime/src/domain/duration.js +1 -0
- package/dist-package/packages/runtime/src/domain/editing.js +1 -0
- package/dist-package/packages/runtime/src/domain/index.js +12 -0
- package/dist-package/packages/runtime/src/domain/media.js +7 -0
- package/dist-package/packages/runtime/src/domain/ports.js +1 -0
- package/dist-package/packages/runtime/src/domain/primitives.js +1 -0
- package/dist-package/packages/runtime/src/domain/project.js +1 -0
- package/dist-package/packages/runtime/src/domain/rough-cut.js +69 -0
- package/dist-package/packages/runtime/src/domain/skills.js +33 -0
- package/dist-package/packages/runtime/src/domain/types.js +5 -1
- package/dist-package/packages/runtime/src/domain/verification.js +1 -0
- package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.js +141 -0
- package/dist-package/packages/runtime/src/editing/duration-policy.js +187 -0
- package/dist-package/packages/runtime/src/editing/edit-service.js +413 -0
- package/dist-package/packages/runtime/src/editing/filler-removal-service.js +337 -0
- package/dist-package/packages/runtime/src/editing/music-service.js +85 -0
- package/dist-package/packages/runtime/src/index.js +12 -3
- package/dist-package/packages/runtime/src/planning/rough-cut.js +65 -0
- package/dist-package/packages/runtime/src/runtime.js +130 -825
- package/dist-package/packages/runtime/src/skills/builtin.js +339 -0
- package/dist-package/packages/runtime/src/skills/index.js +3 -0
- package/dist-package/packages/runtime/src/skills/registry.js +74 -0
- package/dist-package/packages/runtime/src/skills/requirements.js +170 -0
- package/dist-package/packages/runtime/src/skills/runtime.js +239 -0
- package/dist-package/packages/runtime/src/speech/filler-detector.js +132 -0
- package/dist-package/packages/runtime/src/speech/safe-cut-resolver.js +314 -0
- package/dist-package/packages/runtime/src/timeline/rational-time.js +58 -0
- package/dist-package/packages/runtime/src/verification/verification.js +712 -1
- package/dist-package/packages/testkit/src/fixture-analyzers.js +27 -0
- package/dist-package/packages/testkit/src/in-memory-editor.js +286 -3
- package/dist-package/packages/testkit/src/index.js +1 -0
- package/dist-package/packages/testkit/src/skill-fixtures.js +64 -0
- package/package.json +15 -7
- /package/dist-package/packages/runtime/src/{diff/diff.js → timeline/snapshot-diff.js} +0 -0
- /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/
|
|
7
|
-
<img src="https://img.shields.io/badge/
|
|
8
|
-
<img src="https://img.shields.io/badge/
|
|
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-11.10.0-F69220?logo=pnpm&logoColor=white" alt="pnpm 11.10.0" />
|
|
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
|
-
##
|
|
16
|
+
## Get started
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
For repository development, you need:
|
|
19
|
+
|
|
20
|
+
- Node.js 20 or newer;
|
|
21
|
+
- pnpm 11.10.0;
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
44
|
-
|
|
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,
|
|
91
|
+
Contributor setup, repository layout, native checks, and the local pre-commit
|
|
92
|
+
hook are documented in [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
@@ -5,10 +5,12 @@ export function createCommandAnalyzers(options) {
|
|
|
5
5
|
...(options.speechCommand ? { speechAnalyzer: new CommandSpeechAnalyzer({ command: options.speechCommand, timeoutMs: options.timeoutMs }) } : {}),
|
|
6
6
|
...(options.audioCommand ? { audioAnalyzer: new CommandAudioAnalyzer({ command: options.audioCommand, timeoutMs: options.timeoutMs }) } : {}),
|
|
7
7
|
...(options.visualCommand ? { visualAnalyzer: new CommandVisualAnalyzer({ command: options.visualCommand, timeoutMs: options.timeoutMs }) } : {}),
|
|
8
|
+
...(options.metadataCommand ? { metadataAnalyzer: new CommandMetadataAnalyzer({ command: options.metadataCommand, timeoutMs: options.timeoutMs }) } : {}),
|
|
8
9
|
};
|
|
9
10
|
}
|
|
10
11
|
export class CommandSpeechAnalyzer {
|
|
11
12
|
options;
|
|
13
|
+
descriptor = { id: "command.speech", provider: "command" };
|
|
12
14
|
constructor(options) {
|
|
13
15
|
this.options = options;
|
|
14
16
|
}
|
|
@@ -18,6 +20,7 @@ export class CommandSpeechAnalyzer {
|
|
|
18
20
|
}
|
|
19
21
|
export class CommandAudioAnalyzer {
|
|
20
22
|
options;
|
|
23
|
+
descriptor = { id: "command.audio", provider: "command" };
|
|
21
24
|
constructor(options) {
|
|
22
25
|
this.options = options;
|
|
23
26
|
}
|
|
@@ -27,6 +30,7 @@ export class CommandAudioAnalyzer {
|
|
|
27
30
|
}
|
|
28
31
|
export class CommandVisualAnalyzer {
|
|
29
32
|
options;
|
|
33
|
+
descriptor = { id: "command.visual", provider: "command" };
|
|
30
34
|
constructor(options) {
|
|
31
35
|
this.options = options;
|
|
32
36
|
}
|
|
@@ -34,6 +38,16 @@ export class CommandVisualAnalyzer {
|
|
|
34
38
|
return runCommand(this.options, { ...input, range }, "visual");
|
|
35
39
|
}
|
|
36
40
|
}
|
|
41
|
+
export class CommandMetadataAnalyzer {
|
|
42
|
+
options;
|
|
43
|
+
descriptor = { id: "command.metadata", provider: "command" };
|
|
44
|
+
constructor(options) {
|
|
45
|
+
this.options = options;
|
|
46
|
+
}
|
|
47
|
+
async analyze(input, range) {
|
|
48
|
+
return runCommand(this.options, { ...input, range }, "metadata");
|
|
49
|
+
}
|
|
50
|
+
}
|
|
37
51
|
async function runCommand(options, request, kind) {
|
|
38
52
|
const source = request.media.source;
|
|
39
53
|
try {
|
|
@@ -100,6 +114,21 @@ function validateResult(value, kind) {
|
|
|
100
114
|
throw new Error("audio result requires loudness fields");
|
|
101
115
|
return;
|
|
102
116
|
}
|
|
117
|
+
if (kind === "metadata") {
|
|
118
|
+
for (const key of ["subjects", "scenes", "environments", "timeOfDay", "moods"]) {
|
|
119
|
+
if (record[key] !== undefined && (!Array.isArray(record[key]) || record[key].some((value) => !isSemanticTag(value)))) {
|
|
120
|
+
throw new Error(`metadata ${key} must contain typed tags`);
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
if (record.usableRanges !== undefined
|
|
124
|
+
&& (!Array.isArray(record.usableRanges) || record.usableRanges.some((value) => !isTimeRange(value)))) {
|
|
125
|
+
throw new Error("metadata usableRanges must contain valid time ranges");
|
|
126
|
+
}
|
|
127
|
+
if (record.confidence !== undefined && !isFiniteNumber(record.confidence)) {
|
|
128
|
+
throw new Error("metadata confidence must be numeric");
|
|
129
|
+
}
|
|
130
|
+
return;
|
|
131
|
+
}
|
|
103
132
|
if (!Array.isArray(record.scenes) || !Array.isArray(record.subjects) || !Array.isArray(record.keyframes)) {
|
|
104
133
|
throw new Error("visual result requires scenes, subjects, and keyframes");
|
|
105
134
|
}
|
|
@@ -114,3 +143,31 @@ function isSpeechWord(value) {
|
|
|
114
143
|
&& typeof word.confidence === "number"
|
|
115
144
|
&& (word.filler === undefined || typeof word.filler === "boolean");
|
|
116
145
|
}
|
|
146
|
+
function isSemanticTag(value) {
|
|
147
|
+
if (!value || typeof value !== "object")
|
|
148
|
+
return false;
|
|
149
|
+
const tag = value;
|
|
150
|
+
return typeof tag.value === "string" && isFiniteNumber(tag.confidence);
|
|
151
|
+
}
|
|
152
|
+
function isTimeRange(value) {
|
|
153
|
+
if (!value || typeof value !== "object")
|
|
154
|
+
return false;
|
|
155
|
+
const range = value;
|
|
156
|
+
return isFiniteNumber(range.start)
|
|
157
|
+
&& isFiniteNumber(range.end)
|
|
158
|
+
&& range.start >= 0
|
|
159
|
+
&& range.end > range.start
|
|
160
|
+
&& isOptionalRationalTime(range.startTime)
|
|
161
|
+
&& isOptionalRationalTime(range.durationTime);
|
|
162
|
+
}
|
|
163
|
+
function isOptionalRationalTime(value) {
|
|
164
|
+
if (value === undefined)
|
|
165
|
+
return true;
|
|
166
|
+
if (!value || typeof value !== "object")
|
|
167
|
+
return false;
|
|
168
|
+
const time = value;
|
|
169
|
+
return typeof time.value === "string" && typeof time.timescale === "string";
|
|
170
|
+
}
|
|
171
|
+
function isFiniteNumber(value) {
|
|
172
|
+
return typeof value === "number" && Number.isFinite(value);
|
|
173
|
+
}
|
|
@@ -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 (
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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;
|
|
@@ -3,6 +3,7 @@ import { readFile, writeFile } from "node:fs/promises";
|
|
|
3
3
|
import { fileURLToPath } from "node:url";
|
|
4
4
|
import { dirname, isAbsolute, resolve } from "node:path";
|
|
5
5
|
import { XMLBuilder, XMLParser } from "fast-xml-parser";
|
|
6
|
+
import { withCapabilityFamilies } from "../../../../packages/runtime/src/index.js";
|
|
6
7
|
const CLIP_KINDS = new Set(["asset-clip", "clip", "ref-clip", "sync-clip", "mc-clip", "audio", "video"]);
|
|
7
8
|
const TIMELINE_KINDS = new Set([
|
|
8
9
|
...CLIP_KINDS,
|
|
@@ -42,8 +43,14 @@ export class FcpxmlDocumentAdapter {
|
|
|
42
43
|
async getIdentity() {
|
|
43
44
|
return { name: "Final Cut Pro", version: "FCPXML", backend: "fcpxml-document" };
|
|
44
45
|
}
|
|
46
|
+
async getManagedArtifact() {
|
|
47
|
+
return { id: `fcpxml:${this.filePath}`, path: this.filePath, format: "fcpxml" };
|
|
48
|
+
}
|
|
49
|
+
async getManagedArtifactDigest() {
|
|
50
|
+
return hash(await readFile(this.filePath, "utf8"));
|
|
51
|
+
}
|
|
45
52
|
async getCapabilities() {
|
|
46
|
-
return {
|
|
53
|
+
return withCapabilityFamilies({
|
|
47
54
|
editor: {
|
|
48
55
|
projectRead: true,
|
|
49
56
|
timelineSnapshotRead: true,
|
|
@@ -58,9 +65,11 @@ export class FcpxmlDocumentAdapter {
|
|
|
58
65
|
frameCapture: false,
|
|
59
66
|
projectCatalogRead: true,
|
|
60
67
|
projectSelection: true,
|
|
68
|
+
compositeTransactions: true,
|
|
69
|
+
semanticOperations: { "add-marker": true },
|
|
61
70
|
},
|
|
62
71
|
analyzers: emptyAnalyzerCapabilities(),
|
|
63
|
-
};
|
|
72
|
+
}, { backend: "fcpxml-document" });
|
|
64
73
|
}
|
|
65
74
|
async listAssets() {
|
|
66
75
|
return [];
|
|
@@ -142,6 +151,50 @@ export class FcpxmlDocumentAdapter {
|
|
|
142
151
|
throw new Error("STALE_CONTEXT: FCPXML document changed before write");
|
|
143
152
|
}
|
|
144
153
|
this.history.set(expectedRevision.id, structuredClone(this.xml));
|
|
154
|
+
this.applyOperation(operation);
|
|
155
|
+
this.sequence += 1;
|
|
156
|
+
await this.persist();
|
|
157
|
+
return this.revision();
|
|
158
|
+
}
|
|
159
|
+
async previewTransaction(operations, expectedRevision) {
|
|
160
|
+
await this.ensureLoaded();
|
|
161
|
+
if (!sameRevision(expectedRevision, this.revision())) {
|
|
162
|
+
throw new Error("STALE_CONTEXT: FCPXML document changed before preview");
|
|
163
|
+
}
|
|
164
|
+
const originalXml = structuredClone(this.xml);
|
|
165
|
+
const originalSequence = this.sequence;
|
|
166
|
+
const originalSignature = this.fileSignature;
|
|
167
|
+
try {
|
|
168
|
+
for (const operation of operations) {
|
|
169
|
+
if (operation.type === "media.import" || operation.type.startsWith("timeline.")) {
|
|
170
|
+
throw new Error(`CAPABILITY_UNAVAILABLE: FCPXML preview does not support ${operation.type}`);
|
|
171
|
+
}
|
|
172
|
+
this.applyOperation(operation);
|
|
173
|
+
}
|
|
174
|
+
return this.readProject();
|
|
175
|
+
}
|
|
176
|
+
finally {
|
|
177
|
+
this.xml = originalXml;
|
|
178
|
+
this.sequence = originalSequence;
|
|
179
|
+
this.fileSignature = originalSignature;
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
async applyTransaction(operations, expectedRevision) {
|
|
183
|
+
await this.ensureLoaded();
|
|
184
|
+
if (!sameRevision(expectedRevision, this.revision())) {
|
|
185
|
+
throw new Error("STALE_CONTEXT: FCPXML document changed before transaction");
|
|
186
|
+
}
|
|
187
|
+
this.history.set(expectedRevision.id, structuredClone(this.xml));
|
|
188
|
+
for (const operation of operations) {
|
|
189
|
+
if (operation.type === "media.import" || operation.type.startsWith("timeline.")) {
|
|
190
|
+
throw new Error(`CAPABILITY_UNAVAILABLE: FCPXML transaction does not support ${operation.type}`);
|
|
191
|
+
}
|
|
192
|
+
this.applyOperation(operation);
|
|
193
|
+
}
|
|
194
|
+
this.sequence += 1;
|
|
195
|
+
await this.persist();
|
|
196
|
+
}
|
|
197
|
+
applyOperation(operation) {
|
|
145
198
|
const project = this.projectNode();
|
|
146
199
|
const sequenceNode = findElement(project, "sequence");
|
|
147
200
|
const sequence = sequenceNode ?? {};
|
|
@@ -194,9 +247,6 @@ export class FcpxmlDocumentAdapter {
|
|
|
194
247
|
}
|
|
195
248
|
}
|
|
196
249
|
this.updateSequenceDuration(sequence, spine);
|
|
197
|
-
this.sequence += 1;
|
|
198
|
-
await this.persist();
|
|
199
|
-
return this.revision();
|
|
200
250
|
}
|
|
201
251
|
async restore(snapshot, expectedRevision) {
|
|
202
252
|
await this.ensureLoaded();
|
|
@@ -2,7 +2,7 @@ import { createConnection } from "node:net";
|
|
|
2
2
|
import { randomUUID } from "node:crypto";
|
|
3
3
|
import { homedir } from "node:os";
|
|
4
4
|
import { join } from "node:path";
|
|
5
|
-
import {
|
|
5
|
+
import { withCapabilityFamilies } from "../../../../packages/runtime/src/index.js";
|
|
6
6
|
export const FINAL_CUT_LIVE_PROTOCOL_VERSION = 1;
|
|
7
7
|
/** Shared deterministic endpoint used by both the Node client and Swift host. */
|
|
8
8
|
export const DEFAULT_FINAL_CUT_LIVE_SOCKET = join(homedir(), "Library/Containers/com.framekit.finalcut.workflow.extension/Data/framekit.sock");
|
|
@@ -77,7 +77,7 @@ export class FinalCutLiveAdapter {
|
|
|
77
77
|
}
|
|
78
78
|
async getCapabilities() {
|
|
79
79
|
const response = await this.request({ method: "capabilities" });
|
|
80
|
-
return
|
|
80
|
+
return withCapabilityFamilies(response.capabilities, { backend: response.identity.backend });
|
|
81
81
|
}
|
|
82
82
|
async read() {
|
|
83
83
|
return this.readProject();
|