@morshoto/framekit 0.1.18 → 0.2.3

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 (192) hide show
  1. package/README.md +17 -12
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.d.ts +58 -0
  3. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +52 -13
  4. package/dist-package/adapters/final-cut/typescript/src/assets.d.ts +24 -0
  5. package/dist-package/adapters/final-cut/typescript/src/background-export.d.ts +98 -0
  6. package/dist-package/adapters/final-cut/typescript/src/background-materialization.d.ts +47 -0
  7. package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +8 -2
  8. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.d.ts +32 -0
  9. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.js +275 -0
  10. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.d.ts +22 -0
  11. package/dist-package/adapters/final-cut/typescript/src/canonical-verification.d.ts +11 -0
  12. package/dist-package/adapters/final-cut/typescript/src/canonical.d.ts +184 -0
  13. package/dist-package/adapters/final-cut/typescript/src/canonical.js +571 -78
  14. package/dist-package/adapters/final-cut/typescript/src/connection.d.ts +103 -0
  15. package/dist-package/adapters/final-cut/typescript/src/connection.js +6 -1
  16. package/dist-package/adapters/final-cut/typescript/src/disposable-native.d.ts +90 -0
  17. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +6 -0
  18. package/dist-package/adapters/final-cut/typescript/src/documents.d.ts +3 -0
  19. package/dist-package/adapters/final-cut/typescript/src/documents.js +3 -0
  20. package/dist-package/adapters/final-cut/typescript/src/experimental.d.ts +8 -0
  21. package/dist-package/adapters/final-cut/typescript/src/experimental.js +8 -0
  22. package/dist-package/adapters/final-cut/typescript/src/export.d.ts +125 -0
  23. package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.d.ts +54 -0
  24. package/dist-package/adapters/final-cut/typescript/src/fcpxml.d.ts +75 -0
  25. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +28 -9
  26. package/dist-package/adapters/final-cut/typescript/src/index.d.ts +22 -0
  27. package/dist-package/adapters/final-cut/typescript/src/index.js +1 -7
  28. package/dist-package/adapters/final-cut/typescript/src/library-inspection.d.ts +101 -0
  29. package/dist-package/adapters/final-cut/typescript/src/live.d.ts +101 -0
  30. package/dist-package/adapters/final-cut/typescript/src/live.js +35 -2
  31. package/dist-package/adapters/final-cut/typescript/src/media.d.ts +12 -0
  32. package/dist-package/adapters/final-cut/typescript/src/native-operation.d.ts +6 -0
  33. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.d.ts +77 -0
  34. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.js +175 -0
  35. package/dist-package/adapters/final-cut/typescript/src/native-session.d.ts +130 -0
  36. package/dist-package/adapters/final-cut/typescript/src/native-session.js +11 -6
  37. package/dist-package/adapters/final-cut/typescript/src/native.d.ts +828 -0
  38. package/dist-package/adapters/final-cut/typescript/src/native.js +475 -189
  39. package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.d.ts +114 -0
  40. package/dist-package/adapters/final-cut/typescript/src/publish-readback.d.ts +26 -0
  41. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +19 -2
  42. package/dist-package/adapters/final-cut/typescript/src/publisher.d.ts +215 -0
  43. package/dist-package/adapters/final-cut/typescript/src/publisher.js +255 -14
  44. package/dist-package/adapters/final-cut/typescript/src/session.d.ts +43 -0
  45. package/dist-package/adapters/final-cut/typescript/src/session.js +43 -13
  46. package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.d.ts +51 -0
  47. package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.d.ts +156 -0
  48. package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.d.ts +134 -0
  49. package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.d.ts +110 -0
  50. package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.d.ts +132 -0
  51. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.d.ts +61 -0
  52. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +31 -5
  53. package/dist-package/adapters/final-cut/typescript/src/unattended-editing.d.ts +54 -0
  54. package/dist-package/adapters/headless/typescript/src/audio-output.d.ts +3 -0
  55. package/dist-package/adapters/headless/typescript/src/audio-output.js +3 -0
  56. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.d.ts +11 -0
  57. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +26 -2
  58. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.d.ts +25 -0
  59. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +37 -14
  60. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.d.ts +15 -0
  61. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +9 -4
  62. package/dist-package/adapters/headless/typescript/src/index.d.ts +3 -0
  63. package/dist-package/apps/cli/src/dev-doctor.d.ts +25 -0
  64. package/dist-package/apps/cli/src/dev-doctor.js +198 -0
  65. package/dist-package/apps/cli/src/headless-projects.d.ts +3 -0
  66. package/dist-package/apps/cli/src/headless-projects.js +5 -0
  67. package/dist-package/apps/cli/src/main.d.ts +10 -0
  68. package/dist-package/apps/cli/src/main.js +42 -0
  69. package/dist-package/apps/mcp-server/runtime/ffmpeg-audio-backend.py +129 -0
  70. package/dist-package/apps/mcp-server/runtime/speech-analyzer-wrapper.mjs +54 -0
  71. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +271 -0
  72. package/dist-package/apps/mcp-server/src/build-alignment.d.ts +10 -0
  73. package/dist-package/apps/mcp-server/src/build-identity.d.ts +7 -0
  74. package/dist-package/apps/mcp-server/src/build-identity.json +2 -2
  75. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.d.ts +8 -0
  76. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.js +18 -0
  77. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.d.ts +5 -0
  78. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.js +3 -0
  79. package/dist-package/apps/mcp-server/src/headless-project-snapshot.d.ts +3 -0
  80. package/dist-package/apps/mcp-server/src/headless-sessions.d.ts +89 -0
  81. package/dist-package/apps/mcp-server/src/main.d.ts +1 -0
  82. package/dist-package/apps/mcp-server/src/main.js +24 -19
  83. package/dist-package/apps/mcp-server/src/materialization-jobs.d.ts +204 -0
  84. package/dist-package/apps/mcp-server/src/materialization-jobs.js +143 -10
  85. package/dist-package/apps/mcp-server/src/readback-policy.d.ts +18 -0
  86. package/dist-package/apps/mcp-server/src/routing.d.ts +90 -0
  87. package/dist-package/apps/mcp-server/src/routing.js +2 -0
  88. package/dist-package/apps/mcp-server/src/server.d.ts +75 -0
  89. package/dist-package/apps/mcp-server/src/server.js +813 -158
  90. package/dist-package/apps/mcp-server/src/tools/skills/catalog.d.ts +19 -0
  91. package/dist-package/apps/mcp-server/src/tools/skills/catalog.js +142 -0
  92. package/dist-package/apps/mcp-server/src/tools/skills/metadata.d.ts +37 -0
  93. package/dist-package/apps/mcp-server/src/tools/skills/metadata.js +71 -0
  94. package/dist-package/apps/mcp-server/src/tools/skills/register.d.ts +11 -0
  95. package/dist-package/apps/mcp-server/src/tools/skills/register.js +101 -0
  96. package/dist-package/apps/mcp-server/src/version.d.ts +4 -0
  97. package/dist-package/packages/headless-application/src/external-edit.d.ts +30 -0
  98. package/dist-package/packages/headless-application/src/external-edit.js +72 -0
  99. package/dist-package/packages/headless-application/src/headless-projects.d.ts +233 -0
  100. package/dist-package/{apps/mcp-server → packages/headless-application}/src/headless-projects.js +392 -59
  101. package/dist-package/packages/headless-application/src/index.d.ts +2 -0
  102. package/dist-package/packages/headless-application/src/index.js +2 -0
  103. package/dist-package/packages/runtime/src/application/duration-policy-service.d.ts +4 -0
  104. package/dist-package/packages/runtime/src/application/local-media.d.ts +46 -0
  105. package/dist-package/packages/runtime/src/application/media-analysis-service.d.ts +40 -0
  106. package/dist-package/packages/runtime/src/application/media-analysis-service.js +105 -15
  107. package/dist-package/packages/runtime/src/application/project-service.d.ts +35 -0
  108. package/dist-package/packages/runtime/src/application/project-service.js +5 -1
  109. package/dist-package/packages/runtime/src/application/project-store.d.ts +56 -0
  110. package/dist-package/packages/runtime/src/application/project-store.js +13 -36
  111. package/dist-package/packages/runtime/src/application/project-transactions.d.ts +51 -0
  112. package/dist-package/packages/runtime/src/application/runtime-options.d.ts +15 -0
  113. package/dist-package/packages/runtime/src/application/semantic-media-index-store.d.ts +28 -0
  114. package/dist-package/packages/runtime/src/application/transaction-store.d.ts +10 -0
  115. package/dist-package/packages/runtime/src/application/transaction-store.js +1 -1
  116. package/dist-package/packages/runtime/src/audio/analysis.d.ts +3 -0
  117. package/dist-package/packages/runtime/src/audio/analysis.js +95 -0
  118. package/dist-package/packages/runtime/src/audio/dialogue-normalization.d.ts +47 -0
  119. package/dist-package/packages/runtime/src/audio/noise-reduction.d.ts +34 -0
  120. package/dist-package/packages/runtime/src/capabilities.d.ts +45 -0
  121. package/dist-package/packages/runtime/src/capabilities.js +1 -1
  122. package/dist-package/packages/runtime/src/color-correction.d.ts +33 -0
  123. package/dist-package/packages/runtime/src/context/context-engine.d.ts +28 -0
  124. package/dist-package/packages/runtime/src/context/context-engine.js +22 -16
  125. package/dist-package/packages/runtime/src/context/context-service.d.ts +20 -0
  126. package/dist-package/packages/runtime/src/context/context-service.js +2 -2
  127. package/dist-package/packages/runtime/src/context/project-catalog.d.ts +12 -0
  128. package/dist-package/packages/runtime/src/context/revision.d.ts +2 -0
  129. package/dist-package/packages/runtime/src/domain/capabilities.d.ts +170 -0
  130. package/dist-package/packages/runtime/src/domain/context.d.ts +179 -0
  131. package/dist-package/packages/runtime/src/domain/diff.d.ts +104 -0
  132. package/dist-package/packages/runtime/src/domain/duration.d.ts +63 -0
  133. package/dist-package/packages/runtime/src/domain/editing.d.ts +227 -0
  134. package/dist-package/packages/runtime/src/domain/incremental-sync.d.ts +67 -0
  135. package/dist-package/packages/runtime/src/domain/index.d.ts +14 -0
  136. package/dist-package/packages/runtime/src/domain/media.d.ts +406 -0
  137. package/dist-package/packages/runtime/src/domain/ports.d.ts +62 -0
  138. package/dist-package/packages/runtime/src/domain/primitives.d.ts +21 -0
  139. package/dist-package/packages/runtime/src/domain/project.d.ts +119 -0
  140. package/dist-package/packages/runtime/src/domain/rough-cut.d.ts +27 -0
  141. package/dist-package/packages/runtime/src/domain/skills.d.ts +145 -0
  142. package/dist-package/packages/runtime/src/domain/timeline-target.d.ts +57 -0
  143. package/dist-package/packages/runtime/src/domain/timeline-target.js +19 -1
  144. package/dist-package/packages/runtime/src/domain/types.d.ts +5 -0
  145. package/dist-package/packages/runtime/src/domain/verification.d.ts +92 -0
  146. package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.d.ts +18 -0
  147. package/dist-package/packages/runtime/src/editing/duration-policy.d.ts +3 -0
  148. package/dist-package/packages/runtime/src/editing/edit-service.d.ts +44 -0
  149. package/dist-package/packages/runtime/src/editing/edit-service.js +76 -10
  150. package/dist-package/packages/runtime/src/editing/filler-removal-service.d.ts +23 -0
  151. package/dist-package/packages/runtime/src/editing/intent.d.ts +97 -0
  152. package/dist-package/packages/runtime/src/editing/music-service.d.ts +9 -0
  153. package/dist-package/packages/runtime/src/index.d.ts +32 -0
  154. package/dist-package/packages/runtime/src/index.js +2 -0
  155. package/dist-package/packages/runtime/src/planning/rough-cut.d.ts +3 -0
  156. package/dist-package/packages/runtime/src/render/render-and-verify.d.ts +71 -0
  157. package/dist-package/packages/runtime/src/render/render-contract.d.ts +96 -0
  158. package/dist-package/packages/runtime/src/runtime.d.ts +85 -0
  159. package/dist-package/packages/runtime/src/runtime.js +16 -7
  160. package/dist-package/packages/runtime/src/skills/builtin.d.ts +2 -0
  161. package/dist-package/packages/runtime/src/skills/index.d.ts +3 -0
  162. package/dist-package/packages/runtime/src/skills/registry.d.ts +10 -0
  163. package/dist-package/packages/runtime/src/skills/requirements.d.ts +38 -0
  164. package/dist-package/packages/runtime/src/skills/runtime.d.ts +38 -0
  165. package/dist-package/packages/runtime/src/speech/analysis.d.ts +18 -0
  166. package/dist-package/packages/runtime/src/speech/analysis.js +67 -0
  167. package/dist-package/packages/runtime/src/speech/filler-detector.d.ts +49 -0
  168. package/dist-package/packages/runtime/src/speech/filler-removal.d.ts +37 -0
  169. package/dist-package/packages/runtime/src/speech/mapping.d.ts +56 -0
  170. package/dist-package/packages/runtime/src/speech/mapping.js +27 -4
  171. package/dist-package/packages/runtime/src/speech/safe-cut-resolver.d.ts +52 -0
  172. package/dist-package/packages/runtime/src/timeline/drift-reconciliation.d.ts +42 -0
  173. package/dist-package/packages/runtime/src/timeline/editing-session.d.ts +271 -0
  174. package/dist-package/packages/runtime/src/timeline/editing-session.js +48 -2
  175. package/dist-package/packages/runtime/src/timeline/fast-observation.d.ts +77 -0
  176. package/dist-package/packages/runtime/src/timeline/rational-time.d.ts +11 -0
  177. package/dist-package/packages/runtime/src/timeline/reorder-preview.d.ts +32 -0
  178. package/dist-package/packages/runtime/src/timeline/reorder-preview.js +202 -0
  179. package/dist-package/packages/runtime/src/timeline/snapshot-diff.d.ts +3 -0
  180. package/dist-package/packages/runtime/src/timeline/snapshot-diff.js +1 -0
  181. package/dist-package/packages/runtime/src/timeline/snapshot-digest.d.ts +3 -0
  182. package/dist-package/packages/runtime/src/timeline/snapshot-digest.js +1 -1
  183. package/dist-package/packages/runtime/src/verification/verification.d.ts +6 -0
  184. package/dist-package/packages/testkit/src/fixture-analyzers.d.ts +37 -0
  185. package/dist-package/packages/testkit/src/in-memory-editor.d.ts +55 -0
  186. package/dist-package/packages/testkit/src/in-memory-editor.js +3 -3
  187. package/dist-package/packages/testkit/src/index.d.ts +4 -0
  188. package/dist-package/packages/testkit/src/index.js +1 -0
  189. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.d.ts +47 -0
  190. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.js +192 -0
  191. package/dist-package/packages/testkit/src/skill-fixtures.d.ts +3 -0
  192. package/package.json +41 -14
@@ -0,0 +1,406 @@
1
+ import type { ContextRevision, RationalTime, TimeRange } from "./primitives.js";
2
+ import type { ProjectSnapshot, Clip } from "./project.js";
3
+ import type { ProjectSequence } from "./context.js";
4
+ export interface SpeechWord {
5
+ text: string;
6
+ start: number;
7
+ end: number;
8
+ confidence: number;
9
+ filler?: boolean;
10
+ }
11
+ export type SpeechSegmentKind = "speech" | "silence" | "breath" | "laughter" | "noise";
12
+ export interface SpeechSegment {
13
+ start: number;
14
+ end: number;
15
+ kind: SpeechSegmentKind;
16
+ confidence?: number;
17
+ }
18
+ export declare const SPEECH_ANALYSIS_SCHEMA_VERSION: 1;
19
+ export type SpeechAnalysisCapability = "transcription-only" | "transcription-plus-vad";
20
+ export interface SpeechAnalyzerCapabilities {
21
+ transcription: boolean;
22
+ vad: boolean;
23
+ }
24
+ export type MediaAnalysisCapability = "metadata" | "speech" | "audio" | "noise" | "visual";
25
+ export interface SemanticTag {
26
+ value: string;
27
+ confidence: number;
28
+ }
29
+ export interface MetadataAnalysis {
30
+ subjects?: SemanticTag[];
31
+ scenes?: SemanticTag[];
32
+ environments?: SemanticTag[];
33
+ timeOfDay?: SemanticTag[];
34
+ moods?: SemanticTag[];
35
+ usableRanges?: TimeRange[];
36
+ confidence?: number;
37
+ }
38
+ export interface AnalyzerDescriptor {
39
+ id: string;
40
+ provider: string;
41
+ version?: string;
42
+ }
43
+ export interface MediaSourceIdentity {
44
+ mediaId: string;
45
+ source: string;
46
+ sourceDigest?: string;
47
+ mediaKind?: "video" | "audio";
48
+ duration?: number;
49
+ }
50
+ export interface MediaDiscoveryProvenance {
51
+ backend: string;
52
+ guarantee: "observed" | "native-verified";
53
+ source: "filesystem" | "final-cut";
54
+ native?: {
55
+ backend: string;
56
+ guarantee: "none" | "native-verified";
57
+ unavailableReason?: string;
58
+ };
59
+ }
60
+ export interface MediaSourceMetadata {
61
+ fileName: string;
62
+ extension: string;
63
+ sizeBytes: number;
64
+ mimeType?: string;
65
+ modifiedAt?: string;
66
+ }
67
+ export declare function sameMediaSourceIdentity(left: MediaSourceIdentity, right: MediaSourceIdentity): boolean;
68
+ export interface AnalysisProvenance {
69
+ analyzer: AnalyzerDescriptor;
70
+ source: MediaSourceIdentity;
71
+ ranges: TimeRange[];
72
+ }
73
+ export interface MediaAnalysisStatus {
74
+ capability: MediaAnalysisCapability;
75
+ status: "analyzed" | "available" | "unavailable";
76
+ provenance?: AnalysisProvenance;
77
+ reason?: string;
78
+ }
79
+ export interface MediaSemanticDescription {
80
+ subjects: SemanticTag[];
81
+ scenes: SemanticTag[];
82
+ environments: SemanticTag[];
83
+ timeOfDay: SemanticTag[];
84
+ moods: SemanticTag[];
85
+ motion?: VisualMotion;
86
+ usableRanges: TimeRange[];
87
+ transcript?: string;
88
+ audio?: {
89
+ present: boolean;
90
+ integratedLufs?: number;
91
+ truePeakDb?: number;
92
+ silenceMs?: number;
93
+ };
94
+ }
95
+ export interface MediaIndexEntry {
96
+ sourceIdentity: MediaSourceIdentity;
97
+ semantic: MediaSemanticDescription;
98
+ analysis: MediaAnalysisStatus[];
99
+ speech?: SpeechAnalysis;
100
+ audio?: AudioAnalysis;
101
+ analysisRevision?: string;
102
+ }
103
+ export interface MediaIndexQuery {
104
+ query?: string;
105
+ subject?: string;
106
+ scene?: string;
107
+ environment?: string;
108
+ timeOfDay?: string;
109
+ mood?: string;
110
+ motion?: VisualMotion["label"];
111
+ range?: TimeRange;
112
+ capabilities?: MediaAnalysisCapability[];
113
+ }
114
+ export interface RoughCutPlanRequest extends MediaIndexQuery {
115
+ maxShots?: number;
116
+ }
117
+ export interface RoughCutShot {
118
+ order: number;
119
+ sourceIdentity: MediaSourceIdentity;
120
+ range: TimeRange;
121
+ confidence: number;
122
+ matchedProperties: string[];
123
+ rationale: string;
124
+ evidence?: RoughCutSpeechEvidence;
125
+ }
126
+ export interface RoughCutSpeechEvidence {
127
+ kind: "speech";
128
+ transcript: string;
129
+ wordCount: number;
130
+ averageWordConfidence: number;
131
+ vad?: {
132
+ kind: SpeechSegmentKind;
133
+ confidence?: number;
134
+ };
135
+ audio?: {
136
+ integratedLufs?: number;
137
+ truePeakDb?: number;
138
+ silenceMs?: number;
139
+ };
140
+ }
141
+ export interface RoughCutPlan {
142
+ planner: {
143
+ id: string;
144
+ version: number;
145
+ };
146
+ revision: ContextRevision;
147
+ query: RoughCutPlanRequest;
148
+ shots: RoughCutShot[];
149
+ warnings: string[];
150
+ }
151
+ export interface TimelineSemanticContextQuery {
152
+ query?: string;
153
+ occurrenceIds?: string[];
154
+ }
155
+ export interface TimelineSemanticObservation {
156
+ capability: "speech" | "visual" | "metadata";
157
+ range: TimeRange;
158
+ text?: string;
159
+ label?: string;
160
+ confidence?: number;
161
+ analyzer?: AnalyzerDescriptor;
162
+ }
163
+ export interface TimelineSemanticOccurrenceContext {
164
+ occurrenceId: string;
165
+ status: "available" | "unavailable";
166
+ mediaId?: string;
167
+ sourceIdentity?: MediaSourceIdentity;
168
+ sourceRange?: TimeRange;
169
+ reason?: string;
170
+ observations: TimelineSemanticObservation[];
171
+ analysis: MediaAnalysisStatus[];
172
+ analysisRevision?: string;
173
+ }
174
+ export interface TimelineSemanticContext {
175
+ projectId: string;
176
+ timelineId: string;
177
+ revision: ContextRevision;
178
+ query: TimelineSemanticContextQuery;
179
+ occurrences: TimelineSemanticOccurrenceContext[];
180
+ }
181
+ /** VAD observations retained for one source range, including unavailable spans. */
182
+ export type VadCoverageSpan = {
183
+ start: number;
184
+ end: number;
185
+ status: "available";
186
+ segments: SpeechSegment[];
187
+ } | {
188
+ start: number;
189
+ end: number;
190
+ status: "unavailable";
191
+ reason: string;
192
+ };
193
+ export interface SpeechAnalysis {
194
+ /** Provenance fields are optional for backwards-compatible provider ports. */
195
+ schemaVersion?: typeof SPEECH_ANALYSIS_SCHEMA_VERSION;
196
+ mediaId?: string;
197
+ sourceIdentity?: MediaSourceIdentity;
198
+ requestedRange?: TimeRange;
199
+ observedRange?: TimeRange;
200
+ revision?: ContextRevision;
201
+ provider?: AnalyzerDescriptor;
202
+ sourceTimebase?: RationalTime;
203
+ capability?: SpeechAnalysisCapability;
204
+ words: SpeechWord[];
205
+ vadSegments?: SpeechSegment[];
206
+ /** Range-scoped VAD observations; partial coverage does not authorize top-level VAD. */
207
+ vadCoverage?: VadCoverageSpan[];
208
+ /** Optional detector failure; transcription can remain available independently. */
209
+ vadUnavailableReason?: string;
210
+ silenceSegments?: SpeechSegment[];
211
+ protectedSegments?: SpeechSegment[];
212
+ }
213
+ /** Speech evidence that is safe to use for a specific editor revision. */
214
+ export interface RevisionBoundSpeechAnalysis extends SpeechAnalysis {
215
+ schemaVersion: typeof SPEECH_ANALYSIS_SCHEMA_VERSION;
216
+ mediaId: string;
217
+ sourceIdentity: MediaSourceIdentity;
218
+ requestedRange: TimeRange;
219
+ observedRange: TimeRange;
220
+ revision: ContextRevision;
221
+ provider: AnalyzerDescriptor;
222
+ sourceTimebase: RationalTime;
223
+ capability: SpeechAnalysisCapability;
224
+ }
225
+ export interface AudioSignalFormat {
226
+ sampleRate: number;
227
+ channels: number;
228
+ channelLayout?: string;
229
+ }
230
+ export interface AudioAnalysis {
231
+ /** Declared source reference clock; absent means unavailable, never inferred. */
232
+ sourceTimebase?: RationalTime;
233
+ /** Format of the measured signal, interpreted with signalScope. */
234
+ signalFormat?: AudioSignalFormat;
235
+ /** Omitted legacy scope means source-file audio, never post-edit output. */
236
+ signalScope?: "source" | "occurrence";
237
+ /** Required when signalScope is occurrence; echoes an explicit measurement request. */
238
+ occurrenceId?: string;
239
+ schemaVersion?: 1;
240
+ mediaId?: string;
241
+ sourceIdentity?: MediaSourceIdentity;
242
+ requestedRange?: TimeRange;
243
+ measuredRange?: TimeRange;
244
+ revision?: ContextRevision;
245
+ provider?: AnalyzerDescriptor;
246
+ integratedLufs: number;
247
+ truePeakDb: number;
248
+ silenceMs: number;
249
+ audibleSamples?: number;
250
+ analyzedDurationSeconds?: number;
251
+ dialoguePresent?: boolean;
252
+ valid?: boolean;
253
+ invalidReason?: string;
254
+ }
255
+ /** Provider output for locating and reducing unwanted background noise. */
256
+ export interface NoiseAnalysis {
257
+ noiseFloorDb: number;
258
+ peakNoiseDb?: number;
259
+ affectedRanges: TimeRange[];
260
+ recommendedReductionDb: number;
261
+ confidence: number;
262
+ valid?: boolean;
263
+ invalidReason?: string;
264
+ }
265
+ /** Revision-bound noise evidence for one complete timeline occurrence. */
266
+ export interface NoiseMeasurement extends NoiseAnalysis {
267
+ mediaId: string;
268
+ occurrenceId: string;
269
+ requestedRange: TimeRange;
270
+ measuredRange: TimeRange;
271
+ revision: ContextRevision;
272
+ provider: AnalyzerDescriptor;
273
+ }
274
+ /** Revision-bound audio evidence for one complete timeline occurrence. */
275
+ export interface AudioMeasurement {
276
+ sourceTimebase?: RationalTime;
277
+ signalFormat?: AudioSignalFormat;
278
+ signalScope: "source" | "occurrence";
279
+ sourceIdentity?: MediaSourceIdentity;
280
+ mediaId: string;
281
+ occurrenceId: string;
282
+ requestedRange: TimeRange;
283
+ measuredRange: TimeRange;
284
+ revision: ContextRevision;
285
+ provider: AnalyzerDescriptor;
286
+ dialoguePresent: boolean;
287
+ integratedLufs: number;
288
+ truePeakDb: number;
289
+ silenceMs: number;
290
+ analyzedDurationSeconds: number;
291
+ valid: boolean;
292
+ invalidReason?: string;
293
+ }
294
+ export interface VisualScene {
295
+ id: string;
296
+ start: number;
297
+ end: number;
298
+ label?: string;
299
+ confidence?: number;
300
+ }
301
+ export interface VisualSubject {
302
+ id: string;
303
+ label: string;
304
+ confidence: number;
305
+ start?: number;
306
+ end?: number;
307
+ }
308
+ export interface VisualKeyframe {
309
+ time: number;
310
+ source: string;
311
+ labels?: string[];
312
+ }
313
+ export interface VisualMotion {
314
+ score: number;
315
+ label?: "static" | "low" | "medium" | "high";
316
+ }
317
+ export interface VisualAnalysis {
318
+ scenes: VisualScene[];
319
+ subjects: VisualSubject[];
320
+ motion?: VisualMotion;
321
+ keyframes: VisualKeyframe[];
322
+ }
323
+ export interface FrameImage {
324
+ /** Base64-encoded image bytes. */
325
+ data: string;
326
+ mimeType: string;
327
+ width?: number;
328
+ height?: number;
329
+ }
330
+ /** Editor-native frame data before runtime context is attached. */
331
+ export interface CapturedFrameSource {
332
+ image: FrameImage;
333
+ timecode: string;
334
+ }
335
+ export interface TimelineFrameCapture {
336
+ image: FrameImage;
337
+ position: RationalTime;
338
+ timecode: string;
339
+ project: ProjectSequence;
340
+ sequence: ProjectSequence;
341
+ clip?: Pick<Clip, "id" | "mediaId" | "name" | "startTime" | "durationTime" | "track">;
342
+ analysis?: VisualAnalysis;
343
+ }
344
+ export interface MediaContext {
345
+ mediaId: string;
346
+ source: string;
347
+ /** Exact source-coordinate bounds supplied by the snapshot provider, when available. */
348
+ sourceRange?: {
349
+ start: RationalTime;
350
+ duration: RationalTime;
351
+ };
352
+ mediaKind?: "video" | "audio";
353
+ duration?: number;
354
+ sourceDigest?: string;
355
+ sourceMetadata?: MediaSourceMetadata;
356
+ discovery?: MediaDiscoveryProvenance;
357
+ metadata?: MetadataAnalysis;
358
+ analysis?: MediaAnalysisStatus[];
359
+ semantic?: MediaSemanticDescription;
360
+ speech?: SpeechAnalysis;
361
+ audio?: AudioAnalysis;
362
+ noise?: NoiseAnalysis;
363
+ visual?: VisualAnalysis;
364
+ /** Revision of the source context used to produce attached analysis. */
365
+ analysisRevision?: string;
366
+ }
367
+ export interface MediaUnderstanding {
368
+ mediaId: string;
369
+ source: string;
370
+ sourceIdentity: MediaSourceIdentity;
371
+ metadata?: MetadataAnalysis;
372
+ speech?: SpeechAnalysis;
373
+ audio?: AudioAnalysis;
374
+ noise?: NoiseAnalysis;
375
+ visual?: VisualAnalysis;
376
+ semantic: MediaSemanticDescription;
377
+ analysis: MediaAnalysisStatus[];
378
+ analysisRevision: ContextRevision;
379
+ }
380
+ export interface AnalysisInput {
381
+ /** Explicit occurrence signal request; absent for source-file analysis. */
382
+ occurrenceId?: string;
383
+ project: ProjectSnapshot;
384
+ media: MediaContext;
385
+ }
386
+ export interface SpeechAnalyzer {
387
+ analyze(input: AnalysisInput, range?: TimeRange): Promise<SpeechAnalysis>;
388
+ readonly descriptor?: AnalyzerDescriptor;
389
+ readonly capabilities?: SpeechAnalyzerCapabilities;
390
+ }
391
+ export interface AudioAnalyzer {
392
+ analyze(input: AnalysisInput, range?: TimeRange): Promise<AudioAnalysis>;
393
+ readonly descriptor?: AnalyzerDescriptor;
394
+ }
395
+ export interface NoiseAnalyzer {
396
+ analyze(input: AnalysisInput, range?: TimeRange): Promise<NoiseAnalysis>;
397
+ readonly descriptor?: AnalyzerDescriptor;
398
+ }
399
+ export interface VisualAnalyzer {
400
+ analyze(input: AnalysisInput, range?: TimeRange): Promise<VisualAnalysis>;
401
+ readonly descriptor?: AnalyzerDescriptor;
402
+ }
403
+ export interface MetadataAnalyzer {
404
+ analyze(input: AnalysisInput, range?: TimeRange): Promise<MetadataAnalysis>;
405
+ readonly descriptor?: AnalyzerDescriptor;
406
+ }
@@ -0,0 +1,62 @@
1
+ import type { ContextRevision, RationalTime } from "./primitives.js";
2
+ import type { ProjectSnapshot } from "./project.js";
3
+ import type { EditorLiveState, EditorChange, ContextChangeSet, ProjectCatalog, ProjectSelection, ProjectSelectionResult } from "./context.js";
4
+ import type { CapturedFrameSource, MediaContext } from "./media.js";
5
+ import type { CapabilityInspectionOptions, EditorIdentity, RuntimeCapabilities } from "./capabilities.js";
6
+ import type { WorkflowOperation, EditOperation } from "./editing.js";
7
+ export interface EditorAdapter {
8
+ read(): Promise<ProjectSnapshot>;
9
+ /** Apply atomically and return the resulting revision for read-failure rollback. */
10
+ apply(operation: EditOperation, expectedRevision: ContextRevision): Promise<ContextRevision>;
11
+ }
12
+ export interface EditorPort extends EditorAdapter {
13
+ /** Share a single canonical observation only within this read operation. */
14
+ withCanonicalReadScope?<T>(operation: () => Promise<T>): Promise<T>;
15
+ getIdentity(): Promise<EditorIdentity>;
16
+ getCapabilities(options?: CapabilityInspectionOptions): Promise<RuntimeCapabilities>;
17
+ getManagedArtifact?(): Promise<ManagedArtifact>;
18
+ getManagedArtifactDigest?(): Promise<string | undefined>;
19
+ readProject(): Promise<ProjectSnapshot>;
20
+ restore(snapshot: ProjectSnapshot, expectedRevision: ContextRevision): Promise<void>;
21
+ listAssets?(query?: AssetSearchQuery): Promise<EditorAsset[]>;
22
+ listMedia?(query?: MediaSearchQuery): Promise<MediaContext[]>;
23
+ /** Optional native change feed; absence falls back to a snapshot diff. */
24
+ readChanges?(since: ContextRevision): Promise<ContextChangeSet>;
25
+ listProjects?(): Promise<ProjectCatalog>;
26
+ selectProject?(selection: ProjectSelection): Promise<ProjectSelectionResult>;
27
+ /** Capture only if the active editor target still matches the inspected revision. */
28
+ captureFrame?(position: RationalTime, expectedRevision: ContextRevision): Promise<CapturedFrameSource>;
29
+ previewTransaction?(operations: WorkflowOperation[], expectedRevision: ContextRevision): Promise<ProjectSnapshot>;
30
+ applyTransaction?(operations: WorkflowOperation[], expectedRevision: ContextRevision): Promise<void>;
31
+ }
32
+ export interface ManagedArtifact {
33
+ id: string;
34
+ path: string;
35
+ format: "fcpxml";
36
+ digest?: string;
37
+ }
38
+ export interface LiveEditorStatePort {
39
+ readLiveState(): Promise<EditorLiveState>;
40
+ liveChangesSince(revision: ContextRevision, waitMs?: number): Promise<EditorChange[]>;
41
+ }
42
+ export interface EditorAsset {
43
+ id: string;
44
+ kind: "transition" | "effect" | "title" | "generator" | "audio-effect" | "template";
45
+ name: string;
46
+ vendor: string;
47
+ metadata: Record<string, unknown>;
48
+ compatibility?: {
49
+ timelineKinds?: string[];
50
+ mediaKinds?: string[];
51
+ };
52
+ }
53
+ export interface AssetSearchQuery {
54
+ query?: string;
55
+ kind?: EditorAsset["kind"];
56
+ vendor?: string;
57
+ discovery?: "background" | "native" | "all";
58
+ }
59
+ export interface MediaSearchQuery {
60
+ query?: string;
61
+ mediaKind?: "video" | "audio";
62
+ }
@@ -0,0 +1,21 @@
1
+ export interface ContextRevision {
2
+ id: string;
3
+ sequence: number;
4
+ timestamp: string;
5
+ }
6
+ export interface TimeRange {
7
+ start: number;
8
+ end: number;
9
+ /** Exact representation used when the range crossed an editor boundary. */
10
+ startTime?: RationalTime;
11
+ durationTime?: RationalTime;
12
+ }
13
+ export interface RationalTimeRange {
14
+ start: RationalTime;
15
+ duration: RationalTime;
16
+ }
17
+ /** Exact interchange time; strings keep it JSON-safe at the MCP boundary. */
18
+ export interface RationalTime {
19
+ value: string;
20
+ timescale: string;
21
+ }
@@ -0,0 +1,119 @@
1
+ import type { ContextRevision, RationalTime } from "./primitives.js";
2
+ import type { MediaContext } from "./media.js";
3
+ import type { MaskConfiguration } from "./editing.js";
4
+ export type ColorCorrectionPreset = "neutral" | "warm" | "cool" | "high-contrast";
5
+ export interface ColorCorrection {
6
+ exposure: number;
7
+ contrast: number;
8
+ saturation: number;
9
+ temperature: number;
10
+ tint: number;
11
+ preset?: ColorCorrectionPreset;
12
+ }
13
+ export interface PictureInPicturePosition {
14
+ /** Horizontal and vertical offsets in timeline pixels from the canvas center. */
15
+ x: number;
16
+ y: number;
17
+ }
18
+ export interface PictureInPictureCrop {
19
+ /** Fractions of the source frame to crop from each edge. */
20
+ top: number;
21
+ right: number;
22
+ bottom: number;
23
+ left: number;
24
+ }
25
+ export interface PictureInPictureFrame {
26
+ style: "solid";
27
+ color: string;
28
+ width: number;
29
+ }
30
+ export interface Clip {
31
+ /** Stable identity of this timeline occurrence, never the media resource id. */
32
+ id: string;
33
+ mediaId?: string;
34
+ name: string;
35
+ start: number;
36
+ duration: number;
37
+ /** Source-media start for trimmed occurrences; absent means zero. */
38
+ sourceStart?: number;
39
+ sourceStartTime?: RationalTime;
40
+ track: number;
41
+ gainDb?: number;
42
+ noiseReductionDb?: number;
43
+ colorCorrection?: ColorCorrection;
44
+ mask?: MaskConfiguration;
45
+ fadeIn?: number;
46
+ fadeOut?: number;
47
+ enabled?: boolean;
48
+ role?: "video" | "audio" | "music" | "title";
49
+ /** Exact native audio role, including its subrole. */
50
+ nativeAudioRole?: string;
51
+ attachedTo?: string;
52
+ position?: PictureInPicturePosition;
53
+ scale?: number;
54
+ crop?: PictureInPictureCrop;
55
+ frame?: PictureInPictureFrame;
56
+ /** Authoritative exact timeline coordinates; start/duration are convenience seconds. */
57
+ startTime: RationalTime;
58
+ durationTime: RationalTime;
59
+ }
60
+ export interface Marker {
61
+ id: string;
62
+ start: number;
63
+ duration: number;
64
+ name: string;
65
+ startTime?: RationalTime;
66
+ durationTime?: RationalTime;
67
+ }
68
+ export interface Caption {
69
+ id: string;
70
+ start: number;
71
+ duration: number;
72
+ text: string;
73
+ startTime?: RationalTime;
74
+ durationTime?: RationalTime;
75
+ }
76
+ export interface ProjectSnapshot {
77
+ projectId: string;
78
+ projectName: string;
79
+ /** Optional editor playhead observed with the canonical snapshot. */
80
+ playheadTime?: RationalTime;
81
+ timeline: {
82
+ id: string;
83
+ name: string;
84
+ duration: number;
85
+ durationTime?: RationalTime;
86
+ /** Explicit source timecode origin, when independently present in the artifact. */
87
+ timecodeStart?: RationalTime;
88
+ /** Sequence-coordinate frame-grid origin, when supplied by the snapshot provider. */
89
+ frameGridOrigin?: RationalTime;
90
+ frameDuration?: RationalTime;
91
+ clips: Clip[];
92
+ storyElements: StoryElement[];
93
+ markers: Marker[];
94
+ captions: Caption[];
95
+ };
96
+ media: MediaContext[];
97
+ revision: ContextRevision;
98
+ }
99
+ /** Ordered FCPXML story elements retained so heterogeneous spines are not lost. */
100
+ export interface StoryElement {
101
+ id: string;
102
+ kind: string;
103
+ start: number;
104
+ duration: number;
105
+ startTime?: RationalTime;
106
+ durationTime?: RationalTime;
107
+ lane?: number;
108
+ mediaId?: string;
109
+ assetId?: string;
110
+ text?: string;
111
+ attachedTo?: string;
112
+ beforeClipId?: string;
113
+ afterClipId?: string;
114
+ position?: PictureInPicturePosition;
115
+ scale?: number;
116
+ crop?: PictureInPictureCrop;
117
+ frame?: PictureInPictureFrame;
118
+ mask?: MaskConfiguration;
119
+ }
@@ -0,0 +1,27 @@
1
+ import type { ContextRevision } from "./primitives.js";
2
+ import type { CompositeEditPreview, ImportMediaOperation, WorkflowOperation } from "./editing.js";
3
+ import type { MediaContext } from "./media.js";
4
+ import type { ProjectSnapshot } from "./project.js";
5
+ export interface RoughCutConstructionShot {
6
+ occurrenceId: string;
7
+ mediaId: string;
8
+ duration?: number;
9
+ }
10
+ export interface RoughCutConstructionPlanRequest {
11
+ baseRevision: ContextRevision;
12
+ imports?: ImportMediaOperation[];
13
+ shots: RoughCutConstructionShot[];
14
+ }
15
+ export interface RoughCutConstructionPlan {
16
+ projectId: string;
17
+ timelineId: string;
18
+ baseRevision: ContextRevision;
19
+ operations: WorkflowOperation[];
20
+ duration: number;
21
+ }
22
+ export interface RoughCutConstructionPreview extends CompositeEditPreview {
23
+ plan: RoughCutConstructionPlan;
24
+ }
25
+ /** Build a deterministic primary-storyline workflow without mutating a project. */
26
+ export declare function planRoughCutConstruction(snapshot: ProjectSnapshot, request: RoughCutConstructionPlanRequest): RoughCutConstructionPlan;
27
+ export type RoughCutMedia = MediaContext;