@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,271 @@
1
+ #!/usr/bin/env python3
2
+ """Run an optional local Whisper implementation against Framekit's JSON protocol.
3
+
4
+ The script intentionally has no Python package dependency of its own. Install
5
+ either mlx-whisper or openai-whisper in the environment that runs it and select
6
+ the model with FRAMEKIT_WHISPER_MODEL.
7
+ """
8
+
9
+ import importlib
10
+ import hashlib
11
+ import json
12
+ import math
13
+ import os
14
+ import sys
15
+ import subprocess
16
+ from typing import Any
17
+
18
+
19
+ def fail(code: int, message: str) -> None:
20
+ print(message, file=sys.stderr)
21
+ raise SystemExit(code)
22
+
23
+
24
+ def read_request() -> dict[str, Any]:
25
+ try:
26
+ value = json.load(sys.stdin)
27
+ except json.JSONDecodeError as error:
28
+ fail(65, f"WHISPER_REQUEST_INVALID: backend received invalid JSON: {error}")
29
+ if not isinstance(value, dict):
30
+ fail(65, "WHISPER_REQUEST_INVALID: backend request must be an object")
31
+ return value
32
+
33
+
34
+ def required_record(value: Any, name: str) -> dict[str, Any]:
35
+ if not isinstance(value, dict):
36
+ fail(65, f"WHISPER_REQUEST_INVALID: {name} must be an object")
37
+ return value
38
+
39
+
40
+ def finite_number(value: Any, name: str) -> float:
41
+ if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
42
+ fail(65, f"WHISPER_OUTPUT_INVALID: {name} must be a finite number")
43
+ return float(value)
44
+
45
+
46
+ def load_backend() -> tuple[str, Any]:
47
+ requested = os.environ.get("FRAMEKIT_WHISPER_BACKEND", "auto").strip().lower()
48
+ candidates = {
49
+ "mlx-whisper": ("mlx_whisper", "MLX Whisper"),
50
+ "openai-whisper": ("whisper", "openai-whisper"),
51
+ }
52
+ if requested not in {"auto", *candidates}:
53
+ fail(78, "WHISPER_SETUP_REQUIRED: FRAMEKIT_WHISPER_BACKEND must be auto, mlx-whisper, or openai-whisper")
54
+
55
+ ordered = list(candidates) if requested == "auto" else [requested]
56
+ errors: list[str] = []
57
+ for name in ordered:
58
+ module_name, label = candidates[name]
59
+ try:
60
+ return label, importlib.import_module(module_name)
61
+ except ImportError as error:
62
+ errors.append(f"{name}: {error}")
63
+ detail = "; ".join(errors)
64
+ fail(78, f"WHISPER_SETUP_REQUIRED: install a selected local backend ({detail})")
65
+ raise AssertionError("unreachable")
66
+
67
+
68
+ def transcribe(module_label: str, module: Any, source: str) -> dict[str, Any]:
69
+ model = os.environ.get("FRAMEKIT_WHISPER_MODEL", "").strip()
70
+ if not model:
71
+ fail(78, "WHISPER_SETUP_REQUIRED: set FRAMEKIT_WHISPER_MODEL to a local model or model repository")
72
+ language = os.environ.get("FRAMEKIT_WHISPER_LANGUAGE", "").strip() or None
73
+
74
+ try:
75
+ if module_label == "MLX Whisper":
76
+ options: dict[str, Any] = {
77
+ "path_or_hf_repo": model,
78
+ "word_timestamps": True,
79
+ }
80
+ if language:
81
+ options["language"] = language
82
+ result = module.transcribe(source, **options)
83
+ else:
84
+ model_instance = module.load_model(model)
85
+ options = {"word_timestamps": True, "verbose": False, "fp16": False}
86
+ if language:
87
+ options["language"] = language
88
+ result = model_instance.transcribe(source, **options)
89
+ except Exception as error: # noqa: BLE001 - provider diagnostics must cross the process boundary
90
+ fail(78, f"WHISPER_ANALYZER_FAILED: {module_label} could not transcribe the source: {error}")
91
+ if not isinstance(result, dict):
92
+ fail(65, "WHISPER_OUTPUT_INVALID: Whisper backend must return an object")
93
+ return result
94
+
95
+
96
+ def confidence(value: Any) -> float:
97
+ if value is None:
98
+ # Whisper implementations may omit probability even when they expose
99
+ # reliable timestamps. Zero preserves that uncertainty for selectors.
100
+ return 0.0
101
+ number = finite_number(value, "word confidence")
102
+ if number < 0 or number > 1:
103
+ fail(65, "WHISPER_OUTPUT_INVALID: word confidence must be between 0 and 1")
104
+ return number
105
+
106
+
107
+ def normalized_words(result: dict[str, Any], requested: dict[str, Any] | None) -> list[dict[str, Any]]:
108
+ entries: list[dict[str, Any]] = []
109
+ segments = result.get("segments", [])
110
+ if not isinstance(segments, list):
111
+ fail(65, "WHISPER_OUTPUT_INVALID: segments must be an array")
112
+ for segment in segments:
113
+ segment_record = required_record(segment, "segment")
114
+ segment_start = finite_number(segment_record.get("start"), "segment start")
115
+ segment_end = finite_number(segment_record.get("end"), "segment end")
116
+ if segment_start < 0 or segment_end < segment_start:
117
+ fail(65, "WHISPER_OUTPUT_INVALID: segment boundaries are invalid")
118
+ words = segment_record.get("words")
119
+ text = str(segment_record.get("text", "")).strip()
120
+ if segment_start == segment_end:
121
+ if not text and (words is None or words == []):
122
+ continue
123
+ fail(65, "WHISPER_OUTPUT_INVALID: segment boundaries are invalid")
124
+ if not isinstance(words, list) or not words:
125
+ words = [{"word": text, "start": segment_start, "end": segment_end}]
126
+ for word in words:
127
+ word_record = required_record(word, "word")
128
+ text = str(word_record.get("word", word_record.get("text", ""))).strip()
129
+ if not text:
130
+ continue
131
+ start = finite_number(word_record.get("start"), "word start")
132
+ end = finite_number(word_record.get("end"), "word end")
133
+ if start < 0 or end < start:
134
+ fail(65, "WHISPER_OUTPUT_INVALID: word boundaries are invalid")
135
+ if start == end:
136
+ continue
137
+ if requested is not None:
138
+ request_start = finite_number(requested.get("start"), "request start")
139
+ request_end = finite_number(requested.get("end"), "request end")
140
+ if start < request_start or end > request_end:
141
+ continue
142
+ entries.append({
143
+ "text": text,
144
+ "start": start,
145
+ "end": end,
146
+ "confidence": confidence(word_record.get("probability", word_record.get("confidence"))),
147
+ })
148
+
149
+ entries.sort(key=lambda value: (value["start"], value["end"], value["text"]))
150
+ for previous, current in zip(entries, entries[1:]):
151
+ if current["start"] < previous["end"]:
152
+ fail(65, "WHISPER_OUTPUT_INVALID: word timestamps overlap")
153
+ return entries
154
+
155
+
156
+ class VadFailure(Exception):
157
+ def __init__(self, code: str):
158
+ self.code = code
159
+ super().__init__(code)
160
+
161
+
162
+ def analyze_vad(source: str, media: dict[str, Any], requested: dict[str, Any] | None) -> dict[str, Any]:
163
+ """Run a pinned local detector; ASR timestamps are never activity evidence."""
164
+ model_path = os.environ.get("FRAMEKIT_SILERO_VAD_MODEL", "").strip()
165
+ expected = os.environ.get("FRAMEKIT_SILERO_VAD_SHA256", "").strip().lower()
166
+ if not model_path or len(expected) != 64 or any(c not in "0123456789abcdef" for c in expected):
167
+ raise VadFailure("SILERO_VAD_SETUP_REQUIRED")
168
+ try:
169
+ with open(model_path, "rb") as model_file:
170
+ initial = hashlib.sha256(model_file.read()).hexdigest()
171
+ if initial != expected:
172
+ raise VadFailure("SILERO_VAD_MODEL_MISMATCH")
173
+ torch = importlib.import_module("torch")
174
+ detector = importlib.import_module("silero_vad")
175
+ torch.set_num_threads(1)
176
+ model = torch.jit.load(model_path, map_location="cpu")
177
+ model.eval()
178
+ decoded = subprocess.run(["ffmpeg", "-hide_banner", "-nostdin", "-loglevel", "error", "-i", source,
179
+ "-map", "0:a:0", "-ar", "16000", "-ac", "1", "-f", "f32le", "-"],
180
+ capture_output=True, check=True, timeout=45).stdout
181
+ if not decoded or len(decoded) % 4:
182
+ raise VadFailure("SILERO_VAD_SOURCE_INCOMPLETE")
183
+ audio = torch.frombuffer(bytearray(decoded), dtype=torch.float32).clone()
184
+ count = audio.numel()
185
+ start = requested["start"] if requested is not None else 0
186
+ end = requested["end"] if requested is not None else media.get("duration", count / 16000)
187
+ if isinstance(end, bool) or not isinstance(end, (int, float)) or not math.isfinite(end) or end > count / 16000 + 1e-9:
188
+ raise VadFailure("SILERO_VAD_SOURCE_INCOMPLETE")
189
+ first, last = math.ceil(start * 16000), math.floor(end * 16000)
190
+ if first < 0 or last <= first:
191
+ raise VadFailure("SILERO_VAD_SOURCE_INCOMPLETE")
192
+ intervals = detector.get_speech_timestamps(audio, model, sampling_rate=16000, threshold=0.5,
193
+ min_speech_duration_ms=250, min_silence_duration_ms=100,
194
+ speech_pad_ms=30, return_seconds=False)
195
+ if not isinstance(intervals, list):
196
+ raise VadFailure("SILERO_VAD_OUTPUT_INVALID")
197
+ segments = []
198
+ previous = 0
199
+ for interval in intervals:
200
+ if not isinstance(interval, dict):
201
+ raise VadFailure("SILERO_VAD_OUTPUT_INVALID")
202
+ a, b = interval.get("start"), interval.get("end")
203
+ if type(a) is not int or type(b) is not int or a < previous or b <= a or b > count:
204
+ raise VadFailure("SILERO_VAD_OUTPUT_INVALID")
205
+ previous = b
206
+ left, right = max(first, a), min(last, b)
207
+ if right > left:
208
+ segments.append({"start": left / 16000, "end": right / 16000, "kind": "speech"})
209
+ with open(model_path, "rb") as model_file:
210
+ if hashlib.sha256(model_file.read()).hexdigest() != initial:
211
+ raise VadFailure("SILERO_VAD_MODEL_MISMATCH")
212
+ return {"vadSegments": segments, "observedRange": {"start": first / 16000, "end": last / 16000},
213
+ "requestedRange": {"start": start, "end": end}}
214
+ except VadFailure:
215
+ raise
216
+ except Exception: # Optional detector failures must not suppress available ASR.
217
+ raise VadFailure("SILERO_VAD_ANALYZER_FAILED") from None
218
+
219
+
220
+ def main() -> None:
221
+ request = read_request()
222
+ media = required_record(request.get("media"), "media")
223
+ source = media.get("source")
224
+ if not isinstance(source, str) or not source:
225
+ fail(65, "WHISPER_REQUEST_INVALID: media.source is required")
226
+ if not os.path.isfile(source):
227
+ fail(78, f"WHISPER_MEDIA_UNAVAILABLE: source does not exist: {source}")
228
+
229
+ requested = request.get("range")
230
+ if requested is not None:
231
+ requested = required_record(requested, "range")
232
+ start = finite_number(requested.get("start"), "request start")
233
+ end = finite_number(requested.get("end"), "request end")
234
+ if start < 0 or end <= start:
235
+ fail(65, "WHISPER_REQUEST_INVALID: range boundaries are invalid")
236
+
237
+ vad = None
238
+ vad_failure = None
239
+ required_vad = os.environ.get("FRAMEKIT_SPEECH_REQUIRE_VAD") == "1"
240
+ if os.environ.get("FRAMEKIT_SILERO_VAD_MODEL") or required_vad:
241
+ try:
242
+ vad = analyze_vad(source, media, requested)
243
+ except VadFailure as error:
244
+ if required_vad:
245
+ fail(78, error.code + ": required detector unavailable; check its local model pin and dependencies")
246
+ vad_failure = error.code
247
+ module_label, module = load_backend()
248
+ result = transcribe(module_label, module, source)
249
+ output = {
250
+ "words": normalized_words(result, vad["observedRange"] if vad is not None else requested),
251
+ # Both supported Whisper implementations decode input at 16 kHz;
252
+ # detector availability does not change the transcription clock.
253
+ "sourceTimebase": {"value": "1", "timescale": "16000"},
254
+ }
255
+ if vad is not None:
256
+ output.update(vad)
257
+ output["schemaVersion"] = 1
258
+ if "mediaId" in media:
259
+ output.update(mediaId=media["mediaId"], sourceIdentity=media)
260
+ if "revision" in request:
261
+ output["revision"] = request["revision"]
262
+ version = os.environ.get("FRAMEKIT_SPEECH_ANALYZER_VERSION", "").strip()
263
+ if version:
264
+ output["provider"] = {"id": "command.speech", "provider": "command", "version": version}
265
+ if vad_failure is not None:
266
+ output["vadUnavailableReason"] = vad_failure
267
+ print(json.dumps(output, separators=(",", ":")))
268
+
269
+
270
+ if __name__ == "__main__":
271
+ main()
@@ -0,0 +1,10 @@
1
+ import type { FramekitBuildFingerprint } from "./version.js";
2
+ export type BuildAlignmentStatus = "matched" | "missing" | "mismatched";
3
+ export interface BuildAlignmentReport {
4
+ status: BuildAlignmentStatus;
5
+ target: FramekitBuildFingerprint;
6
+ runtime: FramekitBuildFingerprint;
7
+ extension?: FramekitBuildFingerprint;
8
+ message: string;
9
+ }
10
+ export declare function assessBuildAlignment(runtime: FramekitBuildFingerprint, extension: FramekitBuildFingerprint | undefined, targetCommit?: string): BuildAlignmentReport;
@@ -0,0 +1,7 @@
1
+ export interface PackageBuildIdentity {
2
+ schemaVersion: 1;
3
+ version: string;
4
+ commit: string;
5
+ }
6
+ export declare function createPackageBuildIdentity(version: string, commit: string): PackageBuildIdentity;
7
+ export declare function parsePackageBuildIdentity(value: unknown, expectedVersion: string): PackageBuildIdentity | undefined;
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "version": "0.1.18",
4
- "commit": "cc0fc08ebc4ecf62897918d93a54dd35a7c73bf3"
3
+ "version": "0.2.3",
4
+ "commit": "da243be36c46e0471ef25c6f2c50c2306aed2c93"
5
5
  }
@@ -0,0 +1,8 @@
1
+ import type { EditorLiveState, ProjectSnapshot } from "../../../packages/runtime/src/index.js";
2
+ export interface CanonicalNativeSnapshotTarget {
3
+ projectId: string;
4
+ sequenceId: string;
5
+ projectName: string;
6
+ sequenceName: string;
7
+ }
8
+ export declare function createCanonicalNativeSnapshotReader(readLiveState: () => Promise<EditorLiveState>, readSnapshot: (target: CanonicalNativeSnapshotTarget) => Promise<ProjectSnapshot>): () => Promise<ProjectSnapshot>;
@@ -0,0 +1,18 @@
1
+ export function createCanonicalNativeSnapshotReader(readLiveState, readSnapshot) {
2
+ return async () => {
3
+ const live = await readLiveState();
4
+ const project = live.project;
5
+ const sequence = live.sequence;
6
+ if (!project?.id || project.id.startsWith("final-cut:")
7
+ || !project.name.trim() || !sequence?.id || sequence.id.startsWith("final-cut:")
8
+ || !sequence.name.trim()) {
9
+ throw new Error("TARGET_UNAVAILABLE: stable live project and sequence identities are required for canonical export");
10
+ }
11
+ return readSnapshot({
12
+ projectId: project.id,
13
+ sequenceId: sequence.id,
14
+ projectName: project.name,
15
+ sequenceName: sequence.name,
16
+ });
17
+ };
18
+ }
@@ -0,0 +1,5 @@
1
+ export declare function shouldConfigureFinalCutProjectPublisher(input: {
2
+ liveMode: boolean;
3
+ fcpxmlPath: string | undefined;
4
+ canonicalNativeProviderEnabled: boolean;
5
+ }): boolean;
@@ -0,0 +1,3 @@
1
+ export function shouldConfigureFinalCutProjectPublisher(input) {
2
+ return input.liveMode && (Boolean(input.fcpxmlPath) || input.canonicalNativeProviderEnabled);
3
+ }
@@ -0,0 +1,3 @@
1
+ import type { ProjectSnapshot, TimelineIr } from "../../../packages/runtime/src/index.js";
2
+ /** Adapt the persisted headless Timeline IR to the runtime's analysis contract. */
3
+ export declare function projectSnapshotFromTimelineIr(timeline: TimelineIr): ProjectSnapshot;
@@ -0,0 +1,89 @@
1
+ import { EditingSession, type ContextRevision, type EditingSessionDocument, type TimelineIr, type TimelineIrEditOperation, type TimelineIrProvider } from "../../../packages/runtime/src/index.js";
2
+ export interface SessionSqliteObservationProvider {
3
+ inspect(path: string): Promise<{
4
+ status: "partial";
5
+ observation: {
6
+ backend: string;
7
+ databaseKind: "flexolibrary" | "fcpevent" | "unknown";
8
+ digest: string;
9
+ schemaVersion: number;
10
+ revision: {
11
+ timestamp: string;
12
+ };
13
+ };
14
+ } | {
15
+ status: "error" | "unavailable";
16
+ error: {
17
+ code: string;
18
+ message: string;
19
+ };
20
+ }>;
21
+ }
22
+ export interface StoredEditingSession {
23
+ sessionId: string;
24
+ document: EditingSessionDocument;
25
+ }
26
+ export interface EditingSessionProviderChange {
27
+ from: ContextRevision;
28
+ to: ContextRevision;
29
+ }
30
+ export interface EditingSessionChangeSource {
31
+ changesSince(revision: ContextRevision): Promise<EditingSessionProviderChange>;
32
+ }
33
+ export declare function createCanonicalSessionChangeSource(readCurrent: () => Promise<Pick<TimelineIr, "revision">>): EditingSessionChangeSource;
34
+ export declare class EditingSessionRepository {
35
+ private readonly directory;
36
+ private readonly changeSource?;
37
+ constructor(directory: string, changeSource?: EditingSessionChangeSource | undefined);
38
+ create(input: {
39
+ sessionId?: string;
40
+ base: TimelineIr;
41
+ provider?: TimelineIrProvider;
42
+ }): Promise<StoredEditingSession>;
43
+ inspect(sessionId: string): Promise<StoredEditingSession>;
44
+ preview(sessionId: string, operations: TimelineIrEditOperation[], expectedRevision?: ContextRevision): Promise<import("../../../packages/runtime/src/index.js").TimelineIrPreview>;
45
+ execute(sessionId: string, operations: TimelineIrEditOperation[], expectedRevision?: ContextRevision): Promise<StoredEditingSession>;
46
+ status(sessionId: string): Promise<{
47
+ sessionId: string;
48
+ state: import("../../../packages/runtime/src/index.js").EditingSessionState;
49
+ provider?: TimelineIrProvider | undefined;
50
+ baseRevision: ContextRevision;
51
+ desiredRevision: ContextRevision;
52
+ observation?: import("../../../packages/runtime/src/index.js").EditingSessionObservation | undefined;
53
+ readyToMaterialize: boolean;
54
+ }>;
55
+ reconcile(sessionId: string, provider: TimelineIrProvider, providerState: TimelineIr): Promise<{
56
+ sessionId: string;
57
+ document: EditingSessionDocument;
58
+ reconciliation: import("../../../packages/runtime/src/index.js").TimelineReconciliationResult;
59
+ }>;
60
+ observe(sessionId: string, sourcePath: string, provider: SessionSqliteObservationProvider): Promise<{
61
+ sessionId: string;
62
+ document: EditingSessionDocument;
63
+ observation: {
64
+ backend: string;
65
+ sourceId: string;
66
+ databaseKind: "fcpevent" | "flexolibrary" | "unknown";
67
+ digest: string;
68
+ schemaVersion: number;
69
+ observedAt: string;
70
+ canonical: false;
71
+ coverageComplete: false;
72
+ };
73
+ change: "changed" | "observed" | "unchanged";
74
+ }>;
75
+ refresh(sessionId: string): Promise<{
76
+ sessionId: string;
77
+ document: EditingSessionDocument;
78
+ providerRevision: ContextRevision;
79
+ change: "changed" | "unchanged";
80
+ }>;
81
+ loadForMaterialization(sessionId: string): Promise<EditingSession>;
82
+ hasChangeSource(): boolean;
83
+ checkpoint(sessionId: string, session: EditingSession): Promise<StoredEditingSession>;
84
+ private load;
85
+ private refreshLoaded;
86
+ private save;
87
+ private assertMissing;
88
+ private path;
89
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -2,13 +2,15 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
2
2
  import { homedir } from "node:os";
3
3
  import { join } from "node:path";
4
4
  import { InMemoryEditorAdapter } from "../../../packages/testkit/src/index.js";
5
- import { createCommandAnalyzers, createFinalCutLiveAdapter, FcpxmlDocumentAdapter, FinalCutAssetRegistry, FinalCutMediaRegistry, FinalCutConnectionManager, assertCanonicalProviderConfiguration, FinalCutCanonicalNativeProvider, FinalCutCanonicalSnapshotSource, FinalCutLibraryInspectionProvider, FinalCutNativeAutomationAdapter, createFinalCutNativeTargetResolver, DisposableNativeEditWorkflow, FinalCutBackgroundMaterializationPublisher, FinalCutProjectPublisher, parseFinalCutProjectPublishRoute, FinalCutSqliteInspectionProvider, FinalCutVideoExporter, FinalCutSessionAdapter, createNativeOperationLease, createDisposableNativeOperationSession, isFinalCutVideoProbeAvailable, } from "../../../adapters/final-cut/typescript/src/index.js";
5
+ import { createCommandAnalyzers, createFinalCutLiveAdapter, FcpxmlDocumentAdapter, FinalCutAssetRegistry, FinalCutMediaRegistry, FinalCutConnectionManager, assertCanonicalProviderConfiguration, FinalCutCanonicalNativeProvider, FileCanonicalRecoveryGuard, FinalCutCanonicalSnapshotSource, FinalCutLibraryInspectionProvider, FinalCutNativeAutomationAdapter, createFinalCutNativeTargetResolver, DisposableNativeEditWorkflow, FinalCutBackgroundMaterializationPublisher, FinalCutProjectPublisher, parseFinalCutProjectPublishRoute, FinalCutVideoExporter, FinalCutSessionAdapter, createNativeOperationLease, createDisposableNativeOperationSession, isFinalCutVideoProbeAvailable, } from "../../../adapters/final-cut/typescript/src/index.js";
6
6
  import { FixtureAudioAnalyzer, FixtureMetadataAnalyzer, FixtureSpeechAnalyzer, FixtureVisualAnalyzer } from "../../../packages/testkit/src/index.js";
7
7
  import { AgentVideoRuntime, JsonSemanticMediaIndexStore } from "../../../packages/runtime/src/index.js";
8
+ import { HeadlessProjectService } from "../../../packages/headless-application/src/index.js";
8
9
  import { createMcpServer } from "./server.js";
9
10
  import { createCanonicalSessionChangeSource } from "./headless-sessions.js";
10
- import { HeadlessProjectService } from "./headless-projects.js";
11
+ import { createCanonicalNativeSnapshotReader } from "./canonical-native-snapshot.js";
11
12
  import { FfmpegMediaMetadataProbe, FfmpegRenderVerifier, FfmpegTimelineRenderer } from "../../../adapters/headless/typescript/src/index.js";
13
+ import { shouldConfigureFinalCutProjectPublisher } from "./final-cut-runtime-config.js";
12
14
  const fixture = new InMemoryEditorAdapter({
13
15
  projectId: "project-1",
14
16
  projectName: "Phase 2 Fixture",
@@ -53,6 +55,7 @@ const fixture = new InMemoryEditorAdapter({
53
55
  },
54
56
  }],
55
57
  });
58
+ const framekitStateDirectory = process.env.FRAMEKIT_STATE_DIR ?? join(homedir(), ".framekit");
56
59
  const liveMode = process.env.FRAMEKIT_EDITOR === "final-cut-live";
57
60
  const headlessFinalCut = liveMode && process.env.FRAMEKIT_FINAL_CUT_HEADLESS === "1";
58
61
  const fcpxmlPath = liveMode ? process.env.FRAMEKIT_FCPXML_PATH : undefined;
@@ -68,7 +71,11 @@ const canonicalProviderRequired = liveMode
68
71
  && !canonicalNativeProviderEnabled;
69
72
  assertCanonicalProviderConfiguration({ required: canonicalProviderRequired || canonicalNativeProviderEnabled, fcpxmlPath });
70
73
  const connection = liveMode
71
- ? new FinalCutConnectionManager({ headless: headlessFinalCut, canonicalProviderRequired })
74
+ ? new FinalCutConnectionManager({
75
+ headless: headlessFinalCut,
76
+ canonicalProviderRequired,
77
+ existingSocketOnly: process.env.FRAMEKIT_FINAL_CUT_EXISTING_SOCKET_ONLY === "1",
78
+ })
72
79
  : undefined;
73
80
  const autoConnect = liveMode && process.env.FRAMEKIT_AUTO_CONNECT !== "0";
74
81
  if (autoConnect)
@@ -95,8 +102,12 @@ const canonicalNativeMutationEditor = canonicalNativeProviderEnabled
95
102
  const canonicalNativeTargetResolver = canonicalNativeProviderEnabled
96
103
  ? createFinalCutNativeTargetResolver(nativeEditor)
97
104
  : undefined;
105
+ const canonicalRecovery = liveMode
106
+ ? new FileCanonicalRecoveryGuard(join(framekitStateDirectory, "canonical-recovery", "pending.json"))
107
+ : undefined;
98
108
  const canonicalNativeProvider = canonicalNativeProviderEnabled
99
109
  ? new FinalCutCanonicalNativeProvider({
110
+ recoveryGuard: canonicalRecovery,
100
111
  live: liveAdapter,
101
112
  native: {
102
113
  renameSelectedClip: async (name) => {
@@ -125,17 +136,7 @@ const canonicalNativeProvider = canonicalNativeProviderEnabled
125
136
  return { undone: result.undone, verification: result.verification };
126
137
  },
127
138
  },
128
- readSnapshot: async () => {
129
- const live = await liveAdapter.readLiveState();
130
- const projectId = live.project?.id;
131
- const sequenceId = live.sequence?.id;
132
- if (!projectId || projectId.startsWith("final-cut:") || !sequenceId || sequenceId.startsWith("final-cut:")) {
133
- throw new Error("TARGET_UNAVAILABLE: stable live project and sequence identities are required for canonical export");
134
- }
135
- return new FinalCutCanonicalSnapshotSource({
136
- target: { projectId, projectUid: projectId, sequenceId },
137
- }).readSnapshot();
138
- },
139
+ readSnapshot: createCanonicalNativeSnapshotReader(() => liveAdapter.readLiveState(), (target) => new FinalCutCanonicalSnapshotSource({ readbackTarget: target }).readSnapshot()),
139
140
  resolveTarget: canonicalNativeTargetResolver,
140
141
  backgroundCatalog: backgroundLibraryProvider,
141
142
  })
@@ -164,7 +165,6 @@ const editor = liveMode
164
165
  : {}),
165
166
  })
166
167
  : fixture;
167
- const framekitStateDirectory = process.env.FRAMEKIT_STATE_DIR ?? join(homedir(), ".framekit");
168
168
  const analyzers = liveMode
169
169
  ? createCommandAnalyzers({
170
170
  speechCommand: process.env.FRAMEKIT_SPEECH_ANALYZER,
@@ -187,11 +187,11 @@ const runtime = new AgentVideoRuntime(editor, {
187
187
  });
188
188
  const headlessProjects = new HeadlessProjectService({
189
189
  directory: join(framekitStateDirectory, "projects"),
190
+ protectedStateDirectory: framekitStateDirectory,
190
191
  mediaProbe: new FfmpegMediaMetadataProbe(),
191
192
  renderer: new FfmpegTimelineRenderer(),
192
193
  verifier: new FfmpegRenderVerifier(),
193
194
  });
194
- const sqliteObservationProvider = new FinalCutSqliteInspectionProvider();
195
195
  const disposableNative = liveMode && !headlessFinalCut && !fcpxmlPath && nativeEditor
196
196
  ? new DisposableNativeEditWorkflow({
197
197
  native: nativeEditor,
@@ -206,12 +206,17 @@ const disposableNative = liveMode && !headlessFinalCut && !fcpxmlPath && nativeE
206
206
  })
207
207
  : undefined;
208
208
  const nativeOperationSession = disposableNative && nativeEditor
209
- ? createDisposableNativeOperationSession({ workflow: disposableNative, native: nativeEditor })
209
+ ? createDisposableNativeOperationSession({ workflow: disposableNative, native: nativeEditor, recoveryGuard: canonicalRecovery })
210
210
  : undefined;
211
- const projectPublisher = liveMode && fcpxmlPath
211
+ const projectPublisher = shouldConfigureFinalCutProjectPublisher({
212
+ liveMode,
213
+ fcpxmlPath,
214
+ canonicalNativeProviderEnabled,
215
+ })
212
216
  ? new FinalCutProjectPublisher({
213
217
  enabled: !headlessFinalCut && process.env.FRAMEKIT_FINAL_CUT_NATIVE_WRITES === "1",
214
218
  sourcePath: fcpxmlPath,
219
+ publishJobDirectory: join(framekitStateDirectory, "publish-jobs"),
215
220
  publishJobsDirectory: join(framekitStateDirectory, "publish-jobs"),
216
221
  documentDelivery: liveAdapter,
217
222
  publishRoute: parseFinalCutProjectPublishRoute(process.env.FRAMEKIT_FINAL_CUT_PUBLISH_ROUTE, Boolean(liveAdapter)),
@@ -262,6 +267,7 @@ const server = createMcpServer(runtime, {
262
267
  disposableNative,
263
268
  nativeOperationSession,
264
269
  projectPublisher,
270
+ canonicalRecovery,
265
271
  ...(sessionMaterializationPublisher?.isAvailable() ? { sessionMaterializationPublisher } : {}),
266
272
  videoExporter,
267
273
  requireBuildAlignment: process.env.FRAMEKIT_REQUIRE_BUILD_ALIGNMENT === "1",
@@ -271,7 +277,6 @@ const server = createMcpServer(runtime, {
271
277
  sessionDirectory: join(framekitStateDirectory, "sessions"),
272
278
  sessionChangeSource: createCanonicalSessionChangeSource(() => runtime.inspectProject()),
273
279
  materializationDirectory: join(framekitStateDirectory, "materializations"),
274
- sqliteObservationProvider,
275
280
  headlessProjects,
276
281
  });
277
282
  const transport = new StdioServerTransport();