@morshoto/framekit 0.2.2 → 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 (156) 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 +25 -0
  47. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +5 -0
  48. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.d.ts +15 -0
  49. package/dist-package/adapters/headless/typescript/src/index.d.ts +3 -0
  50. package/dist-package/apps/cli/src/dev-doctor.d.ts +25 -0
  51. package/dist-package/apps/cli/src/headless-projects.d.ts +3 -0
  52. package/dist-package/apps/cli/src/main.d.ts +10 -0
  53. package/dist-package/apps/mcp-server/runtime/ffmpeg-audio-backend.py +129 -0
  54. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +92 -2
  55. package/dist-package/apps/mcp-server/src/build-alignment.d.ts +10 -0
  56. package/dist-package/apps/mcp-server/src/build-identity.d.ts +7 -0
  57. package/dist-package/apps/mcp-server/src/build-identity.json +2 -2
  58. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.d.ts +8 -0
  59. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.d.ts +5 -0
  60. package/dist-package/apps/mcp-server/src/headless-project-snapshot.d.ts +3 -0
  61. package/dist-package/apps/mcp-server/src/headless-sessions.d.ts +89 -0
  62. package/dist-package/apps/mcp-server/src/main.d.ts +1 -0
  63. package/dist-package/apps/mcp-server/src/materialization-jobs.d.ts +204 -0
  64. package/dist-package/apps/mcp-server/src/readback-policy.d.ts +18 -0
  65. package/dist-package/apps/mcp-server/src/routing.d.ts +90 -0
  66. package/dist-package/apps/mcp-server/src/server.d.ts +75 -0
  67. package/dist-package/apps/mcp-server/src/server.js +77 -7
  68. package/dist-package/apps/mcp-server/src/tools/skills/catalog.d.ts +19 -0
  69. package/dist-package/apps/mcp-server/src/tools/skills/metadata.d.ts +37 -0
  70. package/dist-package/apps/mcp-server/src/tools/skills/register.d.ts +11 -0
  71. package/dist-package/apps/mcp-server/src/version.d.ts +4 -0
  72. package/dist-package/packages/headless-application/src/external-edit.d.ts +30 -0
  73. package/dist-package/packages/headless-application/src/external-edit.js +72 -0
  74. package/dist-package/packages/headless-application/src/headless-projects.d.ts +233 -0
  75. package/dist-package/packages/headless-application/src/headless-projects.js +1 -1
  76. package/dist-package/packages/headless-application/src/index.d.ts +2 -0
  77. package/dist-package/packages/headless-application/src/index.js +1 -0
  78. package/dist-package/packages/runtime/src/application/duration-policy-service.d.ts +4 -0
  79. package/dist-package/packages/runtime/src/application/local-media.d.ts +46 -0
  80. package/dist-package/packages/runtime/src/application/media-analysis-service.d.ts +40 -0
  81. package/dist-package/packages/runtime/src/application/media-analysis-service.js +105 -15
  82. package/dist-package/packages/runtime/src/application/project-service.d.ts +35 -0
  83. package/dist-package/packages/runtime/src/application/project-store.d.ts +56 -0
  84. package/dist-package/packages/runtime/src/application/project-transactions.d.ts +51 -0
  85. package/dist-package/packages/runtime/src/application/runtime-options.d.ts +15 -0
  86. package/dist-package/packages/runtime/src/application/semantic-media-index-store.d.ts +28 -0
  87. package/dist-package/packages/runtime/src/application/transaction-store.d.ts +10 -0
  88. package/dist-package/packages/runtime/src/audio/analysis.d.ts +3 -0
  89. package/dist-package/packages/runtime/src/audio/analysis.js +95 -0
  90. package/dist-package/packages/runtime/src/audio/dialogue-normalization.d.ts +47 -0
  91. package/dist-package/packages/runtime/src/audio/noise-reduction.d.ts +34 -0
  92. package/dist-package/packages/runtime/src/capabilities.d.ts +45 -0
  93. package/dist-package/packages/runtime/src/color-correction.d.ts +33 -0
  94. package/dist-package/packages/runtime/src/context/context-engine.d.ts +28 -0
  95. package/dist-package/packages/runtime/src/context/context-service.d.ts +20 -0
  96. package/dist-package/packages/runtime/src/context/project-catalog.d.ts +12 -0
  97. package/dist-package/packages/runtime/src/context/revision.d.ts +2 -0
  98. package/dist-package/packages/runtime/src/domain/capabilities.d.ts +170 -0
  99. package/dist-package/packages/runtime/src/domain/context.d.ts +179 -0
  100. package/dist-package/packages/runtime/src/domain/diff.d.ts +104 -0
  101. package/dist-package/packages/runtime/src/domain/duration.d.ts +63 -0
  102. package/dist-package/packages/runtime/src/domain/editing.d.ts +227 -0
  103. package/dist-package/packages/runtime/src/domain/incremental-sync.d.ts +67 -0
  104. package/dist-package/packages/runtime/src/domain/index.d.ts +14 -0
  105. package/dist-package/packages/runtime/src/domain/media.d.ts +406 -0
  106. package/dist-package/packages/runtime/src/domain/ports.d.ts +62 -0
  107. package/dist-package/packages/runtime/src/domain/primitives.d.ts +21 -0
  108. package/dist-package/packages/runtime/src/domain/project.d.ts +119 -0
  109. package/dist-package/packages/runtime/src/domain/rough-cut.d.ts +27 -0
  110. package/dist-package/packages/runtime/src/domain/skills.d.ts +145 -0
  111. package/dist-package/packages/runtime/src/domain/timeline-target.d.ts +57 -0
  112. package/dist-package/packages/runtime/src/domain/timeline-target.js +19 -1
  113. package/dist-package/packages/runtime/src/domain/types.d.ts +5 -0
  114. package/dist-package/packages/runtime/src/domain/verification.d.ts +92 -0
  115. package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.d.ts +18 -0
  116. package/dist-package/packages/runtime/src/editing/duration-policy.d.ts +3 -0
  117. package/dist-package/packages/runtime/src/editing/edit-service.d.ts +44 -0
  118. package/dist-package/packages/runtime/src/editing/filler-removal-service.d.ts +23 -0
  119. package/dist-package/packages/runtime/src/editing/intent.d.ts +97 -0
  120. package/dist-package/packages/runtime/src/editing/music-service.d.ts +9 -0
  121. package/dist-package/packages/runtime/src/index.d.ts +32 -0
  122. package/dist-package/packages/runtime/src/index.js +1 -0
  123. package/dist-package/packages/runtime/src/planning/rough-cut.d.ts +3 -0
  124. package/dist-package/packages/runtime/src/render/render-and-verify.d.ts +71 -0
  125. package/dist-package/packages/runtime/src/render/render-contract.d.ts +96 -0
  126. package/dist-package/packages/runtime/src/runtime.d.ts +85 -0
  127. package/dist-package/packages/runtime/src/skills/builtin.d.ts +2 -0
  128. package/dist-package/packages/runtime/src/skills/index.d.ts +3 -0
  129. package/dist-package/packages/runtime/src/skills/registry.d.ts +10 -0
  130. package/dist-package/packages/runtime/src/skills/requirements.d.ts +38 -0
  131. package/dist-package/packages/runtime/src/skills/runtime.d.ts +38 -0
  132. package/dist-package/packages/runtime/src/speech/analysis.d.ts +18 -0
  133. package/dist-package/packages/runtime/src/speech/analysis.js +67 -0
  134. package/dist-package/packages/runtime/src/speech/filler-detector.d.ts +49 -0
  135. package/dist-package/packages/runtime/src/speech/filler-removal.d.ts +37 -0
  136. package/dist-package/packages/runtime/src/speech/mapping.d.ts +56 -0
  137. package/dist-package/packages/runtime/src/speech/mapping.js +27 -4
  138. package/dist-package/packages/runtime/src/speech/safe-cut-resolver.d.ts +52 -0
  139. package/dist-package/packages/runtime/src/timeline/drift-reconciliation.d.ts +42 -0
  140. package/dist-package/packages/runtime/src/timeline/editing-session.d.ts +271 -0
  141. package/dist-package/packages/runtime/src/timeline/editing-session.js +32 -2
  142. package/dist-package/packages/runtime/src/timeline/fast-observation.d.ts +77 -0
  143. package/dist-package/packages/runtime/src/timeline/rational-time.d.ts +11 -0
  144. package/dist-package/packages/runtime/src/timeline/reorder-preview.d.ts +32 -0
  145. package/dist-package/packages/runtime/src/timeline/reorder-preview.js +202 -0
  146. package/dist-package/packages/runtime/src/timeline/snapshot-diff.d.ts +3 -0
  147. package/dist-package/packages/runtime/src/timeline/snapshot-diff.js +1 -0
  148. package/dist-package/packages/runtime/src/timeline/snapshot-digest.d.ts +3 -0
  149. package/dist-package/packages/runtime/src/timeline/snapshot-digest.js +1 -1
  150. package/dist-package/packages/runtime/src/verification/verification.d.ts +6 -0
  151. package/dist-package/packages/testkit/src/fixture-analyzers.d.ts +37 -0
  152. package/dist-package/packages/testkit/src/in-memory-editor.d.ts +55 -0
  153. package/dist-package/packages/testkit/src/index.d.ts +4 -0
  154. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.d.ts +47 -0
  155. package/dist-package/packages/testkit/src/skill-fixtures.d.ts +3 -0
  156. package/package.json +17 -12
@@ -0,0 +1,15 @@
1
+ import type { FramekitRenderPlan, FramekitRenderProviderResult, FramekitRenderVerificationResult, FramekitRenderArtifactVerifier } from "../../../../packages/runtime/src/index.js";
2
+ export interface FfmpegRenderVerifierOptions {
3
+ ffprobePath?: string;
4
+ durationToleranceSeconds?: number;
5
+ env?: NodeJS.ProcessEnv;
6
+ }
7
+ /** Independently verifies the committed output; it does not trust provider metadata. */
8
+ export declare class FfmpegRenderVerifier implements FramekitRenderArtifactVerifier {
9
+ private readonly ffprobePath;
10
+ private readonly durationToleranceSeconds?;
11
+ private readonly environment;
12
+ constructor(options?: FfmpegRenderVerifierOptions);
13
+ verify(plan: FramekitRenderPlan, result: FramekitRenderProviderResult): Promise<FramekitRenderVerificationResult>;
14
+ private probe;
15
+ }
@@ -0,0 +1,3 @@
1
+ export * from "./ffmpeg-renderer.js";
2
+ export * from "./ffmpeg-verifier.js";
3
+ export * from "./ffmpeg-media-probe.js";
@@ -0,0 +1,25 @@
1
+ export type DevDoctorProfile = "fixture" | "headless" | "native";
2
+ export type DevDoctorStatus = "pass" | "fail" | "unavailable";
3
+ export interface DevDoctorCheck {
4
+ name: string;
5
+ requirement: "required" | "optional";
6
+ status: DevDoctorStatus;
7
+ message: string;
8
+ path?: string;
9
+ }
10
+ export interface DevDoctorReport {
11
+ profile: DevDoctorProfile;
12
+ ready: boolean;
13
+ checks: DevDoctorCheck[];
14
+ }
15
+ export interface CollectDevDoctorOptions {
16
+ profile: DevDoctorProfile;
17
+ rootDirectory: string;
18
+ environment?: NodeJS.ProcessEnv;
19
+ homeDirectory?: string;
20
+ nodeVersion?: string;
21
+ platform?: NodeJS.Platform;
22
+ runCommand?: (command: string, args: string[]) => Promise<string>;
23
+ isPathWritable?: (path: string) => Promise<boolean>;
24
+ }
25
+ export declare function collectDevDoctorReport(options: CollectDevDoctorOptions): Promise<DevDoctorReport>;
@@ -0,0 +1,3 @@
1
+ import { type HeadlessProjectServiceOptions, type HeadlessProjectWorkflow } from "../../../packages/headless-application/src/index.js";
2
+ /** Creates the shared headless workflow for CLI-owned operations. */
3
+ export declare function createCliHeadlessProjectService(options: HeadlessProjectServiceOptions): HeadlessProjectWorkflow;
@@ -0,0 +1,10 @@
1
+ import { spawn } from "node:child_process";
2
+ import { FinalCutConnectionManager } from "../../../adapters/final-cut/typescript/src/index.js";
3
+ type StatusOutput = Pick<NodeJS.WriteStream, "write">;
4
+ export interface McpStartupDependencies {
5
+ connectDevelopmentExtension?: (args: string[], output: StatusOutput) => Promise<ReturnType<FinalCutConnectionManager["getStatus"]>>;
6
+ spawnChild?: typeof spawn;
7
+ stderr?: StatusOutput;
8
+ }
9
+ export declare function runMcp(args: string[], dependencies?: McpStartupDependencies): Promise<void>;
10
+ export {};
@@ -0,0 +1,129 @@
1
+ #!/usr/bin/env python3
2
+ """Measure source audio through Framekit's optional JSON command protocol."""
3
+
4
+ import json
5
+ import math
6
+ import os
7
+ from pathlib import Path
8
+ import re
9
+ import subprocess
10
+ import sys
11
+ import tempfile
12
+
13
+
14
+ def fail(code: str, message: str) -> None:
15
+ print(f"{code}: {message}", file=sys.stderr)
16
+ raise SystemExit(78)
17
+
18
+
19
+ def number(value: object) -> float:
20
+ if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
21
+ fail("AUDIO_REQUEST_INVALID", "range coordinates must be finite numbers")
22
+ return float(value)
23
+
24
+
25
+ def run(args: list[str], code: str) -> subprocess.CompletedProcess:
26
+ try:
27
+ return subprocess.run(args, capture_output=True, text=True, check=True, timeout=45,
28
+ env={**os.environ, "LC_ALL": "C"})
29
+ except (OSError, subprocess.SubprocessError):
30
+ fail(code, "required local media tool failed or exceeded its deadline")
31
+ raise AssertionError("unreachable")
32
+
33
+
34
+ def sample_coordinate(seconds: float, rate: int, start: bool) -> int:
35
+ samples = seconds * rate
36
+ if not math.isfinite(samples) or samples > 2**53 - 1:
37
+ fail("AUDIO_REQUEST_INVALID", "range exceeds supported sample coordinates")
38
+ nearest = round(samples)
39
+ inward = nearest / rate >= seconds if start else nearest / rate <= seconds
40
+ if abs(samples - nearest) < 1e-7 and inward:
41
+ return nearest
42
+ return math.ceil(samples) if start else math.floor(samples)
43
+
44
+
45
+ def main() -> None:
46
+ try:
47
+ request = json.load(sys.stdin)
48
+ except (ValueError, TypeError):
49
+ fail("AUDIO_REQUEST_INVALID", "expected one JSON request")
50
+ if not isinstance(request, dict) or not isinstance(request.get("media"), dict):
51
+ fail("AUDIO_REQUEST_INVALID", "media is required")
52
+ if request.get("occurrenceId") is not None:
53
+ fail("AUDIO_SCOPE_UNAVAILABLE", "this backend measures source audio, not an occurrence or editor output")
54
+ requested = request.get("range")
55
+ if requested is not None:
56
+ if not isinstance(requested, dict):
57
+ fail("AUDIO_REQUEST_INVALID", "range must be an object")
58
+ start, end = number(requested.get("start")), number(requested.get("end"))
59
+ if start < 0 or end <= start:
60
+ fail("AUDIO_REQUEST_INVALID", "range must be nonnegative and positive in duration")
61
+ source = request["media"].get("source")
62
+ if not isinstance(source, str) or not os.path.isfile(source):
63
+ fail("AUDIO_SOURCE_UNAVAILABLE", "a readable local source file is required")
64
+ probe = run(["ffprobe", "-v", "error", "-select_streams", "a", "-show_streams", "-show_format", "-of", "json", source],
65
+ "AUDIO_SOURCE_UNAVAILABLE")
66
+ try:
67
+ metadata = json.loads(probe.stdout)
68
+ streams = metadata["streams"]
69
+ if not isinstance(streams, list) or len(streams) != 1:
70
+ raise ValueError("ambiguous audio streams")
71
+ audio = streams[0]
72
+ rate, channels = int(audio["sample_rate"]), audio["channels"]
73
+ if audio.get("codec_type") != "audio" or rate <= 0 or isinstance(channels, bool) or channels not in (1, 2):
74
+ raise ValueError("unsupported format")
75
+ offset = float(audio.get("start_time", 0))
76
+ if not math.isfinite(offset) or abs(offset) > 1e-9:
77
+ raise ValueError("source offset is not supported")
78
+ layout = audio.get("channel_layout")
79
+ if layout is not None and layout not in ("mono" if channels == 1 else "stereo", "unknown"):
80
+ raise ValueError("unsupported channel layout")
81
+ if requested is None:
82
+ start = 0.0
83
+ end = float(audio.get("duration", metadata.get("format", {}).get("duration")))
84
+ if not math.isfinite(end) or end <= 0:
85
+ raise ValueError("unknown source duration")
86
+ except (ValueError, TypeError, KeyError):
87
+ fail("AUDIO_SOURCE_UNAVAILABLE", "expected one mono/stereo audio stream with supported source timing")
88
+ first, last = sample_coordinate(start, rate, True), sample_coordinate(end, rate, False)
89
+ count = last - first
90
+ if count / rate < 0.4:
91
+ fail("AUDIO_MEASUREMENT_UNAVAILABLE", "at least 400 ms of sample-aligned signal is required")
92
+ with tempfile.TemporaryDirectory(prefix="framekit-source-meter-") as temporary:
93
+ pcm = Path(temporary) / "source.f32le"
94
+ run(["ffmpeg", "-hide_banner", "-nostdin", "-loglevel", "error", "-i", source,
95
+ "-map", "0:a:0", "-vn", "-af", f"atrim=start_sample={first}:end_sample={last},asetpts=PTS-STARTPTS",
96
+ "-ar", str(rate), "-ac", str(channels), "-c:a", "pcm_f32le", "-f", "f32le", "-y", str(pcm)],
97
+ "AUDIO_MEASUREMENT_UNAVAILABLE")
98
+ if pcm.stat().st_size != count * channels * 4:
99
+ fail("AUDIO_MEASUREMENT_UNAVAILABLE", "decoded samples do not cover the requested source interval")
100
+ measured = run(["ffmpeg", "-hide_banner", "-nostdin", "-loglevel", "info", "-f", "f32le",
101
+ "-ar", str(rate), "-ac", str(channels), "-i", str(pcm), "-af",
102
+ "silencedetect=noise=-60dB:d=0.1,ebur128=peak=true:framelog=verbose", "-f", "null", "-"],
103
+ "AUDIO_MEASUREMENT_UNAVAILABLE").stderr
104
+ summary = measured[measured.rfind("Summary:"):]
105
+ try:
106
+ integrated = float(re.search(r"Integrated loudness:\s+I:\s+(\S+)\s+LUFS", summary)[1])
107
+ peak = float(re.search(r"True peak:\s+Peak:\s+(\S+)\s+dBFS", summary)[1])
108
+ silence = sum(float(value) * 1000 for value in re.findall(r"silence_duration:\s*(\S+)", measured))
109
+ if not all(math.isfinite(value) for value in (integrated, peak, silence)) or integrated <= -70 or not 0 <= silence <= count / rate * 1000 + 1:
110
+ raise ValueError("unavailable metrics")
111
+ except (ValueError, TypeError):
112
+ fail("AUDIO_MEASUREMENT_UNAVAILABLE", "signal is silent, below the loudness gate or lacks a valid measurement summary")
113
+ result = {
114
+ "signalScope": "source", "integratedLufs": integrated, "truePeakDb": peak, "silenceMs": silence,
115
+ "sourceTimebase": {"value": "1", "timescale": str(rate)},
116
+ "signalFormat": {"sampleRate": rate, "channels": channels},
117
+ "requestedRange": {"start": start, "end": end},
118
+ "measuredRange": {"start": first / rate, "end": last / rate,
119
+ "startTime": {"value": str(first), "timescale": str(rate)},
120
+ "durationTime": {"value": str(count), "timescale": str(rate)}},
121
+ "analyzedDurationSeconds": count / rate,
122
+ }
123
+ if layout in ("mono", "stereo"):
124
+ result["signalFormat"]["channelLayout"] = layout
125
+ print(json.dumps(result, separators=(",", ":"), allow_nan=False))
126
+
127
+
128
+ if __name__ == "__main__":
129
+ main()
@@ -7,10 +7,12 @@ the model with FRAMEKIT_WHISPER_MODEL.
7
7
  """
8
8
 
9
9
  import importlib
10
+ import hashlib
10
11
  import json
11
12
  import math
12
13
  import os
13
14
  import sys
15
+ import subprocess
14
16
  from typing import Any
15
17
 
16
18
 
@@ -151,6 +153,70 @@ def normalized_words(result: dict[str, Any], requested: dict[str, Any] | None) -
151
153
  return entries
152
154
 
153
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
+
154
220
  def main() -> None:
155
221
  request = read_request()
156
222
  media = required_record(request.get("media"), "media")
@@ -168,12 +234,36 @@ def main() -> None:
168
234
  if start < 0 or end <= start:
169
235
  fail(65, "WHISPER_REQUEST_INVALID: range boundaries are invalid")
170
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
171
247
  module_label, module = load_backend()
172
248
  result = transcribe(module_label, module, source)
173
249
  output = {
174
- "words": normalized_words(result, requested),
175
- "sourceTimebase": {"value": "1", "timescale": "1000"},
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"},
176
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
177
267
  print(json.dumps(output, separators=(",", ":")))
178
268
 
179
269
 
@@ -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.2.2",
4
- "commit": "3af4f3f6cc6b31ddb309c9a32f62d9d4de6bc9fd"
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,5 @@
1
+ export declare function shouldConfigureFinalCutProjectPublisher(input: {
2
+ liveMode: boolean;
3
+ fcpxmlPath: string | undefined;
4
+ canonicalNativeProviderEnabled: boolean;
5
+ }): boolean;
@@ -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 {};
@@ -0,0 +1,204 @@
1
+ import { type TimelineIr } from "../../../packages/runtime/src/index.js";
2
+ import { type FileCanonicalRecoveryGuard, type TimelineIrMaterializationCoverage, type TimelineIrMaterializationProvenance, type TimelineIrToFcpxmlResult, type TimelineIrToFcpxmlTarget } from "../../../adapters/final-cut/typescript/src/index.js";
3
+ import { EditingSessionRepository } from "./headless-sessions.js";
4
+ export interface SessionMaterializationPublishRequest {
5
+ jobId: string;
6
+ artifactPath: string;
7
+ artifactDigest: string;
8
+ target: TimelineIrToFcpxmlTarget;
9
+ destination: TimelineIrToFcpxmlResult["destination"];
10
+ collisionPolicy: "create-only";
11
+ desired: TimelineIr;
12
+ desiredDigest: string;
13
+ baseDigest: string;
14
+ baseRevision: TimelineIr["revision"];
15
+ coverage: TimelineIrMaterializationCoverage;
16
+ provenance: TimelineIrMaterializationProvenance;
17
+ }
18
+ export type MaterializationVerificationTier = "artifact" | "delivery" | "storage-observed" | "canonical-verified" | "interaction-required";
19
+ export type MaterializationDeliveryState = "background" | "activated" | "prompted" | "failed" | "interaction-required";
20
+ export interface MaterializationDeliveryEvidence {
21
+ state: MaterializationDeliveryState;
22
+ route: "background" | "headed" | "unknown";
23
+ }
24
+ export interface MaterializationStructuralDiff {
25
+ target: {
26
+ projectId: string;
27
+ sequenceId: string;
28
+ };
29
+ desiredDigest: string;
30
+ actualDigest: string;
31
+ changes: Array<{
32
+ path: string;
33
+ before?: unknown;
34
+ after?: unknown;
35
+ }>;
36
+ }
37
+ export interface MaterializationVerification {
38
+ tier: MaterializationVerificationTier;
39
+ status: "verified" | "blocked" | "failed";
40
+ artifactDigest: string;
41
+ desiredDigest: string;
42
+ reason?: string;
43
+ canonicalReadbackDigest?: string;
44
+ canonicalTarget?: {
45
+ libraryUid: string;
46
+ eventUid: string;
47
+ projectUid: string;
48
+ sequenceUid: string;
49
+ };
50
+ structuralDiff?: MaterializationStructuralDiff;
51
+ delivery?: MaterializationDeliveryEvidence;
52
+ }
53
+ export interface SessionMaterializationPublisher {
54
+ trackNativeDispatch?<T>(operation: () => Promise<T>, onDispatch: () => void): Promise<T>;
55
+ readCanonicalTarget?(request: {
56
+ target: {
57
+ libraryUid: string;
58
+ eventUid: string;
59
+ projectUid: string;
60
+ sequenceUid: string;
61
+ };
62
+ }): Promise<{
63
+ canonicalReadback: TimelineIr;
64
+ canonicalTarget: {
65
+ libraryUid: string;
66
+ eventUid: string;
67
+ projectUid: string;
68
+ sequenceUid: string;
69
+ };
70
+ delivery?: MaterializationDeliveryEvidence;
71
+ }>;
72
+ publish(request: SessionMaterializationPublishRequest): Promise<{
73
+ state: "completed";
74
+ canonicalReadback: TimelineIr;
75
+ canonicalTarget: {
76
+ libraryUid: string;
77
+ eventUid: string;
78
+ projectUid: string;
79
+ sequenceUid: string;
80
+ };
81
+ headedNativeVerified: boolean;
82
+ delivery?: MaterializationDeliveryEvidence;
83
+ } | {
84
+ state: "blocked";
85
+ code: string;
86
+ message: string;
87
+ retryable: boolean;
88
+ delivery?: MaterializationDeliveryEvidence;
89
+ }>;
90
+ }
91
+ export interface SessionMaterializationJob {
92
+ schemaVersion: 1 | 2;
93
+ jobId: string;
94
+ sessionId: string;
95
+ state: "blocked" | "publishing" | "completed" | "failed";
96
+ nextAction: "retry" | "status" | "none";
97
+ artifactPath: string;
98
+ artifactDigest: string;
99
+ target: TimelineIrToFcpxmlTarget;
100
+ destination: TimelineIrToFcpxmlResult["destination"];
101
+ desired: TimelineIr;
102
+ desiredDigest: string;
103
+ baseDigest: string;
104
+ baseRevision: TimelineIr["revision"];
105
+ coverage?: TimelineIrMaterializationCoverage;
106
+ provenance?: TimelineIrMaterializationProvenance;
107
+ verification?: MaterializationVerification;
108
+ continuation?: {
109
+ state: "canonical-resync-required" | "resynced";
110
+ reason: string;
111
+ sessionId?: string;
112
+ readbackDigest?: string;
113
+ changeSinceHandoff?: "changed" | "unchanged" | "unknown";
114
+ delivery?: MaterializationDeliveryEvidence;
115
+ };
116
+ sessionDigest: string;
117
+ claim?: {
118
+ id: string;
119
+ claimedAt: string;
120
+ };
121
+ recoveryReservation?: {
122
+ reservationId: string;
123
+ reason: "native-quiescence-unproven";
124
+ };
125
+ providerError?: {
126
+ code: string;
127
+ message: string;
128
+ retryable: boolean;
129
+ };
130
+ providerRequestPhase?: "dispatch-intent" | "returned";
131
+ evidence: {
132
+ artifact: {
133
+ verified: true;
134
+ format: "fcpxml";
135
+ digest: string;
136
+ };
137
+ providerRequested: boolean;
138
+ canonicalReadback: boolean;
139
+ headedNative: boolean;
140
+ };
141
+ error?: {
142
+ code: string;
143
+ message: string;
144
+ retryable: boolean;
145
+ };
146
+ }
147
+ export declare class SessionMaterializationJobs {
148
+ private readonly directory;
149
+ private readonly sessions;
150
+ private readonly publisher?;
151
+ private readonly recoveryGuard?;
152
+ constructor(directory: string, sessions: EditingSessionRepository, publisher?: SessionMaterializationPublisher | undefined, recoveryGuard?: Pick<FileCanonicalRecoveryGuard, "beginNative"> | undefined);
153
+ preview(sessionId: string, target: TimelineIrToFcpxmlTarget): Promise<{
154
+ sessionId: string;
155
+ mutating: boolean;
156
+ sessionState: import("../../../packages/runtime/src/index.js").EditingSessionState;
157
+ target: TimelineIrToFcpxmlTarget;
158
+ destination: {
159
+ mode: "versioned" | "reuse-existing";
160
+ projectUid: string;
161
+ sequenceUid: string;
162
+ projectName: string;
163
+ sequenceName: string;
164
+ };
165
+ collisionPolicy: string;
166
+ artifactDigest: string;
167
+ coverage: TimelineIrMaterializationCoverage;
168
+ provenance: TimelineIrMaterializationProvenance;
169
+ evidence: {
170
+ artifact: {
171
+ verified: boolean;
172
+ format: "fcpxml";
173
+ digest: string;
174
+ };
175
+ };
176
+ }>;
177
+ execute(sessionId: string, target: TimelineIrToFcpxmlTarget, confirm: boolean): Promise<SessionMaterializationJob>;
178
+ status(jobId: string): Promise<SessionMaterializationJob>;
179
+ retry(jobId: string): Promise<SessionMaterializationJob>;
180
+ resync(jobId: string, sessionId: string): Promise<{
181
+ jobId: string;
182
+ state: "resynced";
183
+ sessionId: string;
184
+ changeSinceHandoff: "changed" | "unchanged" | "unknown";
185
+ canonicalTarget: {
186
+ libraryUid: string;
187
+ eventUid: string;
188
+ projectUid: string;
189
+ sequenceUid: string;
190
+ };
191
+ readbackDigest: string;
192
+ document: import("../../../packages/runtime/src/index.js").EditingSessionDocument;
193
+ delivery?: MaterializationDeliveryEvidence | undefined;
194
+ }>;
195
+ private attempt;
196
+ private validateStagedJob;
197
+ private claim;
198
+ private release;
199
+ private fail;
200
+ private save;
201
+ private jobPath;
202
+ private claimPath;
203
+ private assertProvider;
204
+ }