@morshoto/framekit 0.2.2 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (160) hide show
  1. package/dist-package/adapters/final-cut/typescript/src/analyzers.d.ts +58 -0
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +52 -13
  3. package/dist-package/adapters/final-cut/typescript/src/assets.d.ts +24 -0
  4. package/dist-package/adapters/final-cut/typescript/src/background-export.d.ts +98 -0
  5. package/dist-package/adapters/final-cut/typescript/src/background-materialization.d.ts +47 -0
  6. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.d.ts +32 -0
  7. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.d.ts +22 -0
  8. package/dist-package/adapters/final-cut/typescript/src/canonical-verification.d.ts +11 -0
  9. package/dist-package/adapters/final-cut/typescript/src/canonical.d.ts +184 -0
  10. package/dist-package/adapters/final-cut/typescript/src/canonical.js +33 -1
  11. package/dist-package/adapters/final-cut/typescript/src/connection.d.ts +103 -0
  12. package/dist-package/adapters/final-cut/typescript/src/disposable-native.d.ts +90 -0
  13. package/dist-package/adapters/final-cut/typescript/src/documents.d.ts +3 -0
  14. package/dist-package/adapters/final-cut/typescript/src/documents.js +3 -0
  15. package/dist-package/adapters/final-cut/typescript/src/experimental.d.ts +8 -0
  16. package/dist-package/adapters/final-cut/typescript/src/export.d.ts +125 -0
  17. package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.d.ts +54 -0
  18. package/dist-package/adapters/final-cut/typescript/src/fcpxml.d.ts +75 -0
  19. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +6 -1
  20. package/dist-package/adapters/final-cut/typescript/src/index.d.ts +22 -0
  21. package/dist-package/adapters/final-cut/typescript/src/library-inspection.d.ts +101 -0
  22. package/dist-package/adapters/final-cut/typescript/src/live.d.ts +101 -0
  23. package/dist-package/adapters/final-cut/typescript/src/live.js +8 -0
  24. package/dist-package/adapters/final-cut/typescript/src/media.d.ts +12 -0
  25. package/dist-package/adapters/final-cut/typescript/src/native-operation.d.ts +6 -0
  26. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.d.ts +77 -0
  27. package/dist-package/adapters/final-cut/typescript/src/native-session.d.ts +130 -0
  28. package/dist-package/adapters/final-cut/typescript/src/native.d.ts +828 -0
  29. package/dist-package/adapters/final-cut/typescript/src/native.js +274 -107
  30. package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.d.ts +114 -0
  31. package/dist-package/adapters/final-cut/typescript/src/publish-readback.d.ts +26 -0
  32. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +18 -2
  33. package/dist-package/adapters/final-cut/typescript/src/publisher.d.ts +215 -0
  34. package/dist-package/adapters/final-cut/typescript/src/session.d.ts +43 -0
  35. package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.d.ts +51 -0
  36. package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.d.ts +156 -0
  37. package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.d.ts +134 -0
  38. package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.d.ts +110 -0
  39. package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.d.ts +132 -0
  40. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.d.ts +61 -0
  41. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +28 -4
  42. package/dist-package/adapters/final-cut/typescript/src/unattended-editing.d.ts +54 -0
  43. package/dist-package/adapters/headless/typescript/src/audio-output.d.ts +3 -0
  44. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.d.ts +11 -0
  45. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +26 -2
  46. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.d.ts +27 -0
  47. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +7 -2
  48. package/dist-package/adapters/headless/typescript/src/ffmpeg-storyboard.d.ts +28 -0
  49. package/dist-package/adapters/headless/typescript/src/ffmpeg-storyboard.js +120 -0
  50. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.d.ts +15 -0
  51. package/dist-package/adapters/headless/typescript/src/index.d.ts +4 -0
  52. package/dist-package/adapters/headless/typescript/src/index.js +1 -0
  53. package/dist-package/apps/cli/src/dev-doctor.d.ts +25 -0
  54. package/dist-package/apps/cli/src/headless-projects.d.ts +3 -0
  55. package/dist-package/apps/cli/src/main.d.ts +10 -0
  56. package/dist-package/apps/mcp-server/runtime/ffmpeg-audio-backend.py +129 -0
  57. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +92 -2
  58. package/dist-package/apps/mcp-server/src/build-alignment.d.ts +10 -0
  59. package/dist-package/apps/mcp-server/src/build-identity.d.ts +7 -0
  60. package/dist-package/apps/mcp-server/src/build-identity.json +2 -2
  61. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.d.ts +8 -0
  62. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.d.ts +5 -0
  63. package/dist-package/apps/mcp-server/src/headless-project-snapshot.d.ts +3 -0
  64. package/dist-package/apps/mcp-server/src/headless-sessions.d.ts +89 -0
  65. package/dist-package/apps/mcp-server/src/main.d.ts +1 -0
  66. package/dist-package/apps/mcp-server/src/main.js +2 -1
  67. package/dist-package/apps/mcp-server/src/materialization-jobs.d.ts +204 -0
  68. package/dist-package/apps/mcp-server/src/readback-policy.d.ts +18 -0
  69. package/dist-package/apps/mcp-server/src/routing.d.ts +90 -0
  70. package/dist-package/apps/mcp-server/src/server.d.ts +75 -0
  71. package/dist-package/apps/mcp-server/src/server.js +93 -9
  72. package/dist-package/apps/mcp-server/src/tools/skills/catalog.d.ts +19 -0
  73. package/dist-package/apps/mcp-server/src/tools/skills/metadata.d.ts +37 -0
  74. package/dist-package/apps/mcp-server/src/tools/skills/register.d.ts +11 -0
  75. package/dist-package/apps/mcp-server/src/version.d.ts +4 -0
  76. package/dist-package/packages/headless-application/src/external-edit.d.ts +30 -0
  77. package/dist-package/packages/headless-application/src/external-edit.js +72 -0
  78. package/dist-package/packages/headless-application/src/headless-projects.d.ts +259 -0
  79. package/dist-package/packages/headless-application/src/headless-projects.js +15 -2
  80. package/dist-package/packages/headless-application/src/index.d.ts +2 -0
  81. package/dist-package/packages/headless-application/src/index.js +1 -0
  82. package/dist-package/packages/runtime/src/application/duration-policy-service.d.ts +4 -0
  83. package/dist-package/packages/runtime/src/application/local-media.d.ts +46 -0
  84. package/dist-package/packages/runtime/src/application/media-analysis-service.d.ts +40 -0
  85. package/dist-package/packages/runtime/src/application/media-analysis-service.js +105 -15
  86. package/dist-package/packages/runtime/src/application/project-service.d.ts +35 -0
  87. package/dist-package/packages/runtime/src/application/project-store.d.ts +56 -0
  88. package/dist-package/packages/runtime/src/application/project-transactions.d.ts +51 -0
  89. package/dist-package/packages/runtime/src/application/runtime-options.d.ts +15 -0
  90. package/dist-package/packages/runtime/src/application/semantic-media-index-store.d.ts +28 -0
  91. package/dist-package/packages/runtime/src/application/transaction-store.d.ts +10 -0
  92. package/dist-package/packages/runtime/src/audio/analysis.d.ts +3 -0
  93. package/dist-package/packages/runtime/src/audio/analysis.js +95 -0
  94. package/dist-package/packages/runtime/src/audio/dialogue-normalization.d.ts +47 -0
  95. package/dist-package/packages/runtime/src/audio/noise-reduction.d.ts +34 -0
  96. package/dist-package/packages/runtime/src/capabilities.d.ts +45 -0
  97. package/dist-package/packages/runtime/src/color-correction.d.ts +33 -0
  98. package/dist-package/packages/runtime/src/context/context-engine.d.ts +28 -0
  99. package/dist-package/packages/runtime/src/context/context-service.d.ts +20 -0
  100. package/dist-package/packages/runtime/src/context/project-catalog.d.ts +12 -0
  101. package/dist-package/packages/runtime/src/context/revision.d.ts +2 -0
  102. package/dist-package/packages/runtime/src/domain/capabilities.d.ts +170 -0
  103. package/dist-package/packages/runtime/src/domain/context.d.ts +179 -0
  104. package/dist-package/packages/runtime/src/domain/diff.d.ts +104 -0
  105. package/dist-package/packages/runtime/src/domain/duration.d.ts +63 -0
  106. package/dist-package/packages/runtime/src/domain/editing.d.ts +227 -0
  107. package/dist-package/packages/runtime/src/domain/incremental-sync.d.ts +67 -0
  108. package/dist-package/packages/runtime/src/domain/index.d.ts +14 -0
  109. package/dist-package/packages/runtime/src/domain/media.d.ts +406 -0
  110. package/dist-package/packages/runtime/src/domain/ports.d.ts +62 -0
  111. package/dist-package/packages/runtime/src/domain/primitives.d.ts +21 -0
  112. package/dist-package/packages/runtime/src/domain/project.d.ts +119 -0
  113. package/dist-package/packages/runtime/src/domain/rough-cut.d.ts +27 -0
  114. package/dist-package/packages/runtime/src/domain/skills.d.ts +145 -0
  115. package/dist-package/packages/runtime/src/domain/timeline-target.d.ts +57 -0
  116. package/dist-package/packages/runtime/src/domain/timeline-target.js +19 -1
  117. package/dist-package/packages/runtime/src/domain/types.d.ts +5 -0
  118. package/dist-package/packages/runtime/src/domain/verification.d.ts +92 -0
  119. package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.d.ts +18 -0
  120. package/dist-package/packages/runtime/src/editing/duration-policy.d.ts +3 -0
  121. package/dist-package/packages/runtime/src/editing/edit-service.d.ts +44 -0
  122. package/dist-package/packages/runtime/src/editing/filler-removal-service.d.ts +23 -0
  123. package/dist-package/packages/runtime/src/editing/intent.d.ts +97 -0
  124. package/dist-package/packages/runtime/src/editing/music-service.d.ts +9 -0
  125. package/dist-package/packages/runtime/src/index.d.ts +32 -0
  126. package/dist-package/packages/runtime/src/index.js +1 -0
  127. package/dist-package/packages/runtime/src/planning/rough-cut.d.ts +3 -0
  128. package/dist-package/packages/runtime/src/render/render-and-verify.d.ts +71 -0
  129. package/dist-package/packages/runtime/src/render/render-contract.d.ts +96 -0
  130. package/dist-package/packages/runtime/src/runtime.d.ts +85 -0
  131. package/dist-package/packages/runtime/src/skills/builtin.d.ts +2 -0
  132. package/dist-package/packages/runtime/src/skills/index.d.ts +3 -0
  133. package/dist-package/packages/runtime/src/skills/registry.d.ts +10 -0
  134. package/dist-package/packages/runtime/src/skills/requirements.d.ts +38 -0
  135. package/dist-package/packages/runtime/src/skills/runtime.d.ts +38 -0
  136. package/dist-package/packages/runtime/src/speech/analysis.d.ts +18 -0
  137. package/dist-package/packages/runtime/src/speech/analysis.js +67 -0
  138. package/dist-package/packages/runtime/src/speech/filler-detector.d.ts +49 -0
  139. package/dist-package/packages/runtime/src/speech/filler-removal.d.ts +37 -0
  140. package/dist-package/packages/runtime/src/speech/mapping.d.ts +56 -0
  141. package/dist-package/packages/runtime/src/speech/mapping.js +27 -4
  142. package/dist-package/packages/runtime/src/speech/safe-cut-resolver.d.ts +52 -0
  143. package/dist-package/packages/runtime/src/timeline/drift-reconciliation.d.ts +42 -0
  144. package/dist-package/packages/runtime/src/timeline/editing-session.d.ts +271 -0
  145. package/dist-package/packages/runtime/src/timeline/editing-session.js +32 -2
  146. package/dist-package/packages/runtime/src/timeline/fast-observation.d.ts +77 -0
  147. package/dist-package/packages/runtime/src/timeline/rational-time.d.ts +11 -0
  148. package/dist-package/packages/runtime/src/timeline/reorder-preview.d.ts +32 -0
  149. package/dist-package/packages/runtime/src/timeline/reorder-preview.js +202 -0
  150. package/dist-package/packages/runtime/src/timeline/snapshot-diff.d.ts +3 -0
  151. package/dist-package/packages/runtime/src/timeline/snapshot-diff.js +1 -0
  152. package/dist-package/packages/runtime/src/timeline/snapshot-digest.d.ts +3 -0
  153. package/dist-package/packages/runtime/src/timeline/snapshot-digest.js +1 -1
  154. package/dist-package/packages/runtime/src/verification/verification.d.ts +6 -0
  155. package/dist-package/packages/testkit/src/fixture-analyzers.d.ts +37 -0
  156. package/dist-package/packages/testkit/src/in-memory-editor.d.ts +55 -0
  157. package/dist-package/packages/testkit/src/index.d.ts +4 -0
  158. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.d.ts +47 -0
  159. package/dist-package/packages/testkit/src/skill-fixtures.d.ts +3 -0
  160. package/package.json +17 -12
@@ -0,0 +1,49 @@
1
+ import type { SpeechAnalysis, SpeechWord } from "../domain/media.js";
2
+ import type { TimeRange } from "../domain/primitives.js";
3
+ export declare const DEFAULT_FILLER_VOCABULARY: readonly ["er", "erm", "hmm", "uh", "um"];
4
+ export declare const DEFAULT_FILLER_CONFIDENCE_THRESHOLD = 0.92;
5
+ export type FillerReasonCode = "ANALYZER_MARKED_FILLER" | "VOCABULARY_MATCH" | "BELOW_CONFIDENCE_THRESHOLD";
6
+ export interface FillerOccurrence {
7
+ occurrenceId: string;
8
+ mediaId?: string;
9
+ sourceRange: TimeRange;
10
+ sequenceRange: TimeRange;
11
+ }
12
+ export interface FillerDetectionInput {
13
+ previewId: string;
14
+ analysis: SpeechAnalysis;
15
+ targetRange: TimeRange;
16
+ occurrence: FillerOccurrence;
17
+ revisionId?: string;
18
+ }
19
+ export interface FillerDetectorOptions {
20
+ vocabulary?: readonly string[];
21
+ confidenceThreshold?: number;
22
+ }
23
+ export interface FillerCandidateEvidence {
24
+ word: SpeechWord;
25
+ analyzerMarkedFiller: boolean;
26
+ vocabularyMatch: boolean;
27
+ withinTarget: boolean;
28
+ }
29
+ export interface FillerCandidate {
30
+ id: string;
31
+ word: SpeechWord;
32
+ wordEvidence: SpeechWord;
33
+ confidence: number;
34
+ confidenceThreshold: number;
35
+ eligible: boolean;
36
+ occurrenceId: string;
37
+ mediaId?: string;
38
+ sourceRange: TimeRange;
39
+ sequenceRange: TimeRange;
40
+ reasonCodes: FillerReasonCode[];
41
+ evidence: FillerCandidateEvidence;
42
+ }
43
+ /** Turn analyzer speech evidence into deterministic, preview-scoped candidates. */
44
+ export declare class FillerDetector {
45
+ private readonly vocabulary;
46
+ private readonly confidenceThreshold;
47
+ constructor(options?: FillerDetectorOptions);
48
+ detect(input: FillerDetectionInput): FillerCandidate[];
49
+ }
@@ -0,0 +1,37 @@
1
+ import type { ContextRevision, TimeRange } from "../domain/primitives.js";
2
+ import type { EditOperation } from "../domain/editing.js";
3
+ import type { SpeechWord } from "../domain/media.js";
4
+ import type { TimelineDiff } from "../domain/diff.js";
5
+ export declare const DEFAULT_FILLER_CONFIDENCE = 0.92;
6
+ export declare const DEFAULT_PRESERVE_PAUSE_MS = 700;
7
+ export declare const DEFAULT_TARGET_PAUSE_MS = 500;
8
+ export interface FillerRemovalOptions {
9
+ confidenceThreshold?: number;
10
+ preservePauseMs?: number;
11
+ targetPauseMs?: number;
12
+ }
13
+ export interface FillerRemovalCandidate {
14
+ word: SpeechWord;
15
+ range: TimeRange;
16
+ }
17
+ export interface FillerRemovalRequest extends FillerRemovalOptions {
18
+ baseRevision: ContextRevision;
19
+ range: TimeRange;
20
+ }
21
+ export interface FillerRemovalTarget extends FillerRemovalCandidate {
22
+ clipId: string;
23
+ mediaId: string;
24
+ sourceRange: TimeRange;
25
+ }
26
+ export interface FillerRemovalPreview {
27
+ previewToken: string;
28
+ baseRevision: ContextRevision;
29
+ range: TimeRange;
30
+ candidates: FillerRemovalTarget[];
31
+ operations: EditOperation[];
32
+ expectedDiff?: TimelineDiff;
33
+ warnings: string[];
34
+ expiresAt: string;
35
+ }
36
+ /** Resolve transcript fillers into conservative, exact timeline ranges. */
37
+ export declare function planFillerRemoval(words: SpeechWord[], selectedRange: TimeRange, options?: FillerRemovalOptions): FillerRemovalCandidate[];
@@ -0,0 +1,56 @@
1
+ import type { RevisionBoundSpeechAnalysis, SpeechSegment, SpeechWord } from "../domain/media.js";
2
+ import type { ContextRevision, RationalTime, TimeRange } from "../domain/primitives.js";
3
+ export interface SpeechOccurrence {
4
+ occurrenceId: string;
5
+ mediaId: string;
6
+ revision: ContextRevision;
7
+ sourceRange: TimeRange;
8
+ sequenceRange: TimeRange;
9
+ /** Expected source clock for this occurrence when the editor exposes one. */
10
+ sourceTimebase?: RationalTime;
11
+ }
12
+ export interface SpeechMappingOptions {
13
+ sequenceFrameDuration: RationalTime;
14
+ }
15
+ export interface MappedSpeechWord {
16
+ word: SpeechWord;
17
+ sourceRange: TimeRange;
18
+ sequenceRange: TimeRange;
19
+ frameAlignedRange: TimeRange;
20
+ }
21
+ export interface MappedSpeechSegment {
22
+ segment: SpeechSegment;
23
+ sourceRange: TimeRange;
24
+ sequenceRange: TimeRange;
25
+ frameAlignedRange: TimeRange;
26
+ }
27
+ export type MappedVadCoverage = {
28
+ sourceRange: TimeRange;
29
+ sequenceRange: TimeRange;
30
+ status: "available";
31
+ segments: MappedSpeechSegment[];
32
+ } | {
33
+ sourceRange: TimeRange;
34
+ sequenceRange: TimeRange;
35
+ status: "unavailable";
36
+ reason: string;
37
+ };
38
+ export interface SpeechOccurrenceMapping {
39
+ occurrenceId: string;
40
+ mediaId: string;
41
+ revision: ContextRevision;
42
+ sourceRange: TimeRange;
43
+ sequenceRange: TimeRange;
44
+ sourceTimebase: RationalTime;
45
+ sequenceFrameDuration: RationalTime;
46
+ capability: RevisionBoundSpeechAnalysis["capability"];
47
+ words: MappedSpeechWord[];
48
+ vadSegments?: MappedSpeechSegment[];
49
+ vadCoverage?: MappedVadCoverage[];
50
+ silenceSegments?: MappedSpeechSegment[];
51
+ protectedSegments?: MappedSpeechSegment[];
52
+ }
53
+ /** Map validated source evidence onto one exact timeline occurrence. */
54
+ export declare function mapSpeechAnalysisToOccurrence(analysis: RevisionBoundSpeechAnalysis, occurrence: SpeechOccurrence, options: SpeechMappingOptions): SpeechOccurrenceMapping;
55
+ /** Map one source range onto an exact timeline occurrence. */
56
+ export declare function mapSourceRangeToSequenceRange(sourceRange: TimeRange, occurrence: Pick<SpeechOccurrence, "sourceRange" | "sequenceRange">): TimeRange;
@@ -1,4 +1,5 @@
1
1
  import { addRationalTimes, parseRational, subtractRationalTimes } from "../timeline/rational-time.js";
2
+ import { validateVadCoverage, validateVadCoverageConsistency } from "./analysis.js";
2
3
  /** Map validated source evidence onto one exact timeline occurrence. */
3
4
  export function mapSpeechAnalysisToOccurrence(analysis, occurrence, options) {
4
5
  validateOccurrence(occurrence);
@@ -25,6 +26,29 @@ export function mapSpeechAnalysisToOccurrence(analysis, occurrence, options) {
25
26
  throw new Error("AMBIGUOUS_MAPPING: source and sequence occurrence durations differ");
26
27
  }
27
28
  validateSequenceRationalRange(occurrence.sequenceRange);
29
+ const sourceCoverage = validateVadCoverage(analysis.vadCoverage, analysis.observedRange, analysis.sourceIdentity.duration);
30
+ validateVadCoverageConsistency(sourceCoverage, analysis.vadSegments, analysis.vadUnavailableReason, analysis.observedRange);
31
+ const vadCoverage = sourceCoverage?.flatMap((span) => {
32
+ const start = Math.max(span.start, occurrence.sourceRange.start);
33
+ const end = Math.min(span.end, occurrence.sourceRange.end);
34
+ if (start >= end)
35
+ return [];
36
+ const sourceRange = { start, end };
37
+ const sequenceRange = mapSourceRangeToSequenceRange(sourceRange, occurrence);
38
+ return span.status === "available"
39
+ ? [{ sourceRange, sequenceRange, status: "available", segments: mapEvidence(span.segments, occurrence, frame, "VAD segment", (segment) => segment) }]
40
+ : [{ sourceRange, sequenceRange, status: "unavailable", reason: span.reason }];
41
+ });
42
+ let cursor = occurrence.sourceRange.start;
43
+ const completeVad = vadCoverage !== undefined && vadCoverage.length > 0 && vadCoverage.every((span) => {
44
+ if (span.status !== "available" || span.sourceRange.start !== cursor)
45
+ return false;
46
+ cursor = span.sourceRange.end;
47
+ return true;
48
+ }) && cursor === occurrence.sourceRange.end;
49
+ const mappedVad = vadCoverage !== undefined
50
+ ? completeVad ? vadCoverage.flatMap((span) => span.status === "available" ? span.segments : []) : undefined
51
+ : analysis.vadSegments ? mapEvidence(analysis.vadSegments, occurrence, frame, "VAD segment", (segment) => segment) : undefined;
28
52
  return {
29
53
  occurrenceId: occurrence.occurrenceId,
30
54
  mediaId: occurrence.mediaId,
@@ -33,11 +57,10 @@ export function mapSpeechAnalysisToOccurrence(analysis, occurrence, options) {
33
57
  sequenceRange: structuredClone(occurrence.sequenceRange),
34
58
  sourceTimebase,
35
59
  sequenceFrameDuration: frame,
36
- capability: analysis.capability,
60
+ capability: vadCoverage !== undefined ? (completeVad ? "transcription-plus-vad" : "transcription-only") : analysis.capability,
37
61
  words: mapEvidence(analysis.words, occurrence, frame, "speech word", (word) => word),
38
- ...(analysis.vadSegments
39
- ? { vadSegments: mapEvidence(analysis.vadSegments, occurrence, frame, "VAD segment", (segment) => segment) }
40
- : {}),
62
+ ...(mappedVad ? { vadSegments: mappedVad } : {}),
63
+ ...(vadCoverage !== undefined ? { vadCoverage } : {}),
41
64
  ...(analysis.silenceSegments
42
65
  ? { silenceSegments: mapEvidence(analysis.silenceSegments, occurrence, frame, "silence segment", (segment) => segment) }
43
66
  : {}),
@@ -0,0 +1,52 @@
1
+ import type { SpeechAnalysis, SpeechSegment, SpeechWord } from "../domain/media.js";
2
+ import type { EditOperation } from "../domain/editing.js";
3
+ import type { RationalTime, TimeRange } from "../domain/primitives.js";
4
+ import type { FillerCandidate, FillerOccurrence } from "./filler-detector.js";
5
+ export declare const DEFAULT_SAFE_CUT_PRESERVE_PAUSE_MS = 700;
6
+ export declare const DEFAULT_SAFE_CUT_TARGET_PAUSE_MS = 500;
7
+ export type SafeCutStatus = "AUTO_APPLY" | "SUGGESTED" | "SKIPPED";
8
+ export type SafeCutReasonCode = "SAFE_BOUNDARY_RESOLVED" | "PAUSE_PRESERVED" | "LOW_CONFIDENCE" | "MISSING_VAD_EVIDENCE" | "INVALID_VAD_EVIDENCE" | "INVALID_SILENCE_EVIDENCE" | "INVALID_PROTECTED_EVIDENCE" | "AMBIGUOUS_MAPPING" | "OVERLAPPING_SPEECH" | "PROTECTED_SEGMENT_OVERLAP" | "OUTSIDE_TARGET_BOUND" | "OUTSIDE_OCCURRENCE_BOUND" | "NO_FRAME_ALIGNED_RANGE";
9
+ export interface SafeCutResolverOptions {
10
+ preservePauseMs?: number;
11
+ targetPauseMs?: number;
12
+ }
13
+ export interface SafeCutRequest {
14
+ candidate: FillerCandidate;
15
+ analysis: SpeechAnalysis;
16
+ targetRange: TimeRange;
17
+ occurrence: FillerOccurrence;
18
+ timelineId: string;
19
+ sequenceFrameDuration: RationalTime;
20
+ }
21
+ export interface SafeCutEvidence {
22
+ word: SpeechWord;
23
+ previousWord?: SpeechWord;
24
+ nextWord?: SpeechWord;
25
+ speechSegments: SpeechSegment[];
26
+ silenceSegments: SpeechSegment[];
27
+ protectedSegments: SpeechSegment[];
28
+ occurrenceRange: TimeRange;
29
+ targetRange: TimeRange;
30
+ frameDuration: RationalTime;
31
+ pauseBeforeCutMs: number;
32
+ pauseAfterCutMs: number;
33
+ safeRange?: TimeRange;
34
+ }
35
+ export interface SafeCutDecision {
36
+ status: SafeCutStatus;
37
+ candidateId: string;
38
+ occurrenceId: string;
39
+ reasonCodes: SafeCutReasonCode[];
40
+ evidence: SafeCutEvidence;
41
+ range?: TimeRange;
42
+ operation?: Extract<EditOperation, {
43
+ type: "ripple-delete";
44
+ }>;
45
+ }
46
+ /** Resolve filler words to safe frame-aligned operations without mutating an editor. */
47
+ export declare class SafeCutResolver {
48
+ private readonly preservePauseMs;
49
+ private readonly targetPauseMs;
50
+ constructor(options?: SafeCutResolverOptions);
51
+ resolve(request: SafeCutRequest): SafeCutDecision;
52
+ }
@@ -0,0 +1,42 @@
1
+ import type { TimelineIr } from "./editing-session.js";
2
+ import type { ContextRevision } from "../domain/primitives.js";
3
+ export type TimelineReconciliationEntity = "project" | "sequence" | "resource" | "occurrence" | "story-element" | "marker" | "caption";
4
+ export type TimelineReconciliationConflictKind = "property-conflict" | "delete-modify-conflict" | "insert-conflict" | "ambiguous-identity" | "invalid-state";
5
+ export interface TimelineReconciliationConflict {
6
+ kind: TimelineReconciliationConflictKind;
7
+ entity: TimelineReconciliationEntity;
8
+ id: string;
9
+ path: string;
10
+ baseValue?: unknown;
11
+ oursValue?: unknown;
12
+ theirsValue?: unknown;
13
+ message: string;
14
+ }
15
+ export interface TimelineReconciliationInput {
16
+ base: TimelineIr;
17
+ ours: TimelineIr;
18
+ theirs: TimelineIr;
19
+ }
20
+ export type TimelineReconciliationResult = {
21
+ status: "rebased";
22
+ providerRevisionChanged: boolean;
23
+ baseRevision: ContextRevision;
24
+ oursRevision: ContextRevision;
25
+ theirsRevision: ContextRevision;
26
+ merged: TimelineIr;
27
+ conflicts: [];
28
+ } | {
29
+ status: "conflicted";
30
+ providerRevisionChanged: boolean;
31
+ baseRevision: ContextRevision;
32
+ oursRevision: ContextRevision;
33
+ theirsRevision: ContextRevision;
34
+ merged?: undefined;
35
+ conflicts: TimelineReconciliationConflict[];
36
+ };
37
+ /**
38
+ * Three-way merge for the provider-neutral timeline. BASE is never written;
39
+ * OURS is the agent's desired state and THEIRS is the latest provider state.
40
+ */
41
+ export declare function reconcileTimelineIr(input: TimelineReconciliationInput): TimelineReconciliationResult;
42
+ export declare function timelineIrContentDigest(timeline: TimelineIr): string;
@@ -0,0 +1,271 @@
1
+ import type { ContextRevision, RationalTime } from "../domain/primitives.js";
2
+ import type { ProjectSnapshot } from "../domain/project.js";
3
+ import { type TimelineReconciliationResult } from "./drift-reconciliation.js";
4
+ export declare const TIMELINE_IR_SCHEMA_VERSION: 1;
5
+ export type TimelineIrRole = "video" | "audio" | "music" | "title";
6
+ export type TimelineIrResourceKind = "video" | "audio" | "unknown";
7
+ export type TimelineIrBindingKind = "project" | "sequence" | "resource" | "occurrence" | "story-element";
8
+ /** Provider identity is kept at the edge of the IR, not in core timeline fields. */
9
+ export interface TimelineIrBinding {
10
+ provider: string;
11
+ kind: TimelineIrBindingKind;
12
+ identity: string;
13
+ }
14
+ export interface TimelineIrProvider {
15
+ id: string;
16
+ version?: string;
17
+ }
18
+ export interface TimelineIrResource {
19
+ id: string;
20
+ name: string;
21
+ mediaKind: TimelineIrResourceKind;
22
+ source?: string;
23
+ sourceKind?: "local-file";
24
+ sourceDigest?: string;
25
+ /** Exact source-coordinate bounds supplied by the snapshot provider. */
26
+ sourceRange?: {
27
+ start: RationalTime;
28
+ duration: RationalTime;
29
+ };
30
+ metadata?: TimelineIrMediaMetadata;
31
+ binding?: TimelineIrBinding;
32
+ }
33
+ export interface TimelineIrMediaMetadata {
34
+ durationTime: RationalTime;
35
+ streams: TimelineIrMediaStream[];
36
+ }
37
+ export interface TimelineIrMediaStream {
38
+ kind: "video" | "audio";
39
+ codec?: string;
40
+ width?: number;
41
+ height?: number;
42
+ frameRate?: RationalTime;
43
+ sourceRange?: {
44
+ start: RationalTime;
45
+ duration: RationalTime;
46
+ };
47
+ sampleRate?: number;
48
+ channels?: number;
49
+ }
50
+ export interface TimelineIrTransform {
51
+ /** Multipliers relative to the source media's untransformed dimensions. */
52
+ scaleX: number;
53
+ scaleY: number;
54
+ /** Timeline-pixel offsets from the output canvas center; +x is right and +y is up. */
55
+ positionX?: number;
56
+ positionY?: number;
57
+ /** Counter-clockwise rotation in degrees around the media center. */
58
+ rotationDegrees?: number;
59
+ }
60
+ export interface TimelineIrOccurrence {
61
+ id: string;
62
+ name: string;
63
+ startTime: RationalTime;
64
+ durationTime: RationalTime;
65
+ sourceStartTime?: RationalTime;
66
+ track: number;
67
+ role?: TimelineIrRole;
68
+ nativeAudioRole?: string;
69
+ mediaId?: string;
70
+ gainDb?: number;
71
+ fadeIn?: number;
72
+ fadeOut?: number;
73
+ enabled?: boolean;
74
+ transform?: TimelineIrTransform;
75
+ attachedTo?: string;
76
+ binding?: TimelineIrBinding;
77
+ }
78
+ export interface TimelineIrStoryElement {
79
+ id: string;
80
+ kind: string;
81
+ startTime: RationalTime;
82
+ durationTime: RationalTime;
83
+ lane?: number;
84
+ occurrenceId?: string;
85
+ text?: string;
86
+ attachedTo?: string;
87
+ binding?: TimelineIrBinding;
88
+ }
89
+ export interface TimelineIrMarker {
90
+ id: string;
91
+ name: string;
92
+ startTime: RationalTime;
93
+ durationTime: RationalTime;
94
+ }
95
+ export interface TimelineIrTitleStyle {
96
+ fontFamily?: string;
97
+ fontSize?: number;
98
+ color?: string;
99
+ alignment?: "left" | "center" | "right";
100
+ }
101
+ export interface TimelineIrTitle {
102
+ id: string;
103
+ text: string;
104
+ startTime: RationalTime;
105
+ durationTime: RationalTime;
106
+ /** Connected/overlay lane; zero is reserved for the primary storyline. */
107
+ lane: number;
108
+ style?: TimelineIrTitleStyle;
109
+ /** Normalized output coordinates in the centered canvas space: x and y are in [-1, 1], +x is right, and +y is up. */
110
+ position?: {
111
+ x: number;
112
+ y: number;
113
+ };
114
+ }
115
+ export interface TimelineIrTransition {
116
+ id: string;
117
+ kind: "cross-dissolve";
118
+ beforeOccurrenceId: string;
119
+ afterOccurrenceId: string;
120
+ durationTime: RationalTime;
121
+ }
122
+ export interface TimelineIrCaption {
123
+ id: string;
124
+ text: string;
125
+ startTime: RationalTime;
126
+ durationTime: RationalTime;
127
+ }
128
+ export interface TimelineIr {
129
+ schemaVersion: typeof TIMELINE_IR_SCHEMA_VERSION;
130
+ project: {
131
+ id: string;
132
+ name: string;
133
+ binding?: TimelineIrBinding;
134
+ };
135
+ sequence: {
136
+ id: string;
137
+ name: string;
138
+ durationTime: RationalTime;
139
+ /** Explicit source timecode origin; absence is not a zero-origin assertion. */
140
+ timecodeStart?: RationalTime;
141
+ /** Provider-supplied origin for the sequence-coordinate frame grid. */
142
+ frameGridOrigin?: RationalTime;
143
+ frameDuration: RationalTime;
144
+ occurrences: TimelineIrOccurrence[];
145
+ storyElements: TimelineIrStoryElement[];
146
+ markers: TimelineIrMarker[];
147
+ captions: TimelineIrCaption[];
148
+ titles?: TimelineIrTitle[];
149
+ transitions?: TimelineIrTransition[];
150
+ binding?: TimelineIrBinding;
151
+ };
152
+ resources: TimelineIrResource[];
153
+ revision: ContextRevision;
154
+ }
155
+ export type TimelineIrEditOperation = {
156
+ type: "insert-occurrence";
157
+ occurrence: TimelineIrOccurrence;
158
+ placement?: "append" | "insert";
159
+ } | {
160
+ type: "rename-occurrence";
161
+ occurrenceId: string;
162
+ name: string;
163
+ } | {
164
+ type: "trim-occurrence";
165
+ occurrenceId: string;
166
+ sourceStartTime?: RationalTime;
167
+ durationTime: RationalTime;
168
+ } | {
169
+ type: "move-occurrence";
170
+ occurrenceId: string;
171
+ startTime: RationalTime;
172
+ track?: number;
173
+ } | {
174
+ type: "split-occurrence";
175
+ occurrenceId: string;
176
+ splitOffsetTime: RationalTime;
177
+ newOccurrenceId: string;
178
+ } | {
179
+ type: "set-gain";
180
+ occurrenceId: string;
181
+ gainDb: number;
182
+ } | {
183
+ type: "set-transform";
184
+ occurrenceId: string;
185
+ transform: TimelineIrTransform;
186
+ } | {
187
+ type: "remove-occurrence";
188
+ occurrenceId: string;
189
+ } | {
190
+ type: "add-marker";
191
+ marker: TimelineIrMarker;
192
+ } | {
193
+ type: "add-title";
194
+ title: TimelineIrTitle;
195
+ } | {
196
+ type: "remove-title";
197
+ titleId: string;
198
+ } | {
199
+ type: "add-transition";
200
+ transition: TimelineIrTransition;
201
+ } | {
202
+ type: "remove-transition";
203
+ transitionId: string;
204
+ };
205
+ export type EditingSessionState = "clean" | "dirty" | "possibly_stale" | "conflicted" | "rebased" | "waiting_for_materialization";
206
+ export interface EditingSessionDocument {
207
+ schemaVersion: typeof TIMELINE_IR_SCHEMA_VERSION;
208
+ provider?: TimelineIrProvider;
209
+ base: TimelineIr;
210
+ desired: TimelineIr;
211
+ state: EditingSessionState;
212
+ observation?: EditingSessionObservation;
213
+ }
214
+ export interface EditingSessionObservation {
215
+ backend: string;
216
+ sourceId: string;
217
+ databaseKind: string;
218
+ digest: string;
219
+ schemaVersion: number;
220
+ observedAt: string;
221
+ canonical: false;
222
+ coverageComplete: false;
223
+ }
224
+ export interface EditingSessionCreateOptions {
225
+ base: TimelineIr;
226
+ provider?: TimelineIrProvider;
227
+ clock?: () => string;
228
+ }
229
+ export interface TimelineIrPreview {
230
+ baseRevision: ContextRevision;
231
+ before: TimelineIr;
232
+ after: TimelineIr;
233
+ operations: TimelineIrEditOperation[];
234
+ changedOccurrenceIds: string[];
235
+ changedMarkerIds: string[];
236
+ changedTitleIds: string[];
237
+ changedTransitionIds: string[];
238
+ state: EditingSessionState;
239
+ }
240
+ export interface EditingSessionApplyResult extends TimelineIrPreview {
241
+ state: "dirty" | "possibly_stale" | "conflicted" | "rebased" | "waiting_for_materialization" | "clean";
242
+ }
243
+ export declare class EditingSession {
244
+ private readonly value;
245
+ private readonly clock;
246
+ private constructor();
247
+ static create(options: EditingSessionCreateOptions): EditingSession;
248
+ static fromJSON(input: string | unknown, clock?: () => string): EditingSession;
249
+ document(): EditingSessionDocument;
250
+ base(): TimelineIr;
251
+ desired(): TimelineIr;
252
+ state(): EditingSessionState;
253
+ serialize(): string;
254
+ observeProviderRevision(providerRevision: ContextRevision): "unchanged" | "changed";
255
+ preview(operations: TimelineIrEditOperation[], expectedRevision?: ContextRevision): TimelineIrPreview;
256
+ apply(operations: TimelineIrEditOperation[], expectedRevision?: ContextRevision): EditingSessionApplyResult;
257
+ assertMaterializationReady(providerRevision: ContextRevision): void;
258
+ reconcile(providerState: TimelineIr): TimelineReconciliationResult;
259
+ markPossiblyStale(): void;
260
+ bindObservation(observation: EditingSessionObservation): "observed" | "unchanged" | "changed";
261
+ markConflicted(): void;
262
+ markRebased(): void;
263
+ markWaitingForMaterialization(): void;
264
+ markClean(): void;
265
+ private nextTimeline;
266
+ private assertEditable;
267
+ }
268
+ export declare function createTimelineIrFromProjectSnapshot(snapshot: ProjectSnapshot, provider?: TimelineIrProvider): TimelineIr;
269
+ export declare function validateTimelineIr(timeline: TimelineIr): void;
270
+ export declare function validateEditingSessionDocument(document: EditingSessionDocument): void;
271
+ export declare function timelineIrDigest(timeline: TimelineIr): string;
@@ -172,6 +172,7 @@ export function createTimelineIrFromProjectSnapshot(snapshot, provider) {
172
172
  mediaKind: media.mediaKind ?? "unknown",
173
173
  source: media.source,
174
174
  ...(media.sourceDigest ? { sourceDigest: media.sourceDigest } : {}),
175
+ ...(media.sourceRange !== undefined ? { sourceRange: structuredClone(media.sourceRange) } : {}),
175
176
  ...(binding ? { binding: binding("resource", media.mediaId) } : {}),
176
177
  }));
177
178
  const occurrences = snapshot.timeline.clips.map((clip) => ({
@@ -222,6 +223,8 @@ export function createTimelineIrFromProjectSnapshot(snapshot, provider) {
222
223
  id: snapshot.timeline.id,
223
224
  name: snapshot.timeline.name,
224
225
  durationTime: requiredRational(snapshot.timeline.durationTime, "timeline durationTime"),
226
+ ...(snapshot.timeline.timecodeStart ? { timecodeStart: normalizeRationalTime(snapshot.timeline.timecodeStart) } : {}),
227
+ ...(snapshot.timeline.frameGridOrigin ? { frameGridOrigin: normalizeRationalTime(snapshot.timeline.frameGridOrigin) } : {}),
225
228
  frameDuration: requiredRational(snapshot.timeline.frameDuration, "timeline frameDuration"),
226
229
  occurrences,
227
230
  storyElements,
@@ -260,6 +263,10 @@ export function validateTimelineIr(timeline) {
260
263
  requireText(timeline.sequence?.id, "sequence.id");
261
264
  requireText(timeline.sequence?.name, "sequence.name");
262
265
  validateRational(timeline.sequence.durationTime, "sequence.durationTime", false);
266
+ if (timeline.sequence.timecodeStart)
267
+ parseRational(timeline.sequence.timecodeStart, "TIMELINE_IR_INVALID");
268
+ if (timeline.sequence.frameGridOrigin)
269
+ parseRational(timeline.sequence.frameGridOrigin, "TIMELINE_IR_INVALID");
263
270
  validateRational(timeline.sequence.frameDuration, "sequence.frameDuration", true);
264
271
  validateRevision(timeline.revision);
265
272
  validateBinding(timeline.project.binding, "project.binding");
@@ -281,6 +288,15 @@ export function validateTimelineIr(timeline) {
281
288
  }
282
289
  if (resource.metadata)
283
290
  validateMediaMetadata(resource.metadata, `resource ${resource.id}.metadata`);
291
+ if (resource.sourceRange !== undefined) {
292
+ if (!resource.sourceRange || typeof resource.sourceRange !== "object")
293
+ throw new Error(`TIMELINE_IR_INVALID: resource ${resource.id} source range is malformed`);
294
+ parseRational(resource.sourceRange.start, "TIMELINE_IR_INVALID");
295
+ validateRational(resource.sourceRange.duration, `resource ${resource.id}.sourceRange.duration`, true);
296
+ if (resource.metadata && compareRational(resource.sourceRange.duration, resource.metadata.durationTime) !== 0) {
297
+ throw new Error(`TIMELINE_IR_INVALID: resource ${resource.id} source range duration conflicts with metadata`);
298
+ }
299
+ }
284
300
  validateBinding(resource.binding, `resource ${resource.id}.binding`);
285
301
  }
286
302
  const occurrenceIds = uniqueIds(timeline.sequence.occurrences.map((occurrence) => occurrence.id), "occurrence");
@@ -300,10 +316,12 @@ export function validateTimelineIr(timeline) {
300
316
  if (occurrence.sourceStartTime)
301
317
  validateRational(occurrence.sourceStartTime, `occurrence ${occurrence.id}.sourceStartTime`, false);
302
318
  const resource = occurrence.mediaId ? timeline.resources.find(({ id }) => id === occurrence.mediaId) : undefined;
303
- if (resource?.metadata) {
319
+ if (resource?.sourceRange || resource?.metadata) {
304
320
  const sourceStartTime = occurrence.sourceStartTime ?? { value: "0", timescale: "1" };
305
321
  const sourceEndTime = addRationalTimes(sourceStartTime, occurrence.durationTime, "TIMELINE_IR_INVALID");
306
- if (compareRational(sourceEndTime, resource.metadata.durationTime) > 0) {
322
+ const lower = resource.sourceRange?.start ?? { value: "0", timescale: "1" };
323
+ const upper = resource.sourceRange ? addRationalTimes(lower, resource.sourceRange.duration, "TIMELINE_IR_INVALID") : resource.metadata.durationTime;
324
+ if (compareRational(sourceStartTime, lower) < 0 || compareRational(sourceEndTime, upper) > 0) {
307
325
  throw new Error(`TIMELINE_IR_INVALID: occurrence ${occurrence.id} source range exceeds resource ${resource.id}`);
308
326
  }
309
327
  }
@@ -390,6 +408,10 @@ function validateMediaMetadata(metadata, field) {
390
408
  if (!stream || (stream.kind !== "video" && stream.kind !== "audio")) {
391
409
  throw new Error(`TIMELINE_IR_INVALID: ${streamField}.kind is unsupported`);
392
410
  }
411
+ if (stream.sourceRange) {
412
+ validateRational(stream.sourceRange.start, `${streamField}.sourceRange.start`, false);
413
+ validateRational(stream.sourceRange.duration, `${streamField}.sourceRange.duration`, true);
414
+ }
393
415
  if (stream.codec !== undefined)
394
416
  requireText(stream.codec, `${streamField}.codec`);
395
417
  if (stream.kind === "video") {
@@ -484,6 +506,14 @@ function applyOperation(timeline, operation) {
484
506
  if (compareRational(splitOffsetTime, occurrence.durationTime) >= 0) {
485
507
  throw new Error("TIMELINE_IR_OPERATION_INVALID: splitOffsetTime must be inside the occurrence duration");
486
508
  }
509
+ if (timeline.sequence.frameGridOrigin) {
510
+ const cut = addRationalTimes(occurrence.startTime, splitOffsetTime, "TIMELINE_IR_OPERATION_INVALID");
511
+ const delta = parseRational(subtractRationalTimes(cut, timeline.sequence.frameGridOrigin, "TIMELINE_IR_OPERATION_INVALID"), "TIMELINE_IR_OPERATION_INVALID");
512
+ const frame = parseRational(timeline.sequence.frameDuration, "TIMELINE_IR_OPERATION_INVALID");
513
+ if ((delta.value * frame.timescale) % (delta.timescale * frame.value) !== 0n) {
514
+ throw new Error("TIMELINE_IR_OPERATION_INVALID: split point is not frame aligned");
515
+ }
516
+ }
487
517
  const right = structuredClone(occurrence);
488
518
  right.id = operation.newOccurrenceId;
489
519
  right.startTime = addRationalTimes(occurrence.startTime, splitOffsetTime, "TIMELINE_IR_OPERATION_INVALID");