davinci-resolve-mcp 2.33.7 → 2.34.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.34.0
+
+First phase of transcript-driven editing: a Cut intermediate representation and a
+mechanical cut proposer.
+
+- **Added** `src/utils/cut_ir.py` — the Cut-IR: a typed representation of an
+  editorial cut ({kind, span, action, confidence, rationale, evidence}) plus a
+  deterministic Pass-1 detector that flags filler words, long pauses, and
+  repeated lines from a timestamped transcript. No LLM.
+- **Added** `timeline(action="propose_cuts", cues?, long_pause_frames?)` — a
+  DRY-RUN that runs Pass-1 over the timeline's subtitle transcript (or provided
+  cues) and returns a CutList. It proposes only; it applies nothing. The semantic
+  Pass-2 and the governed timeline executor are subsequent phases.
+
+## What's New in v2.33.8
+
+Bridge-call performance instrumentation.
+
+- **Added** `src/utils/bridge_metrics.py` — a counting proxy that wraps a Resolve
+  handle and tallies attribute accesses and method calls (each a COM/socket
+  round-trip), so the real bridge cost of an operation is measured rather than
+  guessed.
+- **Added** `scripts/measure_bridge_cost.py` — runs a representative media-pool
+  traversal through the proxy and reports round-trips per clip. A minimal
+  name+type walk measured ~6.7 round-trips per clip, confirming round-trips scale
+  linearly with traversal size. A property cache remains gated on profiling
+  *repeated*-read patterns in real workflows (don't cache blind).
+
 ## What's New in v2.33.7
 
 Read/write symmetry audit and a gap it surfaced.

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.33.7-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.34.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-32%20(341%20full)-blue.svg)](#server-modes)

package/docs/SKILL.md

@@ -729,6 +729,8 @@ Key actions:
 - `get_track_count(track_type)` — track_type: `"video"`, `"audio"`, `"subtitle"`
 - `get_transcript(with_timecodes?)` — read the subtitle track(s) as transcript
   text `{text, cue_count, has_subtitles, cues}`
+- `propose_cuts(cues?, long_pause_frames?)` — DRY-RUN: mechanically detect
+  candidate cuts (fillers, long pauses, repeats) from the transcript; proposes only
 - `add_track(track_type, sub_type?)` / `delete_track(track_type, index)`
 - `get_items(track_type, index)` — items on a track
 - `clip_where(track_type?, track_index?, name_contains?, duration_lt?, duration_gt?)` —

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.33.7"
+VERSION = "2.34.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.33.7",
+  "version": "2.34.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/scripts/measure_bridge_cost.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""Measure DaVinci Resolve bridge round-trips for representative operations.
+
+Wraps the live project in a counting proxy and runs a few common traversals,
+reporting how many attribute accesses + method calls (each a bridge round-trip)
+they cost. This is the measurement that gates whether a property cache is worth
+building. Run against an OPEN project; it only reads.
+
+    PYTHONPATH=. venv/bin/python scripts/measure_bridge_cost.py
+"""
+import sys
+
+import src.server as s
+from src.utils.bridge_metrics import measure
+
+
+def _walk_media_pool(project_proxy):
+    """A typical media-pool traversal: every folder, every clip, name + a property."""
+    mp = project_proxy.GetMediaPool()
+    root = mp.GetRootFolder()
+    clips_seen = 0
+
+    def walk(folder):
+        nonlocal clips_seen
+        for clip in (folder.GetClipList() or []):
+            clip.GetName()
+            clip.GetClipProperty("Type")
+            clips_seen += 1
+        for sub in (folder.GetSubFolderList() or []):
+            walk(sub)
+
+    walk(root)
+    return clips_seen
+
+
+def main():
+    r = s.get_resolve()
+    if not r:
+        print("Not connected to Resolve.")
+        return 1
+    proj = r.GetProjectManager().GetCurrentProject()
+    if not proj:
+        print("No project open.")
+        return 1
+
+    clips_holder = {}
+
+    def op(proj_proxy):
+        clips_holder["n"] = _walk_media_pool(proj_proxy)
+
+    counts = measure(op, proj)
+    n = clips_holder.get("n", 0)
+    total = counts["attr_access"] + counts["calls"]
+    print(f"project: {proj.GetName()!r}")
+    print(f"clips walked: {n}")
+    print(f"bridge attr-accesses: {counts['attr_access']}")
+    print(f"bridge method-calls:  {counts['calls']}")
+    print(f"total round-trips:    {total}")
+    if n:
+        print(f"round-trips per clip: {total / n:.1f}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.33.7"
+VERSION = "2.34.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.33.7"
+VERSION = "2.34.0"
 
 import base64
 import os
@@ -45,6 +45,7 @@ from src.utils.cdl import normalize_cdl_payload
 from src.utils.mcp_stdio import run_fastmcp_stdio
 from src.utils.api_truth import lookup_api_truth, VERIFIED_ON as _API_TRUTH_VERIFIED_ON
 from src.utils.contracts import validate as _validate_params
+from src.utils.cut_ir import build_cut_list as _build_cut_list
 from src.utils.proc import safe_run
 from src.utils.readback import verify_by_readback
 from src.utils.update_check import (
@@ -15202,6 +15203,9 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
       get_media_pool_item() -> {name, id}
       get_transcript(with_timecodes?) -> {text, cue_count, has_subtitles, cues}
         Read the timeline's subtitle track(s) as transcript text.
+      propose_cuts(cues?, long_pause_frames?) -> {cuts, cut_count, basis_cue_count, pass, note}
+        DRY-RUN. Mechanically detect candidate cuts (filler words, long pauses,
+        repeated lines) from the subtitle transcript. Proposes only; applies nothing.
       get_mark_in_out() -> {mark}
       set_mark_in_out(mark_in, mark_out, type?) -> {success}
       clear_mark_in_out(type?) -> {success}
@@ -15489,6 +15493,13 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
         return {"name": mpi.GetName(), "id": mpi.GetUniqueId()} if mpi else {"name": None, "id": None}
     elif action == "get_transcript":
         return _timeline_transcript(tl, with_timecodes=bool(p.get("with_timecodes")))
+    elif action == "propose_cuts":
+        # Dry-run only: detect mechanical cuts (fillers, long pauses, repeats)
+        # from the timeline's subtitle transcript. Proposes; never edits.
+        cues = p.get("cues")
+        if cues is None:
+            cues = _timeline_transcript(tl, with_timecodes=True)["cues"]
+        return _build_cut_list(cues, long_pause_frames=int(p.get("long_pause_frames", 48)))
     elif action == "get_mark_in_out":
         return _ser(tl.GetMarkInOut())
     elif action == "set_mark_in_out":
@@ -15698,7 +15709,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
         if mp_err:
             return mp_err
         return _fairlight_boundary_report(proj, mp, tl, p)
-    return _unknown(action, ["list","get_current","set_current","get_name","set_name","get_start_frame","get_end_frame","get_start_timecode","set_start_timecode","get_track_count","add_track","delete_track","get_track_sub_type","set_track_enable","get_track_enabled","set_track_lock","get_track_locked","get_track_name","set_track_name","get_items","delete_clips","set_clips_linked","duplicate","duplicate_clips","copy_clips","move_clips","copy_range","duplicate_range","overwrite_range","lift_range","story_spine_report","create_variant_from_ranges","bulk_set_item_properties","apply_look_to_items","thumbnail_contact_sheet","marker_thumbnail_review","edit_kernel_capabilities","probe_edit_kernel_item","title_property_scan","set_title_text","bulk_set_title_text","create_compound_clip","create_fusion_clip","import_into_timeline","export","get_setting","set_setting","insert_generator","insert_fusion_generator","insert_fusion_composition","insert_ofx_generator","insert_title","insert_fusion_title","get_unique_id","get_node_graph","get_media_pool_item","get_transcript","get_mark_in_out","set_mark_in_out","clear_mark_in_out","convert_to_stereo","get_items_in_track","get_voice_isolation_state","set_voice_isolation_state","extract_source_frame_ranges","audio_mix_capability_report",*_TIMELINE_CONFORM_KERNEL_ACTIONS,*_TIMELINE_AUDIO_KERNEL_ACTIONS])
+    return _unknown(action, ["list","get_current","set_current","get_name","set_name","get_start_frame","get_end_frame","get_start_timecode","set_start_timecode","get_track_count","add_track","delete_track","get_track_sub_type","set_track_enable","get_track_enabled","set_track_lock","get_track_locked","get_track_name","set_track_name","get_items","delete_clips","set_clips_linked","duplicate","duplicate_clips","copy_clips","move_clips","copy_range","duplicate_range","overwrite_range","lift_range","story_spine_report","create_variant_from_ranges","bulk_set_item_properties","apply_look_to_items","thumbnail_contact_sheet","marker_thumbnail_review","edit_kernel_capabilities","probe_edit_kernel_item","title_property_scan","set_title_text","bulk_set_title_text","create_compound_clip","create_fusion_clip","import_into_timeline","export","get_setting","set_setting","insert_generator","insert_fusion_generator","insert_fusion_composition","insert_ofx_generator","insert_title","insert_fusion_title","get_unique_id","get_node_graph","get_media_pool_item","get_transcript","propose_cuts","get_mark_in_out","set_mark_in_out","clear_mark_in_out","convert_to_stereo","get_items_in_track","get_voice_isolation_state","set_voice_isolation_state","extract_source_frame_ranges","audio_mix_capability_report",*_TIMELINE_CONFORM_KERNEL_ACTIONS,*_TIMELINE_AUDIO_KERNEL_ACTIONS])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════

package/src/utils/bridge_metrics.py

@@ -0,0 +1,76 @@
+"""Instrumentation for counting DaVinci Resolve bridge round-trips.
+
+Every attribute access and method call on a Resolve object is a COM/socket
+round-trip — the dominant cost of most operations. Before optimizing (or adding
+a cache), you have to *measure* where the round-trips concentrate. This module
+provides an opt-in counting proxy that wraps a Resolve handle and tallies
+attribute accesses and method calls, so a hot path's real bridge cost is
+visible instead of guessed.
+
+This is the measurement half of the bridge-perf work. A property cache is only
+worth building once measurement shows a clear, repeated-read hot spot — don't
+cache blind.
+
+Example:
+
+    counts = {}
+    rp = CountingProxy(resolve, counts)
+    rp.GetProjectManager().GetCurrentProject().GetName()
+    print(counts)  # {'attr_access': N, 'calls': M}
+"""
+from typing import Any, Dict, Optional
+
+
+class CountingProxy:
+    """Wrap a Resolve object, counting attribute accesses and method calls.
+
+    Method return values that are themselves objects are wrapped too, so a whole
+    call chain through the bridge is counted. Primitives are returned as-is.
+    """
+
+    __slots__ = ("_target", "_counter")
+
+    def __init__(self, target: Any, counter: Dict[str, int]):
+        object.__setattr__(self, "_target", target)
+        object.__setattr__(self, "_counter", counter)
+        counter.setdefault("attr_access", 0)
+        counter.setdefault("calls", 0)
+
+    def __getattr__(self, name: str) -> Any:
+        counter = object.__getattribute__(self, "_counter")
+        target = object.__getattribute__(self, "_target")
+        counter["attr_access"] += 1
+        attr = getattr(target, name)
+        if callable(attr):
+            def wrapped(*args: Any, **kwargs: Any) -> Any:
+                counter["calls"] += 1
+                result = attr(*args, **kwargs)
+                return _maybe_wrap(result, counter)
+            return wrapped
+        return _maybe_wrap(attr, counter)
+
+
+_PRIMITIVE = (str, int, float, bool, bytes, type(None))
+
+
+def _maybe_wrap(value: Any, counter: Dict[str, int]) -> Any:
+    if isinstance(value, _PRIMITIVE):
+        return value
+    if isinstance(value, (list, tuple)):
+        # Wrap object elements so traversals (e.g. clip lists) are counted.
+        return type(value)(_maybe_wrap(v, counter) for v in value)
+    if isinstance(value, dict):
+        return {k: _maybe_wrap(v, counter) for k, v in value.items()}
+    # Likely a Resolve API object — wrap so its further use is counted.
+    return CountingProxy(value, counter)
+
+
+def measure(fn, target: Any) -> Dict[str, int]:
+    """Run ``fn(proxy)`` against a counting proxy of ``target``; return the counts.
+
+    ``fn`` receives the proxy and should exercise the operation under study.
+    """
+    counter: Dict[str, int] = {}
+    proxy = CountingProxy(target, counter)
+    fn(proxy)
+    return counter

package/src/utils/cut_ir.py

@@ -0,0 +1,115 @@
+"""Cut intermediate representation (Cut-IR) and the mechanical (Pass-1) detector.
+
+The Cut-IR is the typed contract between a timestamped transcript and concrete,
+governed timeline operations. Producers emit Cuts; an executor (a later phase)
+consumes them as governed, versioned edits; a review UI shows them. This module
+provides the schema plus the deterministic Pass-1 detector — filler words, long
+pauses, and repeated lines — with no LLM. The semantic Pass-2 and the timeline
+executor are separate phases (see local/design/research/r1-cut-ir.md).
+
+A Cut:
+    {
+      "kind": "filler" | "long_pause" | "stammer" | "false_start" | "semantic",
+      "span": {"start": <frame>, "end": <frame>},
+      "action": "lift" | "ripple_delete" | "keep" | "reorder" | "swap",
+      "confidence": 0.0..1.0,
+      "rationale": str,
+      "evidence": {...},
+    }
+"""
+from typing import Any, Dict, List, Optional
+
+# Common English fillers (single tokens and short phrases).
+FILLER_WORDS = {
+    "um", "uh", "er", "ah", "eh", "hmm", "mm", "uhh", "umm",
+    "like", "so", "well", "right", "okay", "ok",
+}
+FILLER_PHRASES = {"you know", "i mean", "sort of", "kind of", "you see"}
+
+
+def make_cut(
+    kind: str,
+    start: Optional[int],
+    end: Optional[int],
+    action: str,
+    confidence: float,
+    rationale: str,
+    evidence: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    return {
+        "kind": kind,
+        "span": {"start": start, "end": end},
+        "action": action,
+        "confidence": round(float(confidence), 2),
+        "rationale": rationale,
+        "evidence": evidence or {},
+    }
+
+
+def _norm(text: str) -> str:
+    return (text or "").strip().lower().strip(".,!?;:")
+
+
+def _is_filler_only(text: str) -> bool:
+    low = _norm(text)
+    if not low:
+        return False
+    if low in FILLER_PHRASES:
+        return True
+    tokens = [t.strip(".,!?;:") for t in low.split()]
+    tokens = [t for t in tokens if t]
+    return bool(tokens) and all(t in FILLER_WORDS for t in tokens)
+
+
+def detect_cuts_pass1(
+    cues: List[Dict[str, Any]],
+    *,
+    long_pause_frames: int = 48,
+) -> List[Dict[str, Any]]:
+    """Mechanical Pass-1 detection over timestamped cues.
+
+    cues: list of {"text", "start", "end"} in frames. Returns a list of Cuts.
+    """
+    cuts: List[Dict[str, Any]] = []
+    for i, cue in enumerate(cues):
+        text = (cue.get("text") or "").strip()
+        start, end = cue.get("start"), cue.get("end")
+
+        if _is_filler_only(text):
+            cuts.append(make_cut(
+                "filler", start, end, "lift", 0.8,
+                f"Filler-only cue: {text!r}", {"text": text},
+            ))
+
+        if i > 0:
+            prev_text = (cues[i - 1].get("text") or "").strip()
+            if _norm(prev_text) and _norm(text) == _norm(prev_text):
+                cuts.append(make_cut(
+                    "stammer", start, end, "lift", 0.6,
+                    f"Repeated line: {text!r}", {"text": text},
+                ))
+            prev_end = cues[i - 1].get("end")
+            if (prev_end is not None and start is not None
+                    and start - prev_end > long_pause_frames):
+                cuts.append(make_cut(
+                    "long_pause", prev_end, start, "lift", 0.5,
+                    f"Pause of {start - prev_end} frames before {text!r}",
+                    {"frames": start - prev_end},
+                ))
+    return cuts
+
+
+def build_cut_list(
+    cues: List[Dict[str, Any]],
+    *,
+    long_pause_frames: int = 48,
+) -> Dict[str, Any]:
+    """Run Pass-1 and wrap the result as a (dry-run) CutList."""
+    cuts = detect_cuts_pass1(cues, long_pause_frames=long_pause_frames)
+    return {
+        "cuts": cuts,
+        "cut_count": len(cuts),
+        "basis_cue_count": len(cues),
+        "pass": "mechanical",
+        "note": "Dry-run proposal. Review before applying; no edits were made.",
+    }