@morshoto/framekit 0.2.2 → 0.2.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.
Files changed (160) hide show
  1. package/dist-package/adapters/final-cut/typescript/src/analyzers.d.ts +58 -0
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +52 -13
  3. package/dist-package/adapters/final-cut/typescript/src/assets.d.ts +24 -0
  4. package/dist-package/adapters/final-cut/typescript/src/background-export.d.ts +98 -0
  5. package/dist-package/adapters/final-cut/typescript/src/background-materialization.d.ts +47 -0
  6. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.d.ts +32 -0
  7. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.d.ts +22 -0
  8. package/dist-package/adapters/final-cut/typescript/src/canonical-verification.d.ts +11 -0
  9. package/dist-package/adapters/final-cut/typescript/src/canonical.d.ts +184 -0
  10. package/dist-package/adapters/final-cut/typescript/src/canonical.js +33 -1
  11. package/dist-package/adapters/final-cut/typescript/src/connection.d.ts +103 -0
  12. package/dist-package/adapters/final-cut/typescript/src/disposable-native.d.ts +90 -0
  13. package/dist-package/adapters/final-cut/typescript/src/documents.d.ts +3 -0
  14. package/dist-package/adapters/final-cut/typescript/src/documents.js +3 -0
  15. package/dist-package/adapters/final-cut/typescript/src/experimental.d.ts +8 -0
  16. package/dist-package/adapters/final-cut/typescript/src/export.d.ts +125 -0
  17. package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.d.ts +54 -0
  18. package/dist-package/adapters/final-cut/typescript/src/fcpxml.d.ts +75 -0
  19. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +6 -1
  20. package/dist-package/adapters/final-cut/typescript/src/index.d.ts +22 -0
  21. package/dist-package/adapters/final-cut/typescript/src/library-inspection.d.ts +101 -0
  22. package/dist-package/adapters/final-cut/typescript/src/live.d.ts +101 -0
  23. package/dist-package/adapters/final-cut/typescript/src/live.js +8 -0
  24. package/dist-package/adapters/final-cut/typescript/src/media.d.ts +12 -0
  25. package/dist-package/adapters/final-cut/typescript/src/native-operation.d.ts +6 -0
  26. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.d.ts +77 -0
  27. package/dist-package/adapters/final-cut/typescript/src/native-session.d.ts +130 -0
  28. package/dist-package/adapters/final-cut/typescript/src/native.d.ts +828 -0
  29. package/dist-package/adapters/final-cut/typescript/src/native.js +274 -107
  30. package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.d.ts +114 -0
  31. package/dist-package/adapters/final-cut/typescript/src/publish-readback.d.ts +26 -0
  32. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +18 -2
  33. package/dist-package/adapters/final-cut/typescript/src/publisher.d.ts +215 -0
  34. package/dist-package/adapters/final-cut/typescript/src/session.d.ts +43 -0
  35. package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.d.ts +51 -0
  36. package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.d.ts +156 -0
  37. package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.d.ts +134 -0
  38. package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.d.ts +110 -0
  39. package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.d.ts +132 -0
  40. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.d.ts +61 -0
  41. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +28 -4
  42. package/dist-package/adapters/final-cut/typescript/src/unattended-editing.d.ts +54 -0
  43. package/dist-package/adapters/headless/typescript/src/audio-output.d.ts +3 -0
  44. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.d.ts +11 -0
  45. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +26 -2
  46. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.d.ts +27 -0
  47. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +7 -2
  48. package/dist-package/adapters/headless/typescript/src/ffmpeg-storyboard.d.ts +28 -0
  49. package/dist-package/adapters/headless/typescript/src/ffmpeg-storyboard.js +120 -0
  50. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.d.ts +15 -0
  51. package/dist-package/adapters/headless/typescript/src/index.d.ts +4 -0
  52. package/dist-package/adapters/headless/typescript/src/index.js +1 -0
  53. package/dist-package/apps/cli/src/dev-doctor.d.ts +25 -0
  54. package/dist-package/apps/cli/src/headless-projects.d.ts +3 -0
  55. package/dist-package/apps/cli/src/main.d.ts +10 -0
  56. package/dist-package/apps/mcp-server/runtime/ffmpeg-audio-backend.py +129 -0
  57. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +92 -2
  58. package/dist-package/apps/mcp-server/src/build-alignment.d.ts +10 -0
  59. package/dist-package/apps/mcp-server/src/build-identity.d.ts +7 -0
  60. package/dist-package/apps/mcp-server/src/build-identity.json +2 -2
  61. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.d.ts +8 -0
  62. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.d.ts +5 -0
  63. package/dist-package/apps/mcp-server/src/headless-project-snapshot.d.ts +3 -0
  64. package/dist-package/apps/mcp-server/src/headless-sessions.d.ts +89 -0
  65. package/dist-package/apps/mcp-server/src/main.d.ts +1 -0
  66. package/dist-package/apps/mcp-server/src/main.js +2 -1
  67. package/dist-package/apps/mcp-server/src/materialization-jobs.d.ts +204 -0
  68. package/dist-package/apps/mcp-server/src/readback-policy.d.ts +18 -0
  69. package/dist-package/apps/mcp-server/src/routing.d.ts +90 -0
  70. package/dist-package/apps/mcp-server/src/server.d.ts +75 -0
  71. package/dist-package/apps/mcp-server/src/server.js +93 -9
  72. package/dist-package/apps/mcp-server/src/tools/skills/catalog.d.ts +19 -0
  73. package/dist-package/apps/mcp-server/src/tools/skills/metadata.d.ts +37 -0
  74. package/dist-package/apps/mcp-server/src/tools/skills/register.d.ts +11 -0
  75. package/dist-package/apps/mcp-server/src/version.d.ts +4 -0
  76. package/dist-package/packages/headless-application/src/external-edit.d.ts +30 -0
  77. package/dist-package/packages/headless-application/src/external-edit.js +72 -0
  78. package/dist-package/packages/headless-application/src/headless-projects.d.ts +259 -0
  79. package/dist-package/packages/headless-application/src/headless-projects.js +15 -2
  80. package/dist-package/packages/headless-application/src/index.d.ts +2 -0
  81. package/dist-package/packages/headless-application/src/index.js +1 -0
  82. package/dist-package/packages/runtime/src/application/duration-policy-service.d.ts +4 -0
  83. package/dist-package/packages/runtime/src/application/local-media.d.ts +46 -0
  84. package/dist-package/packages/runtime/src/application/media-analysis-service.d.ts +40 -0
  85. package/dist-package/packages/runtime/src/application/media-analysis-service.js +105 -15
  86. package/dist-package/packages/runtime/src/application/project-service.d.ts +35 -0
  87. package/dist-package/packages/runtime/src/application/project-store.d.ts +56 -0
  88. package/dist-package/packages/runtime/src/application/project-transactions.d.ts +51 -0
  89. package/dist-package/packages/runtime/src/application/runtime-options.d.ts +15 -0
  90. package/dist-package/packages/runtime/src/application/semantic-media-index-store.d.ts +28 -0
  91. package/dist-package/packages/runtime/src/application/transaction-store.d.ts +10 -0
  92. package/dist-package/packages/runtime/src/audio/analysis.d.ts +3 -0
  93. package/dist-package/packages/runtime/src/audio/analysis.js +95 -0
  94. package/dist-package/packages/runtime/src/audio/dialogue-normalization.d.ts +47 -0
  95. package/dist-package/packages/runtime/src/audio/noise-reduction.d.ts +34 -0
  96. package/dist-package/packages/runtime/src/capabilities.d.ts +45 -0
  97. package/dist-package/packages/runtime/src/color-correction.d.ts +33 -0
  98. package/dist-package/packages/runtime/src/context/context-engine.d.ts +28 -0
  99. package/dist-package/packages/runtime/src/context/context-service.d.ts +20 -0
  100. package/dist-package/packages/runtime/src/context/project-catalog.d.ts +12 -0
  101. package/dist-package/packages/runtime/src/context/revision.d.ts +2 -0
  102. package/dist-package/packages/runtime/src/domain/capabilities.d.ts +170 -0
  103. package/dist-package/packages/runtime/src/domain/context.d.ts +179 -0
  104. package/dist-package/packages/runtime/src/domain/diff.d.ts +104 -0
  105. package/dist-package/packages/runtime/src/domain/duration.d.ts +63 -0
  106. package/dist-package/packages/runtime/src/domain/editing.d.ts +227 -0
  107. package/dist-package/packages/runtime/src/domain/incremental-sync.d.ts +67 -0
  108. package/dist-package/packages/runtime/src/domain/index.d.ts +14 -0
  109. package/dist-package/packages/runtime/src/domain/media.d.ts +406 -0
  110. package/dist-package/packages/runtime/src/domain/ports.d.ts +62 -0
  111. package/dist-package/packages/runtime/src/domain/primitives.d.ts +21 -0
  112. package/dist-package/packages/runtime/src/domain/project.d.ts +119 -0
  113. package/dist-package/packages/runtime/src/domain/rough-cut.d.ts +27 -0
  114. package/dist-package/packages/runtime/src/domain/skills.d.ts +145 -0
  115. package/dist-package/packages/runtime/src/domain/timeline-target.d.ts +57 -0
  116. package/dist-package/packages/runtime/src/domain/timeline-target.js +19 -1
  117. package/dist-package/packages/runtime/src/domain/types.d.ts +5 -0
  118. package/dist-package/packages/runtime/src/domain/verification.d.ts +92 -0
  119. package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.d.ts +18 -0
  120. package/dist-package/packages/runtime/src/editing/duration-policy.d.ts +3 -0
  121. package/dist-package/packages/runtime/src/editing/edit-service.d.ts +44 -0
  122. package/dist-package/packages/runtime/src/editing/filler-removal-service.d.ts +23 -0
  123. package/dist-package/packages/runtime/src/editing/intent.d.ts +97 -0
  124. package/dist-package/packages/runtime/src/editing/music-service.d.ts +9 -0
  125. package/dist-package/packages/runtime/src/index.d.ts +32 -0
  126. package/dist-package/packages/runtime/src/index.js +1 -0
  127. package/dist-package/packages/runtime/src/planning/rough-cut.d.ts +3 -0
  128. package/dist-package/packages/runtime/src/render/render-and-verify.d.ts +71 -0
  129. package/dist-package/packages/runtime/src/render/render-contract.d.ts +96 -0
  130. package/dist-package/packages/runtime/src/runtime.d.ts +85 -0
  131. package/dist-package/packages/runtime/src/skills/builtin.d.ts +2 -0
  132. package/dist-package/packages/runtime/src/skills/index.d.ts +3 -0
  133. package/dist-package/packages/runtime/src/skills/registry.d.ts +10 -0
  134. package/dist-package/packages/runtime/src/skills/requirements.d.ts +38 -0
  135. package/dist-package/packages/runtime/src/skills/runtime.d.ts +38 -0
  136. package/dist-package/packages/runtime/src/speech/analysis.d.ts +18 -0
  137. package/dist-package/packages/runtime/src/speech/analysis.js +67 -0
  138. package/dist-package/packages/runtime/src/speech/filler-detector.d.ts +49 -0
  139. package/dist-package/packages/runtime/src/speech/filler-removal.d.ts +37 -0
  140. package/dist-package/packages/runtime/src/speech/mapping.d.ts +56 -0
  141. package/dist-package/packages/runtime/src/speech/mapping.js +27 -4
  142. package/dist-package/packages/runtime/src/speech/safe-cut-resolver.d.ts +52 -0
  143. package/dist-package/packages/runtime/src/timeline/drift-reconciliation.d.ts +42 -0
  144. package/dist-package/packages/runtime/src/timeline/editing-session.d.ts +271 -0
  145. package/dist-package/packages/runtime/src/timeline/editing-session.js +32 -2
  146. package/dist-package/packages/runtime/src/timeline/fast-observation.d.ts +77 -0
  147. package/dist-package/packages/runtime/src/timeline/rational-time.d.ts +11 -0
  148. package/dist-package/packages/runtime/src/timeline/reorder-preview.d.ts +32 -0
  149. package/dist-package/packages/runtime/src/timeline/reorder-preview.js +202 -0
  150. package/dist-package/packages/runtime/src/timeline/snapshot-diff.d.ts +3 -0
  151. package/dist-package/packages/runtime/src/timeline/snapshot-diff.js +1 -0
  152. package/dist-package/packages/runtime/src/timeline/snapshot-digest.d.ts +3 -0
  153. package/dist-package/packages/runtime/src/timeline/snapshot-digest.js +1 -1
  154. package/dist-package/packages/runtime/src/verification/verification.d.ts +6 -0
  155. package/dist-package/packages/testkit/src/fixture-analyzers.d.ts +37 -0
  156. package/dist-package/packages/testkit/src/in-memory-editor.d.ts +55 -0
  157. package/dist-package/packages/testkit/src/index.d.ts +4 -0
  158. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.d.ts +47 -0
  159. package/dist-package/packages/testkit/src/skill-fixtures.d.ts +3 -0
  160. package/package.json +17 -12
@@ -0,0 +1,4 @@
1
+ import type { BuildFingerprint } from "../../../packages/runtime/src/index.js";
2
+ export declare const FRAMEKIT_VERSION: string;
3
+ export type FramekitBuildFingerprint = BuildFingerprint;
4
+ export declare const FRAMEKIT_BUILD_FINGERPRINT: FramekitBuildFingerprint;
@@ -0,0 +1,30 @@
1
+ import type { ContextRevision, ProjectEditCommand, RationalTime, TimelineIr, TimelineIrEditOperation } from "../../runtime/src/index.js";
2
+ export interface ExternalEdit {
3
+ schemaVersion: 1;
4
+ clips: Array<{
5
+ id: string;
6
+ mediaId: string;
7
+ sourceStartTime: RationalTime;
8
+ durationTime: RationalTime;
9
+ }>;
10
+ title: {
11
+ id: string;
12
+ text: string;
13
+ startTime: RationalTime;
14
+ durationTime: RationalTime;
15
+ };
16
+ music: {
17
+ id: string;
18
+ mediaId: string;
19
+ sourceStartTime: RationalTime;
20
+ startTime: RationalTime;
21
+ durationTime: RationalTime;
22
+ gainDb: number;
23
+ };
24
+ }
25
+ /** Convert the bounded interchange format to the existing project transaction operations. */
26
+ export declare function externalEditOperations(edit: ExternalEdit, timeline: TimelineIr, expectedRevision: ContextRevision): TimelineIrEditOperation[];
27
+ /** Check the actual compiler before a JSON edit can be committed. No artifact is written. */
28
+ export declare function verifyExternalEditExportable(timeline: TimelineIr): void;
29
+ /** Bind an approved preview to its target, base revision and translated operations. */
30
+ export declare function externalEditPlanDigest(command: ProjectEditCommand): string;
@@ -0,0 +1,72 @@
1
+ import { createHash } from "node:crypto";
2
+ import { compileTimelineIrToFcpxml } from "../../../adapters/final-cut/typescript/src/documents.js";
3
+ import { ProjectTransactionError } from "../../runtime/src/index.js";
4
+ /** Convert the bounded interchange format to the existing project transaction operations. */
5
+ export function externalEditOperations(edit, timeline, expectedRevision) {
6
+ if (timeline.revision.id !== expectedRevision.id || timeline.revision.sequence !== expectedRevision.sequence) {
7
+ throw new ProjectTransactionError("PROJECT_EDIT_STALE_REVISION", "expected project revision does not match the inspected project", {
8
+ expectedRevision, actualRevision: timeline.revision,
9
+ });
10
+ }
11
+ const sequence = timeline.sequence;
12
+ if (BigInt(sequence.durationTime.value) !== 0n || sequence.occurrences.length || sequence.storyElements.length
13
+ || sequence.markers.length || sequence.captions.length || sequence.titles?.length || sequence.transitions?.length) {
14
+ throw new Error("EXTERNAL_EDIT_INVALID: a new external edit requires an empty timeline");
15
+ }
16
+ const assertSource = (id, kind) => {
17
+ const resource = timeline.resources.find((item) => item.id === id);
18
+ if (!resource || resource.mediaKind !== kind || resource.sourceKind !== "local-file" || !resource.sourceDigest) {
19
+ throw new Error(`EXTERNAL_EDIT_INVALID: ${id} is not a registered ${kind} source`);
20
+ }
21
+ return resource;
22
+ };
23
+ const frame = timeline.sequence.frameDuration;
24
+ const aligned = (time, grid = frame, label = "sequence") => {
25
+ const numerator = BigInt(time.value) * BigInt(grid.timescale);
26
+ const denominator = BigInt(time.timescale) * BigInt(grid.value);
27
+ if (denominator <= 0n || numerator % denominator !== 0n)
28
+ throw new Error(`EXTERNAL_EDIT_INVALID: timing must align to the ${label} frame grid`);
29
+ };
30
+ for (const clip of edit.clips) {
31
+ const resource = assertSource(clip.mediaId, "video");
32
+ const stream = resource.metadata?.streams.find((item) => item.kind === "video");
33
+ const rate = stream?.frameRate;
34
+ if (!rate || BigInt(rate.value) <= 0n || BigInt(rate.timescale) <= 0n) {
35
+ throw new Error(`EXTERNAL_EDIT_INVALID: ${clip.mediaId} has no supported source frame rate`);
36
+ }
37
+ if (!stream?.sourceRange)
38
+ throw new Error(`EXTERNAL_EDIT_INVALID: ${clip.mediaId} has no verified video stream bounds; register the source in a new project`);
39
+ const addRationalTimes = (a, b) => ({ value: String(BigInt(a.value) * BigInt(b.timescale) + BigInt(b.value) * BigInt(a.timescale)), timescale: String(BigInt(a.timescale) * BigInt(b.timescale)) });
40
+ const compare = (a, b) => BigInt(a.value) * BigInt(b.timescale) - BigInt(b.value) * BigInt(a.timescale);
41
+ if (compare(clip.sourceStartTime, stream.sourceRange.start) < 0n || compare(addRationalTimes(clip.sourceStartTime, clip.durationTime), addRationalTimes(stream.sourceRange.start, stream.sourceRange.duration)) > 0n) {
42
+ throw new Error(`EXTERNAL_EDIT_INVALID: ${clip.mediaId} range exceeds video stream bounds`);
43
+ }
44
+ const sourceFrame = { value: rate.timescale, timescale: rate.value };
45
+ aligned(clip.sourceStartTime);
46
+ const sourceOffset = { value: String(BigInt(clip.sourceStartTime.value) * BigInt(stream.sourceRange.start.timescale) - BigInt(stream.sourceRange.start.value) * BigInt(clip.sourceStartTime.timescale)), timescale: String(BigInt(clip.sourceStartTime.timescale) * BigInt(stream.sourceRange.start.timescale)) };
47
+ aligned(sourceOffset, sourceFrame, "source");
48
+ aligned(clip.durationTime);
49
+ aligned(clip.durationTime, sourceFrame, "source");
50
+ }
51
+ assertSource(edit.music.mediaId, "audio");
52
+ for (const time of [edit.music.sourceStartTime, edit.music.startTime, edit.music.durationTime, edit.title.startTime, edit.title.durationTime])
53
+ aligned(time);
54
+ return [
55
+ ...edit.clips.map((clip) => ({ type: "insert-occurrence", placement: "append", occurrence: {
56
+ ...clip, name: clip.id, startTime: { value: "0", timescale: "1" }, track: 0, role: "video",
57
+ } })),
58
+ { type: "insert-occurrence", occurrence: { ...edit.music, name: edit.music.id, track: 1, role: "music" } },
59
+ { type: "add-title", title: { ...edit.title, lane: 1 } },
60
+ ];
61
+ }
62
+ /** Check the actual compiler before a JSON edit can be committed. No artifact is written. */
63
+ export function verifyExternalEditExportable(timeline) {
64
+ compileTimelineIrToFcpxml(timeline, { target: {
65
+ provider: "final-cut", libraryUid: "preview-library", eventUid: "preview-event",
66
+ projectUid: "preview-project", sequenceUid: "preview-sequence", materialization: "versioned",
67
+ } });
68
+ }
69
+ /** Bind an approved preview to its target, base revision and translated operations. */
70
+ export function externalEditPlanDigest(command) {
71
+ return createHash("sha256").update(JSON.stringify(command)).digest("hex");
72
+ }
@@ -0,0 +1,259 @@
1
+ import { ProjectTransactionService, type ContextRevision, type FramekitProjectDocument, type FramekitRenderArtifactVerifier, type FramekitRenderProvider, type FramekitRenderParameters, type LocalMediaRegistrationResult, type LocalMediaMetadataProbe, type ProjectEditCommand, type ProjectEditPreview, type ProjectEditResult, type RoughCutPlan, type TimelineIrEditOperation, type TimelineIr, type TimelineIrResource } from "../../runtime/src/index.js";
2
+ import { type TimelineIrToFcpxmlResult, type TimelineIrToFcpxmlTarget } from "../../../adapters/final-cut/typescript/src/documents.js";
3
+ export interface HeadlessProjectServiceOptions {
4
+ directory: string;
5
+ protectedStateDirectory?: string;
6
+ mediaProbe?: LocalMediaMetadataProbe;
7
+ renderer?: FramekitRenderProvider;
8
+ verifier?: FramekitRenderArtifactVerifier;
9
+ storyboard?: StoryboardRenderer;
10
+ clock?: () => string;
11
+ }
12
+ export interface StoryboardRenderer {
13
+ render(timeline: TimelineIr, dimensions: {
14
+ width: number;
15
+ height: number;
16
+ }, signal?: AbortSignal): Promise<StoryboardImage>;
17
+ }
18
+ export interface StoryboardImage {
19
+ data: string;
20
+ mimeType: "image/png";
21
+ samples: Array<{
22
+ kind: "shot" | "title";
23
+ id: string;
24
+ occurrenceId: string;
25
+ mediaId: string;
26
+ sourceDigest: string;
27
+ timelineSeconds: number;
28
+ sourceSeconds: number;
29
+ }>;
30
+ limitations: string[];
31
+ }
32
+ export type HeadlessProjectEditCommand = Omit<ProjectEditCommand, "target"> & {
33
+ target?: ProjectEditCommand["target"];
34
+ };
35
+ export interface HeadlessProjectWorkflow {
36
+ create(timeline: TimelineIr): Promise<FramekitProjectDocument>;
37
+ list(): Promise<HeadlessProjectSummary[]>;
38
+ open(projectId: string): Promise<FramekitProjectDocument>;
39
+ inspect(projectId: string): Promise<FramekitProjectDocument>;
40
+ registerMedia(projectId: string, sourcePath: string, expectedRevision?: ContextRevision): Promise<LocalMediaRegistrationResult>;
41
+ searchMedia(projectId: string, query: string): Promise<{
42
+ revision: ContextRevision;
43
+ media: TimelineIrResource[];
44
+ }>;
45
+ previewEdit(projectId: string, command: HeadlessProjectEditCommand, sequenceId: string): ReturnType<ProjectTransactionService["preview"]>;
46
+ executeEdit(projectId: string, command: HeadlessProjectEditCommand, sequenceId: string): Promise<ProjectEditResult & {
47
+ undoId: string;
48
+ }>;
49
+ undoEdit(projectId: string, sequenceId: string, undoId: string, expectedRevision: ContextRevision): Promise<HeadlessUndoResult>;
50
+ exportFcpxml(projectId: string, sequenceId: string, expectedRevision: ContextRevision, outputPath: string, target: TimelineIrToFcpxmlTarget): Promise<{
51
+ artifact: {
52
+ path: string;
53
+ digest: string;
54
+ bytes: number;
55
+ verified: true;
56
+ };
57
+ provenance: TimelineIrToFcpxmlResult["provenance"];
58
+ coverage: TimelineIrToFcpxmlResult["coverage"];
59
+ }>;
60
+ previewRoughCut(request: HeadlessRoughCutRequest, signal?: AbortSignal, requireStoryboard?: boolean): Promise<HeadlessRoughCutPreview>;
61
+ executeRoughCut(request: HeadlessRoughCutExecutionRequest): Promise<HeadlessRoughCutExecution>;
62
+ verifyPublishableRoughCut(executionId: string, artifactPath: string, artifactDigest?: string): Promise<HeadlessRoughCutPublishProof>;
63
+ verifyPublishableRoughCutTransaction(request: HeadlessRoughCutPublishVerificationRequest): Promise<HeadlessRoughCutPublishProof>;
64
+ render(projectId: string, sequenceId: string, parameters: FramekitRenderParameters, expectedRevision?: ContextRevision): Promise<HeadlessRenderRecord>;
65
+ inspectRender(renderId: string): Promise<HeadlessRenderRecord>;
66
+ }
67
+ export interface HeadlessProjectSummary {
68
+ projectId: string;
69
+ projectName: string;
70
+ sequenceId: string;
71
+ sequenceName: string;
72
+ revision: ContextRevision;
73
+ path: string;
74
+ }
75
+ export interface HeadlessUndoResult {
76
+ project: FramekitProjectDocument;
77
+ verification: {
78
+ verified: true;
79
+ expectedDigest: string;
80
+ observedDigest: string;
81
+ };
82
+ }
83
+ export interface HeadlessRenderRecord {
84
+ renderId: string;
85
+ projectId: string;
86
+ sequenceId: string;
87
+ requestedRevision: ContextRevision;
88
+ createdAt: string;
89
+ status: "passed" | "failed" | "unavailable";
90
+ outcome: unknown;
91
+ }
92
+ export interface HeadlessRoughCutRequest {
93
+ projectId: string;
94
+ sequenceId: string;
95
+ plan: RoughCutPlan;
96
+ operations?: TimelineIrEditOperation[];
97
+ sourceAudioPolicy?: "preserve-and-mix";
98
+ render: FramekitRenderParameters;
99
+ fcpxml: {
100
+ path: string;
101
+ target: TimelineIrToFcpxmlTarget;
102
+ overwrite?: boolean;
103
+ };
104
+ }
105
+ export interface HeadlessRoughCutExecutionRequest extends HeadlessRoughCutRequest {
106
+ approved: boolean;
107
+ planDigest: string;
108
+ }
109
+ export interface HeadlessRoughCutShotProvenance {
110
+ order: number;
111
+ occurrenceId: string;
112
+ mediaId: string;
113
+ sourceIdentity: RoughCutPlan["shots"][number]["sourceIdentity"];
114
+ sourceRange: RoughCutPlan["shots"][number]["range"];
115
+ confidence: number;
116
+ matchedProperties: string[];
117
+ rationale: string;
118
+ evidence?: HeadlessRoughCutSpeechEvidence;
119
+ }
120
+ interface HeadlessRoughCutSpeechEvidence {
121
+ kind: "speech";
122
+ transcript: string;
123
+ wordCount: number;
124
+ averageWordConfidence: number;
125
+ vad?: {
126
+ kind: "speech" | "silence" | "breath" | "laughter" | "noise";
127
+ confidence?: number;
128
+ };
129
+ audio?: {
130
+ integratedLufs?: number;
131
+ truePeakDb?: number;
132
+ silenceMs?: number;
133
+ };
134
+ }
135
+ export interface HeadlessRoughCutPreview extends ProjectEditPreview {
136
+ plan: RoughCutPlan;
137
+ planDigest: string;
138
+ provenance: HeadlessRoughCutShotProvenance[];
139
+ storyboard?: StoryboardImage & {
140
+ planDigest: string;
141
+ revision: ContextRevision;
142
+ };
143
+ outputIntent: {
144
+ sourceAudioPolicy: "preserve-and-mix";
145
+ render: FramekitRenderParameters;
146
+ fcpxml: {
147
+ path: string;
148
+ target: TimelineIrToFcpxmlTarget;
149
+ overwrite: boolean;
150
+ };
151
+ };
152
+ fcpxml: Pick<TimelineIrToFcpxmlResult, "digest" | "target" | "destination" | "coverage" | "provenance">;
153
+ }
154
+ export interface HeadlessRoughCutExecution extends HeadlessRoughCutPreview {
155
+ executionId: string;
156
+ committed: true;
157
+ render: {
158
+ renderId: string;
159
+ status: "passed";
160
+ outcome: unknown;
161
+ };
162
+ fcpxmlArtifact: {
163
+ path: string;
164
+ digest: string;
165
+ bytes: number;
166
+ verified: true;
167
+ };
168
+ transaction: ProjectEditResult;
169
+ }
170
+ export interface HeadlessRoughCutPublishProof {
171
+ executionId: string;
172
+ sourceTransactionId: string;
173
+ projectId: string;
174
+ sequenceId: string;
175
+ sourceRevision: ContextRevision;
176
+ canonicalRevision: ContextRevision;
177
+ planDigest: string;
178
+ renderId: string;
179
+ artifactPath: string;
180
+ artifactDigest: string;
181
+ sourceAudioPolicy: "preserve-and-mix";
182
+ target: TimelineIrToFcpxmlTarget;
183
+ destination: TimelineIrToFcpxmlResult["destination"];
184
+ coverage: TimelineIrToFcpxmlResult["coverage"];
185
+ provenance: HeadlessRoughCutShotProvenance[];
186
+ targetLibraryUid: string;
187
+ sourceMediaDigests: Array<{
188
+ source: string;
189
+ sha256: string;
190
+ }>;
191
+ }
192
+ export interface HeadlessRoughCutPublishVerificationRequest {
193
+ sourceTransactionId: string;
194
+ artifactPath: string;
195
+ artifactDigest: string;
196
+ }
197
+ export declare class HeadlessProjectService implements HeadlessProjectWorkflow {
198
+ private readonly directory;
199
+ private readonly protectedStateDirectory;
200
+ private readonly mediaProbe?;
201
+ private readonly renderer?;
202
+ private readonly verifier?;
203
+ private readonly storyboard?;
204
+ private readonly clock;
205
+ constructor(options: HeadlessProjectServiceOptions);
206
+ create(timeline: TimelineIr): Promise<FramekitProjectDocument>;
207
+ list(): Promise<HeadlessProjectSummary[]>;
208
+ private isInternalRecord;
209
+ open(projectId: string): Promise<FramekitProjectDocument>;
210
+ inspect(projectId: string): Promise<FramekitProjectDocument>;
211
+ registerMedia(projectId: string, sourcePath: string, expectedRevision?: ContextRevision): Promise<LocalMediaRegistrationResult>;
212
+ searchMedia(projectId: string, query: string): Promise<{
213
+ revision: ContextRevision;
214
+ media: TimelineIrResource[];
215
+ }>;
216
+ previewEdit(projectId: string, command: HeadlessProjectEditCommand, sequenceId: string): Promise<ProjectEditPreview>;
217
+ executeEdit(projectId: string, command: HeadlessProjectEditCommand, sequenceId: string): Promise<{
218
+ command: ProjectEditCommand;
219
+ before: FramekitProjectDocument;
220
+ after: FramekitProjectDocument;
221
+ diff: import("../../runtime/src/index.js").ProjectEditDiff;
222
+ changedOccurrenceIds: string[];
223
+ changedMarkerIds: string[];
224
+ changedTitleIds: string[];
225
+ changedTransitionIds: string[];
226
+ committed: true;
227
+ undoId: string;
228
+ }>;
229
+ undoEdit(projectId: string, sequenceId: string, undoId: string, expectedRevision: ContextRevision): Promise<HeadlessUndoResult>;
230
+ exportFcpxml(projectId: string, sequenceId: string, expectedRevision: ContextRevision, outputPath: string, target: TimelineIrToFcpxmlTarget): Promise<{
231
+ artifact: {
232
+ path: string;
233
+ digest: string;
234
+ bytes: number;
235
+ verified: true;
236
+ };
237
+ provenance: import("../../../adapters/final-cut/typescript/src/documents.js").TimelineIrMaterializationProvenance;
238
+ coverage: import("../../../adapters/final-cut/typescript/src/documents.js").TimelineIrMaterializationCoverage;
239
+ }>;
240
+ previewRoughCut(request: HeadlessRoughCutRequest, signal?: AbortSignal, requireStoryboard?: boolean): Promise<HeadlessRoughCutPreview>;
241
+ executeRoughCut(request: HeadlessRoughCutExecutionRequest): Promise<HeadlessRoughCutExecution>;
242
+ verifyPublishableRoughCut(executionId: string, artifactPath: string, artifactDigest?: string): Promise<HeadlessRoughCutPublishProof>;
243
+ verifyPublishableRoughCutTransaction(request: HeadlessRoughCutPublishVerificationRequest): Promise<HeadlessRoughCutPublishProof>;
244
+ render(projectId: string, sequenceId: string, parameters: FramekitRenderParameters, expectedRevision?: ContextRevision): Promise<HeadlessRenderRecord>;
245
+ inspectRender(renderId: string): Promise<HeadlessRenderRecord>;
246
+ private assertOutputSeparation;
247
+ private store;
248
+ private snapshotStore;
249
+ private projectPath;
250
+ private executionPath;
251
+ private approvalPath;
252
+ private saveRender;
253
+ private saveRoughCutExecution;
254
+ private saveRoughCutApproval;
255
+ private readRoughCutApproval;
256
+ private prepareRoughCut;
257
+ private previewPreparedRoughCut;
258
+ }
259
+ export {};
@@ -2,13 +2,14 @@ import { createHash, randomUUID } from "node:crypto";
2
2
  import { readdir, readFile, rename, writeFile, mkdir, link, unlink, realpath, stat } from "node:fs/promises";
3
3
  import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
4
4
  import { FramekitProjectStore, LocalMediaRegistrar, ProjectTransactionService, createFramekitRenderRequest, renderAndVerifyFramekitProject, timelineIrDigest, } from "../../runtime/src/index.js";
5
- import { FcpxmlDocumentAdapter, compileTimelineIrToFcpxml, resolveMediaSource, } from "../../../adapters/final-cut/typescript/src/index.js";
5
+ import { FcpxmlDocumentAdapter, compileTimelineIrToFcpxml, resolveMediaSource, } from "../../../adapters/final-cut/typescript/src/documents.js";
6
6
  export class HeadlessProjectService {
7
7
  directory;
8
8
  protectedStateDirectory;
9
9
  mediaProbe;
10
10
  renderer;
11
11
  verifier;
12
+ storyboard;
12
13
  clock;
13
14
  constructor(options) {
14
15
  this.directory = options.directory;
@@ -16,6 +17,7 @@ export class HeadlessProjectService {
16
17
  this.mediaProbe = options.mediaProbe;
17
18
  this.renderer = options.renderer;
18
19
  this.verifier = options.verifier;
20
+ this.storyboard = options.storyboard;
19
21
  this.clock = options.clock ?? (() => new Date().toISOString());
20
22
  }
21
23
  async create(timeline) {
@@ -179,7 +181,10 @@ export class HeadlessProjectService {
179
181
  const artifact = await writeVerifiedFcpxml(resolve(outputPath), compiled.xml, compiled.digest, false);
180
182
  return { artifact, provenance: compiled.provenance, coverage: compiled.coverage };
181
183
  }
182
- async previewRoughCut(request) {
184
+ async previewRoughCut(request, signal, requireStoryboard = false) {
185
+ signal?.throwIfAborted();
186
+ if (requireStoryboard && !this.storyboard)
187
+ throw new Error("HEADLESS_STORYBOARD_UNAVAILABLE: storyboard renderer is not configured");
183
188
  const prepared = await this.prepareRoughCut(request);
184
189
  const timestamp = this.clock();
185
190
  const { preview, fcpxml } = await this.previewPreparedRoughCut(request, prepared, timestamp);
@@ -193,12 +198,20 @@ export class HeadlessProjectService {
193
198
  artifactDigest: fcpxml.digest,
194
199
  outputIntent: prepared.outputIntent,
195
200
  });
201
+ const storyboard = this.storyboard && await this.storyboard.render(preview.after.timeline, request.render, signal);
202
+ signal?.throwIfAborted();
203
+ const current = await this.open(request.projectId);
204
+ if (timelineIrDigest(current.timeline) !== timelineIrDigest(prepared.project.timeline)) {
205
+ throw new Error("HEADLESS_ROUGH_CUT_STALE_REVISION: project changed during storyboard generation");
206
+ }
207
+ signal?.throwIfAborted();
196
208
  await this.saveRoughCutApproval(approval);
197
209
  return {
198
210
  ...preview,
199
211
  plan: structuredClone(request.plan),
200
212
  planDigest: approval.planDigest,
201
213
  provenance: prepared.provenance,
214
+ ...(storyboard ? { storyboard: { ...storyboard, planDigest: approval.planDigest, revision: preview.after.timeline.revision } } : {}),
202
215
  outputIntent: prepared.outputIntent,
203
216
  fcpxml: selectFcpxmlMetadata(fcpxml),
204
217
  };
@@ -0,0 +1,2 @@
1
+ export * from "./headless-projects.js";
2
+ export * from "./external-edit.js";
@@ -1 +1,2 @@
1
1
  export * from "./headless-projects.js";
2
+ export * from "./external-edit.js";
@@ -0,0 +1,4 @@
1
+ import type { DurationPolicyPlan, DurationPolicyRequest } from "../domain/duration.js";
2
+ export declare class DurationPolicyService {
3
+ plan(request: DurationPolicyRequest): DurationPolicyPlan;
4
+ }
@@ -0,0 +1,46 @@
1
+ import type { ContextRevision } from "../domain/primitives.js";
2
+ import { type FramekitProjectDocument, type ProjectStore } from "./project-store.js";
3
+ import type { TimelineIrMediaMetadata, TimelineIrResource } from "../timeline/editing-session.js";
4
+ export interface LocalMediaMetadataProbe {
5
+ probe(sourcePath: string): Promise<TimelineIrMediaMetadata>;
6
+ }
7
+ export type LocalMediaRegistrationStatus = "registered" | "already-registered";
8
+ export interface LocalMediaRegistrationResult {
9
+ status: LocalMediaRegistrationStatus;
10
+ project: FramekitProjectDocument;
11
+ resource: TimelineIrResource;
12
+ }
13
+ export type RegisteredMediaStatus = {
14
+ id: string;
15
+ source: string;
16
+ status: "available";
17
+ expectedDigest: string;
18
+ actualDigest: string;
19
+ } | {
20
+ id: string;
21
+ source: string;
22
+ status: "missing";
23
+ expectedDigest: string;
24
+ } | {
25
+ id: string;
26
+ source: string;
27
+ status: "changed";
28
+ expectedDigest: string;
29
+ actualDigest: string;
30
+ };
31
+ export declare class LocalMediaError extends Error {
32
+ readonly code: "MEDIA_MISSING" | "MEDIA_CHANGED" | "MEDIA_AMBIGUOUS";
33
+ readonly details: Readonly<Record<string, unknown>>;
34
+ constructor(code: LocalMediaError["code"], message: string, details: Readonly<Record<string, unknown>>);
35
+ }
36
+ export declare class LocalMediaRegistrar {
37
+ private readonly store;
38
+ private readonly metadataProbe;
39
+ private readonly clock;
40
+ constructor(store: ProjectStore, metadataProbe: LocalMediaMetadataProbe, options?: {
41
+ clock?: () => string;
42
+ });
43
+ register(sourcePath: string, expectedRevision?: ContextRevision): Promise<LocalMediaRegistrationResult>;
44
+ inspect(project?: FramekitProjectDocument): Promise<RegisteredMediaStatus[]>;
45
+ reopen(): Promise<FramekitProjectDocument>;
46
+ }
@@ -0,0 +1,40 @@
1
+ import type { AudioAnalysis, AudioMeasurement, MediaContext, MediaIndexEntry, MediaIndexQuery, RoughCutPlan, RoughCutPlanRequest, MediaUnderstanding, NoiseAnalysis, NoiseMeasurement, RevisionBoundSpeechAnalysis, TimelineSemanticContext, TimelineSemanticContextQuery, VisualAnalysis } from "../domain/media.js";
2
+ import type { EditTransaction } from "../domain/editing.js";
3
+ import type { ProjectSnapshot } from "../domain/project.js";
4
+ import type { TimeRange } from "../domain/primitives.js";
5
+ import { ContextEngine } from "../context/context-engine.js";
6
+ import { ProjectService } from "./project-service.js";
7
+ import type { RuntimeOptions } from "./runtime-options.js";
8
+ export interface PostWriteAnalysisRequirements {
9
+ speech?: boolean;
10
+ audio?: boolean;
11
+ noise?: boolean;
12
+ visual?: boolean;
13
+ }
14
+ export declare class MediaAnalysisService {
15
+ private readonly project;
16
+ private readonly context;
17
+ private readonly options;
18
+ constructor(project: ProjectService, context: ContextEngine, options: RuntimeOptions);
19
+ analyzeSpeech(mediaId: string, range?: TimeRange): Promise<RevisionBoundSpeechAnalysis>;
20
+ analyzeAudio(mediaId: string, range?: TimeRange): Promise<AudioAnalysis>;
21
+ analyzeNoise(mediaId: string, range?: TimeRange): Promise<NoiseAnalysis>;
22
+ measureAudio(mediaId: string, occurrenceId: string): Promise<AudioMeasurement>;
23
+ measureNoise(mediaId: string, occurrenceId: string): Promise<NoiseMeasurement>;
24
+ analyzeVisual(mediaId: string, range?: TimeRange): Promise<VisualAnalysis>;
25
+ understandMedia(mediaId: string): Promise<MediaUnderstanding>;
26
+ understandMediaInProject(mediaId: string, project: ProjectSnapshot, attachToLiveContext?: boolean): Promise<MediaUnderstanding>;
27
+ inspectMedia(mediaId: string): Promise<MediaContext>;
28
+ searchMedia(query: string): Promise<MediaContext[]>;
29
+ indexMedia(query?: MediaIndexQuery): Promise<MediaIndexEntry[]>;
30
+ planRoughCut(request: RoughCutPlanRequest): Promise<RoughCutPlan>;
31
+ planRoughCutInProject(request: RoughCutPlanRequest, project: ProjectSnapshot): Promise<RoughCutPlan>;
32
+ inspectTimelineSemanticContext(query?: TimelineSemanticContextQuery): Promise<TimelineSemanticContext>;
33
+ private inspectTimelineOccurrence;
34
+ private loadCachedUnderstanding;
35
+ private persistedIndexEntries;
36
+ private indexFromProject;
37
+ reanalyzeAffectedRanges(transaction: EditTransaction, requirements: PostWriteAnalysisRequirements): Promise<ProjectSnapshot>;
38
+ private analyzeSpeechForProject;
39
+ private analyzeAudioForProject;
40
+ }